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

package/.docs/reference/auth/okta.md

@@ -0,0 +1,162 @@
+# MastraAuthOkta & MastraRBACOkta class
+
+## MastraAuthOkta class
+
+The `MastraAuthOkta` class provides authentication for Mastra using Okta. It implements an OAuth 2.0 / OIDC login flow with encrypted session cookies and integrates with the Mastra server using the `auth` option.
+
+### Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthOkta } from '@mastra/auth-okta'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthOkta({
+      domain: process.env.OKTA_DOMAIN,
+      clientId: process.env.OKTA_CLIENT_ID,
+      clientSecret: process.env.OKTA_CLIENT_SECRET,
+      redirectUri: process.env.OKTA_REDIRECT_URI,
+    }),
+  },
+})
+```
+
+> **Note:** You can omit the constructor parameters if you have the appropriately named environment variables set. In that case, use `new MastraAuthOkta()` without any arguments.
+
+### Constructor parameters
+
+**domain** (`string`): Your Okta domain (e.g., \`dev-123456.okta.com\`). Used to construct the issuer URL and API endpoints. (Default: `process.env.OKTA_DOMAIN`)
+
+**clientId** (`string`): The OAuth client ID from your Okta application. (Default: `process.env.OKTA_CLIENT_ID`)
+
+**clientSecret** (`string`): The OAuth client secret. Required for the SSO authorization code flow. (Default: `process.env.OKTA_CLIENT_SECRET`)
+
+**issuer** (`string`): The token issuer URL. Override this if you use a custom authorization server. (Default: `` `https://{domain}/oauth2/default` ``)
+
+**redirectUri** (`string`): The OAuth redirect URI for the SSO callback. Must match the redirect URI configured in your Okta application. (Default: `process.env.OKTA_REDIRECT_URI`)
+
+**scopes** (`string[]`): OAuth scopes to request during the login flow. (Default: `['openid', 'profile', 'email', 'groups']`)
+
+**apiToken** (`string`): Okta API token for user lookups via the Users API. Required for \`getUser()\` to return user data by ID. (Default: `process.env.OKTA_API_TOKEN`)
+
+**session** (`OktaSessionOptions`): Session cookie configuration.
+
+**session.cookieName** (`string`): Name of the session cookie.
+
+**session.cookieMaxAge** (`number`): Cookie max age in seconds.
+
+**session.cookiePassword** (`string`): Password for encrypting session cookies. Must be at least 32 characters. If not set, an auto-generated value is used that does not survive restarts.
+
+**session.secureCookies** (`boolean`): Set the \`Secure\` flag on session cookies.
+
+**name** (`string`): Custom name for the auth provider instance. (Default: `'okta'`)
+
+### Environment variables
+
+The following environment variables are automatically used when constructor options are not provided:
+
+**OKTA\_DOMAIN** (`string`): Your Okta domain (e.g., \`dev-123456.okta.com\`). Found in your Okta admin console.
+
+**OKTA\_CLIENT\_ID** (`string`): The OAuth client ID from your Okta application.
+
+**OKTA\_CLIENT\_SECRET** (`string`): The OAuth client secret from your Okta application.
+
+**OKTA\_ISSUER** (`string`): Token issuer URL. Defaults to \`https\://{domain}/oauth2/default\` if not set.
+
+**OKTA\_REDIRECT\_URI** (`string`): OAuth redirect URI for the SSO callback.
+
+**OKTA\_COOKIE\_PASSWORD** (`string`): Password for encrypting session cookies. Must be at least 32 characters.
+
+**OKTA\_API\_TOKEN** (`string`): Okta API token for user lookups and RBAC group resolution.
+
+### Authentication flow
+
+`MastraAuthOkta` authenticates requests in the following order:
+
+1. **Session cookie**: Reads the encrypted session cookie and decrypts it. If the session is valid and not expired, the user is authenticated.
+2. **JWT fallback**: If no session cookie is present, verifies the `Authorization` header token against Okta's JWKS endpoint.
+
+After authentication, `authorizeUser` checks that the user has a valid `oktaId`. Provide a custom `authorizeUser` function to implement additional logic.
+
+### `OktaUser` type
+
+The `OktaUser` type extends the base `EEUser` interface with Okta-specific fields:
+
+**id** (`string`): User identifier (maps to the \`sub\` claim).
+
+**oktaId** (`string`): Okta user ID (same as \`id\`).
+
+**email** (`string`): User email address.
+
+**name** (`string`): User display name, constructed from token claims.
+
+**avatarUrl** (`string`): URL to the user's profile picture.
+
+**groups** (`string[]`): Okta groups the user belongs to, populated from the \`groups\` claim.
+
+## MastraRBACOkta class
+
+The `MastraRBACOkta` class maps Okta groups to Mastra permissions. It fetches user groups from the Okta API and resolves them against a configurable role mapping. Use it with `MastraAuthOkta` or any other auth provider.
+
+> **Note:** RBAC requires a valid Enterprise Edition license. It works without a license in development so you can try it locally, but you’ll need a license for production. [Contact sales](https://mastra.ai/contact) for more information.
+
+### Usage example
+
+Use `MastraRBACOkta` alongside an auth provider by passing it to the `rbac` option:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthOkta, MastraRBACOkta } from '@mastra/auth-okta'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthOkta(),
+    rbac: new MastraRBACOkta({
+      roleMapping: {
+        Admin: ['*'],
+        Engineering: ['agents:*', 'workflows:*', 'tools:*'],
+        Viewer: ['agents:read', 'workflows:read'],
+        _default: [],
+      },
+    }),
+  },
+})
+```
+
+To use Okta RBAC with a different auth provider, pass a `getUserId` function to resolve the Okta user ID from the other provider's user object:
+
+```typescript
+import { MastraAuthAuth0 } from '@mastra/auth-auth0'
+import { MastraRBACOkta } from '@mastra/auth-okta'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthAuth0(),
+    rbac: new MastraRBACOkta({
+      getUserId: user => user.metadata?.oktaUserId || user.email,
+      roleMapping: {
+        Engineering: ['agents:*', 'workflows:*'],
+        Admin: ['*'],
+        _default: [],
+      },
+    }),
+  },
+})
+```
+
+### Constructor parameters
+
+**roleMapping** (`RoleMapping`): Maps Okta group names to arrays of Mastra permission strings. Use \`'\_default'\` to assign permissions to users who do not match any group. Supports wildcards like \`'\*'\` (full access) and \`'agents:\*'\` (all agent actions).
+
+**domain** (`string`): Your Okta domain. Used to initialize the Okta management SDK. (Default: `process.env.OKTA_DOMAIN`)
+
+**apiToken** (`string`): Okta API token for the management SDK. Required to fetch user groups from the Okta API. (Default: `process.env.OKTA_API_TOKEN`)
+
+**getUserId** (`(user: unknown) => string | undefined`): Extract the Okta user ID from a user object. Use this when combining Okta RBAC with a different auth provider. If not provided, falls back to \`oktaId\` or \`id\` on the user object.
+
+**cache** (`PermissionCacheOptions`): Configure the LRU cache for group lookups.
+
+**cache.maxSize** (`number`): Maximum number of users to cache.
+
+**cache.ttlMs** (`number`): Time-to-live in milliseconds.

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

@@ -308,7 +308,7 @@ response.processDataStream({
 
 ## Stored agents
 
-Stored agents are agent configurations stored in a database that can be created, updated, and deleted at runtime. They reference primitives (tools, workflows, other agents, memory, scorers) by key, which are resolved from the Mastra registry when the agent is instantiated.
+Stored agents are agent configurations stored in a database that can be created, updated, and deleted at runtime. They reference primitives (tools, workflows, other agents, scorers) by key, which are resolved from the Mastra registry when the agent is instantiated. Memory is configured inline as a `SerializedMemoryConfig` object with options such as `lastMessages` and `semanticRecall`.
 
 ### `listStoredAgents()`
 
@@ -344,7 +344,7 @@ const agent = await mastraClient.createStoredAgent({
   instructions: 'You are a helpful assistant.',
   model: {
     provider: 'openai',
-    name: 'gpt-4',
+    name: 'gpt-5.4',
   },
 })
 ```
