@mastra/mcp-docs-server 1.2.16-alpha.4 → 1.2.16-alpha.6

package/.docs/docs/agents/guardrails.md

@@ -188,16 +188,16 @@ Visit [`PIIDetector()`](https://mastra.ai/reference/processors/pii-detector) ref
 
 ### Enforce cost limits
 
-The `CostGuardProcessor()` monitors cumulative estimated cost across the agentic loop, blocking or warning when a monetary limit is exceeded. It queries cost data from observability storage before each LLM call. Cost checks are approximate, metrics are persisted asynchronously, so fast-running agents may briefly exceed the configured limit before the guard triggers.
+The `TokenCostControl()` monitors cumulative estimated cost across the agentic loop, blocking or warning when a monetary limit is exceeded. It queries cost data from observability storage before each LLM call. Cost checks are approximate, metrics are persisted asynchronously, so fast-running agents may briefly exceed the configured limit before the guard triggers.
 
 ```typescript
-import { CostGuardProcessor } from '@mastra/core/processors'
+import { TokenCostControl } from '@mastra/core/processors'
 
 export const budgetedAgent = new Agent({
   id: 'budgeted-agent',
   name: 'Budgeted Agent',
   inputProcessors: [
-    new CostGuardProcessor({
+    new TokenCostControl({
       maxCost: 5.0,
       scope: 'thread',
       window: '24h',
@@ -206,7 +206,7 @@ export const budgetedAgent = new Agent({
 })
 ```
 
-Visit [`CostGuardProcessor()`](https://mastra.ai/reference/processors/cost-guard-processor) reference for scoping modes, time windows, metric persistence delays, and the `onViolation` callback. Requires observability storage with `getMetricAggregate` support.
+Visit [`TokenCostControl()`](https://mastra.ai/reference/processors/token-cost-control) reference for scoping modes, time windows, metric persistence delays, and the `onViolation` callback. Requires observability storage with `getMetricAggregate` support.
 
 ## Processor strategies
 
@@ -232,18 +232,19 @@ All processors support an `onViolation` callback that fires when a policy violat
 The callback receives a `ProcessorViolation` object with `processorId`, `message`, and `detail` (processor-specific metadata).
 
 ```typescript
-import { CostGuardProcessor, ModerationProcessor, PIIDetector } from '@mastra/core/processors'
+import { TokenCostControl, ModerationProcessor, PIIDetector } from '@mastra/core/processors'
 
 // Alert when cost limits are exceeded
-const costGuard = new CostGuardProcessor({
+const tokenCostControl = new TokenCostControl({
   maxCost: 10.0,
   scope: 'resource',
   window: '30d',
+  strategy: 'warn',
 })
 
-costGuard.onViolation = ({ processorId, message, detail }) => {
+tokenCostControl.onViolation = ({ processorId, message, detail }) => {
   alertSystem.notify(`[${processorId}] ${message}`)
-  // detail contains: { usage, limit, totalUsage, scope, scopeKey }
+  // detail contains: { usage, limit, totalUsage, scope, scopeKey, threshold }
 }
 
 // Log moderation violations
@@ -257,9 +258,9 @@ moderation.onViolation = ({ processorId, message, detail }) => {
 }
 ```
 
-The `onViolation` property is part of the base [`Processor` interface](https://mastra.ai/reference/processors/processor-interface), so any processor, including custom ones, can use it. The runner automatically invokes `onViolation` when any processor calls `abort()`. For processors using a `warn` strategy (like `CostGuardProcessor`), the callback also fires on warnings without blocking the request.
+The `onViolation` property is part of the base [`Processor` interface](https://mastra.ai/reference/processors/processor-interface), so any processor, including custom ones, can use it. The runner automatically invokes `onViolation` when any processor calls `abort()`. For processors using a `warn` strategy (like `TokenCostControl`), the callback also fires on warnings without blocking the request.
 
-Errors thrown by the callback are silently caught to prevent interfering with the processor's main logic.
+Errors thrown by runner-invoked callbacks after `abort()` are silently caught to prevent interfering with the processor's main logic. On the `TokenCostControl` warning path, callback errors are caught and logged through the Mastra logger.
 
 For more on how violation callbacks integrate with the processor pipeline, see [Violation callbacks](https://mastra.ai/docs/agents/processors) in the Processors documentation.
 

package/.docs/docs/agents/processors.md

@@ -892,7 +892,7 @@ For `StreamErrorRetryProcessor`, also set its `maxRetries` to the same value. It
 All processors expose an `onViolation` property that fires whenever a policy violation is detected, both when `abort()` is called (block strategy) and when a processor issues a warning (warn strategy). Use it for alerting, logging, or side effects without affecting the processor's main logic:
 
 ```typescript
-import { ModerationProcessor, CostGuardProcessor } from '@mastra/core/processors'
+import { ModerationProcessor, TokenCostControl } from '@mastra/core/processors'
 
 const moderation = new ModerationProcessor({
   model: 'openai/gpt-5-nano',
@@ -904,13 +904,13 @@ moderation.onViolation = ({ processorId, message, detail }) => {
   monitor.track('processor_violation', { processorId, message, detail })
 }
 
-const costGuard = new CostGuardProcessor({
+const tokenCostControl = new TokenCostControl({
   maxCost: 10.0,
   scope: 'resource',
   window: '30d',
 })
 
-costGuard.onViolation = ({ processorId, message, detail }) => {
+tokenCostControl.onViolation = ({ processorId, message, detail }) => {
   alertSystem.notify(`[${processorId}] ${message}`)
 }
 ```
@@ -921,7 +921,7 @@ The callback receives a `ProcessorViolation` object with:
 - `message`: A human-readable description of what was violated
 - `detail`: Processor-specific metadata (e.g. cost usage, detected PII types, moderation categories)
 
-`onViolation` is part of the base [`Processor` interface](https://mastra.ai/reference/processors/processor-interface), so any custom processor can use it too. The runner automatically invokes it when any processor calls `abort()`. Errors thrown inside the callback are silently caught to prevent interfering with the processor pipeline.
+`onViolation` is part of the base [`Processor` interface](https://mastra.ai/reference/processors/processor-interface), so any custom processor can use it too. The runner automatically invokes it when any processor calls `abort()`. Errors thrown inside the callback are caught to prevent interfering with the processor pipeline.
 
 ### Abort and tripwire chunks
 

package/.docs/docs/agents/using-tools.md

@@ -287,7 +287,42 @@ Use `transform` when a tool returns raw data your application needs, but browser
 
 If a transform is configured and it fails, Mastra doesn't fall back to the raw payload for display or transcript targets. Input deltas are suppressed when no safe `inputDelta` transform is available.
 
-See the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool) for a `transform` example. For shared rules across several tools, configure the agent-level `transform` policy in the [`Agent` constructor](https://mastra.ai/reference/agents/agent).
+The following example redacts a secret from both targets:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const customerTool = createTool({
+  id: 'lookup-customer',
+  description: 'Looks up a customer by id',
+  inputSchema: z.object({
+    customerId: z.string(),
+  }),
+  outputSchema: z.object({
+    ssn: z.string(),
+  }),
+  execute: async ({ customerId }) => {
+    // const response = await fetch(`https://your-crm.example.com/customers/${customerId}`)
+    // const { ssn } = await response.json()
+    return {
+      ssn: '123-45-6789',
+    }
+  },
+  transform: {
+    display: {
+      output: () => ({ ssn: '***-**-****' }),
+    },
+    transcript: {
+      output: () => ({ ssn: '***-**-****' }),
+    },
+  },
+})
+```
+
+Your application code still receives the raw `ssn` from the tool. Browser-facing streams get the `display` output, and user-visible transcript messages get the `transcript` output.
+
+For more phases, including `input`, `inputDelta`, `error`, `approval`, `suspend`, and `resume`, see the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool). For shared rules across several tools, configure the agent-level `transform` policy in the [`Agent` constructor](https://mastra.ai/reference/agents/agent).
 
 ## Run logic around tool calls
 

package/.docs/reference/index.md

@@ -243,7 +243,6 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Span filtering](https://mastra.ai/reference/observability/tracing/span-filtering)
 - [Spans](https://mastra.ai/reference/observability/tracing/spans)
 - [BatchPartsProcessor](https://mastra.ai/reference/processors/batch-parts-processor)
-- [CostGuardProcessor](https://mastra.ai/reference/processors/cost-guard-processor)
 - [LanguageDetector](https://mastra.ai/reference/processors/language-detector)
 - [MessageHistory](https://mastra.ai/reference/processors/message-history-processor)
 - [ModerationProcessor](https://mastra.ai/reference/processors/moderation-processor)
@@ -258,6 +257,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [SkillSearchProcessor](https://mastra.ai/reference/processors/skill-search-processor)
 - [StreamErrorRetryProcessor](https://mastra.ai/reference/processors/stream-error-retry-processor)
 - [SystemPromptScrubber](https://mastra.ai/reference/processors/system-prompt-scrubber)
+- [TokenCostControl](https://mastra.ai/reference/processors/token-cost-control)
 - [TokenLimiterProcessor](https://mastra.ai/reference/processors/token-limiter-processor)
 - [ToolCallFilter](https://mastra.ai/reference/processors/tool-call-filter)
 - [ToolSearchProcessor](https://mastra.ai/reference/processors/tool-search-processor)

package/.docs/reference/processors/token-cost-control.md

@@ -0,0 +1,154 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# TokenCostControl
+
+The `TokenCostControl` enforces monetary cost limits across the agentic loop, blocking or warning when a configurable cost threshold is exceeded.
+
+It uses `processInputStep` to check the cost limit before each LLM call. Cost data is queried from the observability storage APIs (`getMetricAggregate`) for all scopes. For all scopes except `run`, it aggregates cost across runs within a configurable time window (defaults to 7 days). For `run` scope, it queries cost for the current trace.
+
+For token-based limits, use `TokenLimiterProcessor` instead.
+
+> **Renamed from `CostGuardProcessor`.** The `CostGuardProcessor` export (and its `CostGuard*` option and detail types) remains available as a deprecated alias for the same class, including the `'token-cost-control'` processor id. Migrate imports to `TokenCostControl`.
+
+Supports six scoping modes:
+
+- **Run scope**: Tracks cost within a single agent run via trace ID
+- **Resource scope** (default): Tracks cumulative cost per `resourceId` across runs
+- **Thread scope**: Tracks cumulative cost per `threadId` across runs
+- **User scope**: Tracks cumulative cost per `userId` across runs
+- **Organization scope**: Tracks cumulative cost per `organizationId` across runs
+- **Session scope**: Tracks cumulative cost per `sessionId` across runs
+
+> **Approximate cost control.** Cost data is persisted asynchronously via buffered exporters in the observability pipeline. Fast-running agents may exceed the configured limit before metrics are available for query. Treat `maxCost` as an approximate threshold that fast-running agents may exceed.
+
+> **Agent attribution only.** Cost is attributed via the `entityType: 'agent'` metric filter. Model calls made outside an agent run (for example, direct model usage in workflow steps) have no agent parent span and aren't counted by this guard.
+
+## Usage example
+
+Track cumulative cost per resource (default scope):
+
+```typescript
+import { TokenCostControl } from '@mastra/core/processors'
+
+const tokenCostControl = new TokenCostControl({
+  maxCost: 1.0,
+})
+```
+
+Track cumulative cost per thread with a 24-hour window and a soft warning at 80% of the limit:
+
+```typescript
+import { TokenCostControl } from '@mastra/core/processors'
+
+const tokenCostControl = new TokenCostControl({
+  maxCost: 5.0,
+  scope: 'thread',
+  window: '24h',
+  warnAtPercent: 80,
+})
+```
+
+Use a per-tier budget by passing a function as `maxCost`:
+
+```typescript
+import { TokenCostControl } from '@mastra/core/processors'
+
+const tokenCostControl = new TokenCostControl({
+  maxCost: requestContext => (requestContext?.get('tier') === 'pro' ? 10.0 : 1.0),
+  scope: 'user',
+})
+```
+
+Attach to an agent with an `onViolation` callback and a per-provider/model breakdown:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { TokenCostControl } from '@mastra/core/processors'
+
+const tokenCostControl = new TokenCostControl({
+  maxCost: 5.0,
+  scope: 'resource',
+  window: '30d',
+  strategy: 'warn',
+  includeBreakdown: true,
+})
+
+tokenCostControl.onViolation = ({ detail }) => {
+  console.log(
+    `Cost ${detail.threshold} threshold for ${detail.scopeKey}: $${detail.usage}/$${detail.limit}`,
+  )
+  for (const entry of detail.breakdown ?? []) {
+    console.log(`  ${entry.provider}/${entry.model}: $${entry.estimatedCost}`)
+  }
+}
+
+const agent = new Agent({
+  id: 'my-agent',
+  name: 'my-agent',
+  model: 'openai/gpt-5-nano',
+  inputProcessors: [tokenCostControl],
+})
+```
+
+## Constructor parameters
+
+**maxCost** (`number | ((requestContext?: RequestContext) => number)`): Maximum estimated cost allowed (e.g. 0.50 for $0.50 USD). A number must be finite and positive. A function is called with the request's RequestContext on every check, enabling per-tier or per-user budgets; if it returns anything other than a finite positive number, the check is skipped for that request (fail-open) and a warning is logged. This is an approximate limit due to metric persistence delays.
+
+**scope** (`'run' | 'resource' | 'thread' | 'user' | 'organization' | 'session'`): Scope for cost tracking. 'run' tracks cost within the current agent run via trace ID. 'resource' tracks cumulative cost per resourceId across runs (default). 'thread' tracks cumulative cost per threadId across runs. 'user', 'organization', and 'session' track cumulative cost per userId, organizationId, and sessionId respectively, read from the plain RequestContext keys 'userId', 'organizationId', and 'sessionId'. All scopes require observability storage with getMetricAggregate support. (Default: `'resource'`)
+
+**window** (`'1h' | '6h' | '24h' | '7d' | '30d' | '365d'`): Time window for cost aggregation for all scopes except 'run'. (Default: `'7d'`)
+
+**strategy** (`'block' | 'warn'`): Strategy when the cost limit is exceeded. 'block' aborts with a TripWire error. 'warn' logs a warning and calls onViolation at most once per request, then allows the step to proceed. (Default: `'block'`)
+
+**message** (`string`): Custom message template for the abort reason. Supports {usage} and {limit} placeholders. (Default: `'Cost control: estimated cost limit exceeded ({usage}/{limit})'`)
+
+**warnAtPercent** (`number`): Optional soft threshold as a percentage of maxCost (exclusive 0-100, e.g. 80). When the estimated cost reaches this percentage of the limit but is still below it, a warning is logged and onViolation is called once per request with threshold: "soft", regardless of strategy. Never aborts the step.
+
+**includeBreakdown** (`boolean`): When true, violations (soft and hard) include a per-provider/model cost breakdown queried via getMetricBreakdown. The breakdown is capped at the top 10 provider/model groups ranked by aggregated token volume, not by spend. The breakdown query runs only when a violation trips, never on the happy path. If the configured store does not support breakdown queries or the query fails, the violation fires without the breakdown field. (Default: `false`)
+
+## Instance properties
+
+**id** (`'token-cost-control'`): Processor identifier.
+
+**name** (`'Token Cost Control'`): Processor display name.
+
+**onViolation** (`(violation: ProcessorViolation) => void | Promise<void>`): Callback invoked when a cost violation is detected, regardless of strategy. For the warn strategy and for soft thresholds, the guard calls it with a TokenCostControlViolationDetail (usage, limit, threshold, and optional breakdown) at most once per request per threshold level. Errors thrown by the callback on this path are caught and logged through the Mastra logger. For the block strategy, the processor runner invokes it with the TripWire metadata as the detail (see Error behavior) and silently catches callback errors. Use for side effects like alerting, logging to external systems, or emailing users.
+
+**processInputStep** (`(args: ProcessInputStepArgs) => Promise<void>`): Checks cumulative estimated cost against the resolved maxCost before each LLM call. Queries observability storage for cost data: run scope filters by trace ID, all other scopes filter by their respective IDs with a time window. Calls abort() when the limit is exceeded (block strategy) or logs a warning (warn strategy). Cost checks are approximate due to metric persistence delays.
+
+## Error behavior
+
+When the `block` strategy is active (default), `TokenCostControl` calls `abort()` with `retry: false` when the cost limit is exceeded. The TripWire metadata includes:
+
+- `processorId`: `'token-cost-control'`
+- `usage`: Current cumulative usage (`estimatedCost`, `costUnit`)
+- `maxCost`: The resolved cost limit for the request
+- `scope`: The active scope
+- `scopeKey`: The scope identifier for non-run scopes (if applicable)
+- `threshold`: Always `'hard'`, since only the hard limit aborts
+- `breakdown`: Per-provider/model cost entries (only when `includeBreakdown` is enabled and the breakdown query succeeds)
+
+With the `warn` strategy, the hard-limit warning and `onViolation` callback fire at most once per request. Subsequent steps in the same request proceed without repeating the warning.
+
+Numbers interpolated into violation messages are normalized to at most 6 decimal places, so messages never contain float precision artifacts.
+
+## Scoping behavior
+
+| Scope          | Tracks across runs | Filter                         | Requires context                         |
+| -------------- | ------------------ | ------------------------------ | ---------------------------------------- |
+| `run`          | No                 | `traceId` from current span    | Tracing context (automatic)              |
+| `resource`     | Yes                | `resourceId` + time window     | `resourceId` in `RequestContext`         |
+| `thread`       | Yes                | `threadId` + time window       | `threadId` in `RequestContext`           |
+| `user`         | Yes                | `userId` + time window         | `userId` key in `RequestContext`         |
+| `organization` | Yes                | `organizationId` + time window | `organizationId` key in `RequestContext` |
+| `session`      | Yes                | `sessionId` + time window      | `sessionId` key in `RequestContext`      |
+
+All scopes require observability storage with `getMetricAggregate` support. If the Mastra instance doesn't have observability storage configured, an error is thrown at registration time.
+
+For `run` scope, the processor reads the trace ID from the current span's tracing context. If no tracing context is available, the check is skipped (fail-open).
+
+For all other scopes, if the required context ID is missing at runtime, the check is skipped. Observability query failures are handled with a fail-open strategy: if a query fails, a warning is logged through the Mastra logger and the step proceeds.
+
+> **The `user`, `organization`, and `session` scopes require annotated traces.** These scopes match metric records by their `userId`, `organizationId`, and `sessionId` fields, which are populated from span metadata on the trace (for example, via tracing options metadata). If your traces don't carry the matching metadata, these scopes match zero records and the guard never trips. Setting the RequestContext key alone isn't enough: both the RequestContext key (for scope resolution) and the span metadata (for cost attribution) must be present.
+
+> **Note on metric persistence delay.** The observability pipeline uses buffered exporters that flush metrics asynchronously. A short delay exists between when an LLM call completes and when its cost metrics are available for query. During high-frequency agent execution, the cost control may not detect a limit breach until one or more steps after the actual cost exceeded the threshold.

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.2.16-alpha.5
+
+### Patch Changes
+
+- Updated dependencies [[`d118873`](https://github.com/mastra-ai/mastra/commit/d118873cfd5074b1f814a1c169a97ca7a3a29174), [`161258b`](https://github.com/mastra-ai/mastra/commit/161258b3473a6d0fce00a43cab59d119a49a232f), [`8ea8038`](https://github.com/mastra-ai/mastra/commit/8ea80386fde53d26e2c0b2060c53bc9bd9be10f3)]:
+  - @mastra/core@1.59.0-alpha.3
+
 ## 1.2.16-alpha.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.16-alpha.4",
+  "version": "1.2.16-alpha.6",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,8 +28,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.59.0-alpha.2",
-    "@mastra/mcp": "^1.16.0"
+    "@mastra/mcp": "^1.16.0",
+    "@mastra/core": "1.59.0-alpha.3"
   },
   "devDependencies": {
     "@hono/node-server": "^2.0.0",
@@ -45,9 +45,9 @@
     "tsx": "^4.23.1",
     "typescript": "^6.0.3",
     "vitest": "4.1.10",
-    "@internal/lint": "0.0.122",
-    "@mastra/core": "1.59.0-alpha.2",
-    "@internal/types-builder": "0.0.97"
+    "@internal/types-builder": "0.0.97",
+    "@mastra/core": "1.59.0-alpha.3",
+    "@internal/lint": "0.0.122"
   },
   "homepage": "https://mastra.ai",
   "repository": {

package/.docs/reference/processors/cost-guard-processor.md

@@ -1,115 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# CostGuardProcessor
-
-The `CostGuardProcessor` enforces monetary cost limits across the agentic loop, blocking or warning when a configurable cost threshold is exceeded.
-
-It uses `processInputStep` to check the cost limit before each LLM call. Cost data is queried from the observability storage APIs (`getMetricAggregate`) for all scopes. For `resource` and `thread` scopes, it aggregates cost across runs within a configurable time window (defaults to 7 days). For `run` scope, it queries cost for the current trace.
-
-For token-based limits, use `TokenLimiterProcessor` instead.
-
-Supports three scoping modes:
-
-- **Run scope**: Tracks cost within a single agent run via trace ID
-- **Resource scope** (default): Tracks cumulative cost per `resourceId` across runs
-- **Thread scope**: Tracks cumulative cost per `threadId` across runs
-
-> **Approximate cost guard.** Cost data is persisted asynchronously via buffered exporters in the observability pipeline. Fast-running agents may exceed the configured limit before metrics are available for query. Treat `maxCost` as an approximate threshold that fast-running agents may exceed.
-
-## Usage example
-
-Track cumulative cost per resource (default scope):
-
-```typescript
-import { CostGuardProcessor } from '@mastra/core/processors'
-
-const costGuard = new CostGuardProcessor({
-  maxCost: 1.0,
-})
-```
-
-Track cumulative cost per thread with a 24-hour window:
-
-```typescript
-import { CostGuardProcessor } from '@mastra/core/processors'
-
-const costGuard = new CostGuardProcessor({
-  maxCost: 5.0,
-  scope: 'thread',
-  window: '24h',
-})
-```
-
-Attach to an agent with an `onViolation` callback:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { CostGuardProcessor } from '@mastra/core/processors'
-
-const costGuard = new CostGuardProcessor({
-  maxCost: 5.0,
-  scope: 'resource',
-  window: '30d',
-})
-
-costGuard.onViolation = ({ detail }) => {
-  console.log(`Cost exceeded for ${detail.scopeKey}: $${detail.usage}/$${detail.limit}`)
-}
-
-const agent = new Agent({
-  id: 'my-agent',
-  name: 'my-agent',
-  model: 'openai/gpt-5-nano',
-  processors: {
-    input: [costGuard],
-  },
-})
-```
-
-## Constructor parameters
-
-**maxCost** (`number`): Maximum estimated cost allowed (e.g. 0.50 for $0.50 USD). Must be a positive number. Uses cost data from observability metrics. This is an approximate limit due to metric persistence delays.
-
-**scope** (`'run' | 'resource' | 'thread'`): Scope for cost tracking. 'run' tracks cost within the current agent run via trace ID. 'resource' tracks cumulative cost per resourceId across runs (default). 'thread' tracks cumulative cost per threadId across runs. All scopes require observability storage with getMetricAggregate support. (Default: `'resource'`)
-
-**window** (`'1h' | '6h' | '24h' | '7d' | '30d' | '365d'`): Time window for cost aggregation when using 'resource' or 'thread' scope. Only applicable to non-run scopes. (Default: `'7d'`)
-
-**strategy** (`'block' | 'warn'`): Strategy when the cost limit is exceeded. 'block' aborts with a TripWire error. 'warn' logs a warning but allows the step to proceed. (Default: `'block'`)
-
-**message** (`string`): Custom message template for the abort reason. Supports {usage} and {limit} placeholders. (Default: `'Cost guard: cost limit exceeded ({usage}/{limit})'`)
-
-## Instance properties
-
-**id** (`'cost-guard'`): Processor identifier.
-
-**name** (`'Cost Guard'`): Processor display name.
-
-**onViolation** (`(violation: ProcessorViolation) => void | Promise<void>`): Callback invoked when a cost violation is detected, regardless of strategy. Part of the generalized Processor interface. Use for side effects like alerting, logging to external systems, or emailing users. Errors thrown by this callback are silently caught.
-
-**processInputStep** (`(args: ProcessInputStepArgs) => Promise<void>`): Checks cumulative estimated cost against maxCost before each LLM call. Queries observability storage for cost data: run scope filters by trace ID, resource/thread scopes filter by their respective IDs with a time window. Calls abort() when the limit is exceeded (block strategy) or logs a warning (warn strategy). Cost checks are approximate due to metric persistence delays.
-
-## Error behavior
-
-When the `block` strategy is active (default), `CostGuardProcessor` calls `abort()` with `retry: false` when the cost limit is exceeded. The TripWire metadata includes:
-
-- `processorId`: `'cost-guard'`
-- `usage`: Current cumulative usage (`estimatedCost`, `costUnit`)
-- `maxCost`: The configured cost limit
-- `scope`: The active scope (`'run'`, `'resource'`, or `'thread'`)
-- `scopeKey`: The scope identifier for resource/thread scopes (if applicable)
-
-## Scoping behavior
-
-| Scope      | Tracks across runs | Filter                      | Requires context                 |
-| ---------- | ------------------ | --------------------------- | -------------------------------- |
-| `run`      | No                 | `traceId` from current span | Tracing context (automatic)      |
-| `resource` | Yes                | `resourceId` + time window  | `resourceId` in `RequestContext` |
-| `thread`   | Yes                | `threadId` + time window    | `threadId` in `RequestContext`   |
-
-All scopes require observability storage with `getMetricAggregate` support. If the Mastra instance doesn't have observability storage configured, an error is thrown at registration time.
-
-For `run` scope, the processor reads the trace ID from the current span's tracing context. If no tracing context is available, the check is skipped (fail-open).
-
-For `resource` and `thread` scopes, if the required context ID is missing at runtime, the check is skipped. Observability query failures are handled with a fail-open strategy: if a query fails, cost is treated as zero.
-
-> **Note on metric persistence delay.** The observability pipeline uses buffered exporters that flush metrics asynchronously. A short delay exists between when an LLM call completes and when its cost metrics are available for query. During high-frequency agent execution, the cost guard may not detect a limit breach until one or more steps after the actual cost exceeded the threshold.