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

package/README.md

@@ -46,14 +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.    |
-| `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
 
@@ -61,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
 
@@ -76,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());
 
@@ -86,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
   },
@@ -151,19 +161,55 @@ for await (const event of result.eventStream) {
 }
 ```
 
+### Tool approval timeout
+
+When `requireToolApproval: true` is set on a `chat()` call, the harness suspends the workflow on each
+`tool-approval-request` and waits for the consumer to call `approveToolCall(...)` / `declineToolCall(...)` /
+`submitToolResult(...)`. To bound how long a pending approval can wait — for example, when a UI process crashes or a
+user walks away — the factory accepts a `toolApprovalTimeoutMs` option. It defaults to `600_000` (10 minutes) and
+matches the `ClaudeHarnessFactoryConfig` knob of the same name.
+
+```ts
+const harnessFactory = new MastraHarnessFactory({
+  toolApprovalTimeoutMs: 60_000, // auto-deny pending approvals after 60s
+});
+```
+
+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`:
+
+```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
+synthetic terminal pair lands in your loop:
+
+```ts
+for await (const event of result.eventStream) {
+  if (event.type === 'error' && event.code === 'tool-approval-timeout') {
+    // Pending approval was never answered.
+  }
+}
+```
+
 ### Using LLM Gateway Express
 
 ```ts
 import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
 import { MastraHarnessFactory, LLMGExpressMastraModelConfigFactory } from '@salesforce/sfdx-agent-harness-mastra';
 
-const harnessFactory = new MastraHarnessFactory(
-  new LLMGExpressMastraModelConfigFactory({
+const harnessFactory = new MastraHarnessFactory({
+  modelConfigFactory: new LLMGExpressMastraModelConfigFactory({
     apiKey: process.env.LLMG_EXPRESS_API_KEY!,
     baseUrl: process.env.LLMG_EXPRESS_BASE_URL!,
     modelId: 'claude-sonnet-4-20250514',
   }),
-);
+});
 
 const manager = await createAgentManager('/path/to/storage', harnessFactory);
 ```

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 } from './mastra-harness-factory.js';
+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-factory.d.ts

@@ -1,11 +1,28 @@
 import type { HarnessFactory } from '@salesforce/sfdx-agent-sdk';
 import { type MastraAgentHarness } from './mastra-harness.js';
 import type { MastraModelConfigFactory } from './model-config-factory.js';
+export interface MastraHarnessFactoryConfig {
+    /**
+     * Strategy for resolving the Mastra model configuration. Defaults to
+     * `DefaultMastraModelConfigFactory`, which targets the standard LLM
+     * Gateway path.
+     */
+    modelConfigFactory?: MastraModelConfigFactory;
+    /**
+     * How long to wait for a `requireToolApproval` consumer to call
+     * `approveToolCall` / `declineToolCall` before auto-denying via
+     * `agent.abortRunStream(...)` and yielding a synthetic `error`
+     * (`code: 'tool-approval-timeout'`) + `finish` (`finishReason: 'error'`)
+     * terminal pair. Defaults to `600_000` (10 minutes), matching
+     * `ClaudeHarnessFactoryConfig.toolApprovalTimeoutMs`.
+     */
+    toolApprovalTimeoutMs?: number;
+}
 /** Mastra-backed factory for creating AgentHarness instances. */
 export declare class MastraHarnessFactory implements HarnessFactory<MastraAgentHarness> {
-    private readonly modelConfigFactory?;
+    private readonly config;
     readonly harnessId = "mastra";
     readonly protocolVersion = 1;
-    constructor(modelConfigFactory?: MastraModelConfigFactory | undefined);
+    constructor(config?: MastraHarnessFactoryConfig);
     create(storageRootFolder: string): Promise<MastraAgentHarness>;
 }

package/dist/mastra-harness-factory.js

@@ -3,16 +3,20 @@
  * See LICENSE.txt for license terms.
  */
 import { MastraHarness } from './mastra-harness.js';
+const DEFAULT_TOOL_APPROVAL_TIMEOUT_MS = 600_000;
 /** Mastra-backed factory for creating AgentHarness instances. */
 export class MastraHarnessFactory {
-    modelConfigFactory;
+    config;
     harnessId = 'mastra';
     protocolVersion = 1;
-    constructor(modelConfigFactory) {
-        this.modelConfigFactory = modelConfigFactory;
+    constructor(config = {}) {
+        this.config = config;
     }
     async create(storageRootFolder) {
-        return new MastraHarness(storageRootFolder, this.modelConfigFactory);
+        return new MastraHarness(storageRootFolder, {
+            modelConfigFactory: this.config.modelConfigFactory,
+            toolApprovalTimeoutMs: this.config.toolApprovalTimeoutMs ?? DEFAULT_TOOL_APPROVAL_TIMEOUT_MS,
+        });
     }
 }
 //# sourceMappingURL=mastra-harness-factory.js.map