@mastra/mcp-docs-server 1.2.27-alpha.1 → 1.2.27-alpha.13

package/.docs/docs/mastra-platform/api.md

@@ -107,9 +107,11 @@ The root URL for the endpoints below is: `/v1/gateway`
 | GET    | `/projects/:id/memory/threads/:threadId/observations/history` | Observation history (dashboard)             |
 | GET    | `/models`                                                     | List available models                       |
 
-## Observability feedback query API
+## Feedback API
 
-The hosted feedback query API lists and analyzes feedback exported to Mastra Platform Observability. Because the API is unversioned, backwards compatibility isn't guaranteed. Rate limits, retention, and ingestion-to-query freshness aren't published contracts.
+The Feedback API lists and analyzes feedback exported to Mastra Platform Observability. Because the API is unversioned, backwards compatibility isn't guaranteed. Rate limits, retention, and ingestion-to-query freshness aren't published contracts.
+
+The endpoints share their query parameters, request bodies, and response types with the Mastra runtime feedback routes. See the [feedback reference](https://mastra.ai/reference/observability/feedback) for the full contract, including [list query parameters](https://mastra.ai/reference/observability/feedback) and [`FeedbackFilter`](https://mastra.ai/reference/observability/feedback).
 
 Use the root URL for your environment's data-residency region:
 
@@ -144,7 +146,23 @@ Use an organization-scoped Platform access token. Gateway inference keys such as
 | POST   | `/feedback/timeseries`  | Bucket feedback by interval  |
 | POST   | `/feedback/percentiles` | Return percentile series     |
 
-The list endpoint accepts page-mode parameters such as `page`, `perPage`, `field`, and `direction`, plus feedback filters as query parameters. It also supports delta polling with `mode=delta`, `after`, and `limit`. Responses contain a `feedback` array and page or delta metadata.
+The list endpoint takes every [`FeedbackFilter`](https://mastra.ai/reference/observability/feedback) field as a query parameter with the same name, for example `traceId`, `spanId`, `feedbackType`, `feedbackSource`, `environment`, `entityName`, `experimentId`, or `tags`. Repeat a parameter for multiple values, such as `feedbackType=rating&feedbackType=thumbs`.
+
+```bash
+curl -sS "https://observability.mastra.ai/api/observability/feedback?traceId=trace-123&environment=production" \
+  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
+  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq
+```
+
+| Parameter            | Description                                                       |
+| -------------------- | ----------------------------------------------------------------- |
+| `page`, `perPage`    | Zero-indexed page and page size (1 to 100). Default `0` and `10`. |
+| `field`, `direction` | Sort by `timestamp` in `ASC` or `DESC` order. Default `DESC`.     |
+| `mode=delta`         | Switch from paging to incremental delta polling.                  |
+| `after`              | Delta cursor from the previous delta response. Delta mode only.   |
+| `limit`              | Maximum updates per delta poll (1 to 100). Delta mode only.       |
+
+Responses contain a `feedback` array and page or delta metadata. See [list query parameters](https://mastra.ai/reference/observability/feedback) in the feedback reference for the full parameter contract, including JSON-encoded object filters such as `timestamp`.
 
 Analytics endpoints accept the same JSON request shapes and return types as the [feedback reference](https://mastra.ai/reference/observability/feedback). Analytics operate only on numeric feedback values.
 

package/.docs/docs/mastra-platform/observability.md

@@ -166,7 +166,191 @@ bun x mastra api trace list
 
 The CLI can infer platform credentials from your project environment. See the [`mastra api` CLI reference](https://mastra.ai/reference/cli/mastra) for available commands, filtering, pagination, credential resolution, and `curl` examples.
 
-You can query exported feedback over HTTP. See the [observability feedback query API](https://mastra.ai/docs/mastra-platform/api) for its current status, regional endpoints, authentication, and project scoping.
+You can query exported feedback over HTTP. See the [Feedback API](https://mastra.ai/docs/mastra-platform/api) for its current status, regional endpoints, authentication, project scoping, and supported query parameters such as `traceId` and `environment`.
+
+## Import existing traces
+
+Use `mastra traces import` to move existing trace history from a supported observability provider into an existing Mastra Platform project. The command reads and validates complete traces at the source, converts them into Mastra spans, then uses a shared workflow for preparation, upload, resume, and verification.
+
+The import command currently supports Langfuse. Additional providers can use the same command workflow when their adapters are added.
+
+| Provider | Command argument | Source requirement                                 |
+| -------- | ---------------- | -------------------------------------------------- |
+| Langfuse | `langfuse`       | Langfuse Cloud or self-hosted Langfuse v4 or later |
+
+### Prerequisites
+
+Before starting an import, you need:
+
+- A Mastra Platform project.
+- Mastra Platform authentication through `mastra auth login`, or a `MASTRA_API_TOKEN` and `MASTRA_ORG_ID` for a headless environment.
+- `MASTRA_PLATFORM_ACCESS_TOKEN` for upload and read-back when using an interactive login. A dry run doesn't require this token.
+- Credentials for a supported source provider.
+- Enough local disk space to temporarily store the prepared traces.
+
+### Configure the destination
+
+For an interactive import, sign in and select the organization that owns the destination project:
+
+```bash
+npx mastra auth login
+npx mastra auth orgs switch
+```
+
+Interactive login authorizes project discovery. Set the Platform access token used by the destination project before uploading or verifying traces:
+
+```bash
+MASTRA_PLATFORM_ACCESS_TOKEN=<mastra-platform-access-token>
+```
+
+If `mastra init` configured observability for the project, use the token it wrote to `.env`. Otherwise, create an access token in [Mastra Platform](https://projects.mastra.ai).
+
+You can run `--dry-run` without this token because a dry run doesn't contact the collector or query API.
+
+Specify the destination with `--project`, or set `MASTRA_PROJECT_ID`. You can use a project name, slug, or ID with `--project`:
+
+```bash
+npx mastra traces import langfuse --project my-project --dry-run
+```
+
+If `MASTRA_PROJECT_ID` is set, it takes precedence over `--project`. Without either value, the CLI uses the project linked in `.mastra-project.json`.
+
+For a headless environment, set the API token and organization ID. The command uses `MASTRA_API_TOKEN` for project discovery, upload, and read-back. Set the project ID or pass `--project`:
+
+```bash
+MASTRA_API_TOKEN=<mastra-api-token>
+MASTRA_ORG_ID=<organization-id>
+MASTRA_PROJECT_ID=<project-id>
+```
+
+### Configure Langfuse
+
+Create [project API keys in Langfuse](https://langfuse.com/docs/api-and-data-platform/features/public-api), then add them to `.env` or `.env.local` in the directory where you run the command:
+
+```bash
+LANGFUSE_PUBLIC_KEY=<langfuse-public-key>
+LANGFUSE_SECRET_KEY=<langfuse-secret-key>
+```
+
+Langfuse Cloud defaults to the EU region at `https://cloud.langfuse.com`. Set `LANGFUSE_BASE_URL` to the [regional host](https://langfuse.com/security/data-regions) for US, Japan, or HIPAA Cloud, or to the origin of a self-hosted instance:
+
+```bash
+LANGFUSE_BASE_URL=https://us.cloud.langfuse.com
+```
+
+### Preview the import
+
+Run a dry run before uploading:
+
+```bash
+npx mastra traces import langfuse --project my-project --dry-run
+```
+
+The dry run reads the source, prepares valid Mastra traces locally, and reports:
+
+- The source and destination projects.
+- The fixed import window.
+- Prepared and skipped trace and span counts.
+- The size of the prepared local data.
+- Provider warnings and skip reasons in `report.json`.
+
+It doesn't upload traces. The command prints a `--resume` command that uploads the prepared data later without reading the source again.
+
+### Choose the import window
+
+By default, the command selects the last 30 days, ending when the import starts. Use `--from` and `--to` to choose a smaller window:
+
+```bash
+npx mastra traces import langfuse \
+  --project my-project \
+  --from "$FROM" \
+  --to "$TO" \
+  --dry-run
+```
+
+Set `FROM` and `TO` to ISO 8601 dates or timestamps. The following rules apply:
+
+- `--to` can't be in the future or outside the current 30-day Platform retention period.
+- `--from` must be earlier than `--to` and inside the current retention period.
+- The selected window can't exceed 30 days.
+- If only `--to` is set, the default start is the later of 30 days before `--to` and the current retention boundary.
+
+Trace eligibility is based on the root observation's start time. The Langfuse adapter discovers roots in the selected window and then reads all currently available observations for each selected trace. It skips the complete trace if the available parent-child tree or timestamps are invalid.
+
+### Upload and verify
+
+Run the command without `--dry-run` to upload the prepared traces:
+
+```bash
+npx mastra traces import langfuse --project my-project
+```
+
+The CLI displays the preparation summary and asks for confirmation before upload. Pass `--yes` to skip this prompt in an automated environment:
+
+```bash
+npx mastra traces import langfuse --project my-project --yes
+```
+
+The importer keeps every trace in one upload request and checkpoints progress only after Mastra Platform acknowledges the batch. Temporary source and destination failures use bounded retries.
+
+After every prepared trace is acknowledged, the importer reads back a deterministic sample of up to 10 traces. It verifies span IDs, parent links, names, span types, event flags, timestamps, and whether an error is present. It doesn't read back or compare input, output, attributes, metadata, or tags.
+
+If read-back isn't available yet or a sampled trace differs, the import pauses and keeps its prepared data. Resume the import to retry verification without uploading acknowledged traces again.
+
+### Resume an import
+
+Use the exact command printed by the CLI when a dry run, cancellation, interruption, upload failure, or paused verification leaves an import unfinished:
+
+```bash
+npx mastra traces import langfuse \
+  --resume 00000000-0000-0000-0000-000000000000 \
+  --project my-project
+```
+
+A resumed import must use the original provider and destination project. Its saved date window can't be changed, so `--from`, `--to`, and `--dry-run` can't be combined with `--resume`.
+
+Resume behavior depends on where the command stopped:
+
+- An interrupted preparation reads and prepares the source again.
+- An interrupted upload starts with the first unacknowledged trace.
+- Paused verification retries read-back without re-uploading acknowledged traces.
+- A completed import reports that it's already complete and retries any remaining local cleanup.
+
+### Local files and cleanup
+
+Import state is stored under:
+
+```text
+~/.mastra/imports/traces/<target-project-id>/<import-id>/
+```
+
+| File            | Purpose                                                                     | Lifecycle                                                                                 |
+| --------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `manifest.json` | Stores the source identity, date window, counts, and acknowledged progress. | Retained after completion.                                                                |
+| `traces.jsonl`  | Stores one complete normalized trace per line.                              | Retained for dry runs and unfinished imports, then removed after successful verification. |
+| `report.json`   | Stores counts, warnings, skip samples, and verification results.            | Retained after it's written.                                                              |
+
+These files can contain trace content. Mastra creates the import directory and files with permissions restricted to the local user. Protect the machine and account that run the import.
+
+### Imported data and limits
+
+For Langfuse imports:
+
+- Observations become Mastra spans with their parent-child relationships and timestamps.
+- Supported fields such as names, input, output, errors, model details, usage, cost, tags, and source context are mapped when present.
+- Destination trace and span IDs are deterministic. Original Langfuse IDs remain in span metadata for correlation.
+- Unknown Langfuse observation types become generic spans and produce a warning instead of being silently discarded.
+- Only trace observations are imported. Scores, feedback, datasets, attachments, and logs aren't imported.
+
+The shared importer also applies these limits:
+
+- Prepared local trace data is limited to 5 GiB per import. Use a smaller date window if an import reaches this limit.
+- A complete trace must fit within the importer's 4 MiB upload payload limit. A larger trace is skipped and recorded with the `trace_too_large` reason.
+- A trace is never split between upload requests.
+
+Review `report.json` after a dry run or completed import to see exactly what was prepared, skipped, acknowledged, and verified.
+
+See the [`mastra traces import` CLI reference](https://mastra.ai/reference/cli/mastra) for the complete option and environment-variable reference.
 
 ## Next steps
 

package/.docs/docs/mastra-platform/overview.md

@@ -14,6 +14,8 @@ Deploy with a single command, [`mastra deploy`](https://mastra.ai/docs/mastra-pl
 
 Each project can run multiple [**Environments**](https://mastra.ai/docs/mastra-platform/environments) (for example `production` and `staging`) and provision [**Hosted databases**](https://mastra.ai/docs/mastra-platform/database) from the CLI or project settings to persist application data. Each environment also gets a managed [**Workspace**](https://mastra.ai/docs/mastra-platform/workspaces) that gives agents a filesystem and sandbox with no manual configuration.
 
+Organization-level [**Alerts**](https://mastra.ai/docs/mastra-platform/alerts) notify your team when deploys fail or running services stop. Alerts can cover every project or selected projects and environments, with notifications sent to Slack, email, or webhooks.
+
 [**Trace Intelligence**](https://mastra.ai/docs/mastra-platform/trace-intelligence) finds recurring goals, outcomes, behaviors, and sentiment across your agent traces. Trace Intelligence is available in private beta for selected projects.
 
 ## Get started

package/.docs/docs/memory/message-history.md

@@ -124,6 +124,27 @@ You can use this history in two ways:
 
 > **Note:** `lastMessages` counts every stored message, including tool calls, tool results, and [signals](https://mastra.ai/docs/harness/signals) of any kind, so a single turn can add several messages to the count. The window also slides forward on every request: once a thread grows past the limit, the oldest message leaves context on each turn, which changes the start of the prompt and invalidates the provider prompt cache. For long-running conversations, use [Observational Memory](https://mastra.ai/docs/memory/observational-memory), which keeps the prompt prefix stable.
 
+### Limit history by tokens
+
+Message count is a poor proxy for context size: a tool result can be a few tokens or thousands. Use `messageHistory` to keep recent history within a token budget instead:
+
+```typescript
+export const agent = new Agent({
+  id: 'test-agent',
+  memory: new Memory({
+    options: {
+      messageHistory: { maxTokens: 8_000, atMaxRemoveTokens: 2_000 },
+    },
+  }),
+})
+```
+
+Mastra counts the complete prompt against `maxTokens`, including remembered history, system instructions, context, and the current turn. When the prompt exceeds the budget, Mastra removes the oldest remembered messages until the prompt is at most `maxTokens - atMaxRemoveTokens`. `atMaxRemoveTokens` defaults to 25% of `maxTokens`. Removing history in chunks keeps the prompt prefix stable across several turns, which helps provider prompt caches stay warm.
+
+System messages, context, the current turn's input, and the agent's responses are never trimmed. Linked tool calls and results are removed together. If protected content alone exceeds `maxTokens`, Mastra removes all remembered history but keeps the protected content.
+
+Trimmed messages stay in storage. During agent runs, Mastra persists a per-thread boundary so they're excluded from later turns. Setting `messageHistory` without `lastMessages` disables the default 10-message cap. Set both to combine a count cap with a token budget. Set `maxTokens` to `0` to disable message history.
+
 > **Tip:** When memory is enabled, [Studio](https://mastra.ai/docs/studio/overview) uses message history to display past conversations in the chat sidebar.
 
 ## Thread title generation
@@ -149,6 +170,43 @@ export const supportAgent = new Agent({
 
 Title generation runs asynchronously after the agent responds and doesn't affect response time.
 
+### Streaming the generated title
+
+By default title generation runs in the background and the run's stream doesn't wait for it, so HTTP clients only see the title on their next thread fetch. Set `emitEvent: true` to deliver the title on the run's stream instead: the stream waits for the title and emits a transient `data-thread-title` chunk before `finish`.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support agent',
+  instructions: 'Answer customer support questions.',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory({
+    options: {
+      generateTitle: {
+        emitEvent: true,
+      },
+    },
+  }),
+})
+```
+
+Stream consumers receive the chunk with the persisted title, so a chat UI can rename its thread list entry without polling:
+
+```typescript
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'data-thread-title') {
+    renameThreadInSidebar(chunk.data.threadId, chunk.data.title)
+  }
+}
+```
+
+The chunk is transient: it's delivered to stream consumers but never persisted as part of the conversation's messages. Because the stream waits for the title, `emitEvent` delays the stream's `finish` on the turn that generates the title: the first turn of a thread, or a later turn when `minMessages` sets a higher threshold. Leave it off to keep title generation fully non-blocking.
+
+> **Note:** `emitEvent` applies to `stream()` runs. `generate()` returns JSON and can't carry the chunk, so it keeps non-blocking title generation. [Durable and evented agents](https://mastra.ai/docs/harness/durable-agents) don't emit this chunk yet. In all of these cases the title is still generated and persisted.
+
 To optimize cost or behavior, provide a smaller [`model`](https://mastra.ai/models) and custom `instructions`:
 
 ```typescript

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

@@ -849,6 +849,39 @@ Transform hooks are always awaited, on every path (manual `observe()`/`reflect()
 
 Because hooks receive `threadId` and `resourceId`, you can also use them to update [working memory](https://mastra.ai/docs/memory/working-memory) via `memory.updateWorkingMemory()` during a cycle. These external updates aren't atomic with the OM text commit.
 
+### Redact skill results
+
+Agent skills are injected into the agent as tools (`skill`, `skill_search`, `skill_read`). Their results contain the skill's full instructions or file contents, so without redaction the Observer re-observes that text every time a skill is used. `skillResultRedactor()` is a ready-made `beforeObservation` hook that replaces those results with a placeholder and leaves everything else in place. The tool call survives, so the Observer still records which skill was used and what it was called with.
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { skillResultRedactor } from '@mastra/memory/hooks'
+
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      hooks: {
+        beforeObservation: skillResultRedactor(),
+      },
+    },
+  },
+})
+```
+
+Pass `toolNames` to redact results from a different set of tools. Because a hook is a function over the messages, it composes with your own transforms by chaining the outputs. Await each chained hook so an async one isn't discarded:
+
+```typescript
+const dropSkillResults = skillResultRedactor()
+
+hooks: {
+  beforeObservation: async input => {
+    const messages = (await dropSkillResults(input))?.messages ?? input.messages
+    return { messages: messages.filter(m => m.role !== 'signal') }
+  },
+}
+```
+
 ## Migrating existing threads
 
 No manual migration needed. OM reads existing messages and observes them lazily when thresholds are exceeded.

package/.docs/docs/observability/feedback.md

@@ -108,7 +108,7 @@ const result = await observability!.listFeedback({
 console.log(result.feedback, result.pagination?.hasMore)
 ```
 
-Filters include target fields such as `traceId` and `spanId`, feedback fields such as `feedbackType`, `feedbackSource`, and `feedbackUserId`, and shared context fields such as `entityName`, `environment`, `experimentId`, and `tags`.
+Filters include target fields such as `traceId` and `spanId`, feedback fields such as `feedbackType`, `feedbackSource`, and `feedbackUserId`, and shared context fields such as `entityName`, `environment`, `experimentId`, and `tags`. See [`FeedbackFilter`](https://mastra.ai/reference/observability/feedback) for every filter field. Over HTTP, the same fields are passed as query parameters, for example `GET /api/observability/feedback?traceId=trace-123&environment=production`. See [list query parameters](https://mastra.ai/reference/observability/feedback).
 
 ```typescript
 await observability!.listFeedback({
@@ -130,7 +130,7 @@ await observability!.deleteFeedback({
 })
 ```
 
-Deleted records also disappear from feedback analytics. ClickHouse uses a lightweight delete to hide rows without guaranteeing immediate physical removal, so open-source deployments must configure an [observability retention period](https://mastra.ai/reference/storage/retention) to physically purge them. ClickHouse doesn't configure a retention TTL for deletion requests in open-source deployments. Delete APIs intentionally leave cursor-only delta rows untouched. These rows contain identifiers rather than feedback payloads and expire within two days.
+Deleted records also disappear from feedback analytics. ClickHouse uses a lightweight delete to hide rows without guaranteeing immediate physical removal, so open-source deployments must configure an [observability retention period](https://mastra.ai/reference/storage/retention) to physically purge them. Configure retention for every observability signal to expire deletion requests after the signal rows they protect. If any signal is unbounded, deletion requests also remain unbounded to prevent deleted data from being reintroduced. Delete APIs intentionally leave cursor-only delta rows untouched. These rows contain identifiers rather than feedback payloads and expire within two days.
 
 ## Query feedback analytics
 
@@ -161,7 +161,7 @@ const ratingsOverTime = await observability!.getFeedbackTimeSeries({
 
 See the [feedback reference](https://mastra.ai/reference/observability/feedback) for all fields, filters, return types, and percentile query parameters.
 
-The local runtime exposes the list route at `/api/observability/feedback` and analytics under its related paths. See the [HTTP routes table](https://mastra.ai/reference/observability/feedback). Mastra Platform provides a separate, unversioned hosted query API. See the [observability feedback query API](https://mastra.ai/docs/mastra-platform/api) for regional endpoints, authentication, and project scoping.
+The local runtime exposes the list route at `/api/observability/feedback` and analytics under its related paths. See the [HTTP routes table](https://mastra.ai/reference/observability/feedback) and [list query parameters](https://mastra.ai/reference/observability/feedback). Mastra Platform provides a separate, unversioned hosted query API. See the [Feedback API](https://mastra.ai/docs/mastra-platform/api) for regional endpoints, authentication, and project scoping.
 
 ## Export feedback to Mastra Platform
 

package/.docs/docs/observability/tracing/overview.md

@@ -459,6 +459,8 @@ export const mastra = new Mastra({
 })
 ```
 
+`process()` must mutate the span it receives and return the same instance, or return `undefined` to drop the span. Don't return a copy (for example `{ ...span, input: '...' }`): `exportSpan()` and `isValid` are instance members of the live span, so a copy can't be exported. Mastra logs a processor error and drops the span in that case.
+
 Processors are executed in the order they're defined, allowing you to chain multiple transformations. Common use cases include:
 
 - Redacting sensitive data (passwords, tokens, API keys)

package/.docs/docs/server/custom-adapters.md

@@ -371,6 +371,49 @@ await server.init()
 app.listen(4111)
 ```
 
+## Test adapter compatibility
+
+Use `@mastra/server-adapters-test-suite` to run the same conformance tests as Mastra's official adapters. Install it with its peer dependencies in your adapter project:
+
+**npm**:
+
+```bash
+npm install --save-dev @mastra/server-adapters-test-suite @mastra/core @mastra/mcp @mastra/server vitest zod
+```
+
+**pnpm**:
+
+```bash
+pnpm add --save-dev @mastra/server-adapters-test-suite @mastra/core @mastra/mcp @mastra/server vitest zod
+```
+
+**Yarn**:
+
+```bash
+yarn add --dev @mastra/server-adapters-test-suite @mastra/core @mastra/mcp @mastra/server vitest zod
+```
+
+**Bun**:
+
+```bash
+bun add --dev @mastra/server-adapters-test-suite @mastra/core @mastra/mcp @mastra/server vitest zod
+```
+
+Provide framework-specific setup and request execution functions to the route suite:
+
+```typescript
+import { createRouteAdapterTestSuite } from '@mastra/server-adapters-test-suite'
+import { executeHttpRequest, setupAdapter } from './adapter-test-helpers'
+
+createRouteAdapterTestSuite({
+  suiteName: 'My framework adapter',
+  setupAdapter,
+  executeHttpRequest,
+})
+```
+
+The package also provides root exports for Model Context Protocol (MCP), multipart request, HTTP logging, and body limit tests. See the [package README](https://github.com/mastra-ai/mastra/tree/main/server-adapters/server-adapters-test-suite) for the supported peer dependency versions.
+
 > **Tip:** The existing [@mastra/hono](https://github.com/mastra-ai/mastra/blob/main/server-adapters/hono/src/index.ts) and [@mastra/express](https://github.com/mastra-ai/mastra/blob/main/server-adapters/express/src/index.ts) implementations are good references when building your custom adapter. They show how to handle framework-specific patterns for context storage and middleware registration, plus response handling.
 >
 > If you want to use [Studio](https://mastra.ai/docs/studio/overview) with your server adapter, use [`mastra studio`](https://mastra.ai/reference/cli/mastra) to only launch the Studio UI.

package/.docs/docs/subagents.md

@@ -135,11 +135,13 @@ The subagent reads these entries in its tools and dynamic configuration, such as
 Called after a delegation finishes. Use it to inspect results or provide feedback, or alternatively stop execution:
 
 - `context.bail()`: Stop the parent agent's loop immediately
-- Return `{ feedback: '...' }`: Add feedback that gets saved to the parent agent's memory and is visible to subsequent iterations
+- Return `{ feedback: '...' }`: Add feedback that gets saved to the parent agent's memory and is available on the next turn
 - Return `{ resultText: '...' }`: Replace the tool result text the parent model sees for this delegation, within the current run
 
 Set `resultText` when the subagent's own result would give the parent a misleading signal. For example, empty text from a subagent stopped on a tool-calls step looks like a successful but empty delegation to the parent model. You can also replace the error text from a failed delegation with a more useful message. This doesn't recover the delegation. The parent still receives a failed tool result. Unlike `feedback` on the next turn, `resultText` affects the parent's reasoning immediately.
 
+To stop the parent agent on failure and save feedback for a later turn, call `bail()` and return `feedback`:
+
 ```typescript
 const stream = await parentAgent.stream('Research AI trends', {
   maxSteps: 10,
@@ -161,12 +163,41 @@ const stream = await parentAgent.stream('Research AI trends', {
 
 The `context` object includes:
 
-| Property      | Description                                                                                   |
-| ------------- | --------------------------------------------------------------------------------------------- |
-| `primitiveId` | The ID of the subagent that ran                                                               |
-| `result`      | The subagent's response, including `text`, `usage`, `finishReason`, and `subAgentToolResults` |
-| `error`       | Error if the delegation failed                                                                |
-| `bail()`      | Function to stop the parent agent's loop                                                      |
+| Property      | Description                                                                                                                                            |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `primitiveId` | The ID of the subagent that ran                                                                                                                        |
+| `result`      | The subagent's response, including `text`, `usage`, `finishReason`, `subAgentToolResults`, `subAgentThreadId`, and `subAgentResourceId` when available |
+| `success`     | Whether the delegation succeeded                                                                                                                       |
+| `error`       | The original error if the delegation failed                                                                                                            |
+| `messages`    | The collected subagent transcript, including partial messages when available                                                                           |
+| `bail()`      | Function to stop the parent agent's loop                                                                                                               |
+
+#### Failed delegations
+
+When a subagent run fails, the parent model receives a failed tool result with a generic error message. This doesn't automatically stop the parent agent, which can explain the failure or choose another approach. Call `context.bail()` to stop its loop instead.
+
+The hook receives `success: false`, the original `error`, and any collected partial results and messages. Returning `resultText` replaces the error text the parent model sees without changing the delegation's failed status or discarding its original cause. An empty string is also a valid replacement.
+
+To let the parent continue with a curated failure message instead of stopping its loop, return `resultText` without calling `bail()`:
+
+```typescript
+const stream = await parentAgent.stream('Research AI trends', {
+  maxSteps: 10,
+  delegation: {
+    onDelegationComplete: ({ success }) => {
+      if (!success) {
+        return {
+          resultText: 'The delegated task failed. Try another approach.',
+        }
+      }
+    },
+  },
+})
+```
+
+Prefer a curated message, as in this example. Returning `{ resultText: error.message }` explicitly forwards the underlying message to the parent model's provider, and the model may repeat it to the end user. Provider errors can contain sensitive information. A generic `resultText` isn't a redaction policy for logs, traces, or streamed error payloads.
+
+For delegations run as [background tasks](https://mastra.ai/docs/harness/background-tasks), configured retries can invoke `onDelegationComplete` once per attempt. Account for repeated calls if your hook has side effects.
 
 ### Hook errors
 

package/.docs/integrations/channels/github.md

@@ -41,9 +41,13 @@ GitHub Signals requires:
 - A Mastra storage adapter with memory and notification support. The provider stores each subscription in the thread's metadata, so the thread must already exist.
 - The `gitcrawl` command on `PATH`, configured to access the repositories you want to monitor. The provider runs `gitcrawl sync` and reads its SQLite database.
 - The `sqlite3` command on `PATH`.
-- The [GitHub CLI](https://cli.github.com/) installed and authenticated. The provider uses `gh api` to check whether comment authors have access to the repository before notifying the agent.
+- The [GitHub CLI](https://cli.github.com/) installed and authenticated. The provider uses real `gh api` responses to check repository permissions and GitHub App ownership before notifying the agent.
 
-By default, comments from users with `admin`, `maintain`, or `write` access can trigger notifications. CodeRabbit and Devin bot comments are also allowed. Configure `authorizedPermissions`, `authorizedBots`, or `ignoredBots` when you need different rules.
+By default, comments from users with `admin`, `maintain`, or `write` access can trigger notifications. CodeRabbit and Devin bot comments are explicitly allowed.
+
+Bot authorization checks `ignoredBots` first, using an exact case-insensitive login match. Other bots can trigger notifications when they appear in `authorizedBots`, when the GitHub App is owned by a user whose repository permission appears in `authorizedPermissions`, or when the app is owned by the organization that owns the repository. The default authorized permissions are `admin`, `maintain`, and `write`.
+
+Failed, inaccessible, malformed, and unsupported app-owner lookups deny the bot comment. Successful app-owner lookups are cached for 24 hours; failed lookups aren't cached.
 
 ## Agent and subscription
 

package/.docs/integrations/databases/clickhouse.md

@@ -91,7 +91,7 @@ Trace deletion cascades to spans, trace roots and branches, metrics, logs, score
 
 Lightweight deletion is a hide-only operation that marks rows with ClickHouse's `_row_exists` mask. Physical removal depends on merges and deployment-configured retention TTLs. `ObservabilityStorageClickhouseVNext` applies retention only when you provide a `RetentionConfig`; Mastra OSS doesn't configure a default retention TTL.
 
-Deletion requests aren't purged automatically in Mastra OSS. Automatic retirement will be introduced with future database-agnostic retention configuration.
+When all five observability signals have finite retention, Mastra also applies a TTL to deletion requests so they outlive the signal rows they protect. If any signal is unbounded, deletion requests remain unbounded. See [storage retention](https://mastra.ai/reference/storage/retention) for how the deletion-request TTL is calculated.
 
 ### Observability with the legacy domain