@mastra/client-js 1.52.0-alpha.5 → 1.52.0-alpha.8

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.52.0-alpha.5"
+  version: "1.52.0-alpha.8"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.52.0-alpha.5",
+  "version": "1.52.0-alpha.8",
   "package": "@mastra/client-js",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-auth-jwt.md

@@ -69,7 +69,7 @@ Inside [Studio](https://mastra.ai/docs/studio/overview), go to **Settings** and
 
 ## Configuring `MastraClient`
 
-When `auth` is enabled, all requests made with `MastraClient` must include a valid JWT in the `Authorization` header:
+When `auth` is enabled, requests to protected routes made with `MastraClient` must include a valid JWT in the `Authorization` header:
 
 ```typescript
 import { MastraClient } from '@mastra/client-js'

package/dist/docs/references/docs-harness-agent-controller.md

@@ -93,7 +93,7 @@ The controller, Session, and thread have different lifetimes:
 - **Session**: An isolated live runtime for one user, task, or concurrent work scope. It owns the active mode, model, state, event bus, run state, grants, and current thread binding.
 - **Thread**: A stored conversation containing messages and thread settings. Threads can survive controller and process recreation when you configure storage.
 
-A Session is live state. Arbitrary [`session.state`](https://mastra.ai/reference/agent-controller/session), permission grants, pending approvals, and active runs don't automatically survive process recreation. Thread messages and selected thread settings, including mode and per-mode model choices, can persist through storage.
+A Session is live state. Arbitrary [`session.state`](https://mastra.ai/reference/agent-controller/session), permission grants, pending approvals, and active runs don't automatically survive process recreation. Thread messages and selected thread settings, including the active mode and the current model, can persist through storage, but switching modes doesn't change the model.
 
 ## Sessions and threads
 
@@ -193,19 +193,14 @@ console.log(session.mode.get()) // "build"
 console.log(session.mode.resolve().instructions)
 ```
 
-Switch models independently with [`session.model.switch()`](https://mastra.ai/reference/agent-controller/session), then read the active selection with [`session.model.get()`](https://mastra.ai/reference/agent-controller/session). Thread-scoped selections are stored per mode and restored when the Session returns to that mode:
+Switch models independently with [`session.model.switch()`](https://mastra.ai/reference/agent-controller/session), then read the active selection with [`session.model.get()`](https://mastra.ai/reference/agent-controller/session). The selection is stored as the thread's current model and remains active when the Session changes modes:
 
 ```typescript
-await session.model.switch({
-  modelId: 'anthropic/claude-sonnet-4-6',
-  scope: 'thread',
-})
+await session.model.switch('anthropic/claude-sonnet-4-6')
 
 console.log(session.model.get())
 ```
 
-Use `scope: 'global'` for an in-memory selection that shouldn't be written to thread settings.
-
 ## Manage threads and state
 
 List stored conversations with [`session.thread.list()`](https://mastra.ai/reference/agent-controller/session):
@@ -285,6 +280,8 @@ session.subscribe(event => {
 
 For `submit_plan`, resume with `{ action: 'approved' }` or `{ action: 'rejected', feedback }`. An approved plan can switch to the mode configured by `transitionsTo` before the run continues.
 
+The built-in `submit_plan` tool takes a plan file path, not the plan text. The agent writes the plan to a file and submits its path. It needs a filesystem it can write to, such as a workspace filesystem. To show the plan for approval, your app reads the file at the submitted `path`.
+
 ## Delegate to subagents
 
 Configure available subagent types on the controller. The built-in `subagent` tool can then delegate focused tasks using those definitions:
@@ -354,7 +351,7 @@ const controller = new AgentController({
     },
     onSessionStart: async ({ session, thread }) => {
       const plan = await billing.planFor(thread.resourceId)
-      await session.model.switch({ modelId: plan.modelId })
+      await session.model.switch(plan.modelId)
     },
   },
 })
@@ -445,7 +442,7 @@ Subscriptions are isolated by Session. Events from another Session on the same c
 
 ### Client-side sessions
 
-[`client.getAgentController(id).session(resourceId, scope?)`](https://mastra.ai/reference/client-js/agent-controller) returns a session client bound to one resource. Sessions are get-or-create on the server, so `create()` resumes an existing conversation instead of forking it. Pass `scope` when one resource needs independent sessions, such as one per git worktree:
+[`client.getAgentController(key).session(resourceId, scope?)`](https://mastra.ai/reference/client-js/agent-controller) returns a session client bound to one resource. Pass the key the controller is registered under in `new Mastra({ agentControllers })`, which can differ from the controller's `id`. Sessions are get-or-create on the server, so `create()` resumes an existing conversation instead of forking it. Pass `scope` when one resource needs independent sessions, such as one per git worktree:
 
 ```typescript
 import { MastraClient } from '@mastra/client-js'

package/dist/docs/references/reference-client-js-agent-controller.md

@@ -39,12 +39,22 @@ Retrieve the agent controllers hosted on the connected Mastra instance:
 const controllers = await client.listAgentControllers()
 ```
 
+Each entry's `id` is the key the controller is registered under in `new Mastra({ agentControllers })`, not the controller's own `id`.
+
 ## Working with a specific agent controller
 
-Get an instance of an agent controller by the ID it's registered under:
+Get an instance of an agent controller by the key it's registered under in `new Mastra({ agentControllers })`. The key can differ from the controller's `id`. In this example, pass `'coding'`, not `'coding-controller'`:
+
+```typescript
+const codingController = new AgentController({ id: 'coding-controller', agent, modes })
+
+export const mastra = new Mastra({
+  agentControllers: { coding: codingController },
+})
+```
 
 ```typescript
-const controller = client.getAgentController('coding-controller')
+const controller = client.getAgentController('coding')
 ```
 
 ### `listModes()`
@@ -155,7 +165,13 @@ Switches the active mode.
 
 ### `switchModel(modelId, options?)`
 
-Switches the model. `options.scope` is `'thread'` (default) or `'global'`. `options.modeId` targets a specific mode.
+Switches the session's active model and persists it as the current model for the active thread. Switching modes doesn't change it. Pass `{ thinkingLevel }` as the second argument to apply and persist a thinking level with the model.
+
+```typescript
+await session.switchModel('anthropic/claude-sonnet-4-6', {
+  thinkingLevel: 'high',
+})
+```
 
 ### `listThreads(options?)`
 

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

@@ -122,7 +122,7 @@ console.log(items.data)
 - `data`: Conversation items such as `message`, `function_call`, and `function_call_output`
 - `first_id`: The first item ID in the page
 - `last_id`: The last item ID in the page
-- `has_more`: Whether more items exist beyond the current page
+- `has_more`: Currently always `false`. `items.list()` returns up to 1000 items in a single response.
 
 ## Parameters
 

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

@@ -59,9 +59,9 @@ You can also pass `requestContext` as a `Record<string, any>`.
 
 **getAgent(agentId)** (`Agent`): Retrieves a specific agent instance by ID.
 
-**listAgentControllers()** (`Promise<AgentControllerInfo[]>`): Returns the agent controllers hosted on the connected Mastra instance.
+**listAgentControllers()** (`Promise<AgentControllerInfo[]>`): Returns the agent controllers hosted on the connected Mastra instance. Each entry's id is the key the controller is registered under in new Mastra({ agentControllers }).
 
-**getAgentController(controllerId)** (`AgentController`): Retrieves a specific agent controller by ID. .session(resourceId) returns a session client; call await session.create() to create or resume the server session.
+**getAgentController(controllerId)** (`AgentController`): Retrieves a specific agent controller by the key it is registered under in new Mastra({ agentControllers }), which can differ from the controller id. .session(resourceId) returns a session client; call await session.create() to create or resume the server session.
 
 **listMemoryThreads(params)** (`Promise<StorageThreadType[]>`): Retrieves memory threads for the specified resource and agent. Requires a resourceId and an agentId.
 

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

@@ -223,9 +223,25 @@ A workflow run result yields the following:
 
 **runId** (`string`): Unique identifier for this workflow run instance
 
-**eventTimestamp** (`Date`): The timestamp of the event
+**workflowName** (`string`): Name of the workflow this run belongs to
 
-**payload** (`object`): Contains currentStep (id, status, output, payload) and workflowState (status, steps record)
+**resourceId** (`string`): Resource ID associated with the run, if one was set
+
+**createdAt** (`string`): ISO 8601 timestamp of when the run was created
+
+**updatedAt** (`string`): ISO 8601 timestamp of when the run was last updated
+
+**status** (`WorkflowRunStatus`): Current status of the run, such as 'running', 'success', 'failed', 'suspended', 'waiting', or 'canceled'
+
+**payload** (`Record<string, any>`): Input data the run was started with
+
+**result** (`Record<string, any>`): Final output of the workflow when the run succeeded
+
+**error** (`SerializedError`): Error details when the run failed
+
+**steps** (`Record<string, WorkflowStateStepResult>`): Per-step results, including status, output, payload, and timing
+
+Use the `fields` option to limit which optional fields are returned. Metadata fields and `status` are always included.
 
 ## Dynamic workflows
 

package/dist/index.cjs

@@ -6443,15 +6443,17 @@ var AgentControllerSession = class extends BaseResource {
 			body: { modeId }
 		});
 	}
-	/** Switch the model. Defaults to thread scope. */
-	async switchModel(modelId, options) {
+	/**
+	* Switch the session model and persist it to the active thread. When
+	* `thinkingLevel` is provided it is applied and persisted with the model.
+	*/
+	async switchModel(modelId, { thinkingLevel } = {}) {
 		await this.request(this.url(`${this.base()}/model`), {
 			method: "POST",
-			body: {
+			body: thinkingLevel !== void 0 ? {
 				modelId,
-				scope: options?.scope,
-				modeId: options?.modeId
-			}
+				thinkingLevel
+			} : { modelId }
 		});
 	}
 	/**