@mastra/mcp-docs-server 1.2.17-alpha.14 → 1.2.17-alpha.17

package/.docs/docs/auth/fga.md

@@ -284,6 +284,32 @@ class MyFGAProvider implements IFGAProvider {
 }
 ```
 
+### Propagating an actor into workflow steps
+
+A workflow run's `actor` reaches each step's execute context, but it isn't passed to the agent and tool calls that step makes. Steps that call an agent without an `actor` fall back to user membership resolution, which fails on system runs that have no user.
+
+Set `propagate: true` on the actor to have the framework forward it into the agent and tool calls it makes for declarative `.then(agent)` and `.then(tool)` steps in the run:
+
+```typescript
+await run.start({
+  inputData: { city: 'London' },
+  actor: { actorKind: 'system', sourceWorkflow: 'nightly-report', propagate: true },
+})
+```
+
+Propagation is opt-in and deliberately narrow:
+
+- The `true` shorthand never propagates. Use the object form to opt in.
+- Custom step `execute` functions are never covered. Read `actor` from the step context and pass it explicitly, so a step that acts on a user's behalf can't silently inherit system trust.
+- Pass `actor` when creating the step to override the run actor for that step, including `actor: undefined` to drop back to user authorization mid-run.
+
+```typescript
+// Runs as the system actor even though it loads user-supplied data.
+workflow.then(createStep(reportAgent))
+// Explicitly runs as the user instead.
+workflow.then(createStep(summaryAgent, { actor: undefined }))
+```
+
 ### Trust requirements
 
 The actor signal is trusted input, so construct it server-side:

package/.docs/reference/agents/durable-agent.md

@@ -338,7 +338,7 @@ Returns: [`Promise<DurableAgentStreamResult>`](#durableagentstreamresult)
 
 **onSuspended** (`(data: AgentSuspendedEventData) => void | Promise<void>`): Called when the run suspends, for example for tool approval.
 
-**onAbort** (`AgentExecutionOptions['onAbort']`): Called when the run is aborted via abortSignal or result.abort().
+**onAbort** (`AgentExecutionOptions['onAbort']`): Called when the run is aborted via abortSignal or result.abort(). Receives the steps completed before the abort and, in text, the assistant text streamed so far.
 
 **onIterationComplete** (`AgentExecutionOptions['onIterationComplete']`): Called after every agentic-loop iteration with the latest messageList, finishReason, and isFinal flag. Observation-only on durable agents: returning continue: false or feedback does not influence the loop.
 

package/.docs/reference/agents/generate.md

@@ -78,7 +78,7 @@ const result = await agent.generate('message for agent')
 
 **options.onError** (`({ error }: { error: Error | string }) => Promise<void> | void`): Callback function called when an error occurs during generation.
 
-**options.onAbort** (`(event: any) => Promise<void> | void`): Callback function called when the generation is aborted.
+**options.onAbort** (`(event: { steps: any[]; text?: string }) => Promise<void> | void`): Callback function called when the generation is aborted. steps contains the steps that completed before the abort, and text contains the assistant text generated so far for the step that was in flight.
 
 **options.activeTools** (`Array<keyof ToolSet> | undefined`): Array of tool names that should be active during execution. If undefined, all available tools are active.
 
@@ -164,6 +164,8 @@ const result = await agent.generate('message for agent')
 
 **options.modelSettings.frequencyPenalty** (`number`): Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.
 
+**options.modelSettings.timeout** (`object`): Time-based execution budget for the run. Accepts totalMs, the maximum duration of the entire agent run across every loop iteration, tool call and retry, and stepMs, the maximum duration of a single model call including the time spent consuming its stream. Exceeding either budget fails with a MastraTimeoutError. A totalMs timeout ends the run and does not try fallback models, because it is a hard deadline for the whole run. A stepMs timeout is not retried against the same model but does advance to the next entry in models when fallback models are configured.
+
 **options.modelSettings.stopSequences** (`string[]`): Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.
 
 **options.toolChoice** (`'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }`): Controls how tools are selected during generation.

package/.docs/reference/agents/network.md

