@mastra/mcp-docs-server 1.2.2 → 1.2.3-alpha.3

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

@@ -1,143 +0,0 @@
-# Session
-
-A [`Session`](https://mastra.ai/reference/harness/session) holds the live state of a Harness: who the session is for, which thread is active, the selected mode and model, permission grants, queued follow-ups, token usage, application state, and the display snapshot. You reach it through `harness.session`.
-
-## What the Session tracks
-
-The Session is the live state of a single user's interaction with the Harness. It answers "what is true right now": who the session belongs to, which thread is currently bound, which mode and model are selected, what the user has approved, what's queued or running, the application state, and the snapshot to render. A session has one active thread at a time but can list, switch between, and clone many threads over its lifetime. Anything that describes the current state lives here; the Harness owns the shared infrastructure every session runs on.
-
-Because each session has its own identity and state, one Harness can serve many users at once — each backed by its own Session — without one session's mode, grants, or active thread leaking into another.
-
-The rest of this page walks through the Session's state. Each part is a focused sub-object on `harness.session`:
-
-- **Who and where**: [Identity](#identity) sets the stable session `id`, `ownerId`, and resource the session belongs to, and [Thread](#thread) tracks the currently bound thread.
-- **How the agent behaves**: [Mode and model](#mode-and-model) controls which agent profile and model are active, and [Permission grants](#permission-grants) records what the user has approved to run without prompting.
-- **What's happening right now**: [Run state](#run-state) reflects the in-flight generation, and [Follow-ups](#follow-ups) holds messages queued to send when it finishes.
-- **What you store and render**: [State](#state) holds your application's structured data, and [Display state](#display-state) is the single snapshot your UI renders from.
-
-The Harness performs actions that change this state — switching threads, modes, or models — because those operations coordinate shared infrastructure and emit events. The Session is where you read the result. The sections below note this split where it matters.
-
-## Identity
-
-`session.identity` holds three stable identifiers for the conversation: a session `id`, an `ownerId`, and the resource ID. Threads are scoped to a resource ID, so this is what groups a conversation's threads together:
-
-```typescript
-const sessionId = harness.session.identity.getId()
-const ownerId = harness.session.identity.getOwnerId()
-const resourceId = harness.session.identity.getResourceId()
-const threadId = harness.session.thread.getId()
-```
-
-The session `id` and `ownerId` are stable for the life of the session — they don't change when the resource ID is switched. They mirror the `id` and `ownerId` fields on `SessionRecord` in storage, so storage layers can key sessions by a stable identifier rather than the mutable resource ID.
-
-The resource ID is set when creating a session via [`harness.createSession()`](https://mastra.ai/reference/harness/harness-class) and defaults to the harness `id`. See [Resource IDs](https://mastra.ai/docs/harness/threads-and-state) for how it scopes threads.
-
-## Thread
-
-`session.thread` owns the active thread binding and read access to threads and messages. The Harness performs lifecycle transitions; the Session reads the result:
-
-```typescript
-// Lifecycle transitions live on the Harness
-await harness.switchThread({ threadId: 'thread-abc123' })
-
-// Reads live on the Session
-const threads = await harness.session.thread.list()
-const messages = await harness.session.thread.listActiveMessages()
-```
-
-See [Threads and state](https://mastra.ai/docs/harness/threads-and-state) for the full lifecycle.
-
-## Mode and model
-
-The Harness defines the available modes in `config.modes`. The Session tracks which mode and model are _currently_ selected:
-
-```typescript
-// Switch mode (aborts the run, emits events)
-await harness.session.mode.switch({ modeId: 'build' })
-
-// Read the current selection (Session state)
-const modeId = harness.session.mode.get()
-const mode = harness.session.mode.resolve()
-const modelId = harness.session.model.get()
-```
-
-See [Modes](https://mastra.ai/docs/harness/modes) for how modes carry their own model.
-
-## Permission grants
-
-The Harness owns permission _policy_ — which categories or tools require approval. The Session owns the _grants_ a user makes during the conversation. A grant lets a tool run for the rest of the session without prompting again:
-
-```typescript
-// Grant a category or tool for the rest of the session
-harness.session.grantCategory('edit')
-harness.session.grantTool('mastra_workspace_execute_command')
-
-// Inspect current grants
-const grants = harness.session.getGrants()
-```
-
-Grants are intentionally in-memory and reset when the session restarts. See [Tool approvals](https://mastra.ai/docs/harness/tool-approvals) for the approval flow.
-
-## Run state
-
-`session.run` tracks the in-flight generation: whether a run is active, its run and trace IDs, and the abort signal. Use it to reflect run status in your UI:
-
-```typescript
-if (harness.session.run.isRunning()) {
-  // show a stop button
-}
-
-// Abort the active run (Harness orchestration clears related state)
-harness.abort()
-```
-
-## Follow-ups
-
-A user may want to add to the conversation while the agent is still working. Instead of dropping or interrupting those messages, the Session queues them on `session.followUps` and sends them when the current run finishes:
-
-```typescript
-const queued = harness.session.followUps.count()
-```
-
-Queue a follow-up with `harness.followUp({ content })`. To redirect the agent mid-run instead of waiting, use `harness.steer({ content })`. Both build on [signals](https://mastra.ai/docs/agents/signals).
-
-## State
-
-`session.state` holds the conversation's application state — structured values that agents and the UI share, such as model preferences, feature flags, or progress. The Harness defines the shape with a `stateSchema`; the Session owns the live snapshot, validates updates against the schema, and emits `state_changed` on every write:
-
-```typescript
-const state = harness.session.state.get()
-await harness.session.state.set({ theme: 'light' })
-```
-
-See [Threads and state](https://mastra.ai/docs/harness/threads-and-state) for defining a schema.
-
-## Display state
-
-A conversation emits many fine-grained events: tokens streaming in, tools starting and finishing, approvals pending, tasks updating, token usage climbing. Subscribing to each event type and reassembling the current picture yourself is tedious and error-prone. `session.displayState` does that work for you.
-
-It's a reducer-maintained snapshot. The Session keeps one `HarnessDisplayState` object and folds every harness event into it as it happens, so the snapshot always reflects the latest state. It captures everything a UI needs to render: whether the agent is running and what it's streaming, which tools and subagents are active, anything waiting on the user such as approvals, the current task list, and running totals like token usage and queued follow-ups.
-
-Because it's a single object, you can drive an entire UI from one place: read the current snapshot with `get()`, and re-render whenever the Harness emits `display_state_changed` (fired after every other event):
-
-```typescript
-const snapshot = harness.session.displayState.get()
-
-// Re-render from the snapshot on every change
-harness.subscribe(event => {
-  if (event.type === 'display_state_changed') {
-    render(harness.session.displayState.get())
-  }
-})
-```
-
-This is the recommended pattern for most UIs. Subscribe to individual typed events only when you need to react to a specific transition rather than re-render the whole view.
-
-> **Note:** Visit the [Session reference](https://mastra.ai/reference/harness/session) for the full list of sub-objects and method signatures.
-
-## Related
-
-- [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)
-- [Session reference](https://mastra.ai/reference/harness/session)

package/.docs/docs/harness/threads-and-state.md

@@ -1,141 +0,0 @@
-# Threads and state
-
-Threads and state are how a Harness conversation survives beyond a single exchange. A **thread** is the persistent record of a conversation — its messages and metadata, saved to storage so a user can close the app and resume the same conversation later, or switch between several conversations. **State** is structured data attached to the conversation — values like model preferences, feature flags, or progress — that agents and your UI read and write as the conversation runs.
-
-The two work together: the thread is the message history, and state is the shared scratchpad alongside it. Both persist across mode switches, model changes, and restarts, so nothing is lost when a user switches from plan mode to build mode or reopens the app the next day.
-
-Thread _lifecycle_ transitions — create, switch, clone, delete — live on the Harness because they coordinate the shared thread lock and emit events. The active thread binding and thread/message _reads_ live on the [`Session`](https://mastra.ai/docs/harness/session) as `harness.session.thread`.
-
-## Threads
-
-A thread holds one conversation's full message history. The Harness binds the Session to one active thread at a time; messages you send and the agent's replies are appended to that thread and saved to storage. Threads let users resume a past conversation, keep several conversations side by side, or branch one into alternatives.
-
-### Creating and selecting threads
-
-On startup, call `selectOrCreateThread()` to resume the most recent thread or create a new one:
-
-```typescript
-await harness.init()
-const thread = await harness.selectOrCreateThread()
-```
-
-Create a thread explicitly with a title:
-
-```typescript
-const thread = await harness.createThread({ title: 'New conversation' })
-```
-
-### Switching threads
-
-Switch to an existing thread. The harness aborts any in-progress generation, acquires a lock on the new thread, and emits a `thread_changed` event:
-
-```typescript
-await harness.switchThread({ threadId: 'thread-abc123' })
-```
-
-### Listing threads
-
-List threads for the current resource. Forked subagent threads are hidden by default:
-
-```typescript
-const threads = await harness.session.thread.list()
-
-// Include all resources
-const allThreads = await harness.session.thread.list({ allResources: true })
-```
-
-### Cloning threads
-
-Clone a thread to create a branch of the conversation. The harness copies all messages and switches to the clone:
-
-```typescript
-const cloned = await harness.cloneThread({ title: 'Alternative approach' })
-```
-
-### Thread locking
-
-Pass a `threadLock` to the Harness constructor to prevent concurrent access from multiple processes. The lock is acquired before any thread operation and released on switch or delete:
-
-```typescript
-const harness = new Harness({
-  id: 'my-agent',
-  threadLock: {
-    acquire: async threadId => {
-      /* acquire lock or throw */
-    },
-    release: async threadId => {
-      /* release lock */
-    },
-  },
-})
-```
-
-## State
-
-Where a thread stores the conversation's messages, state stores structured values that describe the conversation but aren't messages — model preferences, feature flags, UI settings, or progress markers. Agents can read and update state during a run, and your UI can react to changes, so state is how the agent and the interface stay in sync on shared facts. You define its shape with a schema, and every update is validated against that schema before it's applied.
-
-### Defining a state schema
-
-Pass a `stateSchema` (Standard JSON Schema) to validate state and extract defaults:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { Harness } from '@mastra/core/harness'
-import { z } from 'zod'
-
-const agent = new Agent({
-  name: 'assistant',
-  instructions: 'Help the user manage a stateful session.',
-  model: 'openai/gpt-5.5',
-})
-
-const harness = new Harness({
-  id: 'stateful-agent',
-  agent,
-  modes: [{ id: 'default', name: 'Default', metadata: { default: true } }],
-  stateSchema: z.object({
-    currentModelId: z.string().optional(),
-    theme: z.enum(['light', 'dark']).default('dark'),
-  }),
-})
-```
-
-### Reading and writing state
-
-State is owned by the [`Session`](https://mastra.ai/docs/harness/session) as `harness.session.state`:
-
-```typescript
-// Read the current state snapshot
-const state = harness.session.state.get()
-
-// Update state — validates against schema and emits state_changed
-await harness.session.state.set({ theme: 'light' })
-```
-
-State changes emit a `state_changed` event with the new state and the set of changed keys.
-
-## Resource IDs
-
-Threads are scoped to a resource ID, which groups a conversation's threads by project, user, or workspace. Set it on the Harness constructor; it defaults to the harness `id` when omitted:
-
-```typescript
-const harness = new Harness({
-  id: 'my-agent',
-  resourceId: 'project-xyz',
-})
-```
-
-The resource ID is part of a conversation's identity, so you read it from the Session:
-
-```typescript
-const resourceId = harness.session.identity.getResourceId()
-```
-
-The session also has a stable `id` and `ownerId` (read with `session.identity.getId()` and `session.identity.getOwnerId()`). Unlike the resource ID, these don't change when you switch resources — see [Session identity](https://mastra.ai/docs/harness/session) for details.
-
-## Related
-
-- [Harness overview](https://mastra.ai/docs/harness/overview)
-- [Session](https://mastra.ai/docs/harness/session)
-- [Modes](https://mastra.ai/docs/harness/modes)
-- [API reference](https://mastra.ai/reference/harness/harness-class)