@@ -359,12 +359,17 @@ const agent = await mastraClient.createStoredAgent({
   instructions: 'You are a helpful assistant.',
   model: {
     provider: 'openai',
-    name: 'gpt-4',
+    name: 'gpt-5.4',
+  },
+  tools: { calculator: {}, weather: {} },
+  workflows: { 'data-processing': {} },
+  agents: { 'subagent-1': {} },
+  memory: {
+    options: {
+      lastMessages: 20,
+      semanticRecall: false,
+    },
   },
-  tools: ['calculator', 'weather'],
-  workflows: ['data-processing'],
-  agents: ['subagent-1'],
-  memory: 'my-memory',
   scorers: {
     'quality-scorer': {
       sampling: { type: 'ratio', rate: 0.1 },
@@ -415,7 +420,7 @@ const updated = await storedAgent.update({
 ```typescript
 // Update just the tools
 await storedAgent.update({
-  tools: ['new-tool-1', 'new-tool-2'],
+  tools: { 'new-tool-1': {}, 'new-tool-2': {} },
 })
 
 // Update metadata

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

@@ -32,7 +32,7 @@ export const mastraClient = new MastraClient({
 
 **getAgent(agentId)** (`Agent`): Retrieves a specific agent instance by ID.
 
-**getMemoryThreads(params)** (`Promise<StorageThreadType[]>`): Retrieves memory threads for the specified resource and agent. Requires a \`resourceId\` and an \`agentId\`.
+**listMemoryThreads(params)** (`Promise<StorageThreadType[]>`): Retrieves memory threads for the specified resource and agent. Requires a \`resourceId\` and an \`agentId\`.
 
 **createMemoryThread(params)** (`Promise<MemoryThread>`): Creates a new memory thread with the given parameters.
 

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

@@ -7,7 +7,7 @@ The Memory API provides methods to manage conversation threads and message histo
 Retrieve all memory threads for a specific resource:
 
 ```typescript
-const threads = await mastraClient.getMemoryThreads({
+const threads = await mastraClient.listMemoryThreads({
   resourceId: 'resource-1',
   agentId: 'agent-1', // Optional - can be omitted if storage is configured
 })

package/.docs/reference/deployer/cloudflare.md

@@ -87,4 +87,34 @@ Use `vars` in the `CloudflareDeployer` constructor only for non-sensitive config
 
 ## Build output
 
-After running `mastra build`, the deployer generates a `wrangler.jsonc` file conforming to Cloudflare's [wrangler configuration](https://developers.cloudflare.com/workers/wrangler/configuration/). It points to files inside `.mastra/output` so you need to run `mastra build` before deploying with Wrangler.
+After running `mastra build`, the deployer generates a `wrangler.jsonc` file conforming to Cloudflare's [wrangler configuration](https://developers.cloudflare.com/workers/wrangler/configuration/). It points to files inside `.mastra/output` so you need to run `mastra build` before deploying with Wrangler.
+
+## Cloudflare bindings
+
+When you use the Cloudflare deployer, you can import runtime bindings from `cloudflare:workers` in your Mastra config file. Mastra automatically preserves protocol-based runtime imports like `cloudflare:workers` during `mastra build` without trying to install them as npm dependencies.
+
+```typescript
+import { env } from 'cloudflare:workers'
+import { Mastra } from '@mastra/core'
+import { registerApiRoute } from '@mastra/core/server'
+import { CloudflareDeployer } from '@mastra/deployer-cloudflare'
+
+export const mastra = new Mastra({
+  deployer: new CloudflareDeployer({
+    name: 'my-worker',
+    kv_namespaces: [{ binding: 'CACHE', id: 'your-kv-namespace-id' }],
+  }),
+  server: {
+    apiRoutes: [
+      registerApiRoute('/bindings', {
+        method: 'GET',
+        requiresAuth: false,
+        handler: async c => {
+          await env.CACHE.put('status', 'ok')
+          return c.json({ status: await env.CACHE.get('status') })
+        },
+      }),
+    ],
+  },
+})
+```

package/.docs/reference/evals/noise-sensitivity.md

@@ -546,9 +546,9 @@ import { createNoiseSensitivityScorerLLM } from '@mastra/evals'
 
 async function compareModelRobustness() {
   const models = [
-    { name: 'GPT-5.1', model: 'openai/gpt-5.4' },
-    { name: 'GPT-4.1', model: 'openai/gpt-4.1' },
-    { name: 'Claude', model: 'anthropic/claude-sonnet-4-6' },
+    { name: 'GPT-5.4', model: 'openai/gpt-5.4' },
+    { name: 'GPT-5.4-mini', model: 'openai/gpt-5.4-mini' },
+    { name: 'Claude', model: 'anthropic/claude-opus-4-6' },
   ]
 
   const testScenario = {

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

@@ -35,7 +35,7 @@ console.log(`Processed ${result.summary.totalItems} items`)
 
 **data** (`RunEvalsDataItem[]`): Array of test cases with input data and optional ground truth.
 
-**scorers** (`MastraScorer[] | WorkflowScorerConfig`): Array of scorers for agents, or configuration object for workflows specifying scorers for the workflow and individual steps.
+**scorers** (`MastraScorer[] | AgentScorerConfig | WorkflowScorerConfig`): Scorers to use. A flat array applies all scorers to the raw output. For agents, an \`AgentScorerConfig\` object separates agent-level and trajectory scorers. For workflows, a \`WorkflowScorerConfig\` object specifies scorers for the workflow, individual steps, and trajectory.
 
 **targetOptions** (`AgentExecutionOptions | WorkflowRunOptions`): Options forwarded to the target during execution. For agents: options passed to agent.generate() (e.g. maxSteps, modelSettings, instructions). For workflows: options passed to run.start() (e.g. perStep, outputOptions, initialState).
 
@@ -49,20 +49,32 @@ console.log(`Processed ${result.summary.totalItems} items`)
 
 **groundTruth** (`any`): Expected or reference output for comparison during scoring.
 
+**expectedTrajectory** (`TrajectoryExpectation`): Expected trajectory configuration for trajectory scoring. Includes expected steps, ordering, efficiency budgets, blacklists, and tool failure tolerance. Passed to trajectory scorers as \`run.expectedTrajectory\`. Overrides the static defaults in scorer constructors.
+
 **requestContext** (`RequestContext`): Request Context to pass to the target during execution.
 
 **tracingContext** (`TracingContext`): Tracing context for observability and debugging.
 
 **startOptions** (`WorkflowRunOptions`): Per-item workflow run options (e.g. initialState, perStep, outputOptions). Merged on top of targetOptions, so per-item values take precedence. Only applicable when the target is a workflow.
 
+## Agent scorer configuration
+
+For agents, use `AgentScorerConfig` to separate agent-level scorers from trajectory scorers:
+
+**agent** (`MastraScorer[]`): Scorers that receive the raw agent output (MastraDBMessage\[]). Use for evaluating response quality, content, etc.
+
+**trajectory** (`MastraScorer[]`): Scorers that receive a pre-extracted Trajectory object. When storage is configured, the pipeline extracts a hierarchical trajectory from observability traces (including nested tool calls and model generations). Otherwise, it falls back to extracting tool calls from agent messages.
+
 ## Workflow scorer configuration
 
-For workflows, you can specify scorers at different levels using `WorkflowScorerConfig`:
+For workflows, use `WorkflowScorerConfig` to specify scorers at different levels:
 
-**workflow** (`MastraScorer[]`): Array of scorers to evaluate the entire workflow output.
+**workflow** (`MastraScorer[]`): Scorers to evaluate the entire workflow output.
 
 **steps** (`Record<string, MastraScorer[]>`): Object mapping step IDs to arrays of scorers for evaluating individual step outputs.
 
+**trajectory** (`MastraScorer[]`): Scorers that receive a pre-extracted Trajectory from the workflow execution. When storage is configured, the pipeline extracts a hierarchical trajectory from observability traces (including nested agent runs and tool calls within workflow steps). Otherwise, it falls back to extracting step results from the workflow output.
+
 ## Returns
 
 **scores** (`Record<string, any>`): Average scores across all test cases, organized by scorer name.
@@ -105,6 +117,36 @@ const result = await runEvals({
 })
 ```
 
+### Agent trajectory evaluation
+
+Use `AgentScorerConfig` to evaluate both the agent response and its tool-calling trajectory:
+
+```typescript
+import { runEvals } from '@mastra/core/evals'
+import { createTrajectoryAccuracyScorerCode } from '@mastra/evals/scorers/code/trajectory'
+
+const trajectoryScorer = createTrajectoryAccuracyScorerCode()
+
+const result = await runEvals({
+  target: chatAgent,
+  data: [
+    {
+      input: 'What is the weather in London?',
+      expectedTrajectory: {
+        steps: [{ stepType: 'tool_call', name: 'weatherTool' }],
+      },
+    },
+  ],
+  scorers: {
+    // agent: [responseQualityScorer], // Optional: add agent-level scorers
+    trajectory: [trajectoryScorer],
+  },
+})
+
+// result.scores.agent — average agent-level scores
+// result.scores.trajectory — average trajectory scores
+```
+
 ### Agent with `targetOptions`
 
 Pass execution options like `maxSteps` or `modelSettings` to customize agent behavior during evaluation:
@@ -149,6 +191,37 @@ const workflowResult = await runEvals({
 })
 ```
 
+### Workflow trajectory evaluation
+
+Add trajectory scoring to workflow evaluations to validate step execution order:
+
+```typescript
+const workflowResult = await runEvals({
+  target: myWorkflow,
+  data: [
+    {
+      input: { query: 'Process this data' },
+      expectedTrajectory: {
+        steps: [
+          { stepType: 'workflow_step', name: 'validate' },
+          { stepType: 'workflow_step', name: 'process' },
+          { stepType: 'workflow_step', name: 'output' },
+        ],
+      },
+    },
+  ],
+  scorers: {
+    workflow: [outputQualityScorer],
+    steps: {
+      validate: [validationScorer],
+    },
+    trajectory: [trajectoryScorer],
+  },
+})
+
+// result.scores.trajectory — workflow trajectory scores
+```
+
 ### Workflow with per-item `startOptions`
 
 Use `startOptions` on individual data items to customize each workflow run. Per-item values take precedence over `targetOptions`:
@@ -175,5 +248,7 @@ const result = await runEvals({
 
 - [createScorer()](https://mastra.ai/reference/evals/create-scorer) - Create custom scorers for experiments
 - [MastraScorer](https://mastra.ai/reference/evals/mastra-scorer) - Learn about scorer structure and methods
+- [Trajectory Accuracy](https://mastra.ai/reference/evals/trajectory-accuracy) - Built-in trajectory evaluation scorers
+- [Scorer Utilities](https://mastra.ai/reference/evals/scorer-utils) - Helper functions for extracting trajectory data
 - [Custom Scorers](https://mastra.ai/docs/evals/custom-scorers) - Guide to building evaluation logic
 - [Scorers Overview](https://mastra.ai/docs/evals/overview) - Understanding scorer concepts

package/.docs/reference/evals/scorer-utils.md

@@ -14,9 +14,21 @@ import {
   extractToolCalls,
   extractInputMessages,
   extractAgentResponseMessages,
+  compareTrajectories,
+  createTrajectoryTestRun,
 } from '@mastra/evals/scorers/utils'
 ```
 
+Trajectory extraction functions are available from `@mastra/core/evals`:
+
+```typescript
+import {
+  extractTrajectory,
+  extractWorkflowTrajectory,
+  extractTrajectoryFromTrace,
+} from '@mastra/core/evals'
+```
+
 ## Message extraction
 
 ### `getAssistantMessageFromRunOutput`
@@ -266,6 +278,182 @@ const result = await myScorer.run({
 })
 ```
 
+## Trajectory utilities
+
+### `extractTrajectory`
+
+Extracts a `Trajectory` from agent output messages (`MastraDBMessage[]`). Converts tool invocations into `ToolCallStep` objects. The `runEvals` pipeline calls this automatically for trajectory scorers — you only need it for direct testing.
+
+Available from `@mastra/core/evals`.
+
+```typescript
+import { extractTrajectory } from '@mastra/core/evals'
+
+const trajectory = extractTrajectory(agentOutputMessages)
+// trajectory.steps — ToolCallStep[] extracted from toolInvocations
+// trajectory.rawOutput — the original MastraDBMessage[] array
+```
+
+**Returns:** `Trajectory` — Contains `steps: TrajectoryStep[]`, `totalDurationMs`, and `rawOutput`.
+
+### `extractWorkflowTrajectory`
+
+Extracts a `Trajectory` from workflow step results. Converts `StepResult` records into `WorkflowStepStep` objects, respecting the execution path ordering.
+
+Available from `@mastra/core/evals`.
+
+```typescript
+import { extractWorkflowTrajectory } from '@mastra/core/evals'
+
+const trajectory = extractWorkflowTrajectory(
+  workflowResult.steps, // Record<string, StepResult>
+  workflowResult.stepExecutionPath, // string[] (optional)
+)
+// trajectory.steps — WorkflowStepStep[] in execution order
+```
+
+**Returns:** `Trajectory` — Contains `steps: TrajectoryStep[]`, `totalDurationMs`, and `rawWorkflowResult`.
+
+### `extractTrajectoryFromTrace`
+
+Builds a hierarchical `Trajectory` from observability trace spans (`SpanRecord[]`). Reconstructs the parent-child span tree and maps each span to the appropriate `TrajectoryStep` discriminated union type with nested `children`.
+
+This is the preferred extraction method when storage is available. The `runEvals` pipeline calls this automatically when the target's `Mastra` instance has a configured storage backend. It produces richer trajectories than `extractTrajectory` or `extractWorkflowTrajectory` because it captures the full execution tree, including nested agent runs, tool calls, and model generations.
+
+Available from `@mastra/core/evals`.
+
+```typescript
+import { extractTrajectoryFromTrace } from '@mastra/core/evals'
+
+// After fetching a trace from the observability store
+const traceData = await observabilityStore.getTrace({ traceId })
+const trajectory = extractTrajectoryFromTrace(traceData.spans, rootSpanId)
+// trajectory.steps — hierarchical TrajectoryStep[] with children
+```
+
+**Parameters:**
+
+- `spans` (`SpanRecord[]`) — Array of span records from a trace query.
+- `rootSpanId` (`string`, optional) — Span ID to use as the starting point. When omitted, uses spans with no parent.
+
+**Returns:** `Trajectory` — Contains `steps: TrajectoryStep[]` with recursive `children` and `totalDurationMs`.
+
+#### Span type mapping
+
+| Span type              | Trajectory step type   | Key fields extracted                                          |
+| ---------------------- | ---------------------- | ------------------------------------------------------------- |
+| `TOOL_CALL`            | `tool_call`            | `toolArgs`, `toolResult`, `success`                           |
+| `MCP_TOOL_CALL`        | `mcp_tool_call`        | `toolArgs`, `toolResult`, `mcpServer`, `success`              |
+| `MODEL_GENERATION`     | `model_generation`     | `modelId`, `promptTokens`, `completionTokens`, `finishReason` |
+| `AGENT_RUN`            | `agent_run`            | `agentId` (from entity ID)                                    |
+| `WORKFLOW_RUN`         | `workflow_run`         | `workflowId` (from entity ID)                                 |
+| `WORKFLOW_STEP`        | `workflow_step`        | `output`                                                      |
+| `WORKFLOW_CONDITIONAL` | `workflow_conditional` | `conditionCount`, `selectedSteps`                             |
+| `WORKFLOW_PARALLEL`    | `workflow_parallel`    | `branchCount`, `parallelSteps`                                |
+| `WORKFLOW_LOOP`        | `workflow_loop`        | `loopType`, `totalIterations`                                 |
+| `WORKFLOW_SLEEP`       | `workflow_sleep`       | `sleepDurationMs`, `sleepType`                                |
+| `WORKFLOW_WAIT_EVENT`  | `workflow_wait_event`  | `eventName`, `eventReceived`                                  |
+| `PROCESSOR_RUN`        | `processor_run`        | `processorId`                                                 |
+
+Spans with types `GENERIC`, `MODEL_STEP`, `MODEL_CHUNK`, and `WORKFLOW_CONDITIONAL_EVAL` are skipped as noise.
+
+### `compareTrajectories`
+
+Compares an actual trajectory against an expected trajectory and returns a detailed comparison result. Used internally by `createTrajectoryAccuracyScorerCode`.
+
+The `expected` parameter accepts either a `Trajectory` (actual trajectory) or `{ steps: ExpectedStep[] }`. When using `ExpectedStep[]`, you can match by name only, name + stepType, or include data for comparison. See [Expected steps](https://mastra.ai/reference/evals/trajectory-accuracy) for details.
+
+```typescript
+import { compareTrajectories } from '@mastra/evals/scorers/utils'
+
+// Using ExpectedStep[] (recommended for expectations)
+// Data fields (e.g. toolArgs) are auto-compared when present on expected steps
+const result = compareTrajectories(
+  actualTrajectory,
+  { steps: [{ name: 'search' }, { name: 'summarize', stepType: 'tool_call' }] },
+  { allowRepeatedSteps: true },
+)
+// result.score — 0.0 to 1.0
+// result.missingSteps — step names not found
+// result.extraSteps — unexpected step names
+// result.outOfOrderSteps — steps found but in wrong order
+```
+
+**Returns:** `TrajectoryComparisonResult`
+
+### `createTrajectoryTestRun`
+
+Creates a test run object for trajectory scorers. Wraps a `Trajectory` into the expected `ScorerRun` format.
+
+```typescript
+import { createTrajectoryTestRun } from '@mastra/evals/scorers/utils'
+
+const run = createTrajectoryTestRun({
+  steps: [
+    { stepType: 'tool_call', name: 'search', toolArgs: { q: 'test' } },
+    { stepType: 'tool_call', name: 'summarize' },
+  ],
+})
+
+const result = await trajectoryScorer.run(run)
+```
+
+### `checkTrajectoryEfficiency`
+
+Evaluates trajectory efficiency against step, token, and duration budgets. Also detects redundant calls (same tool with same arguments).
+
+```typescript
+import { checkTrajectoryEfficiency } from '@mastra/evals/scorers/utils'
+
+const result = checkTrajectoryEfficiency(trajectory, {
+  maxSteps: 5,
+  maxTotalTokens: 2000,
+  maxTotalDurationMs: 5000,
+  noRedundantCalls: true,
+})
+// result.score — 1.0 if within all budgets, lower with penalties
+// result.redundantCalls — duplicate tool+args combos
+// result.overStepBudget — true if maxSteps exceeded
+// result.overTokenBudget — true if maxTotalTokens exceeded
+// result.overDurationBudget — true if maxTotalDurationMs exceeded
+```
+
+**Returns:** `TrajectoryEfficiencyResult`
+
+### `checkTrajectoryBlacklist`
+
+Checks whether a trajectory contains forbidden tools or tool call sequences.
+
+```typescript
+import { checkTrajectoryBlacklist } from '@mastra/evals/scorers/utils'
+
+const result = checkTrajectoryBlacklist(trajectory, {
+  blacklistedTools: ['deleteAll', 'admin-override'],
+  blacklistedSequences: [['escalate', 'admin-override']],
+})
+// result.score — 1.0 if no violations, 0.0 if any found
+// result.violatedTools — blacklisted tools that were called
+// result.violatedSequences — blacklisted sequences that were detected
+```
+
+**Returns:** `TrajectoryBlacklistResult`
+
+### `analyzeToolFailures`
+
+Detects tool failure patterns including retries, fallbacks, and argument corrections.
+
+```typescript
+import { analyzeToolFailures } from '@mastra/evals/scorers/utils'
+
+const result = analyzeToolFailures(trajectory, {
+  maxRetriesPerTool: 2,
+})
+// result.score — 1.0 if no failure patterns, lower if patterns detected
+// result.patterns — detected patterns (retry, fallback, arg_correction)
+```
+
+**Returns:** `ToolFailureAnalysisResult`
+
 ## Complete example
 
 Here's a complete example showing how to use multiple utilities together: