@mastra/mcp-docs-server 1.2.2-alpha.1 → 1.2.2-alpha.4

package/.docs/reference/evals/checks.md

@@ -0,0 +1,210 @@
+# Quick Checks
+
+Quick Checks are zero-LLM, composable micro-scorers for common assertions. They plug into the existing `scorers: [...]` array anywhere scorers are used — in `runEvals`, live scoring, experiments, and Studio.
+
+Internally they are standard `createScorer()` instances, so they have the same observability, storage, and pipeline integration as any other scorer.
+
+## Usage example
+
+```typescript
+import { checks } from '@mastra/evals/checks'
+import { runEvals } from '@mastra/core/evals'
+import { myAgent } from '../agents'
+
+const result = await runEvals({
+  data: [{ input: 'What is the weather in Brooklyn?' }],
+  target: myAgent,
+  scorers: [
+    checks.includes('sunny'),
+    checks.calledTool('get_weather'),
+    checks.toolOrder(['get_weather', 'summarize']),
+    checks.noToolErrors(),
+  ],
+})
+
+console.log(result.scores)
+```
+
+## Text checks
+
+### `checks.includes(expected, options?)`
+
+Scores 1 if the agent's output text contains the expected substring, 0 otherwise.
+
+```typescript
+checks.includes('sunny')
+checks.includes('Sunny', { ignoreCase: false })
+```
+
+**expected** (`string`): Substring to search for in the output.
+
+**options.ignoreCase** (`boolean`): Case-insensitive matching. (Default: `true`)
+
+Returns: `1` if found, `0` otherwise.
+
+### `checks.excludes(unwanted, options?)`
+
+Scores 1 if the agent's output text does NOT contain the substring, 0 otherwise.
+
+```typescript
+checks.excludes('error')
+checks.excludes('Error', { ignoreCase: false })
+```
+
+**unwanted** (`string`): Substring that must not appear in the output.
+
+**options.ignoreCase** (`boolean`): Case-insensitive matching. (Default: `true`)
+
+Returns: `1` if absent, `0` otherwise.
+
+### `checks.equals(expected, options?)`
+
+Scores 1 if the output text exactly equals the expected string after optional normalization.
+
+```typescript
+checks.equals('Hello, world!')
+checks.equals('Hello', { ignoreCase: false })
+```
+
+**expected** (`string`): Exact string the output must match.
+
+**options.ignoreCase** (`boolean`): Case-insensitive matching. (Default: `true`)
+
+Returns: `1` if equal, `0` otherwise.
+
+### `checks.matches(pattern, options?)`
+
+Scores 1 if the output matches the given regular expression.
+
+```typescript
+checks.matches(/\d+°[FC]/)
+checks.matches(/^hello$/, { exact: true })
+```
+
+**pattern** (`RegExp`): Regular expression to test against the output.
+
+**options.exact** (`boolean`): Anchor the pattern to match the entire output (adds ^ and $). (Default: `false`)
+
+Returns: `1` if matched, `0` otherwise.
+
+### `checks.similarity(expected, options?)`
+
+Returns the string similarity score (0-1) between the output and an expected string using the Dice coefficient. When a `threshold` is set, returns binary 1/0 instead.
+
+```typescript
+checks.similarity('Sunny, 72°F')
+checks.similarity('Sunny, 72°F', { threshold: 0.7 })
+```
+
+**expected** (`string`): Reference string to compare against.
+
+**options.threshold** (`number`): Minimum similarity score (0-1) to return 1. When omitted, returns the raw similarity score.
+
+**options.ignoreCase** (`boolean`): Case-insensitive comparison. (Default: `true`)
+
+Returns: Raw similarity score (0-1), or binary `1`/`0` when `threshold` is set.
+
+## Tool call checks
+
+### `checks.calledTool(toolName, options?)`
+
+Scores 1 if the agent called the specified tool at least the required number of times.
+
+```typescript
+checks.calledTool('get_weather')
+checks.calledTool('search', { times: 2 })
+```
+
+**toolName** (`string`): Name of the tool to look for.
+
+**options.times** (`number`): Minimum number of times the tool must be called. (Default: `1`)
+
+Returns: `1` if called at least `times` times, `0` otherwise.
+
+### `checks.didNotCall(toolName)`
+
+Scores 1 if the agent did NOT call the specified tool.
+
+```typescript
+checks.didNotCall('delete_user')
+```
+
+**toolName** (`string`): Name of the tool that must not appear.
+
+Returns: `1` if the tool was not called, `0` otherwise.
+
+### `checks.toolOrder(expectedOrder)`
+
+Scores 1 if the tools were called in the specified order. Uses relaxed matching — other tool calls between the expected tools are allowed.
+
+```typescript
+checks.toolOrder(['search', 'summarize', 'respond'])
+```
+
+**expectedOrder** (`string[]`): Tool names in the expected calling sequence. Must appear as a subsequence of the actual tool calls.
+
+Returns: `1` if the expected order is satisfied, `0` otherwise.
+
+### `checks.maxToolCalls(max)`
+
+Scores 1 if the agent used no more than `max` tool calls.
+
+```typescript
+checks.maxToolCalls(5)
+```
+
+**max** (`number`): Maximum number of tool calls allowed.
+
+Returns: `1` if within the limit, `0` otherwise.
+
+### `checks.usedNoTools()`
+
+Scores 1 if the agent made no tool calls at all.
+
+```typescript
+checks.usedNoTools()
+```
+
+Returns: `1` if no tools were called, `0` otherwise.
+
+### `checks.noToolErrors()`
+
+Scores 1 if none of the tool invocations resulted in an error state. Detects both error results (`result.error` present) and incomplete tool calls (`state === 'call'`).
+
+```typescript
+checks.noToolErrors()
+```
+
+Returns: `1` if all tool calls succeeded, `0` otherwise.
+
+## Combining checks with other scorers
+
+Checks compose with LLM-based and code-based scorers in the same `scorers` array:
+
+```typescript
+import { checks } from '@mastra/evals/checks'
+import { createAnswerRelevancyScorer } from '@mastra/evals/scorers/prebuilt'
+import { runEvals } from '@mastra/core/evals'
+import { myAgent } from '../agents'
+
+const result = await runEvals({
+  data: [{ input: 'What is the weather in Brooklyn?' }],
+  target: myAgent,
+  scorers: [
+    // Zero-LLM checks
+    checks.includes('Brooklyn'),
+    checks.calledTool('get_weather'),
+    checks.noToolErrors(),
+    // LLM-based scorer
+    createAnswerRelevancyScorer({ model: 'openai/gpt-5-mini' }),
+  ],
+})
+```
+
+## Related
+
+- [Quick Checks overview](https://mastra.ai/docs/evals/quick-checks)
+- [Built-in Scorers](https://mastra.ai/docs/evals/built-in-scorers)
+- [`createScorer()` reference](https://mastra.ai/reference/evals/create-scorer)
+- [`runEvals()` reference](https://mastra.ai/reference/evals/run-evals)
+- [Custom Scorers](https://mastra.ai/docs/evals/custom-scorers)

package/.docs/reference/evals/run-evals.md

@@ -29,13 +29,34 @@ console.log(`Average scores:`, result.scores)
 console.log(`Processed ${result.summary.totalItems} items`)
 ```
 
+### With gates and thresholds
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { checks } from '@mastra/evals/checks'
+import { faithfulnessScorer } from './scorers'
+
+const result = await runEvals({
+  target: myAgent,
+  data: [{ input: 'What is the weather in Brooklyn?' }],
+  gates: [checks.calledTool('get_weather'), checks.noToolErrors()],
+  scorers: [{ scorer: faithfulnessScorer, threshold: 0.7 }, checks.includes('Brooklyn')],
+})
+
+result.verdict // 'passed' | 'scored' | 'failed'
+result.gateResults // [{ id, passed, score }]
+result.thresholdResults // [{ id, passed, averageScore, threshold }]
+```
+
 ## Parameters
 
 **target** (`Agent | Workflow`): The agent or workflow to evaluate.
 
 **data** (`RunEvalsDataItem[]`): Array of test cases with input data and optional ground truth.
 
-**scorers** (`MastraScorer[] | AgentScorerConfig | WorkflowScorerConfig`): Scorers to use. A flat array applies all scorers to the raw output. For agents, an \`AgentScorerConfig\` object separates agent-level and trajectory scorers. For workflows, a \`WorkflowScorerConfig\` object specifies scorers for the workflow, individual steps, and trajectory.
+**scorers** (`ScorerEntry[] | AgentScorerConfig | WorkflowScorerConfig`): Scorers to use. Each entry is either a bare \`MastraScorer\` or \`{ scorer, threshold }\` for threshold tracking. An \`AgentScorerConfig\` object separates agent-level and trajectory scorers. A \`WorkflowScorerConfig\` object specifies scorers for the workflow, individual steps, and trajectory.
+
+**gates** (`MastraScorer[]`): Scorers that must score 1.0 for the run to pass. If any gate averages below 1.0 across data items, the verdict is \`failed\`. Gates run before regular scorers on each data item.
 
 **targetOptions** (`AgentExecutionOptions | WorkflowRunOptions`): Options forwarded to the target during execution. For agents: options passed to agent.generate() (e.g. maxSteps, modelSettings, instructions). For workflows: options passed to run.start() (e.g. perStep, outputOptions, initialState).
 
@@ -83,8 +104,55 @@ For workflows, use `WorkflowScorerConfig` to specify scorers at different levels
 
 **summary.totalItems** (`number`): Total number of test cases processed.
 
+**verdict** (`'passed' | 'scored' | 'failed'`): Present when \`gates\` or threshold-bearing scorers are provided. \`passed\` = all gates and thresholds met. \`scored\` = gates passed but a threshold was missed. \`failed\` = at least one gate did not score 1.0.
+
+**gateResults** (`GateResult[]`): Per-gate results averaged across all data items. Each entry has \`id\`, \`passed\` (boolean), and \`score\` (0–1).
+
+**thresholdResults** (`ThresholdResult[]`): Per-threshold-scorer results averaged across all data items. Each entry has \`id\`, \`passed\`, \`averageScore\`, and \`threshold\`.
+
+## ScorerEntry
+
+A scorer entry in the `scorers` array can be either a bare scorer or a scorer with a threshold:
+
+**scorer** (`MastraScorer`): The scorer instance.
+
+**threshold** (`number | { min?: number; max?: number }`): A number implies minimum threshold (score at or above passes). Use \`{ min, max }\` for range-based checks — e.g. \`{ max: 0.3 }\` for scorers like hallucination where a high score is bad. Both \`min\` and \`max\` must be between 0 and 1.
+
 ## Examples
 
+### Gates and verdict
+
+Use `gates` for hard pass/fail requirements and `{ scorer, threshold }` for tracked quality metrics:
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { checks } from '@mastra/evals/checks'
+
+const result = await runEvals({
+  target: weatherAgent,
+  data: [{ input: 'What is the weather in Brooklyn?' }],
+  gates: [checks.calledTool('get_weather'), checks.noToolErrors()],
+  scorers: [
+    { scorer: faithfulnessScorer, threshold: 0.7 }, // min threshold (number shorthand)
+    { scorer: hallucinationScorer, threshold: { max: 0.3 } }, // max threshold (high = bad)
+    { scorer: toneScorer, threshold: { min: 0.5, max: 0.9 } }, // range threshold
+    checks.includes('Brooklyn'), // bare scorer, no threshold
+  ],
+})
+
+if (result.verdict === 'failed') {
+  console.log(
+    'Gate failures:',
+    result.gateResults?.filter(g => !g.passed),
+  )
+} else if (result.verdict === 'scored') {
+  console.log(
+    'Threshold misses:',
+    result.thresholdResults?.filter(t => !t.passed),
+  )
+}
+```
+
 ### Agent Evaluation
 
 ```typescript
@@ -246,6 +314,8 @@ const result = await runEvals({
 
 ## Related
 
+- [Gates and Verdicts](https://mastra.ai/docs/evals/gates-and-verdicts): Conceptual guide to severity semantics
+- [Quick Checks](https://mastra.ai/reference/evals/checks): Zero-LLM composable micro-scorers
 - [createScorer()](https://mastra.ai/reference/evals/create-scorer): Create custom scorers for experiments
 - [MastraScorer](https://mastra.ai/reference/evals/mastra-scorer): Learn about scorer structure and methods
 - [Trajectory Accuracy](https://mastra.ai/reference/evals/trajectory-accuracy): Built-in trajectory evaluation scorers

package/.docs/reference/harness/harness-class.md

@@ -1,6 +1,6 @@
 # Harness class
 
-> **Alpha:** The `Harness` feature is in alpha stage and subject to breaking changes in minor versions until it graduates from its alpha status.
+> **Beta:** The `Harness` feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta status.
 
 The `Harness` class orchestrates multiple agent modes, shared state, memory, and storage. It provides a control layer that a TUI or other UI can drive to manage threads, switch models and modes, send messages, handle tool approvals, and track events.
 
@@ -166,6 +166,33 @@ Initialize the harness. Loads storage, initializes the workspace, propagates mem
 await harness.init()
 ```
 
+#### `createSession({ id, ownerId, resourceId? })`
+
+Create a new, fully-wired `Session` and bring it online. The session starts in the default mode with the seeded model, connects to the Harness's shared machinery (agent, storage/lock, config catalog), and has a current thread (the most recent thread for the resource, or a freshly created one). Call `init()` once before creating sessions so shared storage and workspace are ready.
+
+The Harness owns no session of its own — every consumer creates its own session and drives all work through it. In a server or multiplayer setting, each request, thread, or user gets its own session, isolated from every other: independent event bus, mode, model, state, and current thread.
+
+`id` and `ownerId` are required — they mirror `SessionRecord.id` and `SessionRecord.ownerId` and are stable for the life of the session. `resourceId` is optional and defaults to `config.resourceId` then `config.id`.
+
+```typescript
+const session = await harness.createSession({
+  id: 'session-xyz',
+  ownerId: 'user-123',
+})
+```
+
+You can also override the resource:
+
+```typescript
+const session = await harness.createSession({
+  id: 'session-xyz',
+  ownerId: 'user-123',
+  resourceId: 'project-abc',
+})
+```
+
+Switching the resource ID via `harness.setResourceId()` changes only the resource ID, not `id` or `ownerId`. Read them through `session.identity.getId()` and `session.identity.getOwnerId()`.
+
 #### `selectOrCreateThread()`
 
 Select the most recent thread for the current resource, or create one if none exist. Loads thread metadata and acquires a thread lock.

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

@@ -1,6 +1,6 @@
 # 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.
+> **Beta:** The `Harness` feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta 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.
 
@@ -29,7 +29,7 @@ harness.subscribe(event => {
 
 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.
+**identity** (`SessionIdentity`): Stable session, owner, and resource identity for the conversation. See identity methods below.
 
 **thread** (`SessionThread`): Active thread binding and thread/message reads. See thread methods below.
 
@@ -125,7 +125,23 @@ const usage = harness.session.getTokenUsage()
 
 ## Identity
 
-`session.identity` owns the resource ID for the conversation.
+`session.identity` owns the stable identifiers for the conversation: the resource ID, a session `id`, and an `ownerId`. The `id` and `ownerId` are stable for the life of the session and do not change when the resource ID is switched. They mirror the `id` and `ownerId` fields on `SessionRecord` in storage.
+
+### `session.identity.getId()`
+
+Return the stable session identifier.
+
+```typescript
+const sessionId = harness.session.identity.getId()
+```
+
+### `session.identity.getOwnerId()`
+
+Return the stable owner identifier for the session.
+
+```typescript
+const ownerId = harness.session.identity.getOwnerId()
+```
 
 ### `session.identity.getResourceId()`
 
@@ -143,7 +159,7 @@ Return the resource ID the session was created with.
 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.
+To change the resource ID, use [`harness.setResourceId()`](https://mastra.ai/reference/harness/harness-class), which also tears down the active thread. The session `id` and `ownerId` are not affected by resource switches.
 
 ## Thread
 

package/.docs/reference/index.md

@@ -118,6 +118,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [createScorer()](https://mastra.ai/reference/evals/create-scorer)
 - [filterRun()](https://mastra.ai/reference/evals/filter-run)
 - [MastraScorer](https://mastra.ai/reference/evals/mastra-scorer)
+- [Quick Checks](https://mastra.ai/reference/evals/checks)
 - [runEvals()](https://mastra.ai/reference/evals/run-evals)
 - [Scorer Utils](https://mastra.ai/reference/evals/scorer-utils)
 - [Answer Relevancy Scorer](https://mastra.ai/reference/evals/answer-relevancy)

package/.docs/reference/memory/observational-memory.md

@@ -44,7 +44,7 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **temporalMarkers** (`boolean`): Insert temporal-gap reminder markers before new user messages when the previous message in the thread is at least 10 minutes older. The marker is persisted in memory, emitted as an inline reminder event so clients can render it specially, and shown to the observer so it can anchor observations to when events occurred. (Default: `false`)
 
-**retrieval** (`boolean | { vector?: boolean; scope?: 'thread' | 'resource' }`): \*\*Experimental.\*\* Enable retrieval-mode observation groups as durable pointers to raw message history. \`true\` enables cross-thread browsing by default. \`{ vector: true }\` also enables semantic search using Memory's vector store and embedder. \`{ scope: 'thread' }\` restricts the recall tool to the current thread only. Default scope is \`'resource'\`. (Default: `false`)
+**retrieval** (`boolean | { vector?: boolean; scope?: 'thread' | 'resource' }`): Enable retrieval-mode observation groups as durable pointers to raw message history. \`true\` enables cross-thread browsing by default. \`{ vector: true }\` also enables semantic search using Memory's vector store and embedder. \`{ scope: 'thread' }\` restricts the recall tool to the current thread only. Default scope is \`'resource'\`. (Default: `false`)
 
 **observation** (`ObservationalMemoryObservationConfig`): Configuration for the observation step. Controls when the Observer agent runs and how it behaves.
 

package/.docs/reference/memory/serialized-memory-config.md

@@ -58,7 +58,7 @@ new MastraEditor({
 
 **temporalMarkers** (`boolean`): Persist inline temporal gap markers for long pauses between messages.
 
-**retrieval** (`boolean | { vector?: boolean; scope?: 'thread' | 'resource' }`): Experimental. Enable retrieval-mode observation groups as durable pointers to raw message history.
+**retrieval** (`boolean | { vector?: boolean; scope?: 'thread' | 'resource' }`): Enable retrieval-mode observation groups as durable pointers to raw message history.
 
 **observation** (`SerializedObservationalMemoryObservationConfig`): Observer-step configuration (model, token thresholds, buffering).
 

package/.docs/reference/streaming/agents/stream.md

@@ -78,7 +78,7 @@ const stream = await agent.stream('message for agent')
 
 **options.onAbort** (`(event: any) => Promise<void> | void`): Callback function called when the stream is aborted.
 
-**options.abortSignal** (`AbortSignal`): Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated.
+**options.abortSignal** (`AbortSignal`): Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated, including any in-flight subagent runs the agent delegated to.
 
 **options.activeTools** (`Array<keyof ToolSet> | undefined`): Array of active tool names that can be used during execution.
 

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.2.2-alpha.3
+
+### Patch Changes
+
+- Updated dependencies [[`86623c1`](https://github.com/mastra-ai/mastra/commit/86623c1adf7d22de32cc916dda17f4155184db36), [`7c9dd77`](https://github.com/mastra-ai/mastra/commit/7c9dd77bd18cb8dc72797e25f1a0fbdc71a11347), [`9990965`](https://github.com/mastra-ai/mastra/commit/999096571635a83b42ef40841fd7028cfa630779), [`c0ffa3c`](https://github.com/mastra-ai/mastra/commit/c0ffa3c897ccd326de880df734740a7f0681a18f), [`0504bf5`](https://github.com/mastra-ai/mastra/commit/0504bf5e8cffc571a4b343326178de371e6f859b), [`5afe423`](https://github.com/mastra-ai/mastra/commit/5afe423e4badf040f1b0d4525183a856fcb8146e), [`86623c1`](https://github.com/mastra-ai/mastra/commit/86623c1adf7d22de32cc916dda17f4155184db36), [`8c9f1c0`](https://github.com/mastra-ai/mastra/commit/8c9f1c0361d89066f9bcd14a2f69e761b01766c8)]:
+  - @mastra/core@1.47.0-alpha.2
+
+## 1.2.2-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [[`7f9ae70`](https://github.com/mastra-ai/mastra/commit/7f9ae70826b047e5a66218f9e92f20e54a2d791f), [`1505c07`](https://github.com/mastra-ai/mastra/commit/1505c07603f6346bae12aa82f140e8b88ffea9ab), [`e940f09`](https://github.com/mastra-ai/mastra/commit/e940f099ef5d18b403e6f2b4937e086a4da857b1)]:
+  - @mastra/core@1.46.1-alpha.1
+
 ## 1.2.2-alpha.0
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.2-alpha.1",
+  "version": "1.2.2-alpha.4",
   "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.46.1-alpha.0",
+    "@mastra/core": "1.47.0-alpha.2",
     "@mastra/mcp": "^1.12.0"
   },
   "devDependencies": {
@@ -45,9 +45,9 @@
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
     "vitest": "4.1.8",
-    "@internal/lint": "0.0.108",
+    "@mastra/core": "1.47.0-alpha.2",
     "@internal/types-builder": "0.0.83",
-    "@mastra/core": "1.46.1-alpha.0"
+    "@internal/lint": "0.0.108"
   },
   "homepage": "https://mastra.ai",
   "repository": {