@mastra/mcp-docs-server 1.1.49-alpha.1 → 1.1.49-alpha.2

package/.docs/reference/harness/session.md

@@ -0,0 +1,429 @@
+# Session class
+
+> **Alpha:** The `Harness` feature is in alpha stage and subject to breaking changes in minor versions until it graduates from its alpha status.
+
+A `Session` owns all the state tied to a single conversation. The [`Harness`](https://mastra.ai/reference/harness/harness-class) is the shared host — agents, storage, config, the thread lock, and the event bus — while the `Session` holds everything that is per-conversation: identity, the active thread binding and reads, mode and model selection, run and abort state, the live agent stream, tool suspensions, follow-ups, approvals, permission grants, token usage, and the display-state snapshot.
+
+Access the session through `harness.session`.
+
+For a conceptual introduction, see the [Harness overview](https://mastra.ai/docs/harness/overview).
+
+## Usage example
+
+```typescript
+// Read per-conversation state through harness.session
+const modeId = harness.session.mode.get()
+const modelId = harness.session.model.get()
+const threadId = harness.session.thread.getId()
+const grants = harness.session.getGrants()
+
+// Render from the coalesced display-state snapshot
+harness.subscribe(event => {
+  if (event.type === 'display_state_changed') {
+    render(harness.session.displayState.get())
+  }
+})
+```
+
+## Properties
+
+The session is organized into sub-objects, each owning one domain of per-conversation state.
+
+**identity** (`SessionIdentity`): Resource identity for the conversation. See identity methods below.
+
+**thread** (`SessionThread`): Active thread binding and thread/message reads. See thread methods below.
+
+**mode** (`SessionMode`): Active mode selection. See mode methods below.
+
+**model** (`SessionModel`): Active model selection, including per-mode persistence. See model methods below.
+
+**run** (`SessionRun`): Run and trace identity plus abort state for the in-flight run. See run methods below.
+
+**stream** (`SessionStream`): The live subscription to the agent thread stream. See stream methods below.
+
+**suspensions** (`SessionSuspensions`): Parked interactive tool calls awaiting a resume. See suspensions methods below.
+
+**followUps** (`SessionFollowUps`): Queue of messages submitted while a run is in progress. See follow-up methods below.
+
+**approval** (`SessionApproval`): The pending tool-approval gate. See approval methods below.
+
+**displayState** (`SessionDisplayState`): The canonical HarnessDisplayState snapshot a UI renders from. See display-state methods below.
+
+**state** (`SessionState<TState>`): The schema-validated, session-owned Harness state. See state methods below.
+
+## Methods
+
+### Permissions
+
+Session-scoped grants auto-approve tools without prompting. Grants are ephemeral — they reset when the session restarts and are never persisted.
+
+#### `grantCategory(category)`
+
+Grant a tool category for the current session. Tools in this category are auto-approved.
+
+```typescript
+harness.session.grantCategory('edit')
+```
+
+#### `grantTool(toolName)`
+
+Grant a specific tool for the current session.
+
+```typescript
+harness.session.grantTool('mastra_workspace_execute_command')
+```
+
+#### `getGrants()`
+
+Return the currently granted categories and tools.
+
+```typescript
+const grants = harness.session.getGrants()
+// { categories: string[], tools: string[] }
+```
+
+### Tool approvals
+
+#### `respondToToolApproval({ decision, requestContext? })`
+
+Respond to a pending tool approval request, raised by a `tool_approval_required` event. Pass `always_allow_category` to also grant the tool's whole category for the rest of the session.
+
+```typescript
+harness.session.respondToToolApproval({ decision: 'approve' })
+harness.session.respondToToolApproval({ decision: 'decline' })
+harness.session.respondToToolApproval({ decision: 'always_allow_category' })
+```
+
+### Run control
+
+#### `getCurrentRunId()`
+
+Return the run ID of the in-flight run, or `null` when idle. Prefers the live stream's active run, falling back to the last stored run ID.
+
+```typescript
+const runId = harness.session.getCurrentRunId()
+```
+
+#### `abortRun()`
+
+Abort the in-flight run: aborts the live stream, requests abort on the run, and clears parked tool suspensions.
+
+```typescript
+harness.session.abortRun()
+```
+
+### Token usage
+
+#### `getTokenUsage()`
+
+Return a copy of the running token-usage tally for the active thread.
+
+```typescript
+const usage = harness.session.getTokenUsage()
+// { promptTokens, completionTokens, totalTokens, ... }
+```
+
+## Identity
+
+`session.identity` owns the resource ID for the conversation.
+
+### `session.identity.getResourceId()`
+
+Return the current resource ID.
+
+```typescript
+const resourceId = harness.session.identity.getResourceId()
+```
+
+### `session.identity.getDefaultResourceId()`
+
+Return the resource ID the session was created with.
+
+```typescript
+const defaultResourceId = harness.session.identity.getDefaultResourceId()
+```
+
+To change the resource ID, use [`harness.setResourceId()`](https://mastra.ai/reference/harness/harness-class), which also tears down the active thread.
+
+## Thread
+
+`session.thread` owns the active thread binding plus thread and message reads. Thread lifecycle (create, switch, clone, delete, rename) lives on the [`Harness`](https://mastra.ai/reference/harness/harness-class) because it coordinates the shared thread lock and event bus.
+
+### `session.thread.getId()`
+
+Return the active thread ID, or `null` when no thread is bound.
+
+```typescript
+const threadId = harness.session.thread.getId()
+```
+
+### `session.thread.list(options?)`
+
+List threads from storage. By default only threads for the current resource are returned, and transient forked subagent threads are hidden.
+
+```typescript
+const threads = await harness.session.thread.list()
+const allThreads = await harness.session.thread.list({ allResources: true })
+const everything = await harness.session.thread.list({ includeForkedSubagents: true })
+```
+
+### `session.thread.getById({ threadId })`
+
+Return a single thread by ID, or `null` if it doesn't exist.
+
+```typescript
+const thread = await harness.session.thread.getById({ threadId: 'thread-abc123' })
+```
+
+### `session.thread.listActiveMessages(options?)`
+
+Retrieve messages for the active thread. Returns an empty array when no thread is bound.
+
+```typescript
+const messages = await harness.session.thread.listActiveMessages({ limit: 50 })
+```
+
+### `session.thread.listMessages({ threadId, limit? })`
+
+Retrieve messages for a specific thread.
+
+```typescript
+const messages = await harness.session.thread.listMessages({ threadId: 'thread-abc123' })
+```
+
+### `session.thread.firstUserMessage({ threadId })`
+
+Retrieve the first user message for a thread, or `null` if none.
+
+```typescript
+const firstMsg = await harness.session.thread.firstUserMessage({ threadId: 'thread-abc123' })
+```
+
+### `session.thread.firstUserMessages({ threadIds })`
+
+Retrieve the first user message for many threads at once, returned as a map.
+
+```typescript
+const firstByThread = await harness.session.thread.firstUserMessages({
+  threadIds: ['thread-a', 'thread-b'],
+})
+```
+
+### `session.thread.getSetting({ key })` / `setSetting({ key, value })` / `deleteSetting({ key })`
+
+Read, write, and remove per-thread settings stored on the active thread's metadata.
+
+```typescript
+await harness.session.thread.setSetting({ key: 'omThreshold', value: 0.8 })
+const value = await harness.session.thread.getSetting({ key: 'omThreshold' })
+await harness.session.thread.deleteSetting({ key: 'omThreshold' })
+```
+
+## Mode
+
+`session.mode` owns the active mode selection. Switching modes is performed on the [`Harness`](https://mastra.ai/reference/harness/harness-class) because it emits events and rebinds the stream.
+
+### `session.mode.get()`
+
+Return the active mode ID.
+
+```typescript
+const modeId = harness.session.mode.get()
+```
+
+### `session.mode.resolve()`
+
+Return the full `HarnessMode` object for the active mode, resolved against the harness's configured modes.
+
+```typescript
+const mode = harness.session.mode.resolve()
+```
+
+## Model
+
+`session.model` owns the active model selection, including per-mode model memory. Switching models is performed on the [`Harness`](https://mastra.ai/reference/harness/harness-class).
+
+### `session.model.get()`
+
+Return the active model ID.
+
+```typescript
+const modelId = harness.session.model.get()
+```
+
+### `session.model.hasSelection()`
+
+Check whether a model is currently selected.
+
+```typescript
+if (harness.session.model.hasSelection()) {
+  // Ready to send messages
+}
+```
+
+## Run
+
+`session.run` owns run and trace identity plus abort state for the in-flight run.
+
+### `session.run.getRunId()` / `getTraceId()`
+
+Return the stored run ID and trace ID for the current run, or `null` when idle.
+
+```typescript
+const runId = harness.session.run.getRunId()
+const traceId = harness.session.run.getTraceId()
+```
+
+### `session.run.isRunning()`
+
+Return whether a run is currently in progress.
+
+```typescript
+if (harness.session.run.isRunning()) {
+  // A run is active
+}
+```
+
+## Stream
+
+`session.stream` owns the live subscription to the agent thread stream and its dedup key.
+
+### `session.stream.activeRunId()`
+
+Return the run ID active on the live stream, or `null` when no stream is open.
+
+```typescript
+const runId = harness.session.stream.activeRunId()
+```
+
+### `session.stream.isActive()`
+
+Return whether the stream currently has an active run.
+
+```typescript
+if (harness.session.stream.isActive()) {
+  // The current thread's stream is producing output
+}
+```
+
+## Suspensions
+
+`session.suspensions` owns parked interactive tool calls (such as `ask_user` and `request_access`) awaiting a resume.
+
+### `session.suspensions.hasPending()`
+
+Return whether any tool is currently suspended.
+
+```typescript
+if (harness.session.suspensions.hasPending()) {
+  // At least one interactive tool is waiting for a response
+}
+```
+
+### `session.suspensions.has({ toolCallId })`
+
+Return whether a specific tool call is suspended.
+
+```typescript
+const waiting = harness.session.suspensions.has({ toolCallId: event.toolCallId })
+```
+
+Resume a suspended tool with [`harness.respondToToolSuspension()`](https://mastra.ai/reference/harness/harness-class).
+
+## Follow-ups
+
+`session.followUps` owns the FIFO queue of messages submitted while a run is in progress.
+
+### `session.followUps.count()`
+
+Return the number of queued follow-ups.
+
+```typescript
+const queued = harness.session.followUps.count()
+```
+
+### `session.followUps.isEmpty()`
+
+Return whether the follow-up queue is empty.
+
+```typescript
+if (!harness.session.followUps.isEmpty()) {
+  // Messages are waiting to be processed
+}
+```
+
+## Approval
+
+`session.approval` owns the pending tool-approval gate.
+
+### `session.approval.isArmed()`
+
+Return whether a tool is currently awaiting an approval decision.
+
+```typescript
+if (harness.session.approval.isArmed()) {
+  // Show the approval prompt
+}
+```
+
+Respond with [`session.respondToToolApproval()`](#respondtotoolapproval-decision-requestcontext-).
+
+## Display state
+
+`session.displayState` owns the canonical `HarnessDisplayState` snapshot a UI renders from, and the reducer that keeps it in sync with every harness event.
+
+### `session.displayState.get()`
+
+Return the current `HarnessDisplayState` snapshot for UI rendering.
+
+```typescript
+const displayState = harness.session.displayState.get()
+```
+
+### `session.displayState.restoreTasks(tasks)`
+
+Restore the task portion of the snapshot after a UI replays persisted task tool history. This is a pure update of the snapshot and does not emit an event, so re-render explicitly after calling it.
+
+```typescript
+harness.session.displayState.restoreTasks(replayedTasks)
+```
+
+After every event the harness emits `display_state_changed`, so high-frequency events such as `message_update`, `tool_update`, and `tool_input_delta` are coalesced into the next snapshot. Subscribe with [`harness.subscribe()`](https://mastra.ai/reference/harness/harness-class) and read the latest snapshot from `session.displayState.get()`.
+
+## State
+
+`session.state` owns the schema-validated Harness state for the conversation. It holds the current snapshot, validates updates against the `stateSchema` passed to the Harness, serializes concurrent writes, and emits a `state_changed` event on every change.
+
+### `session.state.get()`
+
+Return a readonly copy of the current state snapshot.
+
+```typescript
+const state = harness.session.state.get()
+```
+
+### `session.state.set(updates)`
+
+Merge a partial update into the state. Updates are queued so concurrent calls apply in order, validated against the schema, and emit `state_changed` with the changed keys.
+
+```typescript
+await harness.session.state.set({ yolo: true })
+```
+
+### `session.state.update(updater)`
+
+Run an updater against the current snapshot and apply its result atomically within the write queue. Use this for read-modify-write changes that must see the latest state. The updater returns `updates` to merge, optional `events` to emit, and a `result` value that `update()` resolves to.
+
+```typescript
+const added = await harness.session.state.update(current => ({
+  updates: { count: (current.count ?? 0) + 1 },
+  result: (current.count ?? 0) + 1,
+}))
+```
+
+## Related
+
+- [Harness class](https://mastra.ai/reference/harness/harness-class)
+- [Harness overview](https://mastra.ai/docs/harness/overview)
+- [Threads and state](https://mastra.ai/docs/harness/threads-and-state)
+- [Tool approvals](https://mastra.ai/docs/harness/tool-approvals)

package/.docs/reference/index.md

@@ -159,6 +159,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.update()](https://mastra.ai/reference/datasets/update)
 - [.updateItem()](https://mastra.ai/reference/datasets/updateItem)
 - [Harness Class](https://mastra.ai/reference/harness/harness-class)
+- [Session Class](https://mastra.ai/reference/harness/session)
 - [API Reference](https://mastra.ai/reference/mastra-platform/api)
 - [Cloned Thread Utilities](https://mastra.ai/reference/memory/clone-utilities)
 - [Memory Class](https://mastra.ai/reference/memory/memory-class)

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.1.49-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [[`339c57c`](https://github.com/mastra-ai/mastra/commit/339c57c5b2c6dbe75a125e138228e0556528976f), [`1dd4117`](https://github.com/mastra-ai/mastra/commit/1dd4117dcbd8e031ede9f0489436bfbc6f0315b8), [`2b11d1f`](https://github.com/mastra-ai/mastra/commit/2b11d1f6ac7024c5dd2b2dd12a48a956ac9d63bd), [`49af8df`](https://github.com/mastra-ai/mastra/commit/49af8df589c4ff71a5015a4553b377b32704b691), [`30ce559`](https://github.com/mastra-ai/mastra/commit/30ce55902ecf819b8ab8697398dd68b108228063), [`c241b92`](https://github.com/mastra-ai/mastra/commit/c241b929dc8c8d6a7b7219c99ed13ac1f3124a77), [`7d6ff70`](https://github.com/mastra-ai/mastra/commit/7d6ff708727297a0526ca0e26e93eeb5bbaaa187)]:
+  - @mastra/core@1.44.0-alpha.2
+
 ## 1.1.49-alpha.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.1.49-alpha.1",
+  "version": "1.1.49-alpha.2",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.44.0-alpha.1",
+    "@mastra/core": "1.44.0-alpha.2",
     "@mastra/mcp": "^1.10.1-alpha.0"
   },
   "devDependencies": {
@@ -45,9 +45,9 @@
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
     "vitest": "4.1.8",
-    "@internal/lint": "0.0.105",
     "@internal/types-builder": "0.0.80",
-    "@mastra/core": "1.44.0-alpha.1"
+    "@internal/lint": "0.0.105",
+    "@mastra/core": "1.44.0-alpha.2"
   },
   "homepage": "https://mastra.ai",
   "repository": {