@mastra/client-js 1.56.0-alpha.8 → 1.56.0-alpha.9

package/dist/client.d.ts

@@ -52,7 +52,7 @@ export declare class MastraClient extends BaseResource {
     listAgentControllers(): Promise<AgentControllerInfo[]>;
     /**
      * Scopes to an agent controller hosted on the connected Mastra instance. Use
-     * `getAgentController(id).session(resourceId)` to create/resume a session,
+     * `getAgentController(id).session(sessionId)` to create/resume a session,
      * stream its events, and send messages.
      * @param controllerId - The id the agent controller is registered under on Mastra
      */

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.56.0-alpha.8"
+  version: "1.56.0-alpha.9"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

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

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

@@ -90,43 +90,40 @@ Use the same controller for many Sessions. Don't store a current Session on the
 The controller, Session, and thread have different lifetimes:
 
 - **Controller**: A shared host for configuration and runtime services. Initialize it once and reuse it.
-- **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.
+- **Session**: An isolated live runtime for one user, task, or concurrent piece of work, addressed by its session id. 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 the active mode and the current model, can persist through storage, but switching modes doesn't change the model.
 
 ## Sessions and threads
 
-`createSession()` is get-or-create by `resourceId` and optional `scope`:
+`createSession()` is get-or-create by session `id`. The `resourceId` names who owns the session's threads and resource-scoped memory. When you omit `id`, it defaults to `resourceId`:
 
 ```typescript
 const webSession = await controller.createSession({
+  id: 'user-123:web',
   resourceId: 'user-123',
-  scope: 'web',
 })
 
-const sameWebSession = await controller.createSession({
-  resourceId: 'user-123',
-  scope: 'web',
-})
+const sameWebSession = await controller.getSession('user-123:web')
 
 const workerSession = await controller.createSession({
+  id: 'user-123:background-worker',
   resourceId: 'user-123',
-  scope: 'background-worker',
 })
 
 console.log(webSession === sameWebSession) // true
 console.log(webSession === workerSession) // false
 ```
 
-Sessions with different scopes have separate event buses, run loops, state, mode and model selections, and current thread bindings. Their stored threads still belong to the shared `resourceId`.
+Sessions with different ids have separate event buses, run loops, state, mode and model selections, and current thread bindings. Their stored threads and resource-scoped memory still belong to the shared `resourceId`, so listing threads by resource returns both sessions' threads.
 
 Pass `threadId` when the host must bind the Session to an exact thread. The controller switches to the existing thread or creates it with that ID when it's missing. This behavior also applies when `createSession()` returns a cached Session:
 
 ```typescript
 const session = await controller.createSession({
+  id: 'user-123:web',
   resourceId: 'user-123',
-  scope: 'web',
   threadId: 'support-ticket-42',
 })
 ```
@@ -430,9 +427,9 @@ channels: {
     const install = await installs.authorize(requestContext.get('teamId'))
 
     return controller.createSession({
+      id: `${install.id}:${thread.id}`,
       resourceId: thread.resourceId,
       threadId: thread.id,
-      scope: install.id,
       ownerId: controller.id,
       requestContext,
     })
@@ -440,7 +437,7 @@ channels: {
 }
 ```
 
-Create the session under `thread.resourceId`. Because a session can bind only threads it owns, use `resolveResourceId` to assign a different owner to the mapped thread. Pass `threadId: thread.id` so the session opens on the mapped thread. Without it, a session that has tags or a `projectPath` doesn't treat the mapped thread as its own, so it creates an extra empty thread before switching to the mapped one. Sessions are get-or-create for each `resourceId` and `scope` combination. Pass `scope` when one thread needs separate sessions for each installation or principal.
+Create the session under `thread.resourceId`. Because a session can bind only threads it owns, use `resolveResourceId` to assign a different owner to the mapped thread. Pass `threadId: thread.id` so the session opens on the mapped thread. Without it, a session that has tags or a `projectPath` doesn't treat the mapped thread as its own, so it creates an extra empty thread before switching to the mapped one. Sessions are get-or-create by `id`. Give each installation or principal its own `id` when one thread needs separate sessions.
 
 Failures that aren't refusals (a storage outage, a bug in your resolver's dependencies) still post an error to the thread, so a broken bot doesn't look like a silent one. If you need to tell them apart in your own code, a refusal is a `ChannelSessionRejectedError` with the original error as its `cause`.
 
@@ -490,7 +487,7 @@ Subscriptions are isolated by Session. Events from another Session on the same c
 
 ### Client-side sessions
 
-[`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:
+[`client.getAgentController(key).session(sessionId)`](https://mastra.ai/reference/client-js/agent-controller) returns a session client addressed by its session id. 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 `resourceId` to `create()` when several sessions share one resource; otherwise the resource defaults to the session id:
 
 ```typescript
 import { MastraClient } from '@mastra/client-js'
@@ -513,7 +510,7 @@ const subscription = await session.subscribe({
 subscription.unsubscribe()
 ```
 
-`subscribe()` takes an options object and is async, unlike the in-process listener. Its promise resolves once the stream is established and rejects when it can't connect. A rejected call leaves nothing running in the background. `reconnect: true` re-establishes a stream that drops after it was established, with exponential backoff. A connection that goes silent without closing, for example after the device sleeps, counts as a drop once no data, including server heartbeats, arrives for `idleTimeoutMs` (default `60000`).
+`subscribe()` takes an options object and is async, unlike the in-process listener. Its promise resolves once the stream is established and rejects when it can't connect. A rejected call leaves nothing running in the background. `reconnect: true` re-establishes a stream that drops after it was established, with exponential backoff. A connection that stays open but stops delivering data, for example after the device sleeps, counts as a drop once no data, including server heartbeats, arrives for `idleTimeoutMs` (default `60000`).
 
 The server doesn't replay events missed while the stream was down, so read `session.state()` from `onReconnect` for the current mode, model, and thread. The client surface has no `session.displayState.get()`.
 

package/dist/docs/references/docs-harness-schedules.md

@@ -171,13 +171,13 @@ const mastra = new Mastra({
       return { prompt: `Status as of ${trigger.firedAt.toISOString()}` }
     },
     onFinish: async ({ agentId, outcome, runId }) => {
-      // Runs on any non-error, non-abort outcome
+      // Runs on any non-error, non-abort outcome. For a threaded schedule, this is the hand-off, not the end of the run
     },
     onError: async ({ agentId, phase, error }) => {
-      // Runs when prepare, the signal, or the agent run threw
+      // Runs when prepare or the signal threw, or a threadless run failed without aborting
     },
     onAbort: async ({ agentId, runId }) => {
-      // Runs when the run was aborted mid-stream
+      // Runs when a threadless run was aborted
     },
   },
 })
@@ -186,9 +186,11 @@ const mastra = new Mastra({
 The hooks are:
 
 - `prepare`: runs before the fire. Return an object to override fire-time parameters such as `prompt` or `threadId`, `null` to skip the fire, or `undefined` to use the stored defaults.
-- `onFinish`: runs once per trigger that reached a non-error, non-abort terminal state.
-- `onError`: runs after a failure in `prepare` or the signal. It also runs when the agent run fails.
-- `onAbort`: runs when the run was aborted mid-stream.
+- `onFinish`: runs once per trigger that reached a non-error, non-abort outcome. When a threaded schedule starts a new run, it runs with `outcome: 'succeeded'` as soon as the run starts, not when it finishes.
+- `onError`: runs after a failure in `prepare` or the signal. For a schedule without a `threadId`, it also runs when the agent run fails with an error that isn't an abort.
+- `onAbort`: runs when the run of a schedule without a `threadId` was aborted.
+
+For a schedule with a `threadId`, the worker sends the prompt to the thread and doesn't wait for the run. Errors and aborts after the run starts surface on that thread's run, not through `onError` or `onAbort`.
 
 Every hook context includes `agentId` (the agent the schedule fired for) alongside `schedule` and `trigger`.
 

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

@@ -81,11 +81,19 @@ Returns the controller's workspace status.
 
 Returns: `Promise<AgentControllerWorkspaceStatus>`
 
-### `session(resourceId, scope?)`
+### `session(sessionId)`
 
-Returns an `AgentControllerSession` bound to one resource. Sessions are get-or-create on the server, so calling `create()` on the same `resourceId` and `scope` resumes the existing conversation instead of forking it.
+Returns an `AgentControllerSession` addressed by its session id. Every request goes to `/agent-controller/:controllerId/sessions/:sessionId/...`. Sessions are get-or-create on the server, so calling `create()` with the same `sessionId` resumes the existing conversation instead of forking it.
 
-Pass `scope` to address an independent session over the same `resourceId`. Sessions that share a `resourceId` but use different scopes each get their own run loop, thread binding, mode, model, and state. A common pattern is one session per git worktree with the worktree path as the scope. The scope travels on every request as a `sessionScope` query parameter.
+Sessions that share a resource but use different session ids each get their own run loop, thread binding, mode, model, and state. Their stored threads and resource-scoped memory belong to the shared resource. Pass the resource to `create()`:
+
+```typescript
+const runA = client.getAgentController('code').session('run-a')
+await runA.create({ resourceId: 'factory-1' })
+
+const runB = client.getAgentController('code').session('run-b')
+await runB.create({ resourceId: 'factory-1' })
+```
 
 ## Session methods
 
@@ -93,6 +101,8 @@ Pass `scope` to address an independent session over the same `resourceId`. Sessi
 
 Creates or resumes the session.
 
+**resourceId** (`string`): Memory resource that owns the session's threads. Defaults to the session id, so a session created with only an id keeps one resource of its own.
+
 **tags** (`Record<string, string>`): Scopes initial thread selection. A thread is a resume candidate only when its metadata matches every tag.
 
 **threadId** (`string`): Binds the session to one exact thread, creating it with that ID when it does not exist.

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

@@ -61,7 +61,7 @@ You can also pass `requestContext` as a `Record<string, any>`.
 
 **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 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.
+**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(sessionId) 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-observability.md

@@ -105,7 +105,7 @@ Combine predicates with `and`, `or` and `not`. Membership uses `{ op: 'in', valu
 
 Each summary includes identity, context, entity lineage, status, timestamps, `durationMs`, model/provider and input/output/error previews. Model/provider are available in returned rows but aren't filterable.
 
-The additional identity, context and parent/root entity filters require an updated storage adapter. With an older adapter, requests using these filters return a structured `422` error.
+Check `capabilities.spanQueryContextFields` from `getObservabilityCapabilities()` before using the additional identity, context and parent/root entity filters. A missing or false value means these filters aren't available. With an older adapter, requests using these filters return a structured `422` error.
 
 DuckDB returns `null` for parent/root entity type, ID and name, and for `executionSource`. Equality filters on these fields match no spans. Parent/root entity version IDs remain available.
 

package/dist/docs/references/reference-observability-tracing-advanced-queries.md

@@ -30,10 +30,11 @@ The configured observability store must support each API. Call `getObservability
 | `traceQueryTimeToFirstChunkSort` | `trace-query-time-to-first-chunk-sort` | `orderBy` on `timeToFirstChunkMs`                                                      |
 | `traceQueryContextIds`           | `trace-query-context-ids`              | `runId`, `sessionId`, `userId`, and `organizationId` predicates                        |
 | `traceQueryRootSpanFields`       | `trace-query-root-span-fields`         | Trace-scope `name` and `spanType` predicates, dimensions, and `countDistinct` measures |
+| `traceQueryRootEntityId`         | `trace-query-root-entity-id`           | Trace-scope `entityId` predicates, dimensions, and `countDistinct` measures            |
 | `traceQueryDiscovery`            | `trace-query-discovery`                | [Field and value discovery](#discover-fields-and-values)                               |
 | `traceQueryTenantScope`          | `trace-query-tenant-scope`             | [Trusted tenant scope](#trusted-tenant-scope)                                          |
 
-A missing `traceAggregate` value means the server doesn't support aggregation. Servers without the aggregate route return `404`, and stores without the feature return `501 TRACE_AGGREGATE_UNSUPPORTED`. Against a store without a sub-feature, a request that uses a gated field returns `501` before storage runs. Root span `name` and `spanType` are the exception and return `422` with a `field_not_allowed` issue.
+A missing `traceAggregate` value means the server doesn't support aggregation. Servers without the aggregate route return `404`, and stores without the feature return `501 TRACE_AGGREGATE_UNSUPPORTED`. Against a store without a sub-feature, a request that uses a gated field returns `501` before storage runs. Root span `name`, `spanType`, and `entityId` are the exception and return `422` with a `field_not_allowed` issue.
 
 ## Select traces
 
@@ -76,7 +77,7 @@ Span clauses examine the current root span and current child spans. The root `ti
 
 | Predicate context | Fields                                                                                                                                                                                                 | Operators                                                                  |
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
-| Trace             | `traceId`, `threadId`, `resourceId`, `runId`, `sessionId`, `userId`, `organizationId`, `entityName`, `entityType`, `name`, `spanType`, `environment`, `status`                                         | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
+| Trace             | `traceId`, `threadId`, `resourceId`, `runId`, `sessionId`, `userId`, `organizationId`, `entityId`, `entityName`, `entityType`, `name`, `spanType`, `environment`, `status`                             | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
 | Trace metadata    | `metadata.<key>`                                                                                                                                                                                       | `eq`, `ne`, `in`, `notIn`, `exists`, `notExists`                           |
 | Trace             | `startedAt`, `endedAt`, `durationMs`, `timeToFirstChunkMs`                                                                                                                                             | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
 | Trace             | `tags`                                                                                                                                                                                                 | `includes`, `notIncludes`, `exists`, `notExists`                           |
@@ -85,7 +86,7 @@ Span clauses examine the current root span and current child spans. The root `ti
 | Span              | `startedAt`, `endedAt`, `durationMs`, `timeToFirstChunkMs`                                                                                                                                             | `eq`, `ne`, `in`, `notIn`, `lt`, `lte`, `gt`, `gte`, `exists`, `notExists` |
 | Span              | `error`                                                                                                                                                                                                | `exists`, `notExists`                                                      |
 
-Trace-scope `name` and `spanType` read the current root span, so `{ op: 'eq', left: { path: 'spanType' }, right: { literal: 'workflow_run' } }` selects traces started by a workflow run. Inside `spans.some` or `spans.none`, the same fields match any span in the trace.
+Trace-scope `name`, `spanType`, and `entityId` read the current root span, so `{ op: 'eq', left: { path: 'spanType' }, right: { literal: 'workflow_run' } }` selects traces started by a workflow run. Inside `spans.some` or `spans.none`, the same fields match any span in the trace.
 
 Compose predicates with `{ op: 'and', args: [...] }`, `{ op: 'or', args: [...] }`, and `{ op: 'not', arg: ... }`. Comparison predicates place a field reference on the left and a literal on the right. Membership predicates use a field reference in `value` and a homogeneous literal array in `set`. Tag predicates name the stored tag collection in `path`. `includes` and `notIncludes` also take one tag in `value`, while `exists` and `notExists` take only `op` and `path`. See [Filter by tags](#filter-by-tags). Text predicates use the comparison shape with a string literal. See [Filter by text](#filter-by-text).
 
@@ -664,12 +665,13 @@ Unknown fields are rejected. Aggregation isn't paginated. Narrow the selection,
 
 Dimensions read the current root span of each selected trace:
 
-| Dimension                                                                             | Notes                                                                                                            |
-| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `entityType`, `entityName`, `environment`, `status`, `serviceName`, `executionSource` | Root span attributes.                                                                                            |
-| `threadId`, `resourceId`, `userId`, `sessionId`, `organizationId`, `experimentId`     | Context identifiers recorded on the root span.                                                                   |
-| `name`, `spanType`                                                                    | Root span name and type. Requires the `traceQueryRootSpanFields` capability.                                     |
-| `metadata.<key>`                                                                      | One non-empty top-level metadata key. Values are trimmed. Missing, empty, and non-string values group as `null`. |
+| Dimension                                                                             | Notes                                                                                                                                |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `entityType`, `entityName`, `environment`, `status`, `serviceName`, `executionSource` | Root span attributes.                                                                                                                |
+| `threadId`, `resourceId`, `userId`, `sessionId`, `organizationId`, `experimentId`     | Context identifiers recorded on the root span.                                                                                       |
+| `name`, `spanType`                                                                    | Root span name and type. Requires the `traceQueryRootSpanFields` capability.                                                         |
+| `entityId`                                                                            | Root span entity ID. Groups traces that have no `entityName`, such as scorer runs. Requires the `traceQueryRootEntityId` capability. |
+| `metadata.<key>`                                                                      | One non-empty top-level metadata key. Values are trimmed. Missing, empty, and non-string values group as `null`.                     |
 
 Every dimension except `serviceName`, `executionSource`, and `experimentId` is also a trace-scope `where` field, so you can drill into a group by adding its values to the predicate. `traceId`, `spanId`, `runId`, and `requestId` aren't groupable. Traces with no value for a dimension form their own group with a `null` value.
 

package/dist/index.cjs

@@ -6800,48 +6800,40 @@ function hydrateEventTimestamps(event) {
 	return isKnownParsedEvent(event) ? hydrateKnownEvent(event) : 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)
-* resumes the existing conversation rather than forking it.
-*
-* Pass a `scope` to address an independent session over the same resourceId:
-* two sessions with the same resourceId but different scopes have their own
-* run loop, thread binding, and mode/model/state (e.g. one session per git
-* worktree, with the worktree path as the scope). The scope travels on every
-* request as a `sessionScope` query param.
+* A session addressed by its `sessionId` within one agent controller. Sessions
+* are get-or-create on the server, so re-creating the same sessionId resumes
+* the existing conversation rather than forking it. Many sessions can work on
+* one `resourceId` (whose threads and memory they use); each has its own run
+* loop, thread binding, and mode/model/state.
 */
 var AgentControllerSession = class extends BaseResource {
 	controllerId;
-	resourceId;
-	scope;
-	constructor(options, controllerId, resourceId, scope) {
+	sessionId;
+	constructor(options, controllerId, sessionId) {
 		super(options);
 		this.controllerId = controllerId;
-		this.resourceId = resourceId;
-		this.scope = scope;
+		this.sessionId = sessionId;
 	}
 	base() {
-		return `/agent-controller/${encodeURIComponent(this.controllerId)}/sessions/${encodeURIComponent(this.resourceId)}`;
-	}
-	/** Append this session's scope (if any) as a `sessionScope` query param. */
-	url(path) {
-		if (this.scope === void 0) return path;
-		return `${path}${path.includes("?") ? "&" : "?"}sessionScope=${encodeURIComponent(this.scope)}`;
+		return `/agent-controller/${encodeURIComponent(this.controllerId)}/sessions/${encodeURIComponent(this.sessionId)}`;
 	}
 	/**
-	* Create or resume this session. Pass `tags` to scope initial thread
-	* selection — a thread is a resume candidate only when its metadata matches
-	* every tag. Pass `threadId` to bind the session to one exact thread,
-	* creating it with that id when it does not exist.
+	* Create or resume this session. `resourceId` names whose threads and memory
+	* the session works on. Without it the server resumes the session on the
+	* resource it already has (the live session's, or the resource of the thread
+	* with the session's id), falling back to the sessionId. Pass `tags` to scope
+	* initial thread selection — a thread is a resume candidate only when its
+	* metadata matches every tag. Pass `threadId` to bind the session to one
+	* exact thread, creating it with that id when it does not exist.
 	*/
 	create(options) {
 		return this.request(`/agent-controller/${encodeURIComponent(this.controllerId)}/sessions`, {
 			method: "POST",
 			body: {
-				resourceId: this.resourceId,
+				resourceId: options?.resourceId,
+				sessionId: this.sessionId,
 				tags: options?.tags,
-				threadId: options?.threadId,
-				sessionScope: this.scope
+				threadId: options?.threadId
 			}
 		});
 	}
@@ -6897,7 +6889,7 @@ var AgentControllerSession = class extends BaseResource {
 			const abort = new AbortController();
 			currentAbort = abort;
 			let openTimer;
-			const request = this.request(this.url(`${this.base()}/stream`), {
+			const request = this.request(`${this.base()}/stream`, {
 				stream: true,
 				signal: abort.signal
 			});
@@ -7107,7 +7099,7 @@ var AgentControllerSession = class extends BaseResource {
 			files: void 0
 		} : message;
 		const requestContext = parseClientRequestContext(options?.requestContext);
-		await this.request(this.url(`${this.base()}/messages`), {
+		await this.request(`${this.base()}/messages`, {
 			method: "POST",
 			body: {
 				message: content,
@@ -7118,7 +7110,7 @@ var AgentControllerSession = class extends BaseResource {
 	}
 	/** Abort the in-flight run for this session. */
 	async abort() {
-		await this.request(this.url(`${this.base()}/abort`), { method: "POST" });
+		await this.request(`${this.base()}/abort`, { method: "POST" });
 	}
 	/**
 	* Approve or decline a pending tool call (`tool_approval_required`). Resolves
@@ -7126,7 +7118,7 @@ var AgentControllerSession = class extends BaseResource {
 	*/
 	async approveTool(toolCallId, approved, options) {
 		const requestContext = parseClientRequestContext(options?.requestContext);
-		return this.request(this.url(`${this.base()}/tool-approval`), {
+		return this.request(`${this.base()}/tool-approval`, {
 			method: "POST",
 			retries: 0,
 			body: {
@@ -7144,7 +7136,7 @@ var AgentControllerSession = class extends BaseResource {
 	*/
 	async respondToToolSuspension(toolCallId, resumeData, options) {
 		const requestContext = parseClientRequestContext(options?.requestContext);
-		return this.request(this.url(`${this.base()}/tool-suspension`), {
+		return this.request(`${this.base()}/tool-suspension`, {
 			method: "POST",
 			retries: 0,
 			body: {
@@ -7164,7 +7156,7 @@ var AgentControllerSession = class extends BaseResource {
 			files: void 0
 		} : message;
 		const requestContext = parseClientRequestContext(options?.requestContext);
-		await this.request(this.url(`${this.base()}/steer`), {
+		await this.request(`${this.base()}/steer`, {
 			method: "POST",
 			body: {
 				message: content,
@@ -7176,18 +7168,18 @@ var AgentControllerSession = class extends BaseResource {
 	/** Get the current mode, model, and thread (for initial UI hydration). */
 	state(options) {
 		const path = options?.threadId ? `${this.base()}?threadId=${encodeURIComponent(options.threadId)}` : this.base();
-		return this.request(this.url(path));
+		return this.request(path);
 	}
 	/** Merge key-value pairs into the session state. Existing keys not in the payload are preserved. */
 	async setState(updates) {
-		await this.request(this.url(`${this.base()}/state`), {
+		await this.request(`${this.base()}/state`, {
 			method: "PUT",
 			body: { state: updates }
 		});
 	}
 	/** Switch the active mode (e.g. `build`, `plan`). */
 	async switchMode(modeId) {
-		await this.request(this.url(`${this.base()}/mode`), {
+		await this.request(`${this.base()}/mode`, {
 			method: "POST",
 			body: { modeId }
 		});
@@ -7197,7 +7189,7 @@ var AgentControllerSession = class extends BaseResource {
 	* `thinkingLevel` is provided it is applied and persisted with the model.
 	*/
 	async switchModel(modelId, { thinkingLevel } = {}) {
-		await this.request(this.url(`${this.base()}/model`), {
+		await this.request(`${this.base()}/model`, {
 			method: "POST",
 			body: thinkingLevel !== void 0 ? {
 				modelId,
@@ -7218,36 +7210,36 @@ var AgentControllerSession = class extends BaseResource {
 		if (opts.limit != null) params.set("limit", String(opts.limit));
 		if (opts.tags && Object.keys(opts.tags).length > 0) params.set("tags", JSON.stringify(opts.tags));
 		const query = params.toString() ? `?${params.toString()}` : "";
-		return (await this.request(this.url(`${this.base()}/threads${query}`))).threads;
+		return (await this.request(`${this.base()}/threads${query}`)).threads;
 	}
 	/** Switch the session to an existing thread (rebinds stream + state). */
 	async switchThread(threadId) {
-		await this.request(this.url(`${this.base()}/thread`), {
+		await this.request(`${this.base()}/thread`, {
 			method: "POST",
 			body: { threadId }
 		});
 	}
 	/** Create a new thread (unbinds previous, binds the new one). */
 	async createThread(title) {
-		return this.request(this.url(`${this.base()}/threads`), {
+		return this.request(`${this.base()}/threads`, {
 			method: "POST",
 			body: { title }
 		});
 	}
 	/** Delete a thread. If it's the active thread the session unbinds. */
 	async deleteThread(threadId) {
-		await this.request(this.url(`${this.base()}/threads/${encodeURIComponent(threadId)}`), { method: "DELETE" });
+		await this.request(`${this.base()}/threads/${encodeURIComponent(threadId)}`, { method: "DELETE" });
 	}
 	/** Rename a thread. */
 	async renameThread(threadId, title) {
-		await this.request(this.url(`${this.base()}/threads/${encodeURIComponent(threadId)}`), {
+		await this.request(`${this.base()}/threads/${encodeURIComponent(threadId)}`, {
 			method: "PUT",
 			body: { title }
 		});
 	}
 	/** Clone a thread (and its messages). The session binds to the clone. */
 	async cloneThread(options) {
-		return this.request(this.url(`${this.base()}/threads/clone`), {
+		return this.request(`${this.base()}/threads/clone`, {
 			method: "POST",
 			body: options ?? {}
 		});
@@ -7268,7 +7260,7 @@ var AgentControllerSession = class extends BaseResource {
 			if (include) queryParams.set("include", JSON.stringify(include));
 		}
 		const query = queryParams.toString();
-		const body = await this.request(this.url(`${this.base()}/threads/${encodeURIComponent(threadId)}/messages${query ? `?${query}` : ""}`));
+		const body = await this.request(`${this.base()}/threads/${encodeURIComponent(threadId)}/messages${query ? `?${query}` : ""}`);
 		const messages = body.messages.map(hydrateMessage);
 		if (legacy) return messages;
 		return {
@@ -7287,7 +7279,7 @@ var AgentControllerSession = class extends BaseResource {
 			files: void 0
 		} : message;
 		const requestContext = parseClientRequestContext(options?.requestContext);
-		await this.request(this.url(`${this.base()}/follow-up`), {
+		await this.request(`${this.base()}/follow-up`, {
 			method: "POST",
 			body: {
 				message: content,
@@ -7298,26 +7290,26 @@ var AgentControllerSession = class extends BaseResource {
 	}
 	/** Get the observational memory record for this session's thread. */
 	async getOMRecord() {
-		return (await this.request(this.url(`${this.base()}/om`))).record;
+		return (await this.request(`${this.base()}/om`)).record;
 	}
 	/** Change the session's resource identity. */
 	async setResourceId(newResourceId) {
-		await this.request(this.url(`${this.base()}/resource`), {
+		await this.request(`${this.base()}/resource`, {
 			method: "POST",
 			body: { newResourceId }
 		});
 	}
 	/** Get known resource IDs for this session. */
 	async getResourceIds() {
-		return (await this.request(this.url(`${this.base()}/resources`))).resourceIds;
+		return (await this.request(`${this.base()}/resources`)).resourceIds;
 	}
 	/** Get the current goal for this session's thread. */
 	async getGoal() {
-		return (await this.request(this.url(`${this.base()}/goal`))).goal;
+		return (await this.request(`${this.base()}/goal`)).goal;
 	}
 	/** Set a new goal objective. The agent's in-loop judge evaluates progress after each turn. */
 	async setGoal(objective, options) {
-		return (await this.request(this.url(`${this.base()}/goal`), {
+		return (await this.request(`${this.base()}/goal`, {
 			method: "POST",
 			body: {
 				objective,
@@ -7327,22 +7319,22 @@ var AgentControllerSession = class extends BaseResource {
 	}
 	/** Update goal options (judge model, max runs, status). */
 	async updateGoal(options) {
-		return (await this.request(this.url(`${this.base()}/goal`), {
+		return (await this.request(`${this.base()}/goal`, {
 			method: "PUT",
 			body: options
 		})).goal;
 	}
 	/** Clear the current goal. */
 	async clearGoal() {
-		await this.request(this.url(`${this.base()}/goal`), { method: "DELETE" });
+		await this.request(`${this.base()}/goal`, { method: "DELETE" });
 	}
 	/** Get the current permission rules (per-category and per-tool policies). */
 	async getPermissions() {
-		return this.request(this.url(`${this.base()}/permissions`));
+		return this.request(`${this.base()}/permissions`);
 	}
 	/** Set the approval policy for a tool category. */
 	async setPermissionForCategory(category, policy) {
-		await this.request(this.url(`${this.base()}/permissions/category`), {
+		await this.request(`${this.base()}/permissions/category`, {
 			method: "PUT",
 			body: {
 				category,
@@ -7352,7 +7344,7 @@ var AgentControllerSession = class extends BaseResource {
 	}
 	/** Set the approval policy for a specific tool. */
 	async setPermissionForTool(toolName, policy) {
-		await this.request(this.url(`${this.base()}/permissions/tool`), {
+		await this.request(`${this.base()}/permissions/tool`, {
 			method: "PUT",
 			body: {
 				toolName,
@@ -7366,7 +7358,7 @@ var AgentControllerSession = class extends BaseResource {
 	* or is persisted for later.
 	*/
 	async sendNotification(input) {
-		return this.request(this.url(`${this.base()}/notifications`), {
+		return this.request(`${this.base()}/notifications`, {
 			method: "POST",
 			body: input
 		});
@@ -7399,12 +7391,11 @@ var AgentController = class extends BaseResource {
 		return this.request(`${this.basePath()}/workspace`);
 	}
 	/**
-	* Scope to a session bound to `resourceId` (e.g. a user or conversation id).
-	* Pass `scope` to address an independent session over the same resourceId
-	* (e.g. one session per git worktree, with the worktree path as the scope).
+	* Address the session with this `sessionId`. Sessions created without an
+	* explicit id are addressed by their `resourceId`.
 	*/
-	session(resourceId, scope) {
-		return new AgentControllerSession(this.options, this.controllerId, resourceId, scope);
+	session(sessionId) {
+		return new AgentControllerSession(this.options, this.controllerId, sessionId);
 	}
 };
 /** Pull the plain text out of an assistant message's nested content parts. */
@@ -7478,7 +7469,7 @@ var MastraClient = class extends BaseResource {
 	}
 	/**
 	* Scopes to an agent controller hosted on the connected Mastra instance. Use
-	* `getAgentController(id).session(resourceId)` to create/resume a session,
+	* `getAgentController(id).session(sessionId)` to create/resume a session,
 	* stream its events, and send messages.
 	* @param controllerId - The id the agent controller is registered under on Mastra
 	*/