## Summary
- Migrates the agent's internal agentic loop onto the evented workflow
engine. Each LLM call and tool call now runs as a workflow step, sharing
suspend/resume and observability with the rest of the workflow system.
No user-visible behavior change yet — this is the structural
prerequisite for future durability and event-based observability
features.
- Fixes a nested-workflow bug where `resumeLabel` wasn't propagated up
through a parent's suspendedPaths, so resuming a nested workflow by
label silently failed.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
ELI5: This change moves the agent's internal loop to run as a series of
steps in the evented workflow engine so each model call and tool call is
tracked like a tiny workflow. That makes suspend/resume, observability,
and future durability much easier and also fixes a bug that broke
resuming nested workflows by label.
- What it does
- Migrates the agentic loop so each LLM and tool call executes as
evented workflow steps (uses createEventedWorkflow /
createEventedWorkflow factory).
- Agents can run without a user-provided Mastra by creating a
lazily-initialized ephemeral Mastra (InMemoryStore + EventEmitterPubSub)
and starting ephemeral workers on first use.
- Adds a per-run runScope (PrepareStreamRunScope) to thread
non-JSON-safe runtime state (MessageList, processorStates,
convertedTools, loopOptions) across prepare-stream workflow steps
instead of passing those objects through step inputs/outputs.
- Introduces runId-scoped internal workflow registration/unregistration
to avoid collisions for concurrent/nested runs.
- Bug fixes / behavioral corrections
- Fixes nested-workflow resume-by-label: resumeLabel is propagated
through parent suspendedPaths and nested suspend metadata so resuming a
nested workflow by label works reliably.
- Preserves and aggregates suspendPayloads (not just resumeLabels)
across suspended foreach iterations and when storage persistence is
skipped/absent.
- Ensures persisted snapshots are retained for pending/paused/suspended
states (not only suspended).
- Tightens internal workflow lookup to prefer runId-scoped internal
workflow instances, preventing wrong closure/registration resolution in
nested/concurrent cases.
- Implementation details / notable API surface changes
- New helper: createEventedWorkflow(...) exported from workflows
entrypoint (throws if evented factory not loaded).
- Mastra changes:
- Defaults to InMemoryStore when storage not provided (with warning) and
augments the store.
- Internal workflow registry supports runId-scoped keys; added
__unregisterInternalWorkflow and updated __registerInternalWorkflow /
__hasInternalWorkflow / __getInternalWorkflow signatures.
- Evented processor and execution engine:
- Nested workflow resolution now passes runId to getNestedWorkflow and
resolveWorkflow.
- Workflow event processor rebuilt resumeLabels and suspend payload
propagation; adjusted foreach aggregation and merge behavior when
storage updates are absent.
- In-memory workflow storage replaced JSON-serialize deep-copy with a
cycle-safe deep clone preserving Dates, Errors, Maps/Sets, prototypes,
typed arrays, etc.
- Tests / tooling
- Added suspend/resume test to validate resuming a suspended nested
workflow step by label and updated many tests to run against an evented
Mastra (InMemoryStore + EventEmitterPubSub) with worker lifecycle
management helpers (createTestMastra, start/stop workers).
- Multiple test updates to use real InMemoryStore + evented pubsub
instead of mocked storage or missing worker lifecycles.
- Minor / UX
- Updated background-task generated system prompt to clarify _background
behavior and placeholder result guidance.
- stream/loop runtime: distinguishes "pre-run" queued signals from
normal "pending" signals and exposes drainPendingSignals(runId, scope?)
with scope 'pending'|'pre-run'; stream lifecycle registers/unregisters
run-scoped internal workflows to prevent leakage on suspend.
- Risk / review notes
- Structural and high-impact refactor touching core agent loop, workflow
engine integration, storage cloning, and Mastra internals—review effort:
high in multiple areas (agent, workflows, mastra, storage, evented
processor).
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/mastra-ai/mastra/pull/16796?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: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Mastra Code (anthropic/claude-opus-4-6) <noreply@mastra.ai>
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: Abhi Aiyer <abhi@mastra.ai>
Co-authored-by: Abhi Aiyer <abhiaiyer91@gmail.com>
## 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>
## Description
Adds a new `@mastra/brightdata` integration package at
`integrations/brightdata/` that exposes two Mastra agent tools backed by
the official [`@brightdata/sdk`](https://github.com/brightdata/sdk-js):
- **`web-search`** - Google SERP via Bright Data's SERP API. Returns
parsed organic results (`link`, `title`, `description`) plus
`currentPage`. Supports `country` (2-letter code) and `start` (offset)
for pagination.
- **`web-fetch`** - Fetches a URL and returns its content as markdown
via Bright Data's Web Unlocker, bypassing bot detection and CAPTCHAs.
Public exports:
- `getBrightDataClient`, `BrightDataClientOptions`, `BrightDataClient`
- `createBrightDataSearchTool`, `createBrightDataFetchTool`
- `createBrightDataTools` bundle returning `{ webSearch, webFetch }`
29 vitest unit tests (mocking `@brightdata/sdk`) cover env/options
resolution, request mapping, response projection, defensive parsing of
organic results, error propagation, JSON-string SERP responses, and
per-execute client closing.
Includes a `minor` changeset under `.changeset/sour-poems-camp.md`.
## Related Issue(s)
<!-- Link to the issue(s) this PR addresses, using hashtag notation:
Fixes#123 -->
## 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 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
This PR adds tools so Mastra agents can search Google results and fetch
full webpage content using Bright Data, letting an agent look things up
and read pages even when sites block bots.
Overview
Adds a new @mastra/brightdata package at integrations/brightdata/ that
wraps the official @brightdata/sdk and provides a client helper plus two
Mastra tools backed by Bright Data’s SERP API and Web Unlocker.
Core Functionality
- brightdata-search: Queries Google SERP via Bright Data; accepts {
query, country? (2-letter), start? (offset) } and returns parsed organic
results (link, title, description) and currentPage.
- brightdata-fetch: Fetches a URL via Bright Data Web Unlocker and
returns { url, content } where content is Markdown.
- createBrightDataTools: convenience bundle returning { webSearch,
webFetch } (tools have IDs brightdata-search and brightdata-fetch).
Public exports
- getBrightDataClient, BrightDataClientOptions, BrightDataClient
- createBrightDataSearchTool, createBrightDataFetchTool
- createBrightDataTools
Implementation Details
- getBrightDataClient resolves apiKey from config.apiKey or
BRIGHTDATA_API_TOKEN (config.apiKey wins) and throws if missing.
- closeClient is best-effort: calls client.close() if present, awaits if
needed, and swallows errors so cleanup cannot mask primary tool errors
(regression test added).
- Search tool: handles SDK responses that are objects or JSON strings;
normalizes/trims organic results, filters out entries missing required
fields, defaults organic → [] and currentPage → 1 when missing/invalid.
- Fetch tool: calls scrapeUrl(url, { dataFormat: 'markdown' }) and
returns { url, content }; always closes the client in a finally block.
- Zod schemas validate inputs/outputs.
Project & Docs
- New package manifest, tsup build config, TypeScript tsconfig files,
ESLint, Turbo, and Vitest configs added for integrations/brightdata.
- README and reference docs
(docs/src/content/en/reference/tools/brightdata.mdx) added and wired
into the docs sidebar.
- .changeset/sour-poems-camp.md and a CHANGELOG header added.
Tests
29 Vitest unit tests (mocking @brightdata/sdk) covering env/options
resolution, request mapping, defensive parsing (including JSON-string
SERP responses), error propagation, and that the client is closed on
both success and failure.
Notable changes / reviewer notes
- zod peer dependency relaxed to ">=3.0.0".
- Removed redundant type cast in fetch implementation and removed
explicit @brightdata/sdk install mention from README (treat as
transitive dependency).
- closeClient wrapped in try/catch to avoid cleanup errors masking tool
errors; regression test added.
- Tests kept colocated under src/__tests__/ per existing integrations;
author offered a follow-up PR if maintainers want test relocation.
[](https://app.coderabbit.ai/change-stack/mastra-ai/mastra/pull/16392)
<!-- 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>