@salesforce/sfdx-agent-harness-mastra 0.13.0 → 0.15.0

package/README.md

@@ -175,18 +175,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

package/dist/default-model-config-factory.d.ts

@@ -1,3 +1,4 @@
+import type { LogBus } from '@salesforce/agentic-common';
 import { type LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
 import type { MastraModelConfigFactory, ResolvedModelConfig } from './model-config-factory.js';
 /**
@@ -6,7 +7,10 @@ import type { MastraModelConfigFactory, ResolvedModelConfig } from './model-conf
  * Wraps the LLMGatewayClient in a SalesforceMastraModelGateway and calls
  * resolveLanguageModel() to produce the LanguageModelV2 that Mastra consumes.
  * Captures the gateway model at creation time to provide multimodal validation.
+ * Forwards the harness's `logBus` into the bridge so streaming anomalies
+ * (e.g. a Bedrock-Anthropic stream that ends without a usage chunk) surface as
+ * structured logs.
  */
 export declare class DefaultMastraModelConfigFactory implements MastraModelConfigFactory {
-    create(llmGatewayClient: LLMGatewayClient): ResolvedModelConfig;
+    create(llmGatewayClient: LLMGatewayClient, logBus?: LogBus): ResolvedModelConfig;
 }

package/dist/default-model-config-factory.js

@@ -10,10 +10,13 @@ import { SalesforceMastraModelGateway } from './salesforce-llm-gateway.js';
  * Wraps the LLMGatewayClient in a SalesforceMastraModelGateway and calls
  * resolveLanguageModel() to produce the LanguageModelV2 that Mastra consumes.
  * Captures the gateway model at creation time to provide multimodal validation.
+ * Forwards the harness's `logBus` into the bridge so streaming anomalies
+ * (e.g. a Bedrock-Anthropic stream that ends without a usage chunk) surface as
+ * structured logs.
  */
 export class DefaultMastraModelConfigFactory {
-    create(llmGatewayClient) {
-        const agentGateway = new SalesforceMastraModelGateway(llmGatewayClient);
+    create(llmGatewayClient, logBus) {
+        const agentGateway = new SalesforceMastraModelGateway(llmGatewayClient, undefined, logBus);
         const model = agentGateway.resolveLanguageModel();
         const gatewayModel = llmGatewayClient.getModel();
         return {

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/llmg-express-model-config-factory.d.ts

@@ -1,3 +1,4 @@
+import type { LogBus } from '@salesforce/agentic-common';
 import { type LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
 import type { MastraModelConfigFactory, ResolvedModelConfig } from './model-config-factory.js';
 export interface LLMGExpressConfig {
@@ -21,5 +22,5 @@ export interface LLMGExpressConfig {
 export declare class LLMGExpressMastraModelConfigFactory implements MastraModelConfigFactory {
     private readonly config;
     constructor(config: LLMGExpressConfig);
-    create(llmGatewayClient: LLMGatewayClient): ResolvedModelConfig;
+    create(llmGatewayClient: LLMGatewayClient, _logBus?: LogBus): ResolvedModelConfig;
 }

package/dist/llmg-express-model-config-factory.js

@@ -18,7 +18,9 @@ export class LLMGExpressMastraModelConfigFactory {
     constructor(config) {
         this.config = config;
     }
-    create(llmGatewayClient) {
+    // _logBus is unused: the express path resolves through Mastra's built-in OpenAI-compatible
+    // provider, not SalesforceMastraModelGateway, so the missing-usage warn from W-22692131 doesn't apply.
+    create(llmGatewayClient, _logBus) {
         const model = {
             providerId: 'llmg-express',
             modelId: this.config.modelId,

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;
+}