0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
Commit graph

73 commits

Author SHA1 Message Date
mastra-platform[bot]
c34ff7e927
docs(models): classify Requesty as a gateway (#29970) 2026-11-10 14:14:49 -08:00
mastra-platform[bot]
a6d7cf6859
docs(models): clarify how to use Azure and Bedrock model strings (#29950) 2026-11-10 14:16:49 -07:00
mastra-platform[bot]
76770b323c
fix(docs): clear pnpm check warnings and run docs-audit checks through pnpm check (#29843)
## Summary

Follow-up to #29801 (unified `pnpm check` for docs).

**Clear the remaining `pnpm check` warnings** — `pnpm --filter
mastra-docs check` now reports 0 errors and 0 warnings across 1,005
files.
- `mastra/no-self-host-url`: links to `https://mastra.ai/...` pages are
now root-relative in the quickstart partials, `reference/auth/neon.mdx`,
`reference/manual-install.mdx`, and the generated `models/index.mdx`.
The generator (`packages/core/scripts/generate-model-docs.ts`) now emits
`/models/providers/<id>` so regeneration stays clean. Link labels are
unchanged, so copied prompts still show full URLs, and the llms.txt
plugin still turns root-relative links into absolute ones with
`siteUrl`.
- `mastra/frontmatter-packages-max`: `integrations/channels/github.mdx`
listed five packages. I removed `@mastra/libsql` because the page only
uses it as the example's storage adapter.

**docs-audit `run-checks.sh` now uses `pnpm check`** — the separate
oxfmt-mdx, remark, Vale, and `pnpm validate` calls are replaced by one
`pnpm check --format json <docs>` run. The script still prints the same
five summary lines that the skill and report template read
(`format-target`, `remark-target`, `vale-target`, `validate-target`,
`repo-wide-failures`). Findings are now matched to audited pages by file
path, which replaces the old grep/awk route matching. Error findings on
audited pages give `fail`. Warning findings on audited pages, or a
skipped Vale run, give `warn`. Errors in other files are listed under
`repo-wide-failures`. The script stays read-only and is still not run in
CI.

## Test plan
- [x] `pnpm check --no-vale --format json` → `passed`, 0 errors, 0
warnings, 1,005 files
- [x] `run-checks.sh` on clean pages → all `pass`, exit 0
- [x] Added a second H1, a fence with no language, and a formatting
error to an audited page → `format-target=fail`, `remark-target=fail`,
diagnostics printed, exit 1
- [x] Out-of-date `vercel.json` while auditing an unrelated page →
targets `pass`, `repo-wide-failures=validate`, exit 0
- [x] Vale binary missing → `vale-target=warn`, exit 0; a path outside
docs/ → exit 2

Co-authored-by: mastra-platform[bot] <mastra-platform[bot]@users.noreply.github.com>
Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com>
2026-11-09 17:53:33 -07:00
mastra-platform[bot]
51a20e848e
feat(docs): one pnpm check command for all docs checks, with JSON output and stable rule IDs (#29801)
Co-authored-by: LekoArts <lekoarts@gmail.com>
2026-11-09 16:59:20 -07:00
Leo
63b4dced00
docs(models): document which providerOptions key reaches custom endpoints (#29423)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: mastra-platform[bot] <mastra-platform[bot]@users.noreply.github.com>
Co-authored-by: mastra-platform[bot] <284800079+mastra-platform[bot]@users.noreply.github.com>
2026-11-04 17:30:00 -08:00
Damien Schneider
7701b35eaa
chore(lint): enable safe syntax simplification rules at root (#28582)
Enables all eleven requested Oxlint rules as errors in the root config
and migrates the 115 existing findings across 55 files. JSX curly-brace
simplification is limited to props (`props: 'never', children:
'ignore'`), boolean props use shorthand, and empty elements become
self-closing.

The manual edits preserve the exact continued-string and template
values, remove redundant assignment-side non-null assertions, and retain
the indexed-read assertion in fastembed's compound assignment. The
BigInt and octal conversions use native globals and exact values
supported by the existing compilation targets. No lint suppressions were
added.

Validation: the eleven-rule scan reports zero diagnostics; before/after
emitted-JavaScript comparison passes for all 55 migrated files,
including 31 JSX files, after normalizing only the reviewed syntax
rewrites. Formatting and whitespace checks pass. Core utility/clone
tests (146), fastembed pooling tests (9), the changed A2A signature test
(1), and fastembed build-config typechecking pass. The root lint scan
retains the same 1,244 pre-existing diagnostics with no new findings.
GitHub CI now also passes the full lint/format job, build, Mastra Code
typecheck, generated-file check, and bundle validation. Local UI/evals
runs were limited by missing dependencies; the CodeDiff folding failure
was reproduced on unchanged baseline code. A second audit confirmed
native unshadowed globals for all five literal conversions, pure targets
for all twelve assignment rewrites, no references or direct eval in all
eight simplified catches, and ordinary semantics for both computed keys.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

<!-- coderabbit-ai-generated:v1 -->

## ELI5

This PR turns on more code-style checks and updates existing code to
pass them. The changes simplify syntax while preserving the intended
behavior.

## Changes

- Enabled eleven Oxlint rules as errors in the root configuration.
- Updated 115 findings across 55 files. Changes include simpler string
and JSX syntax, compound assignments, native BigInt and octal literals,
and catch clauses without unused error variables.
- Configured JSX curly-brace simplification for props only. JSX children
remain unchanged.
- Removed redundant assignment-side non-null assertions while retaining
the indexed-read assertion needed for fastembed’s compound assignment.
- Added no lint suppressions.

## Validation

The author reports zero diagnostics from the eleven-rule scan and no new
findings in the root lint scan, which retains 1,244 pre-existing
diagnostics. Before-and-after emitted-JavaScript comparisons reportedly
pass for all 55 changed files after normalizing the reviewed syntax
rewrites. Formatting and whitespace checks also pass.

Reported tests include 146 core utility and clone tests, 9 fastembed
pooling tests, 1 changed A2A signature test, and fastembed build-config
typechecking. Full workspace lint and the UI/evals suites were limited
by missing dependencies in the checkout. The CodeDiff folding test fails
on unchanged baseline code.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-10-27 14:00:25 +01:00
mastra-platform[bot]
13a82118ba
docs: add missing imports to file-titled code blocks (#28414) 2026-10-26 14:58:17 +01:00
mastra-platform[bot]
80c6d4f769
chore: refresh hardcoded model router defaults to latest models (#28108) 2026-10-22 11:21:31 +02:00
Damien Schneider
92004fd001
feat(core): keep the reasoning options models.dev publishes per model (#26225)
**─────── TLDR ───────**
> Mastra now keeps the reasoning controls models.dev lists for each
model, and `getModelReasoningOptions` reads them.

models.dev publishes `reasoning_options` for about 4,300 of the models
in our registry: the effort levels a model accepts, a thinking-token
budget, or an on/off toggle. The models.dev gateway only copied
`attachment`, `temperature` and `structured_output`, so this was
dropped, and anything offering reasoning levels had to hard-code them
per model. Mastra Code's thinking picker does exactly that and shows
levels models don't have, like Max on Claude Haiku 4.5.

First of a stack: #26229 makes Mastra Code offer levels from this data,
and #26213 puts the picker in Factory's status line.

### Behavior changed

`getModelReasoningOptions('anthropic/claude-sonnet-4-6')`
&nbsp;&nbsp;└─ **new** — effort `low · medium · high · max`, or a budget
of at least 1024 tokens

a gateway route that publishes its own data,
`openrouter/anthropic/claude-haiku-4.5`
&nbsp;&nbsp;└─ **new** — OpenRouter's answer, not Anthropic's

a gateway that publishes per-provider data,
`acme/anthropic/claude-haiku-4-5`
&nbsp;&nbsp;└─ **new** — the gateway's `acme/anthropic` answer, before
Anthropic's

a catalog-only gateway, `netlify/openai/gpt-5`
&nbsp;&nbsp;└─ **new** — falls back to OpenAI's data, like the other
capability lookups

a model models.dev lists without controls,
`xai/grok-4.20-0309-reasoning`
&nbsp;&nbsp;└─ **new** — `[]`, so "no controls" never reads as "no data"
(`undefined`)

an effort list with a non-string entry, `sarvam/sarvam-30b` (`[null,
"low", "medium", "high"]`)
&nbsp;&nbsp;└─ **new** — effort `low · medium · high`, not the whole
option dropped

a versioned Bedrock id, `amazon-bedrock/us.anthropic.claude-opus-4-6-v1`
&nbsp;&nbsp;└─ **new** — `undefined`: the `-v1` suffix isn't stripped,
as in the other lookups

### Shape changed

new on `@mastra/core/llm`, and a new key in each
`capabilities/<provider>.json`
&nbsp;&nbsp;&nbsp;&nbsp;`getModelReasoningOptions(modelRouterId)` ·
`ModelReasoningOption` · `reasoning: { [modelId]: ModelReasoningOption[]
}`

### Decisions

- **kept the models.dev shape, not a Mastra level scale** — each caller
maps it onto its own levels; unknown option types are dropped at parse.
- **one entry per model, not grouped by option set** — a direct lookup
by id; grouping the 169 distinct sets saves about a third of the size
and adds an index to build on load.
- **added only the `reasoning` key to today's files** — a full
regenerate drags unrelated registry drift in; the 6-hourly job writes
the same thing after merge.

### Cost

The capability files grow from 0.4 MB to 0.9 MB in the package. Each
provider's file loads on its first lookup, not at startup.

### Not verified

- [ ] the runtime refresh under `MASTRA_DEV` writing `reasoning` into
`~/.cache/mastra`: it calls the same generator functions, but I only ran
them from a script

---

> ██████████████████ **generated** `+28105 −183` — capability data
> █ **source** `+158 −12`
> █ **tests** `+147 −1`
> █ **changeset** `+17`


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5

Models.dev lists which reasoning controls each AI model supports. This
change saves those details so applications can look them up for a model
and show the controls it supports.

## Summary

- Added `getModelReasoningOptions(modelRouterId)` and exported
`ModelReasoningOption` from `@mastra/core/llm`.
- The lookup returns the model’s reasoning options, `[]` when the model
is listed without options, or `undefined` when no capability data
describes it. It supports gateway data and fallback, including Bedrock
model IDs.
- The models.dev parser keeps recognized toggle, effort, and
token-budget options. It drops options it cannot parse.
- The registry generator writes reasoning data to provider capability
files. The change adds reasoning options for models across providers.
- Added tests for parsing, lookup behavior, and generated capability
files. Test execution results were not provided.
- Runtime refresh with `MASTRA_DEV` was not verified. The author reports
running the generator functions from a script instead.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-10-08 00:41:04 +02:00
Lennart
e4a513f28b
docs: clean up skill naming, model index provider links, and migration frontmatter (#25410) 2026-09-29 09:54:23 +02:00
mastra-platform[bot]
b8e3ee5da5
Support the OpenAI Responses API for custom-URL model configs (#24029)
Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>
2026-09-15 11:16:35 -07:00
Lennart
5b148fa6d8
chore(docs): Link updates, model pages, mermaid diagrams (#23318) 2026-09-08 16:18:14 +02:00
Lennart
0a251e56c6
docs: improve generated model page metadata (#22765) 2026-09-02 10:17:54 +02:00
devin-ai-integration[bot]
75459c7831
docs(models): classify Merge Gateway as a gateway (#21784)
Co-authored-by: alex <alex@mastra.ai>
2026-08-18 13:14:16 -07:00
Lennart
50ef54bdb4
docs: unify integration grids and navigation (#21331) 2026-08-12 14:20:38 +02:00
devin-ai-integration[bot]
9140cacd9d
docs(sidebar): drop Beta badges in Harness, replace remaining Beta badges with New (#21150)
## Description

Harness sidebar entries (Durable Agents, Goals, Schedules, Signals,
Signal Providers, Agent Controller, plus their
`AgentController`/`Signals` reference entries) no longer carry a `beta`
badge. Every other `tags: ['beta']` sidebar entry in
docs/guides/reference is now `tags: ['new']`.

Since the badge no longer conveys beta status, pages that had no beta
admonition got one (`:::experimental`, which renders as a "beta"
callout):

-
`reference/signals/{create-notification-inbox-tool,signal-provider,task-signal-provider,webhook-signal-provider}.mdx`
- `reference/tools/create-code-mode.mdx`
- `docs/server/auth/workers.mdx`, `guides/deployment/mastra-workers.mdx`

All other affected pages already had a beta admonition stating the API
may change (Trace Intelligence keeps its "Private beta" warning).

Interpretation note: harness-related reference entries were treated as
part of Harness, so their badges were removed rather than switched to
New.

Heads up: `pnpm validate` enforces a 30-day window on `new` tags, so
these badges will need removing (or refreshing) within a month.

`pnpm validate` passes.

## Related issue(s)

Requested in Slack:
https://kepler-bej6556.slack.com/archives/C0AV0VBFM0V/p1786355508067289?thread_ts=1786355508.067289&cid=C0AV0VBFM0V

## Type of change

- [x] Documentation update

## Checklist

- [x] I have made corresponding changes to the documentation (if
applicable)


Link to Devin session:
https://app.devin.ai/sessions/b8173ef4fa944cfea51b2fcd708e745a

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## ELI5

This update makes documentation labels more accurate. It marks beta
features with clear notices and labels newer features as `new`.

## Changes

- Removed incorrect `beta` labels from Harness entries.
- Changed remaining `beta` labels in `docs/guides/reference` to `new`.
- Added `:::experimental` callouts to affected documentation pages.
- Kept existing beta warnings unchanged, including Trace Intelligence’s
“Private beta” warning.
- Added untagged sidebar entries for Schedules, Signals, Signal
Providers, and Agent Controller.
- Confirmed that `pnpm validate` passes.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: alex <alex@mastra.ai>
Co-authored-by: Alex Booker <booker@booker.codes>
2026-08-10 16:03:40 +01:00
Lennart
044f257db3
chore(docs): Polish sidebar UI (#20904) 2026-08-07 15:45:27 +02:00
Andre Landgraf
e932ad25d1
docs: add Neon as built-in gateway (#20573)
Co-authored-by: Leo Orel <leodoesdev@gmail.com>
Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>
2026-08-05 10:45:13 -07:00
Tyler Barnes
8b20926cd5
Add structured-output model capability tracking (#19440)
## Summary

Adds native structured-output support to the generated model capability
registry.

- collect `structured_output` metadata from model gateways
- generate `structuredOutput` lists in per-provider capability files
- expose a typed tri-state `modelSupportsStructuredOutput` lookup
- preserve explicit route overrides for provider endpoints whose
advertised capability differs from behavior
- encode gateway-prefixed provider IDs into reversible flat capability
filenames and remove stale legacy nested paths during regeneration

## Test plan

- `pnpm exec vitest run
packages/core/src/llm/model/registry-generator.test.ts
packages/core/src/llm/model/provider-registry.test.ts --reporter=dot
--bail 1`
- `pnpm --filter ./packages/core check`

## Stack

1. **This PR:** capability tracking
2. #19442: automatic structured-output routing and goal scorer consumer
3. #19441: headless MastraCode goal API


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5

This PR lets Mastra keep a reliable “does this model support structured
output?” checklist (think: can it consistently return valid JSON). It
reads that info from model gateways, saves it into the provider
capability registry, and adds a lookup function Mastra can safely call.

## What changed

- Collected `structured_output` metadata from model gateways and
generated per-provider `structuredOutput` model allowlists (in both
`src` and `dist` registry outputs).
- Added `modelSupportsStructuredOutput(modelRouterId)` as a typed
tri-state lookup:
  - `true` when the model is allowlisted for structured output,
- `false` when it is explicitly known to be unsupported (including
override behavior),
  - `undefined` when no capability data exists for the provider.
- Preserved explicit route overrides (notably `deepseek/deepseek-v4-pro`
forced to `false`) even when gateway-advertised capabilities differ from
runtime behavior.
- Flattened capability filenames by encoding provider IDs via
`getCapabilityFileName(provider)` (URL-encoded) so gateway-prefixed
provider IDs map cleanly to reversible flat `capabilities/<file>.json`
outputs.
- Updated regeneration to remove stale capability outputs:
- legacy nested gateway paths (e.g. `capabilities/<gateway>/...`) are
deleted,
- stale legacy/flat capability files are also cleaned up when
regenerating the `capabilities/` directory.
- Added/extended JSON capability files with a new top-level
`structuredOutput: string[]` field for providers that support structured
output.
- Added tests ensuring regeneration removes both legacy nested
capability paths and stale flat capability files, and validating the
structured-output lookup scenarios (supported, explicitly unsupported,
provider-known-but-model-not-listed => `false`, unknown provider =>
`undefined`, and nested gateway route handling).
- Exported `modelSupportsStructuredOutput` from `@mastra/core`
entrypoints and documented the new lookup via the updated changeset.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-07-15 19:48:09 -07:00
Lennart
79c48f8f6d
chore(docs): Add hidden agent prompts (#18698) 2026-07-01 14:56:59 +02:00
Anurag Ojha
003f35d19e
feat(core): strip unsupported sampling params via capability registry (#18622)
## Description

Extends the model capability registry to include a `temperature`
dimension so the model router can proactively strip unsupported sampling
parameters (`temperature`, `topP`, `topK`) before dispatching requests.
Models like `claude-opus-4-7` and `gpt-5-pro` that report `temperature:
false` on models.dev now have these parameters silently removed,
preventing 400 errors with zero user configuration.

- Generalized the attachment-only capability loader into a
multi-dimension system (`CapabilityDimension`) that reads both
`attachment` and `temperature` from per-provider JSON files
- Added `modelSupportsTemperature()` public lookup function following
the same pattern as `modelSupportsAttachments()`
- Added `stripUnsupportedSamplingParams()` in `ModelRouterLanguageModel`
that checks the registry before every `doGenerate` and `doStream` call
- Extended `ModelsDevGateway.fetchProviders()` to collect `temperature`
capability data from models.dev alongside attachments
- Updated `registry-generator` and `generate-providers` script to write
merged capability files with both dimensions
- Added temperature data to `anthropic.json` and `openai.json`
capability files sourced from the live models.dev API

## Related Issue(s)

Fixes #16247

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update

## Checklist

- [ ] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have addressed all Coderabbit comments on this PR

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
Some AI models only accept certain “settings” (like how random the
output should be). This PR teaches Mastra to check whether a model
supports `temperature`/`topP`/`topK` and automatically removes
unsupported ones so requests don’t fail with 400 errors.

## Summary
- Extended the model capability registry to support a new `temperature`
capability dimension (alongside existing `attachment` support), with a
new `modelSupportsTemperature()` lookup exported from core.
- Generalized the registry/capability loader/generator from
attachment-only to multi-dimension capability files, merging
`attachment` and `temperature` per provider.
- Updated `ModelsDevGateway.fetchProviders()` to collect
temperature-capable model IDs from models.dev and include them when
generating the registries.
- Updated the router (`ModelRouterLanguageModel`) to strip unsupported
sampling parameters before dispatch:
- removes `temperature` and `topP` when the target model doesn’t support
temperature
  - additionally removes `topK` for streaming when unsupported
- Refreshed `anthropic.json` and `openai.json` capability lists to
reflect temperature support from live models.dev.
- Added tests validating that the router strips or preserves these
parameters depending on `modelSupportsTemperature()`.

## Notes / known limitations
- Capability matching won’t work for custom proxy aliases (capabilities
are keyed to real model IDs).
- Support is treated as a simple on/off capability and can’t express
conditional “only reject in certain scenarios” behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-07-01 12:02:12 +05:30
devin-ai-integration[bot]
95857bcd66
fix(core): prevent partial gateway sync from corrupting provider registry (#18545)
## Description

Fixes a regression where `syncGateways()` writes partial provider data
to disk when a gateway fails, corrupting the registry. When models.dev
is down but Netlify succeeds, only Netlify providers are written to the
global cache and `dist/`, overwriting the complete bundled registry. On
next load, `PROVIDER_REGISTRY` returns only Netlify providers →
`ModelsDevGateway.getApiKey()` throws `"Could not find config for
provider openai with model id openai/gpt-5-mini"`.

**Root cause**: `fetchProvidersFromGateways` silently skips failed
gateways after 3 retries and returns only successful results.
`syncGateways` then overwrites `~/.cache/mastra/provider-registry.json`
and `dist/provider-registry.json` with these partial results.

**Fix**:
```
// registry-generator.ts
fetchProvidersFromGateways() now returns failedGateways: string[]

// provider-registry.ts  
syncGateways() skips all writes when failedGateways.length > 0,
preserving the existing complete registry

// generate-providers.ts
Generation script also aborts on gateway failures with process.exit(1)
```

## Related issue(s)

Reported in Slack by Alex Booker: brand-new `create-mastra` project
shows only Netlify in provider dropdown and errors with "Could not find
config for provider openai".

Introduced by commit 0504bf5e8c (PR #18382) which added `defaults.ts`
with module-load-time `PROVIDER_REGISTRY` access, but the underlying
issue is `syncGateways` writing partial results.

## Type of change

- [x] Bug fix (non-breaking change that fixes an issue)

## Checklist

- [x] I have linked the related issue(s) in the description above
- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works
- [ ] I have addressed all Coderabbit comments on this PR

Link to Devin session:
https://app.devin.ai/sessions/4103d3871cd1413e9b82133f81f048ce

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: tyler <tylerdbarnes@gmail.com>
2026-06-27 12:16:43 +02:00
devin-ai-integration[bot]
c27c4b9f13
feat: generate provider capabilities file and add auto mode for OM observer attachments (#16922)
## Description

Generates per-provider capability files alongside the existing model
router registry, and adds an `'auto'` mode for the OM
`observeAttachments` setting that uses this data to automatically decide
whether to forward attachments to the observer model.

### What changed

**Provider capabilities generation** (`packages/core`):
- `ModelsDevGateway.fetchProviders()` collects per-model attachment
support from models.dev API
- Generates per-provider files under `capabilities/` directory (e.g.
`capabilities/openai.json`, `capabilities/deepseek.json`):
  ```json
  {
    "attachment": ["gpt-4o", "gpt-4o-mini", "o3", ...]
  }
  ```
Only providers with attachment-capable models get a file. Models not
listed = no attachment support.
- Runtime reads only the single provider file needed for the lookup
(lazy-loaded, cached in memory)
- New exported function: `modelSupportsAttachments(modelRouterId)` from
`@mastra/core/llm`
- `tsup.config.ts` copies the `capabilities/` directory to `dist/`
during build

**Auto mode for observer attachments** (`packages/memory`):
- `observeAttachments` type expanded to include `'auto'` alongside
existing `boolean | string[]`
- Default remains `true` in the memory package (backward compatible)
- `ObserverRunner.resolveAttachmentFilter()` resolves `'auto'` at call
time by checking the capabilities registry for the observer model
- Falls back to `true` (forward attachments) when no capabilities data
exists for the model

**Mastracode UI** (`mastracode/`):
- Schema defaults to `'auto'` in mastracode
- `/om` settings now shows a 3-way Auto/On/Off selector instead of a
binary toggle
- Settings persistence and state wiring updated for the new type

### How it works

When `observeAttachments` is `'auto'` (the mastracode default):
1. Before building observer messages, the `ObserverRunner` looks up the
observer model in `capabilities/<provider>.json`
2. If the model is listed in the provider's attachment array →
attachments are forwarded
3. If the provider file exists but model isn't listed → attachments are
dropped (placeholders remain)
4. If no capability file exists for the provider → falls back to
forwarding attachments

This means switching between text-only and multimodal observer models
automatically does the right thing without manual toggles.

## Related issue(s)

Discussed in Slack:
https://kepler-bej6556.slack.com/archives/C0ACHFXNK7T/p1779380320179049

## Type of change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update

## Checklist

- [x] I have linked the related issue(s) in the description above
- [ ] I have made corresponding changes to the documentation (if
applicable)
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [x] I have addressed all Coderabbit comments on this PR

Link to Devin session:
https://app.devin.ai/sessions/38dfa4e802804bd29b28df41212261cd
Requested by: @TylerBarnes

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5

This PR teaches the system which AI models can receive attachments
(images/files) by generating per-provider capability lists and adds an
"auto" mode so the runtime can automatically decide whether to forward
attachments to an observer model.

## Core Changes

- Provider capability files
- Generates per-provider JSON files under
packages/core/src/llm/model/capabilities/*.json with an "attachment"
array of model IDs that support attachments.
- ModelsDevGateway collects attachment-capable models in
fetchProviders() and exposes them via getAttachmentCapabilities().
- registry-generator aggregates attachmentCapabilities from gateways and
writeRegistryFiles emits per-provider capability files (also copied into
dist/capabilities/ by tsup).
- provider-registry exposes AttachmentCapabilities and adds
modelSupportsAttachments(modelRouterId: string): boolean | undefined
which lazily loads and caches provider JSON files (prefers dist/ then
src/ then CWD), clears caches on dynamic reload, and uses safe atomic
writes when syncing.

- Auto mode for observeAttachments
- Widened observeAttachments type across memory/types, schema, and
settings: 'auto' | boolean | string[] (package default remains true in
memory package until config/schema change).
- ObserverRunner.resolveAttachmentFilter() computes per-call
model-specific attachment behavior when observeAttachments === 'auto',
using modelSupportsAttachments(routerId) and these rules:
    - provider file exists and model listed → forward attachments;
- provider file exists but model not listed → drop attachments
(placeholders retained);
- no provider file / lookup undefined → fallback to forward attachments
(safe default).
- extractModelRouterId() added to correctly resolve function-based
models (using requestContext when needed) before capability checks.
- Memory cacheKey now includes the raw observeAttachments value
(including 'auto') so cached Memory respects the configured mode.

- UI & configuration
- Mastracode onboarding/schema default set to 'auto'; TUI OM settings
replaced boolean toggle with a 3-way Auto/On/Off selector; persistence
and callbacks updated to accept 'auto' | boolean.
- GlobalSettings updated: models.omObserveAttachments: 'auto' | boolean
| null (null inherits default 'auto').

## Tests, safety & build
- Added unit tests covering modelSupportsAttachments fallback behavior
and observer auto-mode behavior (including function-based model
resolution) that assert attachments are forwarded or dropped per
capability lookups.
- syncGlobalCacheToLocal / registry sync now copies valid capability
JSON files into dist/capabilities/, atomically writes files, skips
corrupted JSON, and copies to src when writeToSrc is enabled.
- tsup build hook copies src/llm/model/capabilities/*.json into
dist/capabilities/.

## Public API / Type changes
- fetchProvidersFromGateways() now returns { providers, models,
attachmentCapabilities }.
- writeRegistryFiles(..., attachmentCapabilities?) accepts
attachmentCapabilities to emit capability files.
- New export: modelSupportsAttachments(modelRouterId: string): boolean |
undefined from `@mastra/core/llm`.
- New/expanded type: AttachmentCapabilities exported/re-exported.
- ObservationConfig / ResolvedObservationConfig types updated to accept
'auto' | boolean | string[].
- Mastracode UI and TUI callback signatures updated to accept 'auto' |
boolean where applicable.

## Commit highlights
- Handle function-based models by adding extractModelRouterId() before
capability checks.
- Regression tests added to ensure auto mode drops attachments for
text-only resolved models and forwards for multimodal resolved models.
- Changeset added for `@mastra/core` and `@mastra/memory`.

## Behavior summary when observeAttachments === 'auto'
1. Resolve observer model router id (strings, model objects, or
function-based resolvers using requestContext).
2. Lookup capabilities/<provider>.json:
   - If model listed → forward attachments.
- If provider exists but model not listed → drop attachments
(placeholders remain).
- If no provider file / lookup undefined → forward attachments
(fallback).

<!-- review_stack_entry_start -->

[![Review Change
Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/mastra-ai/mastra/pull/16922?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)

<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: tyler <tylerdbarnes@gmail.com>
Co-authored-by: Mastra Code (openai/gpt-5.5) <noreply@mastra.ai>
2026-05-21 22:47:47 -07:00
Lennart
4136ed2039
chore(docs): Add Mastra to Gateways (#15784) 2026-04-27 10:19:32 +02:00
Anurag Ojha
62919a6ee0
feat(core): per-entry modelSettings, providerOptions, headers on fallbacks (#15429)
## Description

Each entry in an agent's `model: ModelWithRetries[]` fallback array can
now carry its own `modelSettings`, `providerOptions`, and `headers` —
statically or as a function of
`requestContext`. Fully backwards-compatible — every new field is
optional.

```ts
new Agent({
  model: [
    { model: 'google/gemini-2.5-flash', modelSettings: { temperature: 0.3 } },
    { model: 'openai/gpt-5-mini',       modelSettings: { temperature: 0.7 } },
  ],
});
```

Precedence (lowest → highest): agent defaultOptions → call-time options
→ per-fallback entry. modelSettings and headers shallow-merge by key;
providerOptions deep-merges per providerkey

## Related Issue(s)

Fixes #15421

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [x] Test update

## Checklist

- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] I have addressed all Coderabbit comments on this PR

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5 (Explain Like I'm 5)
Each backup model in an agent can now have its own settings (like how
creative it is), provider-specific options, and request headers, and
those can be fixed or computed when a request runs so each fallback can
behave differently from the main model.

## Overview
Adds optional per-entry configuration to an agent's fallback chain: each
ModelWithRetries[] entry may include modelSettings, providerOptions, and
headers as static values or functions of requestContext. These per-entry
values are resolved at call time (disabled entries are skipped) and
merged with call-time options and agent defaults using documented
precedence and merge semantics.

## Key Changes

### Type Definitions
- Added exported type: ModelFallbackSettings = Omit<CallSettings,
'abortSignal' | 'maxRetries' | 'headers'>.
- Extended ModelWithRetries with optional:
  - modelSettings?: DynamicArgument<ModelFallbackSettings>
  - providerOptions?: DynamicArgument<ProviderOptions>
  - headers?: DynamicArgument<Record<string, string>>
- ModelManagerModelConfig updated to carry optional modelSettings and
providerOptions through streaming/LLM execution.

### Implementation
- Agent:
- Centralized fallback-entry normalization via private
Agent.toFallbackEntry(...).
- Added resolveFallbackDynamic<T>() to resolve static or function-valued
per-entry fields at runtime.
- prepareModels() resolves per-entry modelSettings, providerOptions, and
headers (skipping disabled entries) and computes merged headers by
combining router-derived headers with resolved user headers when
present.
- Disabled fallback entries are filtered out before dynamic resolution
to avoid unnecessary work and side effects.
- Provider options:
- Added exported mergeProviderOptions(...) and an internal deepMerge to
recursively merge providerOptions per provider key (override leaves,
replace non-plain values).
- LLM execution:
- llm-execution-step now deep-merges providerOptions (overlaying
step/provider options with modelConfig) and composes modelSettings by
overlaying modelConfig.modelSettings onto step settings while enforcing
modelConfig.maxRetries.

### Precedence & Merge Semantics
Precedence (lowest → highest): agent defaultOptions → call-time options
→ per-fallback entry, with an important nuance:
- For modelSettings and providerOptions: per-fallback entry wins over
call-time options (per-entry overrides).
- For headers: call-time headers win over per-fallback headers to
preserve existing runtime tracing/auth/tenancy behavior.
Merging:
- modelSettings: shallow-merged by key (per-entry keys override).
- providerOptions: deep-merged per provider key (recursive merge of
plain objects; non-plain values are replaced).
- headers: resolved/merged according to the header precedence above.
All three fields may be DynamicArgument functions that receive
requestContext and are resolved at call time (unless the entry is
disabled).

### Tests
- New tests
(packages/core/src/agent/__tests__/per-model-fallback-settings.test.ts)
cover:
  - Per-entry modelSettings application and usage during failover.
- Shallow merging of modelSettings while preserving unrelated call-time
fields.
- Dynamic (function-form) resolution of modelSettings and headers with
RequestContext.
- Deep-merge behavior for providerOptions and prevention of
cross-contamination between fallback entries.
  - Headers forwarding and call-time header precedence.

### Documentation & Docs Generation
- New "Per-model settings" subsection under Model fallbacks in docs and
docs generator with examples and explanation of merge/precedence
behavior and dynamic function support.
- Added changeset describing the feature.

## Backwards Compatibility
All additions are optional; existing behavior remains unchanged when new
fields are omitted.

## Other Notes
- Implementation adjusted to skip resolving DynamicArgument values for
disabled fallback entries (disabled entries are filtered out before the
resolution loop).
- Fixes: #15421 — enables per-fallback/per-provider configuration
(including dynamic resolution) for fallback models.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-04-16 12:09:53 -07:00
Lennart
4ba3bb1e46
chore: Update Mastra Cloud references (#15297) 2026-04-13 16:23:40 +02:00
Lennart
2d713d0e56
feat(docs): Studio category (#14669) 2026-03-31 15:54:38 +02:00
Ehindero Israel
f58d1a7a45
fix(core): use API token for Cloudflare Workers AI (#14687)
Co-authored-by: Ward Peeters <ward@coding-tech.com>
2026-03-30 12:13:51 +01:00
Eric Pinzur
d3930eac51
drop support for zod/v3 in several core packages (#14464)
Co-authored-by: wardpeet <ward@coding-tech.com>
Co-authored-by: Mastra Code (openai/gpt-5.4) <noreply@mastra.ai>
2026-03-23 22:02:41 +01:00
Ehindero Israel
803710dbd3
docs(models): clarify gateway-style custom endpoint ids (#14601) 2026-03-23 16:51:20 +01:00
Ehindero Israel
41aee84561
docs(models): clarify custom endpoint model config (#14594) 2026-03-23 15:30:34 +01:00
Lennart
c3dc91b99d
chore(docs): Update model router values to newer models (#14336) 2026-03-17 09:16:21 +01:00
Lennart
c8f4e36a76
chore(docs): Begin sentence case enforcement (#14083) 2026-03-11 10:09:15 +01:00
Ward Peeters
17c4145166
feat: Add Standard Schema support with Zod v3/v4 compatibility (#12238)
Co-authored-by: Mastra Code <noreply@mastra.ai>
Co-authored-by: Ehindero Israel <iehindero419@stu.ui.edu.ng>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>
2026-03-09 17:51:41 +01:00
Roamin
2015cf9216
feat(core): add Vercel AI Gateway support to model router (#13149)
Adds support for `model: 'vercel/google/gemini-3-flash'` in agents by
using the official AI SDK `createGateway` provider from
`@ai-sdk/gateway`.

Previously this string would fall through to `ModelsDevGateway` as a
flat provider, which didn't work. Now there's a `case 'vercel':` in
`ModelsDevGateway.resolveLanguageModel` that routes through
`createGateway`, same pattern as OpenRouter.

```ts
const agent = new Agent({
  name: "my-agent",
  instructions: "You are a helpful assistant",
  model: "vercel/google/gemini-3-flash",
});
```

Also fixes the doc generator gateway page template to use the actual
`apiKeyEnvVar` from provider config instead of deriving it from the
gateway name (e.g. `AI_GATEWAY_API_KEY` instead of `VERCEL_API_KEY`).

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added support for Vercel AI Gateway integration in the model router
for supported models with agents.

* **Documentation**
* Improved generated docs to show gateway/provider API key environment
variables dynamically for clearer setup instructions.

* **Chores**
  * Published a minor version bump for the shiny-files-sort package.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-02-17 13:59:14 -05:00
Lennart
45de974cf5
chore(docs): Update Netlify deployment guide (#12769)
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
2026-02-10 11:28:43 +01:00
Anurag Ojha
dff54a60b9
chore(docs): Filter out deprecated models from generation (#12432)
Co-authored-by: Lennart <lekoarts@gmail.com>
2026-01-29 11:39:45 +01:00
Lennart
dd62789aff
chore(docs): Add docs on local model usage (#12316) 2026-01-28 09:25:33 +01:00
Lennart
addbdf0397
chore(docs): Add & use npm2yarn (#12197) 2026-01-22 15:38:34 +01:00
Lennart
5f7b9b2078
feat(docs): Stable v1 (#12002) 2026-01-20 17:22:17 +01:00
Lennart
7f0c716110
chore(docs): Cleanup codeblock annotations (#11221) 2025-12-17 12:28:04 +01:00
P
62ffd3c5df
paul/grwth-1265-refactor-server-db (#11120)
## Description

- docs: refactor Server & DB

## Related Issue(s)

<!-- Link to the issue(s) this PR addresses, using hashtag notation:
#123 -->

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update

## Checklist

- [ ] I have made corresponding changes to the documentation (if
applicable)
- [ ] I have added tests that prove my fix is effective or that my
feature works


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Updated many internal doc links to new server and storage paths for
consistency.
* Reorganized sidebar/navigation: separated Server, Auth, and Storage
sections and added new entries.
* Normalized page titles and headings across memory/storage and server
docs.
* Added redirects to preserve legacy links and ensure smooth navigation
continuity.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2025-12-12 16:07:30 +00:00
Roamin
31139b801e
docs(openai): add zero data retention guidance for OpenAI API usage (#10945)
## Description

Introduced a new section in the OpenAI provider documentation detailing
the requirement to set `store: false` for organizations with zero data
retention enabled. Provided examples for both per-request and global
configuration to ensure users can implement this setting correctly in
their agents.

## Related Issue(s)

<!-- Link to the issue(s) this PR addresses, using hashtag notation:
#123 -->

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update

## Checklist

- [ ] I have made corresponding changes to the documentation (if
applicable)
- [ ] I have added tests that prove my fix is effective or that my
feature works


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Enhanced provider option descriptions in generated documentation to
include provider-specific notes and custom details, offering more
comprehensive information for each option.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2025-12-05 20:21:40 -06:00
Daniel Lew
8846867ffa
feat(core): add @ai-sdk/deepseek provider to model router (#10822)
Adds native @ai-sdk/deepseek provider support instead of using the
OpenAI-compatible fallback.

```typescript
const agent = new Agent({
  model: "deepseek/deepseek-reasoner",
});

// With provider options for reasoning
const response = await agent.generate("Solve this problem", {
  providerOptions: {
    deepseek: {
      thinking: { type: "enabled" }
    }
  }
});
```

Also updates the doc generation scripts so DeepSeek provider options
show up in the generated docs.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* Native DeepSeek provider support is now available, enabling seamless
integration with DeepSeek models including deepseek-reasoner.
* Added support for DeepSeek provider options, including a "thinking"
option for enhanced reasoning capabilities.

* **Documentation**
* Updated DeepSeek documentation with provider options guidance and
implementation examples.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2025-12-03 14:02:58 -06:00
Lennart
604a79fecf
fix(core): Type error in defaultOptions.structuredOutput (#10710)
## Description

Fix TypeScript error when defining `structuredOutput.schema` in agent
`defaultOptions`. This happened because `AgentConfig.defaultOptions`
used `AgentExecutionOptions` without a generic parameter, causing the
`OUTPUT` type to default to `undefined`. Changed `defaultOptions` to use
`AgentExecutionOptions<OutputSchema>` instead of
`AgentExecutionOptions`, allowing the `structuredOutput.schema` property
to accept any valid schema type (Zod schemas, JSONSchema7, etc.).

## Related Issue(s)

Fixes #9657

## Type of Change

- [X] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update

## Checklist

- [ ] I have made corresponding changes to the documentation (if
applicable)
- [X] I have added tests that prove my fix is effective or that my
feature works


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

## Release Notes

* **Bug Fixes**
* Fixed TypeScript error preventing the use of Zod schemas in agent
default options. Users can now specify Zod schemas in
`defaultOptions.structuredOutput.schema` without type errors.

* **Tests**
* Added type-level validation tests for agent configuration to ensure
schema compatibility and correct type inference.

<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: naaa760 <neh6a683@gmail.com>
2025-12-01 09:02:57 -06:00
Ward Peeters
0dd734d829
feat(config): enforce node: prefix for Node.js built-in imports (#10625) 2025-11-28 14:05:35 +01:00
RichardLoRicco
21a15de369
feat: add Azure OpenAI gateway with deployment discovery (#9990)
Co-authored-by: Harold Camacho <harold.camacho.diaz@gmail.com>
Co-authored-by: Daniel Lew <51924260+DanielSLew@users.noreply.github.com>
2025-11-25 08:42:38 -05:00
Daniel Lew
43ca8f2c73
fix(core): resolve netlify gateway double-prefix in model docs generation (#10392)
Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>
2025-11-24 15:40:34 -05:00
Paul Scanlon
ae69f0a3b2
paul/grwth-1080-fix-model-build-errors-1.x (#9920)
## Description

- fix: remove imports from generate model provider template

## Related Issue(s)

<!-- Link to the issue(s) this PR addresses, using hashtag notation:
#123 -->

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update

## Checklist

- [ ] I have made corresponding changes to the documentation (if
applicable)
- [ ] I have added tests that prove my fix is effective or that my
feature works


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Chores**
* Cleaned up documentation structure across multiple AI provider pages.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2025-11-10 15:12:11 +00:00
Paul Scanlon
e511481b49
paul/grwth-1073-fix-broken-links-nov-7th-1.x (#9862)
## Description

- docs: update v1 links in generate-model-docs

## Related Issue(s)

<!-- Link to the issue(s) this PR addresses, using hashtag notation:
#123 -->

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [ ] Test update

## Checklist

- [ ] I have made corresponding changes to the documentation (if
applicable)
- [ ] I have added tests that prove my fix is effective or that my
feature works


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Documentation**
* Fixed a formatting issue in the scores explanation within the
documentation.
* Updated documentation hyperlinks across gateways, providers, and
models sections to reference versioned v1 API paths.
* Updated the documentation generation script to consistently use
v1-prefixed paths for all generated documentation links.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2025-11-07 10:53:39 +00:00