@mastra/client-js 1.40.1-alpha.7 → 1.41.0-alpha.11

package/CHANGELOG.md

@@ -1,5 +1,86 @@
 # @mastra/client-js
 
+## 1.41.0-alpha.11
+
+### Minor Changes
+
+- Added a `durable` option to stored agents so agents created through the Agents API can run with durable execution — no code deployment required. ([#21715](https://github.com/mastra-ai/mastra/pull/21715))
+
+  ```typescript
+  await mastraClient.createStoredAgent({
+    id: 'helper',
+    name: 'Helper',
+    instructions: 'You are a helpful assistant.',
+    model: { provider: 'openai', name: 'gpt-5' },
+    durable: true,
+  });
+  ```
+
+  Pass `true` for defaults, or `{ maxSteps, cleanupTimeoutMs }` to tune the durable loop. Cache and pubsub are inherited from the server's Mastra instance, so configure distributed backends there for durability across replicas. Automatic recovery is still configured in code via `recovery.durableAgents`.
+
+- Fixed the agent controller event types, which described payloads the server never sends. ([#21739](https://github.com/mastra-ai/mastra/pull/21739))
+
+  `KnownAgentControllerEvent` was written by hand and had drifted from the controller. Narrowing on `om_activation` gave you an `enabled` boolean that does not exist, `om_status` a `status` string instead of the token windows, `om_thread_title_updated` a `title` instead of `newTitle`, and `subagent_end` only a `toolCallId` — its `agentType`, `result`, `isError` and `durationMs` were missing. `usage_update` typed its payload as `unknown`, so every consumer cast it. Seven events the controller emits (`state_changed`, `command_exit`, `tool_suspension_cancelled`, and the four remaining `subagent_*` events) were not typed at all and fell through `isKnownAgentControllerEvent`.
+
+  `isKnownAgentControllerEvent` now returns `true` for those seven events as well. If you route unrecognised events to a fallback branch, they no longer reach it — give them a case in your `switch` or they are silently dropped.
+
+  `thread_created` now delivers `thread.createdAt` and `thread.updatedAt` as `Date`s, the way the `message_*` events already did — the stream carries them as ISO strings.
+
+  Payload drift is now a compile error instead of a wrong field at runtime, so handlers reading the old fields need updating.
+
+  ```ts
+  // Before: compiled, but `enabled` is always undefined
+  if (event.type === 'om_activation' && event.enabled) { ... }
+
+  // After: tsc rejects it; the event carries cycleId, tokensActivated, generationCount, …
+  if (event.type === 'om_activation') { console.log(event.tokensActivated) }
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`6223446`](https://github.com/mastra-ai/mastra/commit/6223446ddce6166e96e0ba5e00d628b615dee8ca), [`583e235`](https://github.com/mastra-ai/mastra/commit/583e23519c13af16c1746f9c49722d011216611b), [`a77f8d4`](https://github.com/mastra-ai/mastra/commit/a77f8d4740d2178a74c41e4bf678b4fcd8fa0bb2), [`40d358e`](https://github.com/mastra-ai/mastra/commit/40d358e29d55543803e64b49241122f598ffabc7), [`e80cd7e`](https://github.com/mastra-ai/mastra/commit/e80cd7e7683e7d732e1cc6784bcac1d2640d2ce3), [`20504b2`](https://github.com/mastra-ai/mastra/commit/20504b2ecebd0e077acda3d457ab57480a98ed3e)]:
+  - @mastra/core@1.60.0-alpha.11
+
+## 1.41.0-alpha.10
+
+### Patch Changes
+
+- Updated dependencies [[`b860493`](https://github.com/mastra-ai/mastra/commit/b86049391100e665d579f700c8a2034c036defc3)]:
+  - @mastra/core@1.60.0-alpha.10
+
+## 1.41.0-alpha.9
+
+### Patch Changes
+
+- Preserve tool-call `providerMetadata` at the message-part level during client-tool continuations. ([#21703](https://github.com/mastra-ai/mastra/pull/21703))
+
+  The stream reducers nested `providerMetadata` inside `toolInvocation`, but the server reads it from `part.providerMetadata` when rebuilding the prompt. As a result the metadata was dropped on the recursive request, and Gemini thinking models (e.g. `gemini-3-flash-preview`) failed the follow-up turn with `Function call is missing a thought_signature in functionCall parts`.
+
+- Updated dependencies [[`b0a2a07`](https://github.com/mastra-ai/mastra/commit/b0a2a07800d42bd9823292e7db832374ed084c9c), [`ccbbcd9`](https://github.com/mastra-ai/mastra/commit/ccbbcd974eedff4367a54ed0e24c9ee742ab2f61), [`3f5c6f7`](https://github.com/mastra-ai/mastra/commit/3f5c6f728ea35da344248de9aa070f12849f3aa0), [`77e6b1b`](https://github.com/mastra-ai/mastra/commit/77e6b1bc4c46ce94fe501023fb4393c812ec6be3), [`2e1d098`](https://github.com/mastra-ai/mastra/commit/2e1d0984e325fd319d32ea182f596b3170be3847)]:
+  - @mastra/core@1.60.0-alpha.9
+
+## 1.41.0-alpha.8
+
+### Minor Changes
+
+- Added `Agent.readPlan()` for loading submitted plan Markdown. ([#21658](https://github.com/mastra-ai/mastra/pull/21658))
+
+  ```ts
+  const agent = client.getAgent('agent-id');
+  const plan = await agent.readPlan('.mastracode/plans/add-dark-mode.md');
+  ```
+
+### Patch Changes
+
+- `session.state()` now accepts a `threadId`, so reopening a chat can load the durable task list for that specific thread. ([#21545](https://github.com/mastra-ai/mastra/pull/21545))
+
+  ```ts
+  const state = await session.state({ threadId: 'thread-123' });
+  ```
+
+- Updated dependencies [[`4e7a421`](https://github.com/mastra-ai/mastra/commit/4e7a421dce8a48742f785d1e93ad2f43a572b282), [`242e324`](https://github.com/mastra-ai/mastra/commit/242e3241e73cbd5c9bb86a31ebb49ca0256488d4), [`217e967`](https://github.com/mastra-ai/mastra/commit/217e9672d8b3160eb729d8e9f0044949e88da239), [`d774e89`](https://github.com/mastra-ai/mastra/commit/d774e8930c781df8c9effe3763e6b501c099b6cc), [`9c27a53`](https://github.com/mastra-ai/mastra/commit/9c27a53cd9d3de4f3f025bc387d94ce371c33f95), [`dff25a1`](https://github.com/mastra-ai/mastra/commit/dff25a1103fa72ee082a9b6f805ebeb5ce400753), [`217e967`](https://github.com/mastra-ai/mastra/commit/217e9672d8b3160eb729d8e9f0044949e88da239), [`7f78585`](https://github.com/mastra-ai/mastra/commit/7f785857e401570e2ffb316911f126ed363aa537), [`f2a4afd`](https://github.com/mastra-ai/mastra/commit/f2a4afd7e37e809669001ed17724b341a5c1f45e), [`d438148`](https://github.com/mastra-ai/mastra/commit/d438148e222c1e2fb3c652725ce75680962ebec4), [`ba05fe0`](https://github.com/mastra-ai/mastra/commit/ba05fe0738f70cb686777546e968237d09269142), [`d26a8d4`](https://github.com/mastra-ai/mastra/commit/d26a8d4281f28414715b333c85bedaf70d0b2890), [`677cdc6`](https://github.com/mastra-ai/mastra/commit/677cdc6af564dec29a13464d12b7ab2a4efc22e9), [`a318490`](https://github.com/mastra-ai/mastra/commit/a318490e17da32f338d50929c770d901a9b3dd72), [`763e0c6`](https://github.com/mastra-ai/mastra/commit/763e0c61e04d76ad9a9efd301aa57525ca0cbea9), [`23e0be2`](https://github.com/mastra-ai/mastra/commit/23e0be261381e49534b4ff3101c60ee64a946cbf), [`7fc8806`](https://github.com/mastra-ai/mastra/commit/7fc880627d3cbf995d31ea0e8b807bf15417e651), [`0e02eac`](https://github.com/mastra-ai/mastra/commit/0e02eacdb2e30e1697a41910b41163742a181dc1), [`4df174c`](https://github.com/mastra-ai/mastra/commit/4df174c32bddf093a82f273070b8380aef7c9e90), [`f7c25b5`](https://github.com/mastra-ai/mastra/commit/f7c25b5106ddfb48e591f98df7a51e0f2dd01dba), [`dc09cc1`](https://github.com/mastra-ai/mastra/commit/dc09cc1083d861cde192c1cd235324dc75b8c731), [`36b4649`](https://github.com/mastra-ai/mastra/commit/36b4649045a3a380cbab8ceca866db4086223aff), [`377eb81`](https://github.com/mastra-ai/mastra/commit/377eb81ce43b964e3a6b541df172da74a8ff3716)]:
+  - @mastra/core@1.60.0-alpha.8
+
 ## 1.40.1-alpha.7
 
 ### Patch Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-client-js
 description: Documentation for @mastra/client-js. Use when working with @mastra/client-js APIs, configuration, or implementation.
 metadata:
   package: "@mastra/client-js"
-  version: "1.40.1-alpha.7"
+  version: "1.41.0-alpha.11"
 ---
 
 ## When to use
@@ -16,12 +16,12 @@ Read the individual reference documents for detailed explanations and code examp
 
 ### Docs
 
-- [A2A (Agent-to-Agent)](references/docs-agents-a2a.md) - Expose and call remote Mastra agents over the Agent-to-Agent protocol.
-- [Editor](references/docs-editor-overview.md) - Let collaborators update an agent in Studio, test their changes, and publish without editing code.
-- [Schedules](references/docs-long-running-agents-schedules.md) - Run an agent on a cron schedule to deliver a recurring prompt, with optional thread delivery and lifecycle hooks.
-- [Signals](references/docs-long-running-agents-signals.md) - Learn how to send real-time messages and context into a Mastra agent thread.
-- [JSON Web Token](references/docs-server-auth-jwt.md) - Documentation for JSON Web Token usage inside Mastra.
+- [JSON Web Token](references/docs-auth-jwt.md) - Documentation for JSON Web Token usage inside Mastra.
+- [A2A (Agent-to-Agent)](references/docs-connections-a2a.md) - Expose and call remote Mastra agents over the Agent-to-Agent protocol.
+- [Schedules](references/docs-harness-schedules.md) - Run an agent on a cron schedule to deliver a recurring prompt, with optional thread delivery and lifecycle hooks.
+- [Signals](references/docs-harness-signals.md) - Learn how to send real-time messages and context into a Mastra agent thread.
 - [Mastra client](references/docs-server-mastra-client.md) - Learn how to set up and use the Mastra Client SDK
+- [Editor](references/docs-studio-editor.md) - Let collaborators update an agent in Studio, test their changes, and publish without editing code.
 
 ### Integrations
 

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.40.1-alpha.7",
+  "version": "1.41.0-alpha.11",
   "package": "@mastra/client-js",
   "exports": {},
   "modules": {}

package/dist/docs/references/{docs-agents-a2a.md → docs-connections-a2a.md}

@@ -80,7 +80,7 @@ Use `A2AAgent` when another Mastra agent should delegate work to a remote agent.
 
 ## Consume A2A agents as subagents
 
-Use `A2AAgent` to wrap a remote A2A agent, then add it to a parent agent with the [supervisor agents](https://mastra.ai/docs/capabilities/subagents) pattern. Pass an explicit agent card URL when the remote server hosts multiple agents or uses a custom well-known path.
+Use `A2AAgent` to wrap a remote A2A agent, then add it to a parent agent with the [supervisor agents](https://mastra.ai/docs/subagents) pattern. Pass an explicit agent card URL when the remote server hosts multiple agents or uses a custom well-known path.
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -221,7 +221,7 @@ A2A models human-in-the-loop (HITL) work with the `input-required` task state. W
 
 Mastra maps its agent suspension model to this state in both directions:
 
-- **As a server**: when an exposed agent suspends, the task transitions to `input-required`. This includes suspensions caused by [tool approval](https://mastra.ai/docs/agents/agent-approval) or a tool that calls `suspend()`. The task status message includes a text prompt and a data part with the structured `suspendPayload` and `resumeSchema`. A follow-up `message/send` or `message/stream` request with the same `taskId` resumes the suspended run with the provided input.
+- **As a server**: when an exposed agent suspends, the task transitions to `input-required`. This includes suspensions caused by [tool approval](https://mastra.ai/docs/agents/human-in-the-loop) or a tool that calls `suspend()`. The task status message includes a text prompt and a data part with the structured `suspendPayload` and `resumeSchema`. A follow-up `message/send` or `message/stream` request with the same `taskId` resumes the suspended run with the provided input.
 - **As a client**: when a remote task reaches `input-required` or `auth-required`, `A2AAgent` returns a suspended result with `finishReason: 'suspended'` and a `suspendPayload`. Calling `resumeGenerate()` or `resumeStream()` sends the input or credentials back to the remote task with the original `taskId`.
 
 ```typescript

package/dist/docs/references/{docs-long-running-agents-schedules.md → docs-harness-schedules.md}

@@ -6,11 +6,11 @@
 
 > **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
-A schedule runs an agent on a cron cadence. On each fire, Mastra sends a prompt to the agent, either as a [signal](https://mastra.ai/docs/long-running-agents/signals) into a thread or as a threadless [`agent.generate()`](https://mastra.ai/reference/agents/generate) run. Use schedules for recurring agent work such as daily summaries, periodic checks, or scheduled nudges into a conversation.
+A schedule runs an agent on a cron cadence. On each fire, Mastra sends a prompt to the agent, either as a [signal](https://mastra.ai/docs/harness/signals) into a thread or as a threadless [`agent.generate()`](https://mastra.ai/reference/agents/generate) run. Use schedules for recurring agent work such as daily summaries, periodic checks, or scheduled nudges into a conversation.
 
 Schedules are persisted, so they survive restarts and redeploys. Manage them at runtime through [`mastra.schedules`](https://mastra.ai/reference/schedules/overview), the canonical create, read, update, and delete (CRUD) surface. The same surface also manages [workflow schedules](https://mastra.ai/docs/workflows/scheduled-workflows) (pass `workflowId` instead of `agentId` to schedule a workflow).
 
-> **Note:** Schedules require a [storage](https://mastra.ai/docs/storage/overview) adapter that implements the schedules domain. See the [`mastra.schedules` reference](https://mastra.ai/reference/schedules/overview) for supported adapters and API behavior.
+> **Note:** Schedules require a [storage](https://mastra.ai/docs/storage) adapter that implements the schedules domain. See the [`mastra.schedules` reference](https://mastra.ai/reference/schedules/overview) for supported adapters and API behavior.
 
 ## Quickstart
 
@@ -71,7 +71,7 @@ Without a `threadId`, each fire is an isolated `agent.generate()` run. Nothing i
 
 ### Threaded
 
-With a `threadId`, the schedule sends a [signal](https://mastra.ai/docs/long-running-agents/signals) into that thread, so the prompt joins the agent's conversation. Threaded schedules require a `resourceId` alongside the `threadId`.
+With a `threadId`, the schedule sends a [signal](https://mastra.ai/docs/harness/signals) into that thread, so the prompt joins the agent's conversation. Threaded schedules require a `resourceId` alongside the `threadId`.
 
 ```typescript
 await mastra.schedules.create({
@@ -83,7 +83,7 @@ await mastra.schedules.create({
 })
 ```
 
-Threaded schedules accept extra fields that control how the signal behaves, including the signal type, XML tag, tag attributes, and active-or-idle delivery behavior. They mirror the options [`agent.sendSignal()`](https://mastra.ai/docs/long-running-agents/signals) accepts and stay JSON-serializable so they persist with the schedule.
+Threaded schedules accept extra fields that control how the signal behaves, including the signal type, XML tag, tag attributes, and active-or-idle delivery behavior. They mirror the options [`agent.sendSignal()`](https://mastra.ai/docs/harness/signals) accepts and stay JSON-serializable so they persist with the schedule.
 
 These fields require a `threadId`. For the full threaded input shape, see the [agent schedule input reference](https://mastra.ai/reference/schedules/overview).
 
@@ -197,5 +197,5 @@ Hook exceptions are caught and logged. They never re-route the worker or trigger
 ## Related
 
 - [`mastra.schedules`](https://mastra.ai/reference/schedules/overview): API reference for creating and managing schedules.
-- [Signals](https://mastra.ai/docs/long-running-agents/signals): the delivery mechanism behind threaded schedules.
+- [Signals](https://mastra.ai/docs/harness/signals): the delivery mechanism behind threaded schedules.
 - [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows): declare a cron schedule on a workflow definition.

package/dist/docs/references/docs-server-mastra-client.md

@@ -2,7 +2,7 @@
 
 # Mastra client
 
-The Mastra Client SDK provides a concise and type-safe interface for interacting with your [Mastra Server](https://mastra.ai/docs/server/mastra-server) from your client environment.
+The Mastra Client SDK provides a concise and type-safe interface for interacting with your [Mastra Server](https://mastra.ai/docs/server/overview) from your client environment.
 
 ## Prerequisites
 
@@ -59,7 +59,7 @@ export const mastraClient = new MastraClient({
 The Mastra Client SDK exposes all resources served by the Mastra Server.
 
 - **[Agents](https://mastra.ai/reference/client-js/agents)**: Generate responses and stream conversations.
-- **[A2A](https://mastra.ai/docs/agents/a2a)**: Discover agents through agent cards and work with task-based A2A streams.
+- **[A2A](https://mastra.ai/docs/connections/a2a)**: Discover agents through agent cards and work with task-based A2A streams.
 - **[Memory](https://mastra.ai/reference/client-js/memory)**: Manage conversation threads and message history.
 - **[Tools](https://mastra.ai/reference/client-js/tools)**: Executed and managed tools.
 - **[Workflows](https://mastra.ai/reference/client-js/workflows)**: Trigger workflows and track their execution.

package/dist/docs/references/integrations-auth-workos.md

@@ -89,7 +89,7 @@ By default, `MastraAuthWorkos` grants access to any authenticated WorkOS user. T
 
 ### FGA membership loading
 
-Set `fetchMemberships: true` when you use [`MastraFGAWorkos`](https://mastra.ai/docs/server/auth/fga). This tells the auth provider to load the user's WorkOS organization memberships during authentication so FGA checks can resolve the correct organization membership ID.
+Set `fetchMemberships: true` when you use [`MastraFGAWorkos`](https://mastra.ai/docs/auth/fga). This tells the auth provider to load the user's WorkOS organization memberships during authentication so FGA checks can resolve the correct organization membership ID.
 
 ```typescript
 import { MastraAuthWorkos, MastraFGAWorkos } from '@mastra/auth-workos'

package/dist/docs/references/reference-client-js-agents.md

@@ -285,7 +285,7 @@ await subscription.processDataStream({
 
 ### `streamUntilIdle()`
 
-Stream a response and keep the stream open until every [background task](https://mastra.ai/docs/long-running-agents/background-tasks) dispatched during the run completes. The server re-enters the agentic loop on each task completion so the LLM can react to results in the same call. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call uses a plain `stream()`.
+Stream a response and keep the stream open until every [background task](https://mastra.ai/docs/harness/background-tasks) dispatched during the run completes. The server re-enters the agentic loop on each task completion so the LLM can react to results in the same call. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call uses a plain `stream()`.
 
 ```typescript
 const response = await agent.streamUntilIdle('Research solana for me', {
@@ -307,7 +307,7 @@ response.processDataStream({
 
 ### `resumeStreamUntilIdle()`
 
-Resume a suspended agent stream with custom data and keep the stream open until every [background task](https://mastra.ai/docs/long-running-agents/background-tasks) dispatched during the run completes. Use this to continue execution after a suspension point, such as a workflow suspend within an agent. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call uses a plain `resumeStream()`:
+Resume a suspended agent stream with custom data and keep the stream open until every [background task](https://mastra.ai/docs/harness/background-tasks) dispatched during the run completes. Use this to continue execution after a suspension point, such as a workflow suspend within an agent. Requires background tasks to be [enabled on the Mastra instance](https://mastra.ai/reference/configuration) and a memory thread; otherwise the call uses a plain `resumeStream()`:
 
 ```typescript
 const response = await agent.resumeStreamUntilIdle(
@@ -497,7 +497,7 @@ if (output.finishReason === 'suspended') {
 
 ## Agent schedules
 
-Use the client SDK schedule methods to manage persisted agent schedules over the `/api/schedules` routes. For concepts and server-side examples, see [Schedules](https://mastra.ai/docs/long-running-agents/schedules) and the [`mastra.schedules` reference](https://mastra.ai/reference/schedules/overview).
+Use the client SDK schedule methods to manage persisted agent schedules over the `/api/schedules` routes. For concepts and server-side examples, see [Schedules](https://mastra.ai/docs/harness/schedules) and the [`mastra.schedules` reference](https://mastra.ai/reference/schedules/overview).
 
 ### `createSchedule()`
 
@@ -778,9 +778,29 @@ const agent = await mastraClient.createStoredAgent({
     version: '1.0',
     team: 'engineering',
   },
+  durable: true,
 })
 ```
 
+#### Durable stored agents
+
+Set `durable` to run the agent as a [durable agent](https://mastra.ai/docs/harness/durable-agents) once the server hydrates it. Pass `true` to accept the defaults, or an object to tune the durable loop:
+
+```typescript
+const agent = await mastraClient.createStoredAgent({
+  id: 'durable-agent',
+  name: 'Durable Agent',
+  instructions: 'You are a helpful assistant.',
+  model: {
+    provider: 'openai',
+    name: 'gpt-5.4',
+  },
+  durable: { maxSteps: 50, cleanupTimeoutMs: 0 },
+})
+```
+
+Only serializable options are accepted. The durable cache and pubsub are inherited from the server's `Mastra` instance. If it has no distributed cache or pubsub configured, durability is process-local. Automatic recovery is still configured in code through `recovery.durableAgents`.
+
 ### `getStoredAgent()`
 
 Get an instance of a specific stored agent:
@@ -839,7 +859,7 @@ console.log(result.success) // true
 
 ## Version management
 
-Both `Agent` (code-defined) and `StoredAgent` instances have methods for managing configuration versions. See [Editor versioning](https://mastra.ai/docs/editor/overview) for lifecycle and selection behavior.
+Both `Agent` (code-defined) and `StoredAgent` instances have methods for managing configuration versions. See [Editor versioning](https://mastra.ai/docs/studio/editor) for lifecycle and selection behavior.
 
 ### Getting an agent with a specific version
 

package/dist/docs/references/reference-editor-versioning.md

@@ -4,7 +4,7 @@
 
 Editor versions stored agents and prompt blocks. Database-backed resources use draft and publish operations. Code-backed agent overrides use deterministic files and Git history.
 
-See [Editor versioning](https://mastra.ai/docs/editor/overview) for release and experimentation patterns.
+See [Editor versioning](https://mastra.ai/docs/studio/editor) for release and experimentation patterns.
 
 ## Database lifecycle
 
@@ -35,7 +35,7 @@ See [`MastraEditor`](https://mastra.ai/reference/editor/mastra-editor) for sourc
 
 ## Select an agent version
 
-Calling [`mastra.getAgentById()`](https://mastra.ai/reference/core/getAgentById) without a selector returns the registered code-defined agent. Pass `status` or `versionId` to apply a stored override. See [Select a version](https://mastra.ai/docs/editor/overview) for a TypeScript example.
+Calling [`mastra.getAgentById()`](https://mastra.ai/reference/core/getAgentById) without a selector returns the registered code-defined agent. Pass `status` or `versionId` to apply a stored override. See [Select a version](https://mastra.ai/docs/studio/editor) for a TypeScript example.
 
 With the default server prefix, pass selectors as query parameters under `/api`:
 
@@ -54,7 +54,7 @@ See the [Client SDK agents reference](https://mastra.ai/reference/client-js/agen
 
 ## Sub-agent versioning
 
-Version overrides propagate through [supervisor-agent delegation](https://mastra.ai/docs/capabilities/subagents) in request context. Define selectors at three levels:
+Version overrides propagate through [supervisor-agent delegation](https://mastra.ai/docs/subagents) in request context. Define selectors at three levels:
 
 1. `Mastra` instance `versions`: Defaults for every invocation
 2. Server request-body `versions`: Per-request values added to request context

package/dist/index.cjs

@@ -884,6 +884,15 @@ var Agent = class extends BaseResource {
 		return this.request(`/agents/${this.agentId}${this.getQueryString(requestContext)}`);
 	}
 	/**
+	* Reads a markdown plan submitted by this agent through the core submit_plan tool.
+	* The server only serves paths under `.mastracode/plans/` and only when the
+	* agent exposes that capability.
+	*/
+	readPlan(path, requestContext) {
+		const contextQuery = this.getQueryString(requestContext, "&");
+		return this.request(`/agents/${this.agentId}/plans/file?path=${encodeURIComponent(path)}${contextQuery}`);
+	}
+	/**
 	* Probe the agent's browser session state before opening a screencast WebSocket.
 	*
 	* Returns `{ hasSession, screencastAvailable }`. Use this to avoid opening a WS
@@ -1404,13 +1413,22 @@ var Agent = class extends BaseResource {
 		let currentTextPart = void 0;
 		let currentReasoningPart = void 0;
 		let currentReasoningTextDetail = void 0;
-		function updateToolInvocationPart(toolCallId, invocation) {
+		function updateToolInvocationPart(toolCallId, invocation, partProviderMetadata) {
 			const part = message.parts.find((part) => part.type === "tool-invocation" && part.toolInvocation.toolCallId === toolCallId);
-			if (part != null) part.toolInvocation = invocation;
-			else message.parts.push({
-				type: "tool-invocation",
-				toolInvocation: invocation
-			});
+			if (part != null) {
+				part.toolInvocation = invocation;
+				if (partProviderMetadata !== void 0) part.providerMetadata = {
+					...part.providerMetadata ?? {},
+					...partProviderMetadata
+				};
+			} else {
+				const newPart = {
+					type: "tool-invocation",
+					toolInvocation: invocation
+				};
+				if (partProviderMetadata !== void 0) newPart.providerMetadata = partProviderMetadata;
+				message.parts.push(newPart);
+			}
 		}
 		const data = [];
 		let messageAnnotations = replaceLastMessage ? lastMessage?.annotations : void 0;
@@ -1548,7 +1566,7 @@ var Agent = class extends BaseResource {
 					if (message.toolInvocations == null) message.toolInvocations = [];
 					message.toolInvocations.push(invocation);
 				}
-				updateToolInvocationPart(value.toolCallId, invocation);
+				updateToolInvocationPart(value.toolCallId, invocation, value.providerMetadata);
 				execUpdate();
 				if (onToolCall) {
 					const result = await onToolCall({ toolCall: value });
@@ -1560,7 +1578,7 @@ var Agent = class extends BaseResource {
 							result
 						};
 						message.toolInvocations[message.toolInvocations.length - 1] = invocation;
-						updateToolInvocationPart(value.toolCallId, invocation);
+						updateToolInvocationPart(value.toolCallId, invocation, value.providerMetadata);
 						execUpdate();
 					}
 				}
@@ -1576,7 +1594,7 @@ var Agent = class extends BaseResource {
 					...value
 				};
 				toolInvocations[toolInvocationIndex] = invocation;
-				updateToolInvocationPart(value.toolCallId, invocation);
+				updateToolInvocationPart(value.toolCallId, invocation, value.providerMetadata);
 				execUpdate();
 			},
 			onDataPart(value) {
@@ -1656,13 +1674,22 @@ var Agent = class extends BaseResource {
 		let currentTextPart = void 0;
 		let currentReasoningPart = void 0;
 		let currentReasoningTextDetail = void 0;
-		function updateToolInvocationPart(toolCallId, invocation) {
+		function updateToolInvocationPart(toolCallId, invocation, partProviderMetadata) {
 			const part = message.parts.find((part) => part.type === "tool-invocation" && part.toolInvocation.toolCallId === toolCallId);
-			if (part != null) part.toolInvocation = invocation;
-			else message.parts.push({
-				type: "tool-invocation",
-				toolInvocation: invocation
-			});
+			if (part != null) {
+				part.toolInvocation = invocation;
+				if (partProviderMetadata !== void 0) part.providerMetadata = {
+					...part.providerMetadata ?? {},
+					...partProviderMetadata
+				};
+			} else {
+				const newPart = {
+					type: "tool-invocation",
+					toolInvocation: invocation
+				};
+				if (partProviderMetadata !== void 0) newPart.providerMetadata = partProviderMetadata;
+				message.parts.push(newPart);
+			}
 		}
 		const data = [];
 		let messageAnnotations = replaceLastMessage ? lastMessage?.annotations : void 0;
@@ -1758,7 +1785,7 @@ var Agent = class extends BaseResource {
 							if (message.toolInvocations == null) message.toolInvocations = [];
 							message.toolInvocations.push(invocation);
 						}
-						updateToolInvocationPart(chunk.payload.toolCallId, invocation);
+						updateToolInvocationPart(chunk.payload.toolCallId, invocation, chunk.payload.providerMetadata);
 						execUpdate();
 						if (onToolCall) {
 							const result = await onToolCall({ toolCall: chunk.payload });
@@ -1770,7 +1797,7 @@ var Agent = class extends BaseResource {
 									result
 								};
 								message.toolInvocations[message.toolInvocations.length - 1] = invocation;
-								updateToolInvocationPart(chunk.payload.toolCallId, invocation);
+								updateToolInvocationPart(chunk.payload.toolCallId, invocation, chunk.payload.providerMetadata);
 								execUpdate();
 							}
 						}
@@ -1827,7 +1854,7 @@ var Agent = class extends BaseResource {
 							...chunk.payload
 						};
 						toolInvocations[toolInvocationIndex] = invocation;
-						updateToolInvocationPart(chunk.payload.toolCallId, invocation);
+						updateToolInvocationPart(chunk.payload.toolCallId, invocation, chunk.payload.providerMetadata);
 						execUpdate();
 						break;
 					}
@@ -5645,22 +5672,29 @@ const KNOWN_AGENT_CONTROLLER_EVENT_TYPES = new Set(Object.keys({
 	message_start: true,
 	message_update: true,
 	message_end: true,
+	state_changed: true,
 	tool_input_start: true,
 	tool_input_delta: true,
 	tool_input_end: true,
 	tool_start: true,
 	tool_update: true,
 	shell_output: true,
+	command_exit: true,
 	tool_end: true,
 	tool_approval_required: true,
 	tool_suspended: true,
+	tool_suspension_cancelled: true,
 	mode_changed: true,
 	model_changed: true,
 	thread_changed: true,
 	thread_created: true,
 	thread_deleted: true,
 	subagent_start: true,
+	subagent_text_delta: true,
+	subagent_tool_start: true,
+	subagent_tool_end: true,
 	subagent_end: true,
+	subagent_model_changed: true,
 	task_updated: true,
 	notification: true,
 	notification_summary: true,
@@ -5691,19 +5725,37 @@ const KNOWN_AGENT_CONTROLLER_EVENT_TYPES = new Set(Object.keys({
 function isKnownAgentControllerEvent(event) {
 	return KNOWN_AGENT_CONTROLLER_EVENT_TYPES.has(event.type);
 }
+const toDate = (value) => value instanceof Date ? value : new Date(value);
 function hydrateMessage(message) {
 	return {
 		...message,
-		createdAt: message.createdAt instanceof Date ? message.createdAt : new Date(message.createdAt)
+		createdAt: toDate(message.createdAt)
 	};
 }
-function hydrateEventMessage(event) {
-	if (event.type !== "message_start" && event.type !== "message_update" && event.type !== "message_end") return event;
+function hydrateThread(thread) {
 	return {
-		...event,
-		message: hydrateMessage(event.message)
+		...thread,
+		createdAt: toDate(thread.createdAt),
+		updatedAt: toDate(thread.updatedAt)
 	};
 }
+/** The stream carries every timestamp as an ISO string; give consumers back the `Date`s the type promises. */
+function hydrateEventTimestamps(event) {
+	if (!isKnownAgentControllerEvent(event)) return event;
+	switch (event.type) {
+		case "message_start":
+		case "message_update":
+		case "message_end": return {
+			...event,
+			message: hydrateMessage(event.message)
+		};
+		case "thread_created": return {
+			...event,
+			thread: hydrateThread(event.thread)
+		};
+		default: return event;
+	}
+}
 /**
 * A session bound to a `resourceId` within one agent controller. Sessions are
 * get-or-create on the server, so re-creating the same resourceId (and scope)
@@ -5835,7 +5887,7 @@ var AgentControllerSession = class extends BaseResource {
 							if (!data) continue;
 							let event;
 							try {
-								event = hydrateEventMessage(JSON.parse(data));
+								event = hydrateEventTimestamps(JSON.parse(data));
 							} catch {
 								continue;
 							}
@@ -5989,8 +6041,9 @@ var AgentControllerSession = class extends BaseResource {
 		});
 	}
 	/** Get the current mode, model, and thread (for initial UI hydration). */
-	state() {
-		return this.request(this.url(this.base()));
+	state(options) {
+		const path = options?.threadId ? `${this.base()}?threadId=${encodeURIComponent(options.threadId)}` : this.base();
+		return this.request(this.url(path));
 	}
 	/** Merge key-value pairs into the session state. Existing keys not in the payload are preserved. */
 	async setState(updates) {