## Summary
This PR migrates the AgentController message surface from the bespoke
flattened `AgentControllerMessage` shape to the canonical persisted
`MastraDBMessage` shape used elsewhere in Mastra.
- Replaces AgentController message events and session message APIs with
DB-native `MastraDBMessage` values.
- Emits signals such as user messages, reminders, notifications, and
reactive signals as standalone `role: 'signal'` messages instead of
flattened assistant content.
- Updates core, server, playground, client/test, and mastracode
consumers to read `content.parts` and terminal status from
`content.metadata`.
- Keeps streamed assistant message folding DB-native, including text,
reasoning, tool invocations, and terminal status.
- Consolidates release notes into a single changeset for the migration.
## Test plan
- `pnpm --filter ./packages/core check`
- `pnpm --filter mastracode exec vitest run --reporter=verbose
src/tui/components/__tests__/assistant-message.test.ts
src/tui/__tests__/mastra-tui-queueing.test.ts`
- `pnpm --filter ./packages/core exec vitest run
src/agent-controller/signal-messages.test.ts
src/agent-controller/signal-history.test.ts
src/agent-controller/__tests__/run-engine-db-message.test.ts`
Note: local pnpm emitted the existing Node engine warning because this
machine is on Node 22.14.0 while the package wants >=22.19.0, but the
checks above passed.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR makes AgentController messages use the same “save format” (the
database-native shape) as the rest of Mastra. Assistant text/tools still
stream and fold normally, but reminders/notifications/etc. show up as
their own separate `role: "signal"` messages so clients can handle them
cleanly.
## Summary
- Migrated the AgentController message surface (events + session/thread
message APIs) from the bespoke flattened `AgentControllerMessage` shape
to canonical persisted `MastraDBMessage`.
- Updated the message content model to be DB-native:
- `content` is now `format: 2` with ordered `content.parts` (text,
reasoning, tool-invocation, attachments, and signal payloads).
- Terminal/ending state moved into `content.metadata` (e.g.,
`stopReason`, `errorMessage`), including updated `message_end`
expectations and explicit error state for completed tools.
- Changed reminders/notifications/reactive/system items to be emitted as
standalone `role: "signal"` messages (instead of being
embedded/flattened into assistant content), and updated consumers to
render/filter based on `role`.
- Preserved DB-native streamed assistant folding:
- accumulated text + reasoning parts,
- tool invocations folded into a single `tool-invocation` part
(including tool result/error handling),
- terminal finish/error propagation via `content.metadata`.
- Added regression coverage for snapshot immutability during streaming.
- Strengthened stream processing with typed `StreamChunk` handling and
safer runtime extraction in `SessionRunEngine` (including correct
handling of `argsTextDelta` as `unknown`).
- Updated server/API schemas and serialization, plus clients and UI
layers (mastracode ACP mapper, TUI view helpers, web
transcript/composer) to read `content.parts` + terminal status from
`content.metadata` and to treat signal-role messages as first-class.
- Updated SDK/public exports and tests across `@mastra/core`,
`@mastra/client-js`, and mastracode to use `MastraDBMessage`
consistently (including `createdAt` hydration to `Date` in the client
SDK).
- Consolidated the AgentController migration into a single changeset,
and added related patch release notes for nearby fixes (signal handling
in ACP clients; explicit error state for completed tools).
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Mastra Code (anthropic/claude-opus-4-8) <noreply@mastra.ai>
## Description
<!-- Required: Provide a brief description of the changes in this PR.
-->
## Related issue(s)
<!-- Required: Link to the issue(s) this PR addresses, e.g. with: Fixes
#123. PRs without linked issues may be closed. -->
## 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 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
- [ ] I have addressed all Coderabbit comments on this PR
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR upgrades the Turbo monorepo build tool from version 2.9.6 to
2.9.12 and updates all configuration files across the entire codebase to
use the newer schema version that corresponds to this updated tool
version. Think of it like updating a recipe book to the latest version
and making sure all your cookbook references point to the new edition.
## Changes Summary
### Turbo Version Upgrade
- Updated root `package.json` `devDependencies`: `turbo` upgraded from
`^2.9.6` to `^2.9.12`
### Turbo Configuration Schema Updates
Updated the `$schema` field in 73 `turbo.json` configuration files
throughout the repository from the legacy
`https://turbo.build/schema.json` to the newer
`https://v2-9-16.turborepo.dev/schema.json`:
**Auth modules** (9 files): auth0, better-auth, clerk, cloud, firebase,
okta, studio, supabase, workos
**Client SDKs** (3 files): ai-sdk, client-js, react
**Deployers** (2 files): cloud, vercel
**Integrations** (3 files): brightdata, opencode, perplexity, tavily
**Observability** (11 files): arize, braintrust, datadog, laminar,
langfuse, langsmith, mastra, otel-bridge, otel-exporter, posthog, sentry
**Package modules** (19 files): _external-types, _internal-core,
agent-builder, auth, cli, codemod, core, create-mastra, deployer, evals,
fastembed, loggers, mcp, mcp-docs-server, mcp-registry-registry, memory,
playground, rag, schema-compat, server
**Data stores** (21 files): astra, chroma, clickhouse, cloudflare,
cloudflare-d1, convex, couchbase, duckdb, dynamodb, elasticsearch,
lance, libsql, mongodb, mssql, mysql, opensearch, pg, pinecone, qdrant,
redis, s3vectors, spanner, turbopuffer, upstash, vectorize
**Root configuration**: turbo.json
All other configuration content (extends, tasks, inputs/outputs) remains
unchanged across all files.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
This fills in missing package-local lint-staged configs so staged files
in those workspaces get formatted/fixed before CI catches import
ordering.
It also switches the Husky hook to Corepack so the hook can resolve the
repo's pnpm version consistently. On my machine, plain `pnpm` was
failing in the hook env and the fallback made the hook silently skip
lint-staged.
Before:
```sh
pnpm --version || exit 0
pnpm lint-staged --quiet
```
After:
```sh
corepack pnpm@10.29.3 --version || exit 0
corepack pnpm@10.29.3 lint-staged --quiet
```
I checked workspace coverage and verified package-local lint-staged runs
cleanly against the branch diff with:
```sh
corepack pnpm@10.29.3 exec lint-staged --diff HEAD --quiet
```
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5
This PR makes sure every package in the repo automatically formats and
fixes staged files before you commit, and it makes the pre-commit hook
run a specific, consistent pnpm version so those fixes actually run
reliably.
## Changes to Pre-Commit Hook
- Updated .husky/pre-commit to run pnpm via Corepack with an explicit
pin: corepack pnpm@10.29.3 --version || exit 0 and corepack pnpm@10.29.3
lint-staged --quiet (replacing plain pnpm). This ensures the hook
resolves the repository's pnpm version consistently and prevents
lint-staged from being skipped in environments where a global pnpm may
be absent or incompatible.
## Workspace Package lint-staged Configs
- Added package-local lint-staged configuration files
(lint-staged.config.js or .mjs) across ~40+ workspace packages and
subpackages.
- Two consistent patterns applied:
- TypeScript/TSX-focused packages: run eslint --fix --max-warnings=0
then prettier --write on *.{ts,tsx}, and run prettier --write on
*.{js,jsx} and *.{json,md,yml,yaml}.
- Prettier-only packages (test-utils and simpler packages): run prettier
--write for *.{ts,tsx,js,jsx,json,md,yml,yaml}.
- These package-local configs ensure staged files within each workspace
are formatted and lint-fixed (including TS import ordering via eslint
--fix) before commit, reducing CI failures and manual formatting fixes.
## Other Notes
- Author verified workspace coverage and confirmed package-local
lint-staged runs cleanly against the branch diff using: corepack
pnpm@10.29.3 exec lint-staged --diff HEAD --quiet.
- Commit message notes an adjustment to align with pnpm 11 in a
follow-up commit (chore: align lint-staged hook with pnpm 11).
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/mastra-ai/mastra/pull/17220?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: Mastra Code (openai/gpt-5.5) <noreply@mastra.ai>
This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and publish to npm
yourself or [setup this action to publish
automatically](https://github.com/changesets/action#with-publishing). If
you're not ready to do a release yet, that's fine, whenever you add more
changesets to main, this PR will be updated.
⚠️⚠️⚠️⚠️⚠️⚠️
`main` is currently in **pre mode** so this branch has prereleases
rather than normal releases. If you want to exit prereleases, run
`changeset pre exit` on `main`.
⚠️⚠️⚠️⚠️⚠️⚠️
# Releases
## @mastra/browser-viewer@0.1.0-alpha.0
### Minor Changes
- Initial release of @mastra/browser-viewer
([#15415](https://github.com/mastra-ai/mastra/pull/15415))
Playwright-based browser viewer for CLI providers that enables
screencast visualization in Studio. Supports thread-isolated browser
sessions and automatic CDP connection management.
```typescript
import { BrowserViewer } from '@mastra/browser-viewer';
const workspace = new Workspace({
sandbox: new LocalSandbox({ cwd: './workspace' }),
browser: new BrowserViewer({
cli: 'agent-browser',
headless: false,
}),
});
```
### Patch Changes
- Updated dependencies
\[[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349)]:
- @mastra/core@1.27.0-alpha.1
## @mastra/core@1.27.0-alpha.1
### Minor Changes
- Added support for CLI-driven browser automation with screencast
support in `@mastra/core`, including automatic CDP injection for browser
CLIs. ([#15415](https://github.com/mastra-ai/mastra/pull/15415))
Fixed local process spawning so workspace-relative `cwd` values no
longer get duplicated.
### Patch Changes
- Added opt-in temporal-gap markers for observational memory. When
enabled via `observationalMemory.temporalMarkers: true`, the agent
receives a `<system-reminder type="temporal-gap">` before any user
message that arrives more than 10 minutes after the previous one, so it
can anchor responses in real elapsed time. Markers are persisted,
surfaced to the observer, and rendered by the MastraCode TUI on reload.
([#15605](https://github.com/mastra-ai/mastra/pull/15605))
## @mastra/memory@1.17.0-alpha.0
### Minor Changes
- Added opt-in temporal-gap markers for observational memory. When
enabled via `observationalMemory.temporalMarkers: true`, the agent
receives a `<system-reminder type="temporal-gap">` before any user
message that arrives more than 10 minutes after the previous one, so it
can anchor responses in real elapsed time. Markers are persisted,
surfaced to the observer, and rendered by the MastraCode TUI on reload.
([#15605](https://github.com/mastra-ai/mastra/pull/15605))
### Patch Changes
- Fixed observer agent truncation that could cut UTF-16 surrogate pairs
in half when formatting messages, tool results, or observation lines
with emoji or other astral-plane characters. This produced lone
surrogates that strict JSON parsers (including Anthropic's) reject with
errors like `no low surrogate in string`, causing observer runs to fail.
([#15634](https://github.com/mastra-ai/mastra/pull/15634))
- Updated dependencies
\[[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349)]:
- @mastra/core@1.27.0-alpha.1
## @mastra/client-js@1.14.1-alpha.1
### Patch Changes
- Updated dependencies
\[[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349)]:
- @mastra/core@1.27.0-alpha.1
## @mastra/react@0.2.28-alpha.1
### Patch Changes
- Updated dependencies
\[[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349)]:
- @mastra/core@1.27.0-alpha.1
- @mastra/client-js@1.14.1-alpha.1
## @mastra/deployer-cloud@1.27.0-alpha.1
### Patch Changes
- Updated dependencies
\[[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349)]:
- @mastra/core@1.27.0-alpha.1
- @mastra/deployer@1.27.0-alpha.1
## @mastra/deployer-cloudflare@1.1.25-alpha.1
### Patch Changes
- Updated dependencies
\[[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349)]:
- @mastra/core@1.27.0-alpha.1
- @mastra/deployer@1.27.0-alpha.1
## @mastra/deployer-netlify@1.1.1-alpha.1
### Patch Changes
- Updated dependencies
\[[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349)]:
- @mastra/core@1.27.0-alpha.1
- @mastra/deployer@1.27.0-alpha.1
## @mastra/deployer-vercel@1.1.19-alpha.1
### Patch Changes
- Updated dependencies
\[[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349)]:
- @mastra/core@1.27.0-alpha.1
- @mastra/deployer@1.27.0-alpha.1
## @mastra/longmemeval@1.0.30-alpha.1
### Patch Changes
- Updated dependencies
\[[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349),
[`6e9ab07`](6e9ab07b71)]:
- @mastra/core@1.27.0-alpha.1
- @mastra/memory@1.17.0-alpha.0
## @mastra/opencode@0.0.27-alpha.1
### Patch Changes
- Updated dependencies
\[[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349),
[`6e9ab07`](6e9ab07b71)]:
- @mastra/core@1.27.0-alpha.1
- @mastra/memory@1.17.0-alpha.0
## @mastra/tavily@1.0.1-alpha.0
### Patch Changes
- Fixed runtime `ERR_MODULE_NOT_FOUND` for `@tavily/core` by making it a
direct dependency. Consumers no longer need to install `@tavily/core`
manually. ([#15628](https://github.com/mastra-ai/mastra/pull/15628))
- Updated dependencies
\[[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349)]:
- @mastra/core@1.27.0-alpha.1
## mastracode@0.15.1-alpha.1
### Patch Changes
- Added opt-in temporal-gap markers for observational memory. When
enabled via `observationalMemory.temporalMarkers: true`, the agent
receives a `<system-reminder type="temporal-gap">` before any user
message that arrives more than 10 minutes after the previous one, so it
can anchor responses in real elapsed time. Markers are persisted,
surfaced to the observer, and rendered by the MastraCode TUI on reload.
([#15605](https://github.com/mastra-ai/mastra/pull/15605))
- Improved model ID display in the Mastra Code TUI status line.
Fireworks model IDs are now shown in compact form (e.g.
fireworks/kimi-k2.6 instead of the full
fireworks-ai/accounts/fireworks/models/... path). Version separators in
model names are also normalized (e.g. kimi-k2p6 is displayed as
kimi-k2.6). ([#15631](https://github.com/mastra-ai/mastra/pull/15631))
- Updated dependencies
\[[`0a0aa94`](0a0aa94729),
[`96f6fb2`](96f6fb2dc9),
[`01a7d51`](01a7d51349),
[`6e9ab07`](6e9ab07b71)]:
- @mastra/core@1.27.0-alpha.1
- @mastra/tavily@1.0.1-alpha.0
- @mastra/memory@1.17.0-alpha.0
## @mastra/agent-builder@1.0.28-alpha.1
### Patch Changes
- Updated dependencies
\[[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349),
[`6e9ab07`](6e9ab07b71)]:
- @mastra/core@1.27.0-alpha.1
- @mastra/memory@1.17.0-alpha.0
## mastra@1.6.2-alpha.1
### Patch Changes
- Improved server deploy errors: the CLI now shows the platform API
message (for example billing or payment errors) instead of only a
generic status code.
([#15459](https://github.com/mastra-ai/mastra/pull/15459))
- Improved env file handling for `mastra server deploy` and `mastra
studio deploy`. Deploy now selects a single env file instead of silently
merging multiple files. When multiple `.env` files exist, you are
prompted to choose one. Added `--env-file` to specify the file directly
(e.g. `--env-file .env.staging`), which is required in non-interactive
mode when multiple env files are present.
([#15641](https://github.com/mastra-ai/mastra/pull/15641))
- Updated dependencies
\[[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349)]:
- @mastra/core@1.27.0-alpha.1
- @mastra/deployer@1.27.0-alpha.1
## @mastra/deployer@1.27.0-alpha.1
### Patch Changes
- Updated dependencies
\[[`2a87046`](2a87046c18),
[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349),
[`0a0aa94`](0a0aa94729)]:
- @mastra/server@1.27.0-alpha.1
- @mastra/core@1.27.0-alpha.1
## @mastra/editor@0.7.18-alpha.0
### Patch Changes
- Updated dependencies
\[[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349),
[`6e9ab07`](6e9ab07b71)]:
- @mastra/core@1.27.0-alpha.1
- @mastra/memory@1.17.0-alpha.0
## @mastra/mcp-docs-server@1.1.27-alpha.2
### Patch Changes
- Updated dependencies
\[[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349)]:
- @mastra/core@1.27.0-alpha.1
## @mastra/playground-ui@23.0.1-alpha.1
### Patch Changes
- Updated dependencies
\[[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349)]:
- @mastra/core@1.27.0-alpha.1
- @mastra/client-js@1.14.1-alpha.1
- @mastra/react@0.2.28-alpha.1
## @mastra/server@1.27.0-alpha.1
### Patch Changes
- Forward `requestContext` from the `/approve-tool-call`,
`/decline-tool-call`, `/approve-tool-call-generate` and
`/decline-tool-call-generate` REST handlers to
`agent.approveToolCall(...)` / `declineToolCall(...)` /
`approveToolCallGenerate(...)` / `declineToolCallGenerate(...)`.
([#15620](https://github.com/mastra-ai/mastra/pull/15620))
Previously `requestContext` was destructured from the handler arguments
but never passed through. On resume, `dynamicInstructions` ran with
`requestContext: undefined`, so any value placed on the per-request
`RequestContext` by upstream middleware (or by `body.requestContext`
auto-merge) was lost for the rest of the turn. Agents whose prompt
assembly depends on request-scoped data (e.g. read-only state from the
frontend) produced blank or placeholder responses after the user
approved a HITL tool call. Other agent entry points (`stream`,
`generate`) already forwarded `requestContext` correctly; this brings
the approval routes in line.
- Fixed screencast panel staying "Live" after browser closes due to an
error. The `ViewerRegistry` now broadcasts `browser_closed` status when
a screencast stream emits an error, not just when it stops cleanly.
([#15415](https://github.com/mastra-ai/mastra/pull/15415))
- Updated dependencies
\[[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349)]:
- @mastra/core@1.27.0-alpha.1
## @mastra/express@1.3.11-alpha.1
### Patch Changes
- Updated dependencies
\[[`2a87046`](2a87046c18),
[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349),
[`0a0aa94`](0a0aa94729)]:
- @mastra/server@1.27.0-alpha.1
- @mastra/core@1.27.0-alpha.1
## @mastra/fastify@1.3.11-alpha.1
### Patch Changes
- Fix custom route handlers on the Fastify adapter silently overwriting
request-body fields named `tools` (e.g. `POST /stored/agents`, `POST
/stored/workspaces`). The adapter now exposes registered tools as
`registeredTools` in handler params, matching the Express and Hono
adapters and the `@mastra/server` handler contract.
([#15635](https://github.com/mastra-ai/mastra/pull/15635))
- Updated dependencies
\[[`2a87046`](2a87046c18),
[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349),
[`0a0aa94`](0a0aa94729)]:
- @mastra/server@1.27.0-alpha.1
- @mastra/core@1.27.0-alpha.1
## @mastra/hono@1.4.6-alpha.1
### Patch Changes
- Updated dependencies
\[[`2a87046`](2a87046c18),
[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349),
[`0a0aa94`](0a0aa94729)]:
- @mastra/server@1.27.0-alpha.1
- @mastra/core@1.27.0-alpha.1
## @mastra/koa@1.4.11-alpha.1
### Patch Changes
- Updated dependencies
\[[`2a87046`](2a87046c18),
[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349),
[`0a0aa94`](0a0aa94729)]:
- @mastra/server@1.27.0-alpha.1
- @mastra/core@1.27.0-alpha.1
## @mastra/clickhouse@1.5.1-alpha.1
### Patch Changes
- Improved ClickHouse v-next observability initialization errors to
include the underlying ClickHouse message in the standard error text.
This makes init failures actionable in loggers that only print
`error.message`.
([#15588](https://github.com/mastra-ai/mastra/pull/15588))
- Updated dependencies
\[[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349)]:
- @mastra/core@1.27.0-alpha.1
## create-mastra@1.6.2-alpha.1
## @internal/playground@1.6.2-alpha.1
### Patch Changes
- Updated dependencies
\[[`0a0aa94`](0a0aa94729),
[`01a7d51`](01a7d51349)]:
- @mastra/core@1.27.0-alpha.1
- @mastra/client-js@1.14.1-alpha.1
- @mastra/ai-sdk@1.4.1
- @mastra/react@0.2.28-alpha.1
- @mastra/playground-ui@23.0.1-alpha.1
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
## Description
- Add `@mastra/tavily` - a new integration package that wraps
`@tavily/core` as first-class Mastra tools (search, extract, crawl,
map).
- Migrate `mastracode` from direct `@tavily/core` usage to the new
package.
- Add `Tavily tools` to the "Tools & MCP" section in `docs/reference`
The integration exposes factory functions (`createTavilySearchTool`,
`createTavilyExtractTool`, `createTavilyCrawlTool`,
`createTavilyMapTool`) that return Mastra `createTool`-compatible tools
with full Zod input/output schemas. A convenience `createTavilyTools()`
returns all four with shared config. Tools lazily instantiate the Tavily
client and default `clientSource` to `'mastra'` for attribution.
## 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
- [x] Code refactoring
- [ ] Performance improvement
- [ ] 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
This PR adds a new package, @mastra/tavily, that makes Tavily’s web
search, extraction, crawling, and site-mapping features available as
ready-to-use Mastra tools. It also updates existing code to use these
tools and adds docs, tests, packaging, and a changeset for the
integration.
## Overview
Introduces the @mastra/tavily integration package that wraps
@tavily/core into first-class Mastra tools (search, extract, crawl, map)
with Zod input/output schemas, lazy client initialization, and API-key
handling (config apiKey takes precedence over TAVILY_API_KEY). The PR
migrates mastracode to use the new package, adds docs and a sidebar
entry, includes tests for client and all tools, and adds
package/build/test configs and a changeset. Review feedback (remove
example, add changeset) was addressed.
## Key Changes
- New package: integrations/tavily/ (exports @mastra/tavily)
- Exports: createTavilySearchTool, createTavilyExtractTool,
createTavilyCrawlTool, createTavilyMapTool, createTavilyTools,
getTavilyClient, and types (TavilyClientOptions, TavilyClient)
- Client: getTavilyClient(config?) resolves apiKey (config >
TAVILY_API_KEY), defaults clientSource to 'mastra', throws if no key
- Tools: each tool lazily caches a Tavily client in a closure, defines
Zod input/output schemas, normalizes responses (images, results,
responseTime, etc.), and conforms to Mastra createTool
- Convenience: createTavilyTools() returns all four tools with shared
config
- Tests (Vitest) added:
- client.test.ts: apiKey resolution, clientSource default/override,
error on missing key
- search.test.ts, extract.test.ts, crawl.test.ts, map.test.ts: param
mapping, response normalization, error propagation
- tools.test.ts: createTavilyTools returns all tools with expected IDs
and schemas
- Documentation:
- docs/reference/tools/tavily.mdx: reference page documenting tools,
options, schemas, example usage, and environment variable
- docs/reference/sidebars.js: adds "Tavily Tools" sidebar entry
- integrations/tavily/README.md and CHANGELOG.md
- Packaging & config:
- integrations/tavily/package.json, tsup.config.ts,
tsconfig.json/tsconfig.build.json, vitest.config.ts, turbo.json,
eslint.config.js added
- .changeset/legal-bats-hope.md added to version the new package and
mastracode change
- Code migration:
- mastracode: replaced direct @tavily/core usage with
createTavilySearchTool/createTavilyExtractTool from @mastra/tavily;
removed local client logic; delegated validation and execution to the
new tools; preserved post-processing (relevance filtering, markdown
formatting, truncation)
- mastracode/package.json now depends on workspace @mastra/tavily
instead of @tavily/core
## Technical highlights
- Lazy, cached Tavily client instantiation per tool
- API key precedence: config.apiKey > TAVILY_API_KEY; explicit error
when absent
- Full Zod schemas for inputs/outputs and consistent response
normalization across tools
- Tools export Mastra-compatible metadata and execute handlers
- Comprehensive unit tests and documentation included
## Impact
Provides a maintained, standardized integration for Tavily within
Mastra, simplifying agent wiring, reducing duplicated client/setup code,
and preparing the integration for publication in the monorepo. Review
comments were addressed and a changeset was included.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>
Co-authored-by: Mastra Code (anthropic/claude-opus-4-7) <noreply@mastra.ai>