@salesforce/sfdx-agent-harness-mastra 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to `@salesforce/sfdx-agent-harness-mastra` are documented in this file.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.16.0] - 2026-06-09
+
+### Features
+- **release**: auto-generate per-package CHANGELOG.md on publish ([#567](https://github.com/forcedotcom/agentic-dx/pull/567))
+- unify tool-exposure policy under toolSearch.alwaysActive ([#566](https://github.com/forcedotcom/agentic-dx/pull/566))
+- add ClaudeAgentConfig.skillSearch + decouple Mastra skillSearch from toolSearch ([#563](https://github.com/forcedotcom/agentic-dx/pull/563))
+- **agent-sdk**: preserve MCP clients across updateAgentConfig ([#560](https://github.com/forcedotcom/agentic-dx/pull/560))
+- **agent-sdk,harness-claude,harness-mastra**: first-class tool-result redaction ([#546](https://github.com/forcedotcom/agentic-dx/pull/546))
+
+### Fixes
+- **harness-claude,harness-mastra**: align event/log payload shapes ([#562](https://github.com/forcedotcom/agentic-dx/pull/562))
+- **harness-mastra**: honor MCPServerConfig.alwaysLoad when toolSearch is set ([#558](https://github.com/forcedotcom/agentic-dx/pull/558))
+
+### Chores
+- **harness-claude,harness-mastra**: re-enable monorepoLintPack at four offender sites ([#561](https://github.com/forcedotcom/agentic-dx/pull/561))
+- **deps-dev**: bump the eslint group across 1 directory with 2 updates ([#553](https://github.com/forcedotcom/agentic-dx/pull/553))
+- **deps**: bump the mastra group across 1 directory with 3 updates ([#539](https://github.com/forcedotcom/agentic-dx/pull/539))
+- **deps-dev**: bump the dev-dependencies group across 1 directory with 4 updates ([#536](https://github.com/forcedotcom/agentic-dx/pull/536))
+- **deps-dev**: bump the vitest group across 1 directory with 3 updates ([#552](https://github.com/forcedotcom/agentic-dx/pull/552))
+

package/README.md

@@ -62,13 +62,14 @@ These types let consumers reach Mastra-specific features through the SDK's typed
 `MastraAgentHarness` from `MastraHarnessFactory.create()`, so consumers usually don't reference these types explicitly —
 they show up via inference at the call site.
 
-| Export                   | Kind | Description                                                                                                                                          |
-| ------------------------ | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `MastraAgentHarness`     | type | Branded `AgentHarness` subtype; carries the Mastra-specific `extensions` namespace and the inferred config type.                                     |
-| `MastraAgentConfig`      | type | `AgentConfig` extended with Mastra-only fields (currently `toolSearch`). Inferred at `manager.createAgent` automatically — annotation rarely needed. |
-| `MastraToolSearchConfig` | type | Shape of `MastraAgentConfig.toolSearch` (`pool`, `alwaysActive`, `topK`, `ttl`).                                                                     |
-| `ToolSearchHandle`       | type | Stable interface for the tool-search runtime: `id`, `getStateStats`, `clearState`, `clearAllState`, `cleanupNow`. Wraps Mastra's internal processor. |
-| `SkillSearchHandle`      | type | Stable interface for the skill-search runtime: `id` (Mastra's processor has no other public methods today; the harness owns lifecycle).              |
+| Export                    | Kind | Description                                                                                                                                               |
+| ------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MastraAgentHarness`      | type | Branded `AgentHarness` subtype; carries the Mastra-specific `extensions` namespace and the inferred config type.                                          |
+| `MastraAgentConfig`       | type | `AgentConfig` extended with Mastra-only fields (`toolSearch`, `skillSearch`). Inferred at `manager.createAgent` automatically — annotation rarely needed. |
+| `MastraToolSearchConfig`  | type | Shape of `MastraAgentConfig.toolSearch` (`pool`, `alwaysActive`, `topK`, `ttl`).                                                                          |
+| `MastraSkillSearchConfig` | type | Shape of `MastraAgentConfig.skillSearch` (`topK`). Opts into Mastra's `SkillSearchProcessor`.                                                             |
+| `ToolSearchHandle`        | type | Stable interface for the tool-search runtime: `id`, `getStateStats`, `clearState`, `clearAllState`, `cleanupNow`. Wraps Mastra's internal processor.      |
+| `SkillSearchHandle`       | type | Stable interface for the skill-search runtime: `id` (Mastra's processor has no other public methods today; the harness owns lifecycle).                   |
 
 The Mastra-specific accessors live on `manager.extensions.mastra` (`getToolSearchProcessor(agentId)`,
 `getSkillSearchProcessor(agentId)`, `formatMcpToolName(serverName, toolName)`) and require no separate import.
@@ -90,12 +91,13 @@ const agent = await manager.createAgent(projectRoot, {
   toolSearch: {
     pool: '*', // or an explicit name list
     alwaysActive: [
-      'lookup_account',
-      // Build the Mastra-specific namespaced name for an MCP tool that hasn't
-      // been discovered yet. The output format is harness-specific
-      // (Mastra: `${server}_${tool}`); for cross-harness tool identification
-      // anywhere else, prefer the `(serverName, toolName)` pair on `McpToolInfo`.
-      manager.extensions.mastra.formatMcpToolName('sfdx', 'deploy_metadata'),
+      // Every tool from a server (post-discovery expansion).
+      { serverName: 'sfdx' },
+      // Exactly one tool on a specific server.
+      { serverName: 'other', toolName: 'lookup_account' },
+      // Any tool by this name, regardless of source — built-ins, workspace
+      // tools, consumer-declared tools, AND any MCP server's tool surface.
+      { toolName: 'resume_tool_operation' },
     ],
     topK: 5, // advisory; defaults to Mastra's 5
     ttl: 3_600_000, // ms; advisory; defaults to Mastra's 1h
@@ -105,16 +107,35 @@ const agent = await manager.createAgent(projectRoot, {
 
 When `toolSearch` is set, `createAgent` blocks on MCP discovery so MCP tools enter the searchable pool. Without
 `toolSearch`, MCP discovery stays non-blocking (existing behavior). `alwaysActive` tools are visible directly to the
-model; everything else lives in the searchable pool. Unknown `alwaysActive` names are kept (for late MCP discovery);
-unknown `pool` names are dropped.
+model; everything else lives in the searchable pool.
+
+Each `alwaysActive` entry is an `AlwaysActiveEntry` (re-exported from `@salesforce/sfdx-agent-sdk/harness` and shared
+with `ClaudeAgentConfig.toolSearch.alwaysActive`). At least one of `serverName` or `toolName` must be present — `{}`
+rejects at config time. Unknown `pool` names are dropped; unmatched `{ toolName }`-only entries are kept for late MCP
+discovery.
 
 `MastraToolSearchConfig.topK` and `ttl` are advisory — Mastra applies its own defaults if omitted.
 
 #### Skill search
 
-Skills (`AgentConfig.skills`) load eagerly by default. When `toolSearch` is also set, skills load on demand via
-harness-injected `search_skills` / `load_skill` meta-tools (Mastra's `SkillSearchProcessor`). The gating is deliberate —
-consumers who opt into `toolSearch` get the same on-demand pattern across tools and skills.
+Skills (`AgentConfig.skills`) load eagerly by default. Set `MastraAgentConfig.skillSearch` to switch to on-demand
+loading via harness-injected `search_skills` / `load_skill` meta-tools (Mastra's `SkillSearchProcessor`):
+
+```ts
+const agent = await manager.createAgent(projectRoot, {
+  instructions: '...',
+  skills: ['/path/to/skills'],
+  skillSearch: { topK: 5 }, // ranked, on-demand discovery; eager catalog stays out of the prompt
+});
+```
+
+`skillSearch.topK` is advisory; Mastra defaults to 5 if omitted. The same `skillSearch` field exists on
+`ClaudeAgentConfig`, so cross-harness consumers can opt into on-demand skill discovery on either harness with the same
+shape.
+
+> **Breaking change (#468).** Pre-#468, on-demand skill search was implicitly gated on `skills && toolSearch`. That
+> coupling has been removed: `skillSearch` is now the explicit opt-in, independent of `toolSearch`. Consumers who relied
+> on the coupling must add `skillSearch: {}` to their config to keep the previous behavior.
 
 #### Operational handles
 
@@ -175,18 +196,19 @@ const harnessFactory = new MastraHarnessFactory({
 });
 ```
 
-When the timer fires, the harness aborts the suspended Mastra run, drops the `activeRuns` entry for the thread, and
-yields a synthetic terminal pair on the active `eventStream`:
+When the timer fires, the harness aborts the suspended Mastra run via the per-`(agentId, threadId)`
+`MastraApprovalCoordinator`, marks every emitted approval as auto-resolved, and yields a synthetic terminal pair on the
+active `eventStream`:
 
 ```ts
 { type: 'error', error: Error('Tool approval timed out after 60000ms.'), code: 'tool-approval-timeout' }
 { type: 'finish', finishReason: 'error' }
 ```
 
-Subsequent `approveToolCall` / `declineToolCall` / `submitToolResult` calls for the timed-out tool reject with
-`no active run found for thread "<id>"`. The granularity is per thread — each suspended `ActiveRun` arms its own timer
-because Mastra suspends one tool approval at a time per thread; multi-tool turns get a fresh timer with each
-continuation. To observe the timeout, keep iterating the `eventStream` past the `tool-approval-request` event so the
+Subsequent `approveToolCall` / `declineToolCall` / `submitToolResult` calls for the timed-out tool throw because the
+coordinator has already auto-resolved them. The granularity is per `toolCallId` — each emitted approval arms its own
+timer; the first one to fire tears down the whole turn (since Mastra can't continue the suspended run after timeout
+anyway). To observe the timeout, keep iterating the `eventStream` past the `tool-approval-request` event so the
 synthetic terminal pair lands in your loop:
 
 ```ts
@@ -197,6 +219,20 @@ for await (const event of result.eventStream) {
 }
 ```
 
+### Tool-result redaction
+
+Tool-result redaction is configured at the manager layer, not the factory. Pass a `hooksForAgent` callback to
+`createAgentManager`; the SDK threads the resolved `AgentHooks` bag through `createAgent`'s `options.hooks`, and the
+Mastra harness registers a `ToolResultRedactionProcessor` on the agent's `inputProcessors` chain whose
+`processInputStep` walks new tool-result rows on the MessageList and replaces their content in place. The same
+`ToolResultRedactor` works on the Claude harness. See the SDK README → "Tool-Result Redaction" for the full pattern
+(including a `failClosed(...)` wrapper consumers can use to substitute a safe stub on throw).
+
+The processor composes with existing harness-internal processors (`ToolSearchProcessor`, `SkillSearchProcessor`); no
+consumer-supplied processor passthrough is needed. Throws propagate from `processInputStep` and the harness's approval
+coordinator surfaces them as an `error` ChatEvent on the consumer's eventStream — see ARCHITECTURE.md for the full
+contract.
+
 ### Using LLM Gateway Express
 
 ```ts

package/dist/gen-sink.d.ts

@@ -1,23 +1,8 @@
 /**
- * Buffered async generator wrapper used by `MastraStreamBroker` to deliver
- * `ChatEvent`s to a consumer's `ChatStreamResult.eventStream`.
- *
- * The buffer holds events pushed before the consumer starts iterating, so the
- * broker can begin populating the sink eagerly without coordinating with the
- * consumer's `for await` loop. Events pushed after iteration starts unblock
- * the awaiting consumer via an internal Promise waiter.
- *
- * Internal to `@salesforce/sfdx-agent-harness-mastra`; not part of the public
- * harness surface. Mirrors the same primitive in `@salesforce/sfdx-agent-harness-claude`
- * to keep each harness's broker self-contained without forcing a shared
- * cross-package surface.
+ * Re-export of the `GenSink` primitive from the SDK's harness-implementation
+ * subpath (`@salesforce/sfdx-agent-sdk/harness`). See that surface for the
+ * single-iteration invariant; issue #529 is the rationale for the
+ * cross-harness lift and for the subpath split (consumer applications can no
+ * longer import `GenSink` from the bare specifier — they have no use for it).
  */
-export declare class GenSink<T> {
-    private readonly buffered;
-    private ended;
-    private waiter;
-    push(event: T): void;
-    end(): void;
-    generator(): AsyncGenerator<T, void>;
-    private wake;
-}
+export { GenSink } from '@salesforce/sfdx-agent-sdk/harness';

package/dist/gen-sink.js

@@ -3,54 +3,11 @@
  * See LICENSE.txt for license terms.
  */
 /**
- * Buffered async generator wrapper used by `MastraStreamBroker` to deliver
- * `ChatEvent`s to a consumer's `ChatStreamResult.eventStream`.
- *
- * The buffer holds events pushed before the consumer starts iterating, so the
- * broker can begin populating the sink eagerly without coordinating with the
- * consumer's `for await` loop. Events pushed after iteration starts unblock
- * the awaiting consumer via an internal Promise waiter.
- *
- * Internal to `@salesforce/sfdx-agent-harness-mastra`; not part of the public
- * harness surface. Mirrors the same primitive in `@salesforce/sfdx-agent-harness-claude`
- * to keep each harness's broker self-contained without forcing a shared
- * cross-package surface.
+ * Re-export of the `GenSink` primitive from the SDK's harness-implementation
+ * subpath (`@salesforce/sfdx-agent-sdk/harness`). See that surface for the
+ * single-iteration invariant; issue #529 is the rationale for the
+ * cross-harness lift and for the subpath split (consumer applications can no
+ * longer import `GenSink` from the bare specifier — they have no use for it).
  */
-export class GenSink {
-    buffered = [];
-    ended = false;
-    waiter = null;
-    push(event) {
-        if (this.ended)
-            return;
-        this.buffered.push(event);
-        this.wake();
-    }
-    end() {
-        if (this.ended)
-            return;
-        this.ended = true;
-        this.wake();
-    }
-    async *generator() {
-        while (true) {
-            if (this.buffered.length > 0) {
-                yield this.buffered.shift();
-                continue;
-            }
-            if (this.ended)
-                return;
-            await new Promise((resolve) => {
-                this.waiter = { resolve };
-            });
-        }
-    }
-    wake() {
-        const w = this.waiter;
-        if (w) {
-            this.waiter = null;
-            w.resolve();
-        }
-    }
-}
+export { GenSink } from '@salesforce/sfdx-agent-sdk/harness';
 //# sourceMappingURL=gen-sink.js.map

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { MastraHarnessFactory, type MastraHarnessFactoryConfig } from './mastra-harness-factory.js';
 export type { MastraAgentHarness } from './mastra-harness.js';
-export { type MastraAgentConfig, type MastraToolSearchConfig, type SkillSearchHandle, type ToolSearchHandle, } from './tool-search.js';
+export { type MastraAgentConfig, type MastraSkillSearchConfig, type MastraToolSearchConfig, type SkillSearchHandle, type ToolSearchHandle, } from './tool-search.js';
 export type { MastraModelConfigFactory, ResolvedModelConfig } from './model-config-factory.js';
 export { DefaultMastraModelConfigFactory } from './default-model-config-factory.js';
 export { LLMGExpressMastraModelConfigFactory, type LLMGExpressConfig } from './llmg-express-model-config-factory.js';

package/dist/mastra-approval-coordinator.d.ts

@@ -0,0 +1,273 @@
+import type { Agent } from '@mastra/core/agent';
+import type { RequestContext } from '@mastra/core/request-context';
+import type { ChunkType } from '@mastra/core/stream';
+import { type ChatEvent, type McpToolAnnotations } from '@salesforce/sfdx-agent-sdk';
+import { GenSink } from '@salesforce/sfdx-agent-sdk/harness';
+import type { LogBus } from '@salesforce/agentic-common';
+/**
+ * Output shape from `agent.stream()` / `agent.approveToolCall()` /
+ * `agent.declineToolCall()`. Captured as a structural type so the
+ * coordinator doesn't depend on Mastra's exact `StreamOutput` generic.
+ *
+ * Mastra's actual output also carries `textStream`; the coordinator doesn't
+ * need it (it derives text deltas from `fullStream` via the event adapter)
+ * and structural typing accepts the wider value at the call site.
+ */
+export interface MastraStreamOutput {
+    runId: string;
+    fullStream: ReadableStream<ChunkType>;
+}
+/**
+ * Looks up MCP-server enrichment (`serverName` / `annotations`) for a given
+ * Mastra-namespaced tool name (`${serverName}_${toolName}`). Returns
+ * `undefined` for non-MCP tools (consumer-declared, workspace, built-in).
+ */
+export type MastraMcpToolMetadataLookup = (namespacedToolName: string) => {
+    serverName: string;
+    annotations?: McpToolAnnotations;
+} | undefined;
+export interface MastraApprovalCoordinatorOptions {
+    agent: Agent;
+    threadId: string;
+    memory: {
+        thread: string;
+        resource: string;
+    };
+    requestContext: RequestContext;
+    toolApprovalTimeoutMs: number;
+    /**
+     * Approval-emission mode (#447). Defaults to `undefined` (no gating).
+     *
+     * - `undefined`: stream is run without `requireToolApproval`. Mastra
+     *   suspends only on tools whose per-tool `requireApproval` is `true`
+     *   (consumer tools post-2c are `false` so they don't suspend; the
+     *   bridge's parker `execute` handles their lifecycle natively).
+     * - `'serial'`: stream runs with `requireToolApproval: true`. The
+     *   coordinator emits one `tool-approval-request` per natural
+     *   `tool-call-approval` chunk — Mastra serializes one approval per
+     *   suspension.
+     * - `'batch'`: same as serial except `tool-approval-request` is
+     *   front-loaded off the adapter's `tool-call` events so parallel
+     *   `tool_use` batches all surface their approval-requests on the
+     *   single per-turn stream.
+     *
+     * Note: in approval mode, consumer-executed tools still bypass the
+     * approval gate (per the `StreamOptions.requireToolApproval` JSDoc) —
+     * the coordinator silently calls `agent.approveToolCall(id)` for them
+     * without surfacing a `tool-approval-request` ChatEvent.
+     */
+    mode?: 'serial' | 'batch';
+    /**
+     * Set of tool names registered via `AgentConfig.tools`. The coordinator
+     * uses this to route `tool-call-approval` chunks: if the toolName is in
+     * the set, auto-approve silently (consumer tools bypass the gate); else
+     * surface a `tool-approval-request` ChatEvent and park.
+     *
+     * Empty set when no consumer tools are configured — every approval
+     * chunk surfaces to the consumer in approval mode.
+     */
+    consumerToolNames: ReadonlySet<string>;
+    /**
+     * Resolves MCP enrichment for a Mastra-namespaced tool name. Wired to
+     * `lookupMcpToolMetadata` in {@link MastraHarness} so the same lookup
+     * the legacy `createEventStream` used post-enriches `tool-call` /
+     * `tool-result` / `tool-approval-request` events.
+     */
+    lookupMcpToolMetadata?: MastraMcpToolMetadataLookup;
+    logBus?: LogBus;
+}
+/**
+ * Per-`(agentId, threadId)` coordinator that subsumes the pre-#529
+ * `MastraStreamBroker` + `activeRuns` pair into one object owning a single
+ * sink, single multi-source pump loop, and single set of teardown paths.
+ *
+ * Responsibilities:
+ *  - Approval gating in `'serial'` / `'batch'` mode: emit
+ *    `tool-approval-request` for non-consumer tools, drive
+ *    `agent.approveToolCall(...)` / `declineToolCall(...)` when the
+ *    consumer settles.
+ *  - Consumer-tool plumbing: every `AgentConfig.tools` entry has
+ *    `requireApproval: false` and a Promise-returning `execute` that parks
+ *    on the coordinator's `parkConsumerToolCall(...)`. Mastra natively
+ *    suspends the agentic loop while the Promise pends, so consumer tools
+ *    don't go through `agent.approveToolCall(...)` in non-approval mode.
+ *    In approval mode the coordinator auto-approves them silently so the
+ *    bridge `execute` parker still runs on the resumed stream.
+ *  - Multi-source pump: Mastra returns a fresh `fullStream` per resume
+ *    call; the coordinator pumps each one into the same `initial` sink so
+ *    the consumer iterates one stream per turn.
+ *  - Snapshot-drain before each resume call (Mastra-specific: workflow
+ *    snapshots persist asynchronously after `tool-call-approval`).
+ *  - Approval-timeout / abort / dispose teardown — single helper drains
+ *    timers, rejects pending parkers, marks emitted approvals as
+ *    coordinator-settled, and pushes the synthetic terminal pair on the
+ *    sink.
+ *
+ * Issue #529 contract: settle calls (`approveToolCall` / `declineToolCall` /
+ * `submitToolResult`) are control messages on the chat() turn's existing
+ * eventStream. There is exactly one sink (`initial`) per turn; post-resume
+ * events flow through the same sink the consumer is iterating from
+ * `chat()`. There are no per-tool sinks and no `lastGenSinkStale` flag.
+ */
+export declare class MastraApprovalCoordinator {
+    private readonly agent;
+    private readonly memory;
+    private readonly requestContext;
+    private readonly toolApprovalTimeoutMs;
+    private readonly mode;
+    private readonly consumerToolNames;
+    private readonly lookupMcpToolMetadata?;
+    private readonly adapter;
+    /** Single per-turn sink. Issue #529 contract: one stream per turn. */
+    private readonly initial;
+    /** Buffered consumer decisions keyed by `toolCallId`. */
+    private readonly decisions;
+    /** ToolCallIds for which a `tool-approval-request` ChatEvent has been emitted. */
+    private readonly emittedApprovals;
+    /** ToolCallIds the consumer has settled. Rejects double-settle. */
+    private readonly consumerSettled;
+    /**
+     * ToolCallIds the coordinator auto-resolved (timeout / abort / dispose
+     * / consumer-tool auto-approve). A subsequent settle for these ids
+     * rejects with "already auto-resolved by the coordinator".
+     */
+    private readonly settledByCoordinator;
+    /** Per-toolCallId approval-timeout timers (armed when an approval is emitted). */
+    private readonly approvalTimers;
+    /** Args from the adapter's `tool-call` ChatEvent keyed by `toolCallId`. */
+    private readonly toolCallArgs;
+    /**
+     * Mastra's current `runId` after the latest stream/resume. Updated on
+     * each successful pump entry. Needed for the next
+     * `agent.approveToolCall(...)` / `declineToolCall(...)`.
+     */
+    private currentRunId;
+    /**
+     * The toolCallId Mastra is currently suspended on (after the natural
+     * `tool-call-approval` chunk). `null` when no suspension. The
+     * coordinator's pump loop reads this when the current `fullStream`
+     * closes to decide whether to drive a resume.
+     */
+    private currentSuspendId;
+    /** Consumer-tool: bound parkers, keyed by `toolCallId`. `submitToolResult` resolves these. */
+    private readonly pendingByToolCallId;
+    /**
+     * Consumer-tool: results submitted before the bridge `execute` handler
+     * parked. Keyed by `toolCallId`. Used when `submitToolResult` arrives
+     * during the gap between the `tool-call` ChatEvent and the bridge
+     * handler's actual invocation — the staged result resolves the next
+     * parker invocation for the same id.
+     */
+    private readonly preSubmittedByToolCallId;
+    /**
+     * Callbacks invoked exactly once during teardown (`abort` or `dispose`,
+     * whichever fires first, or natural pump exit).
+     */
+    private readonly teardownCallbacks;
+    /**
+     * Resolved by `recordDecision` (consumer settled) or `teardown`. The
+     * outer pump loop awaits this when it sees a suspension chunk before
+     * the consumer has settled. `'continued'` means a decision is now in
+     * `decisions`; `'done'` means the pump should exit (teardown fired).
+     */
+    private continuationResolver?;
+    private aborted;
+    private disposed;
+    private timedOut;
+    constructor(opts: MastraApprovalCoordinatorOptions);
+    initialSink(): GenSink<ChatEvent>;
+    onTeardown(callback: () => void): void;
+    private runTeardownCallbacks;
+    /**
+     * Begin pumping the initial Mastra `fullStream`. Stores `runId` and
+     * spawns the multi-source pump loop. The consumer iterates
+     * `initialSink().generator()` to observe events.
+     */
+    start(output: MastraStreamOutput): void;
+    abort(): void;
+    dispose(): void;
+    /**
+     * Single teardown path for abort / dispose / approval-timeout / pump-
+     * error. Drains timers, rejects pending consumer-tool parkers, marks
+     * every emitted approval as coordinator-settled, releases Mastra's
+     * suspended run, pushes the synthetic terminal pair on the sink, and
+     * fires teardown callbacks.
+     *
+     * The `reason` parameter only changes the sink's terminal shape:
+     * `'dispose'` pushes error-only (matches Claude's dispose contract);
+     * everything else pushes error+finish.
+     */
+    private teardown;
+    approve(toolCallId: string): void;
+    decline(toolCallId: string): void;
+    private recordDecision;
+    /**
+     * Parker callback the consumer-tool bridge `execute` handler invokes
+     * when Mastra calls the tool. Returns a Promise the consumer settles
+     * via {@link submitToolResult}.
+     *
+     * Mastra's bridge `execute` knows the `toolCallId` from its execution
+     * context, so binding is direct (no FIFO match by name). The
+     * pre-submit ladder handles the rare case where `submitToolResult`
+     * lands before the bridge handler's `execute` actually runs:
+     *
+     *  1. A pre-submitted result is staged for this `toolCallId` →
+     *     resolve immediately.
+     *  2. Otherwise → bind under `toolCallId`; the eventual
+     *     `submitToolResult` resolves us.
+     */
+    readonly parkConsumerToolCall: (toolCallId: string) => Promise<{
+        result: unknown;
+        isError?: boolean;
+    }>;
+    /**
+     * Settle a parked consumer-tool call. Issue #529 contract: returns
+     * `void`; post-resume events flow through the same `initial` sink the
+     * consumer is iterating from `chat()`. Mastra natively continues the
+     * agentic loop on the same `fullStream` once the parker Promise
+     * resolves (probe-validated, see #529 step 2c).
+     */
+    submitToolResult(toolCallId: string, result: unknown, isError?: boolean): void;
+    /**
+     * Multi-source pump loop. Drains the initial Mastra `fullStream` plus
+     * every continuation stream returned by `agent.approveToolCall(...)` /
+     * `declineToolCall(...)` into the same `initial` sink.
+     *
+     * Termination conditions:
+     *  - Saw `finish` chunk on a stream and no further suspension awaits a
+     *    decision.
+     *  - Saw an `error` chunk (terminal under SDK contract).
+     *  - `abort()` / `dispose()` / approval-timeout fired.
+     */
+    private runPumpLoop;
+    /**
+     * Pump one `ReadableStream<ChunkType>` into the sink until one of:
+     *  - `'terminal'`: saw `finish` chunk; sink ended.
+     *  - `'suspended'`: saw `tool-call-approval` chunk on a non-consumer
+     *    tool (or auto-approved consumer tool didn't suspend on it). The
+     *    stream may still be pumping — drain remaining chunks for the
+     *    Mastra-snapshot-persistence guarantee, then return.
+     *  - `'pump-error'`: stream threw; sink ended with error+finish.
+     */
+    private pumpUntilSuspendOrTerminal;
+    /**
+     * Drive a resume call and set up the next stream for the pump loop.
+     * Returns `'done'` if the resume rejected (turn over, error already
+     * pushed) or the new `fullStream` to pump next.
+     */
+    private driveResumeReturning;
+    private awaitContinuation;
+    /**
+     * Push an event onto the sink with MCP-server enrichment applied (when
+     * the toolName resolves to a known MCP catalog entry). Mirrors the
+     * pre-#529 `createEventStream`'s post-enrichment of `tool-call` /
+     * `tool-result` / `tool-approval-request`.
+     */
+    private routeEnriched;
+    private maybeEnrich;
+    private emitApprovalRequest;
+    private armApprovalTimer;
+    private cancelTimer;
+    private cancelAllTimers;
+    private handleApprovalTimeout;
+}