@@ -100,6 +100,8 @@ await agent.network(`
 
 **options.modelSettings.frequencyPenalty** (`number`): Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.
 
+**options.modelSettings.timeout** (`object`): Time-based execution budget for the run. Accepts totalMs, the maximum duration of the entire agent run across every loop iteration, tool call and retry, and stepMs, the maximum duration of a single model call including the time spent consuming its stream. Exceeding either budget fails with a MastraTimeoutError. A totalMs timeout ends the run and does not try fallback models, because it is a hard deadline for the whole run. A stepMs timeout is not retried against the same model but does advance to the next entry in models when fallback models are configured.
+
 **options.modelSettings.stopSequences** (`string[]`): Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.
 
 **options.structuredOutput** (`StructuredOutputOptions`): Configuration for generating a typed structured output from the network result.

package/.docs/reference/auth/fga.md

@@ -122,6 +122,8 @@ Identifies a call made by a trusted non-user actor rather than an authenticated
 
 **sourceWorkflow** (`string`): Name of the workflow that started the actor run, when applicable.
 
+**propagate** (`boolean`): Forwards this actor into the agent and tool calls the framework makes for the run's declarative .then(agent) and .then(tool) steps. Custom step execute functions aren't covered and must pass actor explicitly. Ignored by authorization itself. (Default: `false`)
+
 ## `FGADeniedError`
 
 Thrown when an authorization check is denied. `require` and `requireActor` throw it to deny, and Mastra surfaces it as an HTTP `403`.

package/.docs/reference/index.md

@@ -211,6 +211,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.getThreadById()](https://mastra.ai/reference/memory/getThreadById)
 - [.listThreads()](https://mastra.ai/reference/memory/listThreads)
 - [.recall()](https://mastra.ai/reference/memory/recall)
+- [.settled()](https://mastra.ai/reference/memory/settled)
 - [.summarizeThread()](https://mastra.ai/reference/memory/summarizeThread)
 - [AgentNetwork to .network()](https://mastra.ai/reference/migrations/agentnetwork)
 - [AI SDK v4 to v5](https://mastra.ai/reference/migrations/ai-sdk-v4-to-v5)

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

@@ -145,4 +145,5 @@ export const agent = new Agent({
 - [listThreads](https://mastra.ai/reference/memory/listThreads)
 - [deleteMessages](https://mastra.ai/reference/memory/deleteMessages)
 - [cloneThread](https://mastra.ai/reference/memory/cloneThread)
+- [settled](https://mastra.ai/reference/memory/settled)
 - [Clone Utility Methods](https://mastra.ai/reference/memory/clone-utilities)

package/.docs/reference/memory/settled.md

@@ -0,0 +1,57 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Memory.settled()
+
+The `.settled()` method resolves once all background work the `Memory` instance started has finished. Some memory work continues after an agent run returns:
+
+- Observational memory cycles (buffered observation and reflection, including the nested agent runs they spawn)
+- Vector cleanup started by `deleteThread()` and `deleteMessages()`
+
+Await this method before closing a storage connection you own. Without it, background statements can run against a closed connection.
+
+The method is declared on the base memory class, so it's also available on the `MastraMemory` instance returned by `agent.getMemory()`.
+
+## Usage example
+
+```typescript
+await agent.generate('Hello', {
+  memory: { thread: 'thread-123', resource: 'user-456' },
+})
+
+await memory.settled()
+await store.close()
+```
+
+## Parameters
+
+This method takes no parameters.
+
+## Returns
+
+**void** (`Promise<void>`): A promise that resolves when all background memory work has finished. Background work that fails does not reject this promise.
+
+## Extended usage example
+
+Test suites and short-lived processes are the most common places to need this, since they close the store immediately after a run finishes.
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { PostgresStore } from '@mastra/pg'
+
+const store = new PostgresStore({ connectionString })
+const memory = new Memory({ storage: store })
+
+// ... run your agent ...
+
+// Wait for observational memory and vector cleanup to finish before closing.
+await memory.settled()
+await store.close()
+```
+
+> **Note:** `settled()` joins the work that had started by the time you called it, plus any work that work enqueues. It does not prevent new work from starting afterwards, so call it once the agent runs you care about have returned.
+
+## Related
+
+- [Memory Class Reference](https://mastra.ai/reference/memory/memory-class)
+- [Observational Memory](https://mastra.ai/docs/memory/observational-memory)
+- [deleteMessages](https://mastra.ai/reference/memory/deleteMessages)

package/.docs/reference/rag/graph-rag.md

@@ -9,10 +9,7 @@ The `GraphRAG` class implements a graph-based approach to retrieval augmented ge
 ```typescript
 import { GraphRAG } from '@mastra/rag'
 
-const graphRag = new GraphRAG({
-  dimension: 1536,
-  threshold: 0.7,
-})
+const graphRag = new GraphRAG(1536, 0.7)
 
 // Create the graph from chunks and embeddings
 graphRag.createGraph(documentChunks, embeddings)
@@ -88,13 +85,79 @@ Returns an array of `RankedNode` objects, where each node contains:
 
 **score** (`number`): Combined relevance score from graph traversal
 
+### `serialize`
+
+Returns a JSON-safe snapshot of the graph so it can be persisted and restored later instead of rebuilt with `createGraph`.
+
+```typescript
+serialize(): GraphRAGSnapshot
+```
+
+#### Returns
+
+Returns a `GraphRAGSnapshot` object containing:
+
+**version** (`number`): Snapshot format version, used to reject snapshots this version of the class can't load
+
+**dimension** (`number`): Dimension of the embedding vectors the graph was built with
+
+**threshold** (`number`): Similarity threshold the graph was built with
+
+**nodes** (`GraphNode[]`): All nodes in the graph, each including its full embedding
+
+**edges** (`GraphEdge[]`): All edges in the graph
+
+The snapshot is a deep copy, so mutating it doesn't affect the graph it came from. Every node carries its full embedding, so snapshots are large: a 1,000-node graph built with 1536-dimension embeddings serializes to about 20 MB of JSON. Size your storage column accordingly.
+
+### `deserialize`
+
+Rebuilds a `GraphRAG` instance from a snapshot produced by `serialize`.
+
+```typescript
+static deserialize(snapshot: GraphRAGSnapshot): GraphRAG
+```
+
+#### Parameters
+
+**snapshot** (`GraphRAGSnapshot`): A snapshot previously returned by serialize
+
+Throws if the snapshot version is unsupported, if a node embedding doesn't match the snapshot dimension, or if an edge references a node that isn't in the snapshot. A bad snapshot therefore fails at load time instead of during a later query.
+
+## Persisting a graph
+
+Building a graph is O(n²) in the number of chunks, so rebuilding it on every process start is wasteful. Serialize the graph once and store the snapshot wherever you already keep state. A snapshot is plain JSON, so any store works (a file, a blob column, a key-value cache), and `GraphRAG` doesn't depend on a storage backend.
+
+```typescript
+import { readFile, writeFile } from 'node:fs/promises'
+import { GraphRAG } from '@mastra/rag'
+import type { GraphRAGSnapshot } from '@mastra/rag'
+
+const SNAPSHOT_PATH = './docs-graph.json'
+
+async function loadOrBuildGraph() {
+  try {
+    const snapshot = JSON.parse(await readFile(SNAPSHOT_PATH, 'utf8')) as GraphRAGSnapshot
+    return GraphRAG.deserialize(snapshot)
+  } catch {
+    // No usable snapshot yet, so build the graph from scratch
+  }
+
+  const graphRag = new GraphRAG(1536, 0.7)
+  graphRag.createGraph(documentChunks, embeddings)
+
+  await writeFile(SNAPSHOT_PATH, JSON.stringify(graphRag.serialize()))
+
+  return graphRag
+}
+```
+
+A snapshot reflects the chunks it was built from and isn't updated incrementally. When the underlying documents change, build the graph again and store a new snapshot.
+
 ## Advanced example
 
 ```typescript
-const graphRag = new GraphRAG({
-  dimension: 1536,
-  threshold: 0.8, // Stricter similarity threshold
-})
+// Stricter similarity threshold
+const graphRag = new GraphRAG(1536, 0.8)
 
 // Create graph from chunks and embeddings
 graphRag.createGraph(documentChunks, embeddings)

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

@@ -80,7 +80,7 @@ const stream = await agent.stream('message for agent')
 
 **options.onError** (`({ error }: { error: Error | string }) => Promise<void> | void`): Callback function called when an error occurs during streaming.
 
-**options.onAbort** (`(event: any) => Promise<void> | void`): Callback function called when the stream is aborted.
+**options.onAbort** (`(event: { steps: any[]; text?: string }) => Promise<void> | void`): Callback function called when the stream is aborted. steps contains the steps that completed before the abort, and text contains the assistant text streamed so far for the step that was in flight.
 
 **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.
 
@@ -158,6 +158,8 @@ const stream = await agent.stream('message for agent')
 
 **options.modelSettings.frequencyPenalty** (`number`): Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.
 
+**options.modelSettings.timeout** (`object`): Time-based execution budget for the run. Accepts totalMs, the maximum duration of the entire agent run across every loop iteration, tool call and retry, and stepMs, the maximum duration of a single model call including the time spent consuming its stream. Exceeding either budget fails with a MastraTimeoutError. A totalMs timeout ends the run and does not try fallback models, because it is a hard deadline for the whole run. A stepMs timeout is not retried against the same model but does advance to the next entry in models when fallback models are configured.
+
 **options.modelSettings.stopSequences** (`string[]`): Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.
 
 **options.toolChoice** (`'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }`): Controls how the agent uses tools during streaming.
@@ -264,6 +266,26 @@ for await (const chunk of stream.fullStream) {
 const fullText = await stream.text
 ```
 
+### Limiting execution time
+
+Use `modelSettings.timeout` to bound how long a run may take. `totalMs` limits the entire run, including every loop iteration, tool call and retry. `stepMs` limits a single model call, covering both establishing the stream and consuming it.
+
+```ts
+const stream = await agent.stream('Tell me a story', {
+  modelSettings: {
+    timeout: {
+      totalMs: 30000, // fail the run if it takes longer than 30s
+      stepMs: 10000, // fail an individual model call after 10s
+    },
+  },
+})
+```
+
+Exceeding either budget fails with a `MastraTimeoutError`, which carries a `timeoutType` of `'total'` or `'step'`. Each budget behaves differently when the agent is configured with fallback [`models`](https://mastra.ai/reference/agents/agent):
+
+- A `totalMs` timeout ends the run immediately and doesn't try the next model, because it's a hard deadline for the run as a whole.
+- A `stepMs` timeout isn't retried against the same model, but does advance to the next model, which makes it a way to fail over from a slow provider.
+
 ### AI SDK v5+ Format
 
 To use the stream with AI SDK v5 (and later), you can convert it using our utility function `toAISdkStream`.
@@ -303,8 +325,9 @@ const stream = await agent.stream('Tell me a story', {
   onError: ({ error }) => {
     console.error('Streaming error:', error)
   },
-  onAbort: event => {
-    console.log('Stream aborted:', event)
+  onAbort: ({ steps, text }) => {
+    console.log('Stream aborted after', steps.length, 'steps')
+    console.log('Partial text:', text)
   },
 })
 

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.2.17-alpha.17
+
+### Patch Changes
+
+- Updated dependencies [[`b860493`](https://github.com/mastra-ai/mastra/commit/b86049391100e665d579f700c8a2034c036defc3)]:
+  - @mastra/core@1.60.0-alpha.10
+
+## 1.2.17-alpha.15
+
+### Patch Changes
+
+- Updated dependencies [[`b0a2a07`](https://github.com/mastra-ai/mastra/commit/b0a2a07800d42bd9823292e7db832374ed084c9c), [`ccbbcd9`](https://github.com/mastra-ai/mastra/commit/ccbbcd974eedff4367a54ed0e24c9ee742ab2f61), [`3f5c6f7`](https://github.com/mastra-ai/mastra/commit/3f5c6f728ea35da344248de9aa070f12849f3aa0), [`77e6b1b`](https://github.com/mastra-ai/mastra/commit/77e6b1bc4c46ce94fe501023fb4393c812ec6be3), [`2e1d098`](https://github.com/mastra-ai/mastra/commit/2e1d0984e325fd319d32ea182f596b3170be3847)]:
+  - @mastra/core@1.60.0-alpha.9
+
 ## 1.2.17-alpha.14
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.17-alpha.14",
+  "version": "1.2.17-alpha.17",
   "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.60.0-alpha.8",
+    "@mastra/core": "1.60.0-alpha.10",
     "@mastra/mcp": "^1.17.0-alpha.1"
   },
   "devDependencies": {
@@ -46,7 +46,7 @@
     "typescript": "^6.0.3",
     "vitest": "4.1.10",
     "@internal/types-builder": "0.0.98",
-    "@mastra/core": "1.60.0-alpha.8",
+    "@mastra/core": "1.60.0-alpha.10",
     "@internal/lint": "0.0.123"
   },
   "homepage": "https://mastra.ai",