@salesforce/sfdx-agent-harness-mastra 0.11.0 → 0.12.0

package/README.md

@@ -46,15 +46,15 @@ Linux and macOS release the handle eagerly; the retry options are no-ops on thos
 
 ### Core
 
-| Export                                | Kind      | Description                                                                                 |
-| ------------------------------------- | --------- | ------------------------------------------------------------------------------------------- |
-| `MastraHarnessFactory`                | class     | `HarnessFactory` that produces a Mastra-backed `AgentHarness` bound to a storage root.      |
-| `MastraHarnessFactoryConfig`          | interface | Configuration for `MastraHarnessFactory` (`modelConfigFactory?`, `toolApprovalTimeoutMs?`). |
-| `MastraModelConfigFactory`            | interface | Strategy for creating model configurations; injected into `MastraHarnessFactory`.           |
-| `ResolvedModelConfig`                 | type      | Return type of `MastraModelConfigFactory.create()` — wraps a `MastraModelConfig`.           |
-| `DefaultMastraModelConfigFactory`     | class     | Default factory using the Salesforce LLM Gateway (`SalesforceMastraModelGateway`).          |
-| `LLMGExpressMastraModelConfigFactory` | class     | Factory for LLM Gateway Express (API-key-authenticated, OpenAI-compatible endpoint).        |
-| `LLMGExpressConfig`                   | type      | Configuration for `LLMGExpressMastraModelConfigFactory` (`apiKey`, `baseUrl`, `modelId`).   |
+| Export                                | Kind      | Description                                                                                                                                                                            |
+| ------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MastraHarnessFactory`                | class     | `HarnessFactory` that produces a Mastra-backed `AgentHarness` bound to a storage root.                                                                                                 |
+| `MastraHarnessFactoryConfig`          | interface | Configuration for `MastraHarnessFactory` (`modelConfigFactory?`, `toolApprovalTimeoutMs?`).                                                                                            |
+| `MastraModelConfigFactory`            | interface | Strategy for creating model configurations; injected into `MastraHarnessFactory`.                                                                                                      |
+| `ResolvedModelConfig`                 | type      | Return type of `MastraModelConfigFactory.create()` — a `MastraModelConfig` plus a `validateFiles(files)` hook the harness calls for pre-flight multimodal (`image`/`file`) validation. |
+| `DefaultMastraModelConfigFactory`     | class     | Default factory using the Salesforce LLM Gateway (`SalesforceMastraModelGateway`).                                                                                                     |
+| `LLMGExpressMastraModelConfigFactory` | class     | Factory for LLM Gateway Express (API-key-authenticated, OpenAI-compatible endpoint).                                                                                                   |
+| `LLMGExpressConfig`                   | type      | Configuration for `LLMGExpressMastraModelConfigFactory` (`apiKey`, `baseUrl`, `modelId`).                                                                                              |
 
 ### Extension surface
 
@@ -62,14 +62,16 @@ 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`).                                                                          |
-| `formatMcpToolName`      | function | `(serverName: string, toolName: string) => string` — builds the namespaced MCP tool name (`${serverName}_${toolName}`) used in `toolSearch.alwaysActive`. |
-| `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 (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).              |
+
+The Mastra-specific accessors live on `manager.extensions.mastra` (`getToolSearchProcessor(agentId)`,
+`getSkillSearchProcessor(agentId)`, `formatMcpToolName(serverName, toolName)`) and require no separate import.
 
 #### Tool search
 
@@ -77,7 +79,7 @@ Hide a large tool catalog behind Mastra's `search_tools` / `load_tool` meta-tool
 
 ```ts
 import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
-import { MastraHarnessFactory, formatMcpToolName } from '@salesforce/sfdx-agent-harness-mastra';
+import { MastraHarnessFactory } from '@salesforce/sfdx-agent-harness-mastra';
 
 const manager = await createAgentManager(storageRoot, new MastraHarnessFactory());
 
