@salesforce/sfdx-agent-harness-mastra 0.35.0 → 0.37.0

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 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.37.0] - 2026-07-28
+
+### Fixes
+- **harness-openai**: treat usage: null like missing usage in finalizeUsage @W-23577076@ ([#697](https://github.com/forcedotcom/agentic-dx/pull/697))
+
+### Chores
+- **deps**: bump the mastra group with 5 updates ([#706](https://github.com/forcedotcom/agentic-dx/pull/706))
+
+## [0.36.0] - 2026-07-27
+
+### Features
+- **chat-generations**: GovCloud chat/generations fallback @W-23560954@ ([#695](https://github.com/forcedotcom/agentic-dx/pull/695))
+
 ## [0.35.0] - 2026-07-27
 
 _No changes — released alongside dependent packages._

package/README.md

@@ -44,12 +44,14 @@ 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` (`toolApprovalTimeoutMs?`).                                                                                                                                                                     |
-| `MASTRA_BUILT_IN_TOOL_POLICIES` | const     | Frozen `ReadonlyArray<ToolPolicyRule>` the harness feeds the SDK's `resolveToolApprovalPolicy` as the `tiers.harness` slice — `allow` rules for Mastra's built-in `updateWorkingMemory` / `skill` / `skill_search` / `skill_read` tools. |
-| `MASTRA_BUILT_IN_TOOL_NAMES`    | const     | The four built-in tool leaf names `MASTRA_BUILT_IN_TOOL_POLICIES` covers.                                                                                                                                                                |
+| Export                              | Kind      | Description                                                                                                                                                                                                                              |
+| ----------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MastraHarnessFactory`              | class     | `HarnessFactory` that produces a Mastra-backed `AgentHarness` bound to a storage root.                                                                                                                                                   |
+| `MastraHarnessFactoryConfig`        | interface | Configuration for `MastraHarnessFactory` (`toolApprovalTimeoutMs?`, `languageModelBuilders?`).                                                                                                                                           |
+| `MastraLanguageModelBuilderContext` | type      | Context bag the harness threads into each `LanguageModelV3` builder (`getInfo`, `logBus`, `emitWireCommunication`, `innerFetch`).                                                                                                        |
+| `MastraLanguageModelBuilder`        | type      | Factory function shape for a consumer-injected builder: `(ctx: MastraLanguageModelBuilderContext) => LanguageModelV3`.                                                                                                                   |
+| `MASTRA_BUILT_IN_TOOL_POLICIES`     | const     | Frozen `ReadonlyArray<ToolPolicyRule>` the harness feeds the SDK's `resolveToolApprovalPolicy` as the `tiers.harness` slice — `allow` rules for Mastra's built-in `updateWorkingMemory` / `skill` / `skill_search` / `skill_read` tools. |
+| `MASTRA_BUILT_IN_TOOL_NAMES`        | const     | The four built-in tool leaf names `MASTRA_BUILT_IN_TOOL_POLICIES` covers.                                                                                                                                                                |
 
 Connectivity (model + provider auth) is supplied by the SDK's `AgentConnectivityResolver`. Use the bundled
 `DefaultAgentConnectivityResolver` for the standard Salesforce LLM Gateway path, or `ApiKeyConnectivityResolver` for
@@ -66,6 +68,32 @@ no `globalThis` mutation. When no proxy env is set, `fetch` runs unwrapped (zero
 **Snapshot timing.** `HTTPS_PROXY` / `HTTP_PROXY` are captured at `create()` time and pinned for the harness's lifetime;
 `NO_PROXY` is re-evaluated per request. Set the proxy env vars before constructing the factory's first harness.
 
+#### Injecting custom wire shapes
+
+A consumer can register a `LanguageModelV3` builder for a custom `providerHint` via
+`MastraHarnessFactoryConfig.languageModelBuilders` without editing the harness's internal switch. Each injected key
+becomes a supported provider hint and a dispatch arm. Used to inject wire shapes the harness does not ship natively
+(e.g., a temporary GovCloud `chat/generations` fallback).
+
+```ts
+import {
+  CHAT_GENERATIONS_PROVIDER_HINT,
+  buildChatGenerationsLanguageModel,
+} from '@salesforce/sfdx-agent-chat-generations';
+
+const factory = new MastraHarnessFactory({
+  languageModelBuilders: {
+    [CHAT_GENERATIONS_PROVIDER_HINT]: buildChatGenerationsLanguageModel,
+  },
+});
+```
+
+The builder receives the same `MastraLanguageModelBuilderContext` bag (`getInfo`, `logBus`, `emitWireCommunication`,
+`innerFetch`) the harness's built-in builders get, so an injected builder can emit wire-monitoring events and honor
+`HTTPS_PROXY` routing without duplicating the harness's plumbing. Injected keys MUST NOT collide with built-in hints
+(`anthropic`, `bedrock-anthropic`, `openai`, `openai-responses`, `openai-compatible`) — the factory throws at
+construction time if a collision is detected.
+
 ### Extension surface
 
 These types let consumers reach Mastra-specific features through the SDK's typed `extensions` slot. The SDK infers

package/dist/index.d.ts

@@ -1,4 +1,50 @@
+import type { LogBus } from '@salesforce/agentic-common';
+import type { ModelConnectivityInfo, WireCommunicationEvent } from '@salesforce/sfdx-agent-sdk';
+import type { LanguageModelV3 } from '@ai-sdk/provider';
 export { MastraHarnessFactory, type MastraHarnessFactoryConfig } from './mastra-harness-factory.js';
 export type { MastraAgentHarness } from './mastra-harness.js';
 export { MASTRA_BUILT_IN_TOOL_NAMES, MASTRA_BUILT_IN_TOOL_POLICIES } from './mastra-built-in-policies.js';
 export { type MastraAgentConfig, type MastraSkillSearchConfig, type MastraToolSearchConfig, type SkillSearchHandle, type ToolSearchHandle, } from './tool-search.js';
+/**
+ * Context the harness threads into each `LanguageModelV3` builder — both the
+ * built-in builders and any consumer-injected builders registered via
+ * `MastraHarnessFactoryConfig.languageModelBuilders`. The shape mirrors what
+ * `MastraHarness.buildLanguageModel` currently hands its internal builders, so an
+ * injected builder receives the same context bag and can compose wire monitoring +
+ * proxy routing identically to the native pass-through builders.
+ *
+ * @remarks
+ * All fields come from the harness:
+ * - `getInfo()` returns the live `ModelConnectivityInfo` per outbound call (JWT
+ *   rotation + within-shape model swaps land on the next request without rebuilding).
+ * - `logBus` is the harness's `LogBus` (optional — may be undefined during early
+ *   construction phases).
+ * - `emitWireCommunication` emits `LlmRequestEvent` / `LlmResponseEvent` pairs onto
+ *   the harness's wire bus (for monitoring / debugging).
+ * - `innerFetch` is the harness's proxy-aware fetch (HTTPS_PROXY routing when
+ *   configured; `globalThis.fetch` otherwise).
+ */
+export type MastraLanguageModelBuilderContext = {
+    getInfo: () => ModelConnectivityInfo;
+    logBus?: LogBus;
+    emitWireCommunication: (event: WireCommunicationEvent) => void;
+    innerFetch: typeof fetch;
+};
+/**
+ * Factory function shape for a consumer-injected `LanguageModelV3` builder.
+ * Registered via `MastraHarnessFactoryConfig.languageModelBuilders` keyed by a custom
+ * `providerHint`, used to inject wire shapes the harness does not ship natively
+ * (e.g. a temporary GovCloud `chat/generations` fallback). The builder receives the
+ * same context bag the harness's built-in pass-through builders get, so an injected
+ * builder can emit `WireCommunicationEvent`s and honor `HTTPS_PROXY` routing without
+ * duplicating the harness's own fetch wrapper / wire-monitoring plumbing.
+ *
+ * @example
+ * ```ts
+ * // A consumer package registers a builder for its own custom providerHint.
+ * const factory = new MastraHarnessFactory({
+ *   languageModelBuilders: { 'my-custom-wire-shape': (ctx) => buildMyLanguageModel(ctx) },
+ * });
+ * ```
+ */
+export type MastraLanguageModelBuilder = (ctx: MastraLanguageModelBuilderContext) => LanguageModelV3;

package/dist/index.js

@@ -8,11 +8,4 @@ export { MastraHarnessFactory } from './mastra-harness-factory.js';
 // inspect which Mastra built-ins the harness auto-approves.
 export { MASTRA_BUILT_IN_TOOL_NAMES, MASTRA_BUILT_IN_TOOL_POLICIES } from './mastra-built-in-policies.js';
 export {} from './tool-search.js';
-// Mastra drives requests through provider-native pass-through endpoints —
-// Bedrock-Anthropic, direct Anthropic Messages API, OpenAI Responses, and
-// OpenAI Chat Completions (LLMG Express / openai-compatible) — dispatched on
-// the connectivity resolver's `ModelConnectivityInfo.providerHint`. There's
-// no consumer-facing knob for switching the wire path; the resolver drives
-// it. For BYOK / direct-Anthropic / LLMG-Express deployments use
-// `ApiKeyConnectivityResolver` from `@salesforce/sfdx-agent-sdk`.
 //# sourceMappingURL=index.js.map

package/dist/mastra-harness-factory.d.ts

@@ -1,5 +1,6 @@
 import type { HarnessFactory, ProviderHint } from '@salesforce/sfdx-agent-sdk';
 import { type MastraAgentHarness } from './mastra-harness.js';
+import type { MastraLanguageModelBuilder } from './index.js';
 export interface MastraHarnessFactoryConfig {
     /**
      * How long to wait for a consumer to call
@@ -10,6 +11,34 @@ export interface MastraHarnessFactoryConfig {
      * `ClaudeHarnessFactoryConfig.toolApprovalTimeoutMs`.
      */
     toolApprovalTimeoutMs?: number;
+    /**
+     * Consumer-registered `LanguageModelV3` builders keyed by `providerHint`. Each key
+     * becomes a supported provider hint and a dispatch arm in `buildLanguageModel`. Used
+     * to inject wire shapes the harness does not ship natively (e.g. a temporary
+     * GovCloud `chat/generations` fallback path). Keys MUST NOT collide with the
+     * harness's built-in hints (`anthropic`, `bedrock-anthropic`, `openai`,
+     * `openai-responses`, `openai-compatible`) — constructing with a colliding key
+     * throws at factory construction time rather than silently shadowing the built-in.
+     *
+     * @remarks
+     * The builder's context parameter provides the full `ModelConnectivityInfo` bag
+     * (via `getInfo()`), the harness's `LogBus`, a `WireCommunicationEvent` emitter,
+     * and the proxy-aware `innerFetch` — identical to what the harness's built-in
+     * builders receive. Each injected `providerHint` is advertised on
+     * `MastraHarnessFactory.supportedProviderHints` so the manager's pre-flight
+     * validation (G8) passes.
+     *
+     * @example
+     * ```ts
+     * // A consumer package supplies a builder for its own custom providerHint.
+     * const factory = new MastraHarnessFactory({
+     *   languageModelBuilders: {
+     *     'my-custom-wire-shape': (ctx) => buildMyLanguageModel(ctx),
+     *   },
+     * });
+     * ```
+     */
+    languageModelBuilders?: Readonly<Record<string, MastraLanguageModelBuilder>>;
 }
 /** Mastra-backed factory for creating AgentHarness instances. */
 export declare class MastraHarnessFactory implements HarnessFactory<MastraAgentHarness> {
@@ -17,6 +46,7 @@ export declare class MastraHarnessFactory implements HarnessFactory<MastraAgentH
     readonly harnessId = "mastra";
     readonly protocolVersion = 1;
     readonly supportedProviderHints: readonly ProviderHint[];
+    private static readonly BUILT_IN_HINTS;
     constructor(config?: MastraHarnessFactoryConfig);
     create(storageRootFolder: string): Promise<MastraAgentHarness>;
 }

package/dist/mastra-harness-factory.js

@@ -19,7 +19,8 @@ export class MastraHarnessFactory {
     config;
     harnessId = 'mastra';
     protocolVersion = 1;
-    supportedProviderHints = [
+    supportedProviderHints;
+    static BUILT_IN_HINTS = [
         'anthropic',
         'bedrock-anthropic',
         'openai',
@@ -28,12 +29,23 @@ export class MastraHarnessFactory {
     ];
     constructor(config = {}) {
         this.config = config;
+        const injected = Object.keys(config.languageModelBuilders ?? {});
+        // Collision guard: an injected key shadowing a built-in hint is a footgun
+        // (silent override of a native wire shape). Fail loud at construction time
+        // so the mistake is caught before any harness work runs.
+        for (const hint of injected) {
+            if (MastraHarnessFactory.BUILT_IN_HINTS.includes(hint)) {
+                throw new Error(`MastraHarnessFactory: injected languageModelBuilder key "${hint}" collides with a built-in provider hint. Choose a distinct key.`);
+            }
+        }
+        this.supportedProviderHints = [...MastraHarnessFactory.BUILT_IN_HINTS, ...injected];
     }
     async create(storageRootFolder) {
         const innerFetch = createProxyAwareFetch(resolveProxyDispatcher());
         return new MastraHarness(storageRootFolder, {
             toolApprovalTimeoutMs: this.config.toolApprovalTimeoutMs ?? DEFAULT_TOOL_APPROVAL_TIMEOUT_MS,
             innerFetch,
+            languageModelBuilders: this.config.languageModelBuilders,
         });
     }
 }

package/dist/mastra-harness.d.ts

@@ -3,10 +3,12 @@ import { SkillSearchProcessor, ToolSearchProcessor } from '@mastra/core/processo
 import { MCPClient } from '@mastra/mcp';
 import { McpServerStatus, type AgentHarness, type WithAgentConfig, type ChatStreamResult, type HarnessAgentConfig, type MCPConfiguration, type McpServerErrorDetail, type McpServerInfo, type Message, type MessagePart, type ModelConnectivityInfo, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo, type WireCommunicationEventCallback } from '@salesforce/sfdx-agent-sdk';
 import { type AgentHooks } from '@salesforce/sfdx-agent-sdk/harness';
+import type { MastraLanguageModelBuilderContext } from './index.js';
 import { MastraApprovalCoordinator } from './mastra-approval-coordinator.js';
 import { type HttpErrorCapture } from './mcp-config-mapper.js';
 import { type MastraAgentConfig, type SkillSearchHandle, type ToolSearchHandle } from './tool-search.js';
 import { type MultimodalFile } from '@salesforce/sfdx-agent-sdk';
+import type { LanguageModelV3 } from '@ai-sdk/provider';
 import { Clock, type LogRecord, type UniqueIDGenerator, type Unsubscribe } from '@salesforce/agentic-common';
 import { type ToolsInput } from './utils.js';
 import { Workspace } from '@mastra/core/workspace';
@@ -223,6 +225,14 @@ export interface MastraHarnessOptions {
      * any `globalThis` mutation.
      */
     innerFetch?: typeof fetch;
+    /**
+     * Consumer-registered `LanguageModelV3` builders keyed by `providerHint`.
+     * Forwarded from `MastraHarnessFactoryConfig.languageModelBuilders`. The
+     * harness consults this map in `buildLanguageModel`'s `default` arm before
+     * throwing `MODEL_NOT_SUPPORTED_BY_HARNESS`, so an injected builder can
+     * handle a custom hint without editing the harness's internal switch.
+     */
+    languageModelBuilders?: Readonly<Record<string, (ctx: MastraLanguageModelBuilderContext) => LanguageModelV3>>;
 }
 export declare class MastraHarness implements MastraAgentHarness {
     private readonly storageRootFolder;
@@ -256,6 +266,7 @@ export declare class MastraHarness implements MastraAgentHarness {
     private readonly idGenerator;
     private readonly toolApprovalTimeoutMs;
     private readonly innerFetch;
+    private readonly languageModelBuilders?;
     constructor(storageRootFolder: string, opts?: MastraHarnessOptions);
     /**
      * @requirements

package/dist/mastra-harness.js

@@ -398,12 +398,14 @@ export class MastraHarness {
     idGenerator;
     toolApprovalTimeoutMs;
     innerFetch;
+    languageModelBuilders;
     constructor(storageRootFolder, opts = {}) {
         this.storageRootFolder = storageRootFolder;
         this.clock = opts.clock ?? new RealClock();
         this.idGenerator = opts.idGenerator ?? new UUIDGenerator();
         this.toolApprovalTimeoutMs = opts.toolApprovalTimeoutMs ?? 600_000;
         this.innerFetch = opts.innerFetch ?? globalThis.fetch;
+        this.languageModelBuilders = opts.languageModelBuilders;
         this.storage = new LibSQLStore({
             id: 'mastra-storage',
             url: `file:${this.storageRootFolder}/mastra.db`,
@@ -1307,11 +1309,20 @@ export class MastraHarness {
                 // Different wire shape from Responses — `/v1/chat/completions` with
                 // `choices[0].delta` streaming events.
                 return buildOpenAIChatCompletionsLanguageModel({ getInfo, logBus, emitWireCommunication, innerFetch });
-            default:
+            default: {
+                // Consult the injected builders map before throwing. This is the
+                // extension point for consumer-registered wire shapes (e.g. a temporary
+                // GovCloud chat/generations fallback, W-23560954). The builder receives
+                // the same context bag the built-in builders get.
+                const custom = this.languageModelBuilders?.[initial.providerHint];
+                if (custom) {
+                    return custom({ getInfo, logBus, emitWireCommunication, innerFetch });
+                }
                 // Defensive — manager-side G8 should have caught this before
                 // we got here. Make the error typed so consumers can branch
                 // on `err.type` instead of regexing the message.
                 throw new AgentSDKError(`Mastra harness has no language-model builder for providerHint "${initial.providerHint}".`, AgentSDKErrorType.MODEL_NOT_SUPPORTED_BY_HARNESS);
+            }
         }
     }
     async destroyThreadBestEffort(agentId, threadId) {

package/dist/pass-through-openai.js

@@ -357,7 +357,9 @@ function toOpenAIInputFileOrImage(part) {
  * back to `undefined` `UsageMetadata` for consumers.
  */
 function finalizeUsage(usage, ctx, finishRaw) {
-    const mapped = mapOpenAIUsage(usage === undefined
+    const mapped = mapOpenAIUsage(
+    // Gateway returns usage: null (not undefined) on billable-token-free completions; both collapse to the sentinel.
+    usage == null
         ? undefined
         : {
             prompt_tokens: usage.input_tokens,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -32,21 +32,21 @@
     "@ai-sdk/provider": "^3.0.10",
     "@anthropic-ai/bedrock-sdk": "^0.32.0",
     "@anthropic-ai/sdk": "^0.111.0",
-    "@mastra/core": "^1.50.1",
-    "@mastra/libsql": "^1.15.1",
-    "@mastra/mcp": "^1.13.1",
-    "@mastra/memory": "^1.22.2",
+    "@mastra/core": "^1.51.0",
+    "@mastra/libsql": "^1.16.0",
+    "@mastra/mcp": "^1.14.0",
+    "@mastra/memory": "^1.23.0",
     "@mastra/schema-compat": "^1.2.11",
     "@salesforce/agentic-common": "0.13.0",
     "openai": "^6.0.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.36.0"
+    "@salesforce/sfdx-agent-sdk": "0.38.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@salesforce/harness-conformance": "0.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.36.0",
+    "@salesforce/sfdx-agent-sdk": "0.38.0",
     "@types/node": "^22.20.0",
     "@vitest/coverage-istanbul": "^4.1.10",
     "@vitest/eslint-plugin": "^1.6.22",