@mastra/mcp-docs-server 1.3.8-alpha.0 → 1.3.8-alpha.11

package/.docs/reference/cli/mastra.md

@@ -1648,19 +1648,27 @@ mastra api trace list '{"page":0,"perPage":20}' --verbose
 
 #### `mastra api trace query`
 
-Queries completed observability traces with recursive predicates over trace and related span or score fields. The inline JSON input is required. Like other observability commands, it targets `https://observability.mastra.ai` by default.
+Queries completed observability traces with recursive predicates over trace fields and related spans. The inline JSON input is required and uses the same query structure as the SDK and HTTP API. Like other observability commands, it targets `https://observability.mastra.ai` by default. Pass `--url http://localhost:4111` to query a local server.
 
 ```bash
 mastra api trace query <input>
 mastra api trace query '{"timeRange":{"from":"2026-08-01T00:00:00.000Z","to":"2026-08-08T00:00:00.000Z"}}'
 ```
 
-Inspect the target server's exact request contract before constructing a query:
+Inspect the command with:
 
 ```bash
-mastra api trace query --schema
+mastra api trace query --help
 ```
 
+For supported fields, operators, and request options, see [Trace queries](https://mastra.ai/reference/observability/tracing/trace-query). For a local Mastra server, you can also inspect its request and response schemas:
+
+```bash
+mastra api --url http://localhost:4111 trace query --schema
+```
+
+Mastra Platform doesn't currently expose the schema endpoint used by `--schema`. To find fields and values recorded in your project, use [field and value discovery](https://mastra.ai/reference/observability/tracing/trace-query).
+
 The response remains nested under `data` to preserve cursor pagination:
 
 ```json
@@ -1672,7 +1680,7 @@ The response remains nested under `data` to preserve cursor pagination:
 }
 ```
 
-Pass a non-null `page.next` value back as `page.after` in the next query. See [Advanced trace queries](https://mastra.ai/reference/observability/tracing/trace-query) for supported fields and operators, recursive predicates, limits, pagination, and errors.
+Each invocation makes one query. Pass a non-null `data.page.next` value back as `page.after` in the next query. See [Pagination and errors](https://mastra.ai/reference/observability/tracing/trace-query) for pagination modes, cursor handling, and errors.
 
 To load a numbered page and then poll, keep the same time range and predicate in both requests:
 

package/.docs/reference/client-js/agents.md

@@ -213,6 +213,23 @@ await agent.queueMessage({
 })
 ```
 
+### `queueSignal()`
+
+Queue a typed signal for the next thread turn. It follows the same ordering as `queueMessage()`, but keeps the signal's `type`, `tagName`, and `attributes`.
+
+```typescript
+await agent.queueSignal({
+  signal: {
+    type: 'reactive',
+    tagName: 'skill',
+    attributes: { name: 'triage' },
+    contents: 'Triage the new issue.',
+  },
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+})
+```
+
 ### `sendSignal()`
 
 Send a lower-level signal to an active agent run or memory thread. Use this for system-generated context such as reactive reminders or notification-shaped context that doesn't need inbox storage. For durable notification records, use the server-side [`Agent.sendNotificationSignal()`](https://mastra.ai/reference/agents/agent) API. For user-authored input, prefer `sendMessage()` or `queueMessage()`.

package/.docs/reference/client-js/observability.md

@@ -45,7 +45,7 @@ const completeTrace = await mastraClient.getTrace(traces.spans[0].traceId)
 
 ## Listing traces for a list view
 
-`listTracesLight()` returns the same rows as a trace list, without the `input`, `output` and `attributes` payloads. Each row carries a short `inputPreview` string instead, so a list can render a preview column without transferring the whole prompt, plus `threadId` and `resourceId` for the memory context columns.
+`listTracesLight()` returns the same rows as a trace list, without the `input`, `output` and `attributes` payloads. Each row carries short `inputPreview`, `outputPreview` and `errorPreview` strings instead (at most 100 characters, ending with `…` when cut), so a list can render preview columns without transferring the whole payload, plus `threadId` and `resourceId` for the memory context columns.
 
 Prefer it whenever you are rendering many traces at once, and fetch the full record only when a row is opened:
 
@@ -65,9 +65,9 @@ const selected = await mastraClient.getTrace(list.spans[0].traceId)
 
 It accepts the same filtering, ordering and delta-polling arguments as `listTraces()`. Use `listTraces()` when you actually need the full span payloads.
 
-## Querying traces and threads
+## Querying traces
 
-`queryTraces()` finds completed logical traces using trace fields and conditions over related spans, scores, or feedback. Every query requires an ISO timestamp range of at most 31 days.
+`queryTraces()` finds completed logical traces using trace fields and conditions over related spans. Every query requires an ISO timestamp range.
 
 ```typescript
 const result = await mastraClient.queryTraces({
@@ -76,12 +76,12 @@ const result = await mastraClient.queryTraces({
     to: '2026-08-08T00:00:00.000Z',
   },
   where: {
-    scores: {
+    spans: {
       some: {
         op: 'and',
         args: [
-          { op: 'eq', left: { path: 'scorerId' }, right: { literal: 'factuality' } },
-          { op: 'lt', left: { path: 'score' }, right: { literal: 0.6 } },
+          { op: 'eq', left: { path: 'spanType' }, right: { literal: 'tool_call' } },
+          { op: 'exists', path: 'error' },
         ],
       },
     },
@@ -89,6 +89,8 @@ const result = await mastraClient.queryTraces({
 })
 ```
 
+See [Trace queries](https://mastra.ai/reference/observability/tracing/trace-query) for request fields, predicates, limits, response shapes, and errors.
+
 ### Load a page and poll for traces
 
 `queryTraces()` supports keyset traversal with `page`, numbered pages with `pagination`, and delta polling with `mode: 'delta'`. Use one mode per request. To migrate from `listTracesLight()`, read `traces` instead of `spans` and retain the numbered page's `deltaCursor`:
@@ -114,7 +116,7 @@ const changes = await mastraClient.queryTraces({
 
 Merge `changes.traces` by `traceId`, retain `changes.deltaCursor`, and continue while `changes.delta.hasMore` is `true`. Keep the same time range and predicate across polls. Only completed traces are returned; polling doesn't guarantee notifications for related-record updates, deletions, or traces that stop matching.
 
-See [Delta polling](https://mastra.ai/reference/observability/tracing/trace-query) for bootstrap behavior, cursor lifetime, retention, and a complete polling loop. `queryTraceThreads()` remains keyset-only.
+See [Delta polling](https://mastra.ai/reference/observability/tracing/trace-query) for bootstrap behavior, cursor lifetime, retention, and a complete polling loop.
 
 ### Discover trace-query fields and values
 
@@ -134,7 +136,7 @@ const fields = await mastraClient.getTraceQueryFields({
 })
 ```
 
-Use the exact local path from the response with the same scope. For example, `model` belongs inside a `spans.some` or `spans.none` predicate. A global picker can fetch `trace`, `spans`, `scores`, and `feedback` in parallel.
+Use the exact local path from the response with the same scope. For example, `model` belongs inside a `spans.some` or `spans.none` predicate. A field picker can fetch the `trace` and `spans` scopes in parallel.
 
 Call `getTraceQueryValues()` only after selecting a field with `valueSuggestions: true`:
 
@@ -162,89 +164,6 @@ Suggestions are bounded and advisory. Manual values remain valid when suggestion
 
 A discovery timeout rejects with `504 TRACE_QUERY_EXECUTION_TIMEOUT`. Backend memory or resource exhaustion rejects with `503 TRACE_QUERY_RESOURCE_LIMIT`. Neither error contains partial suggestions; truncation flags are only present on successful, completely ranked responses.
 
-`queryTraceThreads()` returns thread identities derived from observability traces after applying eligibility and cross-trace conditions. It doesn't read or return memory thread records or messages. In this example, one production trace can have the low factuality score while another production trace in the same thread has the clinician correction:
-
-```typescript
-const result = await mastraClient.queryTraceThreads({
-  traces: {
-    timeRange: {
-      from: '2026-08-01T00:00:00.000Z',
-      to: '2026-08-08T00:00:00.000Z',
-    },
-    where: {
-      op: 'eq',
-      left: { path: 'environment' },
-      right: { literal: 'production' },
-    },
-  },
-  where: {
-    op: 'and',
-    args: [
-      {
-        traces: {
-          some: {
-            scores: {
-              some: {
-                op: 'lt',
-                left: { path: 'score' },
-                right: { literal: 0.6 },
-              },
-            },
-          },
-        },
-      },
-      {
-        traces: {
-          some: {
-            feedback: {
-              some: {
-                op: 'eq',
-                left: { path: 'feedbackType' },
-                right: { literal: 'clinician-correction' },
-              },
-            },
-          },
-        },
-      },
-    ],
-  },
-})
-
-// { threads: [{ threadId: 'thread-123' }], page: { next: null } }
-```
-
-The API limits predicate depth, nodes, related clauses, set members, literal bytes, and the total literal budget before storage execution. Cursor pages are deterministic but aren't a database snapshot, so signals written between requests can change later pages. PostgreSQL and ClickHouse trace and thread queries have a configurable 15-second execution timeout.
-
-See [Advanced trace queries](https://mastra.ai/reference/observability/tracing/trace-query) for the complete limits, request fields, predicates, thread qualification semantics, cursor pagination, response shapes, and errors.
-
-## Querying spans
-
-`querySpans()` returns one row per matching completed span across traces. Use it to list the spans themselves. `queryTraces()` with a `spans.some` predicate returns the traces that contain a matching span instead. Every query requires an ISO timestamp range of at most 31 days.
-
-```typescript
-const result = await mastraClient.querySpans({
-  timeRange: {
-    from: '2026-10-01T00:00:00.000Z',
-    to: '2026-10-02T00:00:00.000Z',
-  },
-  where: {
-    op: 'eq',
-    left: { path: 'spanType' },
-    right: { literal: 'tool_call' },
-  },
-  orderBy: [{ field: 'startedAt', direction: 'desc' }],
-  page: { limit: 50 },
-})
-
-// { spans: [{ traceId, spanId, name, spanType, status, durationMs, cost, ... }], page: { next } }
-```
-
-Pass `result.page.next` back as `page.after` with the same time range, filter, and ordering to load the next page. Each row contains identifiers, display fields, input and output previews, and the span's model cost. Use `getSpan()` to load the full span.
-
-Span queries are optional for observability stores. Check `capabilities.spanQuery` from `getObservabilityCapabilities()` before calling `querySpans()`, and treat a missing value as unsupported. Unsupported servers reject with `501 SPAN_QUERY_UNSUPPORTED`.
-
-See [Query individual spans](https://mastra.ai/reference/observability/tracing/trace-query) for filters, ordering, cursors, cost states, limits, and errors.
-
 ## Deleting traces
 
 Delete traces and their associated spans, metrics, logs, scores, and feedback:
@@ -393,7 +312,7 @@ const ratingPercentiles = await mastraClient.getFeedbackPercentiles({
 
 ## Related
 
-- [Advanced trace queries](https://mastra.ai/reference/observability/tracing/trace-query): Query completed traces with recursive predicates
+- [Trace queries](https://mastra.ai/reference/observability/tracing/trace-query): Query completed traces with recursive predicates
 - [Feedback guide](https://mastra.ai/docs/observability/feedback): Learn how to create, list, and query feedback
 - [Feedback reference](https://mastra.ai/reference/observability/feedback): Review feedback schemas and HTTP routes
 - [Agents API](https://mastra.ai/reference/client-js/agents): Learn about agent interactions that generate traces

package/.docs/reference/code-sdk/mount-agent-controller.md

@@ -72,6 +72,8 @@ const { controller } = await mountAgentControllerOnMastra({ mastra })
 
 **disabledTools** (`string[]`): Tools removed from the dynamic tool set before exposure to the model.
 
+**disableBuiltinTools** (`BuiltinToolId[]`): Agent controller built-in tools (for example, 'submit\_plan') removed from every session. Tool guidance skips disabled tools, and plan mode writes the plan file instead of calling 'submit\_plan' when it's disabled.
+
 **storage** (`StorageConfig`): Custom storage config instead of the auto-detected default.
 
 **workspace** (`AgentControllerConfig["workspace"]`): Override the workspace. (Default: `local filesystem + local sandbox based on the detected project`)

package/.docs/reference/index.md

@@ -266,11 +266,11 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Automatic Metrics](https://mastra.ai/reference/observability/metrics/automatic-metrics)
 - [Metric queries](https://mastra.ai/reference/observability/metrics/queries)
 - [Configuration](https://mastra.ai/reference/observability/tracing/configuration)
-- [Advanced trace queries](https://mastra.ai/reference/observability/tracing/trace-query)
 - [Instances](https://mastra.ai/reference/observability/tracing/instances)
 - [Interfaces](https://mastra.ai/reference/observability/tracing/interfaces)
 - [Span filtering](https://mastra.ai/reference/observability/tracing/span-filtering)
 - [Spans](https://mastra.ai/reference/observability/tracing/spans)
+- [Trace queries](https://mastra.ai/reference/observability/tracing/trace-query)
 - [AgentsMDInjector](https://mastra.ai/reference/processors/agents-md-injector)
 - [BatchPartsProcessor](https://mastra.ai/reference/processors/batch-parts-processor)
 - [ClassifierProcessor](https://mastra.ai/reference/processors/classifier-processor)

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

@@ -93,6 +93,8 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **observation.bufferOnIdle** (`boolean`): Run background observation buffering when an agent turn ends and the agent becomes idle. This is separate from bufferTokens, which controls step-time async buffering. Set this to true to buffer short idle turns without waiting for the next turn or the messageTokens threshold.
 
+**observation.observeOnContextOverflow** (`boolean`): Recover when the model provider rejects a request for exceeding its context window. Provider token counts can be higher than Observational Memory's local estimate, for example with attachments or after switching to a model with a smaller window, so a request can overflow before the messageTokens threshold is reached. When this happens, Observational Memory activates buffered observations, observes every pending message regardless of the threshold, and retries the request once with the smaller context. Set to false to let the error reach the caller instead.
+
 **observation.bufferActivation** (`number`): How much of the message window to clear when buffered observations activate. Values between 0 and 1 are the fraction of messageTokens to remove: 0.8 removes \~80% of the message history and keeps \~20% (6k tokens with the default 30k). Values of 1000 or more are the token count to keep: 4000 keeps \~4k message tokens after activation. Note the direction flips: a higher ratio removes more history, while a higher token count keeps more.
 
 **observation.activateAfterIdle** (`number | string | false | "auto" | Record<string, number | string | false | "auto">`): Time before buffered observations are forced to activate after inactivity. Accepts milliseconds, a duration string, "auto" for a provider-aware prompt cache TTL, false, or an object of per-provider TTLs. An object replaces the top-level value and is not merged with it. If unset, the top-level activateAfterIdle value is used for observations. Set false to disable the top-level idle setting for observations. Currently only applied when using the standalone ObservationalMemory class; new Memory(...) applies the top-level activateAfterIdle only.
@@ -777,6 +779,17 @@ The standalone `ObservationalMemory` class accepts all the same options as the `
 
 **obscureThreadIds** (`boolean`): When enabled, thread IDs are hashed before being included in observation context. This prevents the LLM from recognizing patterns in thread identifiers. Automatically enabled when using resource scope through the Memory class. (Default: `false`)
 
+### Forcing observation
+
+`observe()` only observes once pending tokens reach the observation threshold. Pass `force: true` to observe pending messages regardless of the threshold. The bypass applies to that call only and isn't saved to the record's config.
+
+```typescript
+const result = await om.observe({ threadId, resourceId, force: true })
+// result.observed: true if pending messages were observed
+```
+
+Agents don't need this to recover from context-window errors. `observation.observeOnContextOverflow` handles that automatically.
+
 ## Recall tool
 
 When `retrieval` is truthy, Mastra registers a `recall` tool that pages through raw messages behind observation group ranges. With the default resource scope, the tool can list threads (`mode: "threads"`) and browse another thread through `threadId`. It also supports cross-thread search. Set `retrieval: { vector: true }` for semantic search (`mode: "search"`), or use `scope: 'thread'` to restrict the tool to the current thread. The tool is automatically added to the agent.