@@ -87,7 +89,14 @@ const agent = await manager.createAgent(projectRoot, {
   mcpServers: { sfdx: { type: 'stdio', command: 'npx', args: ['@salesforce/mcp'] } },
   toolSearch: {
     pool: '*', // or an explicit name list
-    alwaysActive: ['lookup_account', formatMcpToolName('sfdx', 'deploy_metadata')],
+    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'),
+    ],
     topK: 5, // advisory; defaults to Mastra's 5
     ttl: 3_600_000, // ms; advisory; defaults to Mastra's 1h
   },

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

@@ -1,10 +1,11 @@
-import type { LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
+import { type LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
 import type { MastraModelConfigFactory, ResolvedModelConfig } from './model-config-factory.js';
 /**
  * Default model configuration factory that uses the Salesforce LLM Gateway.
  *
  * 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.
  */
 export declare class DefaultMastraModelConfigFactory implements MastraModelConfigFactory {
     create(llmGatewayClient: LLMGatewayClient): ResolvedModelConfig;

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

@@ -2,17 +2,24 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
+import { validateMultimodalFiles } from '@salesforce/llm-gateway-sdk';
 import { SalesforceMastraModelGateway } from './salesforce-llm-gateway.js';
 /**
  * Default model configuration factory that uses the Salesforce LLM Gateway.
  *
  * 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.
  */
 export class DefaultMastraModelConfigFactory {
     create(llmGatewayClient) {
         const agentGateway = new SalesforceMastraModelGateway(llmGatewayClient);
-        return { model: agentGateway.resolveLanguageModel() };
+        const model = agentGateway.resolveLanguageModel();
+        const gatewayModel = llmGatewayClient.getModel();
+        return {
+            model,
+            validateFiles: (files) => validateMultimodalFiles(files, gatewayModel),
+        };
     }
 }
 //# sourceMappingURL=default-model-config-factory.js.map

package/dist/gen-sink.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+export declare class GenSink<T> {
+    private readonly buffered;
+    private ended;
+    private waiter;
+    push(event: T): void;
+    end(): void;
+    generator(): AsyncGenerator<T, void>;
+    private wake;
+}

package/dist/gen-sink.js

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * 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.
+ */
+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();
+        }
+    }
+}
+//# 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, formatMcpToolName, } from './tool-search.js';
+export { type MastraAgentConfig, 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/index.js

@@ -3,7 +3,7 @@
  * See LICENSE.txt for license terms.
  */
 export { MastraHarnessFactory } from './mastra-harness-factory.js';
-export { formatMcpToolName, } from './tool-search.js';
+export {} from './tool-search.js';
 export { DefaultMastraModelConfigFactory } from './default-model-config-factory.js';
 export { LLMGExpressMastraModelConfigFactory } from './llmg-express-model-config-factory.js';
 //# sourceMappingURL=index.js.map

package/dist/llmg-express-model-config-factory.d.ts

@@ -1,4 +1,4 @@
-import type { LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
+import { type LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
 import type { MastraModelConfigFactory, ResolvedModelConfig } from './model-config-factory.js';
 export interface LLMGExpressConfig {
     /** API key for authenticating with LLM Gateway Express. */
@@ -12,12 +12,14 @@ export interface LLMGExpressConfig {
  * Model configuration factory for LLM Gateway Express (non-production,
  * API-key-authenticated, OpenAI-compatible endpoint).
  *
- * This factory ignores the LLMGatewayClient parameter entirely and produces
- * a Mastra OpenAICompatibleConfig that Mastra resolves internally using its
- * built-in OpenAI-compatible provider support.
+ * Routing is via a Mastra OpenAICompatibleConfig that Mastra resolves
+ * internally using its built-in OpenAI-compatible provider support.
+ * Multimodal validation uses the gateway client's model as a proxy for
+ * the express endpoint's capabilities (the express endpoint does not
+ * publish its own file-format caps).
  */
 export declare class LLMGExpressMastraModelConfigFactory implements MastraModelConfigFactory {
     private readonly config;
     constructor(config: LLMGExpressConfig);
-    create(_llmGatewayClient: LLMGatewayClient): ResolvedModelConfig;
+    create(llmGatewayClient: LLMGatewayClient): ResolvedModelConfig;
 }

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

@@ -2,27 +2,34 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
+import { validateMultimodalFiles } from '@salesforce/llm-gateway-sdk';
 /**
  * Model configuration factory for LLM Gateway Express (non-production,
  * API-key-authenticated, OpenAI-compatible endpoint).
  *
- * This factory ignores the LLMGatewayClient parameter entirely and produces
- * a Mastra OpenAICompatibleConfig that Mastra resolves internally using its
- * built-in OpenAI-compatible provider support.
+ * Routing is via a Mastra OpenAICompatibleConfig that Mastra resolves
+ * internally using its built-in OpenAI-compatible provider support.
+ * Multimodal validation uses the gateway client's model as a proxy for
+ * the express endpoint's capabilities (the express endpoint does not
+ * publish its own file-format caps).
  */
 export class LLMGExpressMastraModelConfigFactory {
     config;
     constructor(config) {
         this.config = config;
     }
-    create(_llmGatewayClient) {
+    create(llmGatewayClient) {
         const model = {
             providerId: 'llmg-express',
             modelId: this.config.modelId,
             url: this.config.baseUrl,
             apiKey: this.config.apiKey,
         };
-        return { model };
+        const gatewayModel = llmGatewayClient.getModel();
+        return {
+            model,
+            validateFiles: (files) => validateMultimodalFiles(files, gatewayModel),
+        };
     }
 }
 //# sourceMappingURL=llmg-express-model-config-factory.js.map

package/dist/mastra-event-adapter.d.ts

@@ -1,5 +1,5 @@
 import type { ChunkType } from '@mastra/core/stream';
-import { type LogBus } from '@salesforce/agentic-common';
+import type { LogBus } from '@salesforce/agentic-common';
 import type { ChatEvent } from '@salesforce/sfdx-agent-sdk';
 /**
  * Adapts Mastra `ChunkType` stream events to our {@link ChatEvent} discriminated union.

package/dist/mastra-event-adapter.js

@@ -2,7 +2,6 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
-import { getErrorMessage } from '@salesforce/agentic-common';
 /**
  * Adapts Mastra `ChunkType` stream events to our {@link ChatEvent} discriminated union.
  *
@@ -103,14 +102,17 @@ export class MastraEventAdapter {
                     result: chunk.payload.result,
                     isError: false,
                 };
-            case 'tool-error':
+            case 'tool-error': {
+                const error = chunk.payload.error instanceof Error ? chunk.payload.error : new Error(String(chunk.payload.error));
                 return {
                     type: 'tool-result',
                     toolCallId: chunk.payload.toolCallId,
                     toolName: chunk.payload.toolName,
-                    result: getErrorMessage(chunk.payload.error),
+                    result: error.message,
                     isError: true,
+                    error,
                 };
+            }
             case 'step-start':
                 return { type: 'step-start', stepIndex: this.stepIndex++ };
             case 'step-finish':
@@ -199,6 +201,7 @@ function mapUsage(usage) {
         totalTokens: usage.totalTokens ?? undefined,
         reasoningTokens: usage.reasoningTokens,
         cachedInputTokens: usage.cachedInputTokens,
+        cacheWriteInputTokens: usage.cacheCreationInputTokens ? usage.cacheCreationInputTokens : undefined,
     };
 }
 //# sourceMappingURL=mastra-event-adapter.js.map

package/dist/mastra-harness.d.ts

@@ -2,10 +2,11 @@ import { Agent } from '@mastra/core/agent';
 import { SkillSearchProcessor, ToolSearchProcessor } from '@mastra/core/processors';
 import type { ChunkType } from '@mastra/core/stream';
 import { MCPClient } from '@mastra/mcp';
-import { McpServerStatus, type AgentHarness, type WithAgentConfig, type ChatStreamResult, type HarnessAgentConfig, type MCPConfiguration, type McpServerErrorDetail, type McpServerInfo, type Message, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo } from '@salesforce/sfdx-agent-sdk';
+import { McpServerStatus, type AgentHarness, type WithAgentConfig, type ChatStreamResult, type HarnessAgentConfig, type MCPConfiguration, type McpServerErrorDetail, type McpServerInfo, type Message, type MessagePart, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo } from '@salesforce/sfdx-agent-sdk';
+import { MastraStreamBroker } from './mastra-stream-broker.js';
 import type { MastraModelConfigFactory } from './model-config-factory.js';
 import { type MastraAgentConfig, type SkillSearchHandle, type ToolSearchHandle } from './tool-search.js';
-import type { LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
+import { type LLMGatewayClient, type MultimodalFile } from '@salesforce/llm-gateway-sdk';
 import { Clock, type LogRecord, type UniqueIDGenerator, type Unsubscribe } from '@salesforce/agentic-common';
 import { type ToolsInput } from './utils.js';
 import { Workspace } from '@mastra/core/workspace';
@@ -103,6 +104,13 @@ interface McpServerState {
 interface MastraAgentState {
     /** Mastra Agent instance. */
     agent: Agent;
+    /**
+     * Pre-flight multimodal validation for this agent's model configuration.
+     * Captured from {@link ResolvedModelConfig.validateFiles} at `createAgent`
+     * time. Called by `toMastraStreamInput` before every stream that carries
+     * `image` or `file` parts. Throws `LLMGClientError` on violation.
+     */
+    validateFiles: (files: readonly MultimodalFile[]) => void;
     /** Per-server MCP state, keyed by server name. Empty map when no MCP servers are configured. */
     mcpServers: Map<string, McpServerState>;
     /** Original MCP configuration, retained so getMcpServerInfo can report disabled servers. */
@@ -111,6 +119,16 @@ interface MastraAgentState {
     mastraWorkspace?: Workspace;
     /** Tracks the active workflow run per thread for tool approval. */
     activeRuns: Map<string, ActiveRun>;
+    /**
+     * Per-thread MastraStreamBroker, allocated when a `stream()` call sets
+     * `requireToolApproval: true`. Owns the parallel-approval UX (#447):
+     * front-loaded `tool-approval-request` emission, decision buffering,
+     * Mastra suspend/resume coordination, per-tool sink routing, and the
+     * approval-timeout/abort lifecycle. When approval gating is off, the
+     * entry is absent and `stream()` falls through to `toChatStreamResult` /
+     * `createEventStream` (the pre-#447 path).
+     */
+    streamBrokers: Map<string, MastraStreamBroker>;
     /** Tool-search processor instance, when `toolSearch` is configured on the factory. */
     toolSearchProcessor?: ToolSearchProcessor;
     /** Skill-search processor instance, when both `skills` and `toolSearch` are configured. */
@@ -156,6 +174,25 @@ export type MastraAgentHarness = WithAgentConfig<AgentHarness & {
              * Mastra falls back to eager skill loading).
              */
             getSkillSearchProcessor(agentId: string): SkillSearchHandle | undefined;
+            /**
+             * Build the namespaced tool name Mastra registers for an
+             * MCP-discovered tool: `${serverName}_${toolName}`. Reach for
+             * this when constructing `MastraAgentConfig.toolSearch.alwaysActive`
+             * entries that reference MCP tools at agent-creation time, before
+             * MCP discovery has settled — without it you'd have to hard-code
+             * the namespaced string (brittle if the server name changes) or
+             * wait for discovery (which defeats the point of `alwaysActive`).
+             *
+             * Custom tools listed in `alwaysActive` should use their declared
+             * name directly; do NOT wrap them with this helper.
+             *
+             * The output format is **Mastra-specific** — Claude uses a
+             * different namespacing shape (`mcp__${server}__${tool}`). For
+             * cross-harness tool identification, use {@link McpToolInfo.serverName}
+             * + {@link McpToolInfo.toolName} (both populated identically by
+             * every harness) instead.
+             */
+            formatMcpToolName(serverName: string, toolName: string): string;
         };
     };
 }, MastraAgentConfig>;
@@ -332,7 +369,28 @@ export declare class MastraHarness implements MastraAgentHarness {
      *   the thread's `ActiveRun` entry. See ARCHITECTURE.md → "Tool Approval Flow → Abort
      *   during pending approval (#409)".
      */
-    stream(agentId: string, threadId: string, message: string, options?: StreamOptions): Promise<ChatStreamResult>;
+    /**
+     * Maps an SDK `MessagePart[]` into the single AI SDK v5 user `ModelMessage` that
+     * `agent.stream()` accepts.
+     *
+     * `text` parts collapse into text content blocks; `image` / `file` parts become v5 `file`
+     * content blocks (`mediaType` + base64 `data` + optional `filename`) that Mastra forwards to the
+     * gateway bridge, which collects them into `ChatMessageIn.files[]`. Pre-stream validation and the
+     * input-part guard live in the SDK's {@link lowerStreamInput}, so file caps and the
+     * `MULTIMODAL_NOT_SUPPORTED` / `INVALID_MESSAGE_CONTENT` semantics are identical to the Claude
+     * harness; this method only supplies the Mastra-specific lowering of each part.
+     */
+    private toMastraStreamInput;
+    stream(agentId: string, threadId: string, message: string | MessagePart[], options?: StreamOptions): Promise<ChatStreamResult>;
+    /**
+     * Allocate a `MastraStreamBroker` for the (agentId, threadId) pair,
+     * dispose any prior broker on the same thread, hand the initial Mastra
+     * `output` to it, and wire the consumer's `abortSignal` (if any) to
+     * `broker.abort()`. The returned `ChatStreamResult.eventStream` reads
+     * from the broker's initial sink, where parallel
+     * `tool-approval-request` events surface for batch-style consumer UI.
+     */
+    private startBrokerStream;
     /**
      * @requirements
      * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.