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

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/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-event-adapter.d.ts

@@ -47,7 +47,7 @@ import type { ChatEvent } from '@salesforce/sfdx-agent-sdk';
  * | `tool-call-delta`,      |                           |                                                        |
  * | `tool-call-suspended`,  |                           |                                                        |
  * | `object`, `tool-output` |                           |                                                        |
- * | *(all others)*          | `unmapped-chunk`          | `{ chunkType, rawChunk }` for observability            |
+ * | *(all others)*          | *(skipped)*               | Logged via `LogBus.debug` with `{ chunkType, rawChunk }` |
  *
  * Stateful per stream — a new instance must be created for each `MastraHarness.stream()` call.
  */
@@ -56,18 +56,20 @@ export declare class MastraEventAdapter {
     private stepIndex;
     /**
      * @param logBus - Optional structured-log sink. When supplied, the adapter emits a `debug`
-     *   log for each chunk it intentionally drops (informational lifecycle events the SDK
-     *   doesn't model, and known-but-unsupported chunk types) so consumers can observe what's
-     *   being filtered without it leaking into the public `ChatEvent` stream.
+     *   log for every chunk it intentionally drops — informational lifecycle events, known-but-
+     *   unsupported chunk types, and any unrecognized chunk type the adapter has not seen — so
+     *   harness developers can observe forward-compat gaps without harness internals leaking
+     *   onto the public `ChatEvent` stream.
      */
     constructor(logBus?: LogBus | undefined);
     /**
      * Convert a Mastra stream chunk to a ChatEvent.
      *
      * @param chunk - A Mastra `ChunkType` from `agent.stream().fullStream`.
-     * @returns The corresponding {@link ChatEvent}, `undefined` for
-     *   informational chunks that should be silently skipped, or an
-     *   `UnmappedChunkEvent` for truly unrecognized chunk types.
+     * @returns The corresponding {@link ChatEvent}, or `undefined` for chunks the
+     *   adapter intentionally skips (informational lifecycle events, known-but-
+     *   unsupported chunk types, and unrecognized chunk types). Skipped chunks are
+     *   logged via the optional `LogBus` so harness developers can still observe them.
      */
     toChatEvent(chunk: ChunkType): ChatEvent | undefined;
 }

package/dist/mastra-event-adapter.js

@@ -48,7 +48,7 @@
  * | `tool-call-delta`,      |                           |                                                        |
  * | `tool-call-suspended`,  |                           |                                                        |
  * | `object`, `tool-output` |                           |                                                        |
- * | *(all others)*          | `unmapped-chunk`          | `{ chunkType, rawChunk }` for observability            |
+ * | *(all others)*          | *(skipped)*               | Logged via `LogBus.debug` with `{ chunkType, rawChunk }` |
  *
  * Stateful per stream — a new instance must be created for each `MastraHarness.stream()` call.
  */
@@ -57,9 +57,10 @@ export class MastraEventAdapter {
     stepIndex = 0;
     /**
      * @param logBus - Optional structured-log sink. When supplied, the adapter emits a `debug`
-     *   log for each chunk it intentionally drops (informational lifecycle events the SDK
-     *   doesn't model, and known-but-unsupported chunk types) so consumers can observe what's
-     *   being filtered without it leaking into the public `ChatEvent` stream.
+     *   log for every chunk it intentionally drops — informational lifecycle events, known-but-
+     *   unsupported chunk types, and any unrecognized chunk type the adapter has not seen — so
+     *   harness developers can observe forward-compat gaps without harness internals leaking
+     *   onto the public `ChatEvent` stream.
      */
     constructor(logBus) {
         this.logBus = logBus;
@@ -68,9 +69,10 @@ export class MastraEventAdapter {
      * Convert a Mastra stream chunk to a ChatEvent.
      *
      * @param chunk - A Mastra `ChunkType` from `agent.stream().fullStream`.
-     * @returns The corresponding {@link ChatEvent}, `undefined` for
-     *   informational chunks that should be silently skipped, or an
-     *   `UnmappedChunkEvent` for truly unrecognized chunk types.
+     * @returns The corresponding {@link ChatEvent}, or `undefined` for chunks the
+     *   adapter intentionally skips (informational lifecycle events, known-but-
+     *   unsupported chunk types, and unrecognized chunk types). Skipped chunks are
+     *   logged via the optional `LogBus` so harness developers can still observe them.
      */
     toChatEvent(chunk) {
         switch (chunk.type) {
@@ -168,8 +170,8 @@ export class MastraEventAdapter {
                 this.logBus?.debug('Skipping informational Mastra chunk', { chunkType: chunk.type });
                 return undefined;
             // Known harness chunk types not yet supported in the SDK's ChatEvent
-            // model. Silently dropped to avoid leaking harness internals via
-            // unmapped-chunk. Candidates for future ChatEvent variants when the
+            // model. Silently dropped to avoid leaking harness internals onto the
+            // public stream. Candidates for future ChatEvent variants when the
             // corresponding features (citations, file generation, tool arg
             // streaming, tool suspension, structured output) are supported.
             case 'source':
@@ -183,7 +185,15 @@ export class MastraEventAdapter {
                 this.logBus?.debug('Skipping unsupported Mastra chunk type', { chunkType: chunk.type });
                 return undefined;
             default:
-                return { type: 'unmapped-chunk', chunkType: chunk.type, rawChunk: chunk };
+                // Forward-compat: a newer Mastra version can emit a chunk type the
+                // adapter has not seen. Surface it on `LogBus.debug` for harness
+                // developers and skip it on the public stream so harness internals
+                // never reach consumers.
+                this.logBus?.debug('Skipping unrecognized Mastra chunk type', {
+                    chunkType: chunk.type,
+                    rawChunk: chunk,
+                });
+                return undefined;
         }
     }
 }
@@ -195,13 +205,21 @@ function mapFinishReason(reason) {
 function mapUsage(usage) {
     if (!usage)
         return undefined;
-    return {
-        inputTokens: usage.inputTokens ?? undefined,
-        outputTokens: usage.outputTokens ?? undefined,
-        totalTokens: usage.totalTokens ?? undefined,
-        reasoningTokens: usage.reasoningTokens,
-        cachedInputTokens: usage.cachedInputTokens,
-        cacheWriteInputTokens: usage.cacheCreationInputTokens ? usage.cacheCreationInputTokens : undefined,
-    };
+    const inputTokens = usage.inputTokens ?? undefined;
+    const outputTokens = usage.outputTokens ?? undefined;
+    const totalTokens = usage.totalTokens ?? undefined;
+    const reasoningTokens = usage.reasoningTokens;
+    const cachedInputTokens = usage.cachedInputTokens;
+    const cacheWriteInputTokens = usage.cacheCreationInputTokens ? usage.cacheCreationInputTokens : undefined;
+    // Collapse all-falsy usage to undefined so consumers see "no usage" instead of a populated-but-empty object (W-22692131).
+    if (!inputTokens &&
+        !outputTokens &&
+        !totalTokens &&
+        !reasoningTokens &&
+        !cachedInputTokens &&
+        !cacheWriteInputTokens) {
+        return undefined;
+    }
+    return { inputTokens, outputTokens, totalTokens, reasoningTokens, cachedInputTokens, cacheWriteInputTokens };
 }
 //# sourceMappingURL=mastra-event-adapter.js.map

package/dist/mastra-harness.d.ts

@@ -332,7 +332,7 @@ export declare class MastraHarness implements MastraAgentHarness {
      * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.
      * - MUST clone the source thread's messages into a new thread.
      */
-    cloneThread(agentId: string, sourceThreadId: string, targetThreadId?: string): Promise<string>;
+    cloneThread(agentId: string, sourceThreadId: string): Promise<string>;
     /**
      * @requirements
      * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.

package/dist/mastra-harness.js

@@ -23,7 +23,7 @@ import { buildMcpErrorDetail, sanitizeMcpErrorMessage } from './mcp-error-classi
 import { DefaultMastraModelConfigFactory } from './default-model-config-factory.js';
 import { partitionPool, } from './tool-search.js';
 import {} from '@salesforce/llm-gateway-sdk';
-import { buildSummaryPrompt, Clock, getErrorMessage, RealClock, splitFrontmatterAndBody, UUIDGenerator, } from '@salesforce/agentic-common';
+import { backfillCreatedAt, buildSummaryPrompt, Clock, getErrorMessage, RealClock, splitFrontmatterAndBody, UUIDGenerator, } from '@salesforce/agentic-common';
 import { makeAbortable } from './utils.js';
 import { Workspace, LocalFilesystem, LocalSandbox, WORKSPACE_TOOLS, WORKSPACE_TOOLS_PREFIX, } from '@mastra/core/workspace';
 /**
@@ -529,7 +529,7 @@ export class MastraHarness {
             }
         }
         const customTools = config.tools?.length ? mapToolDefinitionsToMastraTools(config.tools) : {};
-        const { model: resolvedModel, validateFiles } = this.modelConfigFactory.create(llmGatewayClient);
+        const { model: resolvedModel, validateFiles } = this.modelConfigFactory.create(llmGatewayClient, this.buses.getLogBus());
         let mastraWorkspace;
         let agent;
         let mastraAgentAdded = false;
@@ -870,12 +870,9 @@ export class MastraHarness {
      * - MUST throw an error if the specified `agentId` is not found in `activeAgents`.
      * - MUST clone the source thread's messages into a new thread.
      */
-    async cloneThread(agentId, sourceThreadId, targetThreadId) {
+    async cloneThread(agentId, sourceThreadId) {
         const memory = await this.getMemoryOrThrow(agentId);
-        const { thread } = await memory.cloneThread({
-            sourceThreadId,
-            newThreadId: targetThreadId,
-        });
+        const { thread } = await memory.cloneThread({ sourceThreadId });
         return thread.id;
     }
     /**
@@ -1265,10 +1262,26 @@ export class MastraHarness {
         // `'system' | 'user' | 'assistant' | 'tool'` and surfacing experimental upstream concepts would leak the
         // harness internals up to consumers. If Mastra promotes signals to stable and we want them, the SDK
         // contract needs to add the role first.
+        // Per-position fallback for any persisted row whose `createdAt` is
+        // null/undefined (legacy rows from before the optional-on-write
+        // contract, partial-write recovery, or a libsql schema change).
+        // Mirrors the Claude harness's clock.nextAfter pattern so the
+        // read-side contract — every returned Message.createdAt populated;
+        // sort ascending — holds even when the persisted layer fails to
+        // produce a timestamp. Without this, the prior `?? 0` form would
+        // silently bucket null-timestamp rows at epoch and propagate
+        // `undefined` to consumers.
+        let lastFallback = this.clock.now();
         return messages
             .filter((m) => m.role !== 'signal')
             .map((m) => mapMastraToMessage(m, logBus))
-            .sort((a, b) => (a.createdAt?.getTime() ?? 0) - (b.createdAt?.getTime() ?? 0));
+            .map((m) => {
+            if (m.createdAt)
+                return m;
+            lastFallback = this.clock.nextAfter(lastFallback);
+            return { ...m, createdAt: lastFallback };
+        })
+            .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
     }
     /**
      * @requirements
@@ -1294,7 +1307,15 @@ export class MastraHarness {
     async addContext(agentId, threadId, messages) {
         const memory = await this.getMemoryOrThrow(agentId);
         const resourceId = this.agentResourceId(agentId);
-        const mapped = messages.map((m) => mapMessageToMastra(m, threadId, resourceId, this.clock));
+        // Backfill `createdAt` on any caller-supplied message that omits it.
+        // The SDK's `ChatSession.addContext` already does this for SDK-routed
+        // calls; the harness backfills defensively so a direct
+        // `harness.addContext` call still produces a sortable persisted
+        // record (Mastra's libsql column is non-nullable). Routes through the
+        // shared `backfillCreatedAt` helper from `agentic-common` so the SDK
+        // and both harnesses can't drift on the per-position step policy.
+        const filled = backfillCreatedAt(messages, this.clock);
+        const mapped = filled.map((m) => mapMessageToMastra(m, threadId, resourceId));
         await memory.saveMessages({ messages: mapped });
     }
     // ── Private Helpers ──────────────────────────────────────────────
@@ -1372,7 +1393,7 @@ export class MastraHarness {
     getAgentStateOrThrow(agentId) {
         const state = this.activeAgents.get(agentId);
         if (!state) {
-            throw new Error(`Agent with id "${agentId}" is not registered`);
+            throw new AgentSDKError(`No Agent found with id: "${agentId}"`, AgentSDKErrorType.AGENT_NOT_FOUND);
         }
         return state;
     }

package/dist/mastra-message-mapper.d.ts

@@ -1,6 +1,6 @@
 import type { MastraDBMessage, MastraMessagePart } from '@mastra/core/agent';
 import type { Message, MessagePart } from '@salesforce/sfdx-agent-sdk';
-import { Clock, type LogBus } from '@salesforce/agentic-common';
+import type { LogBus } from '@salesforce/agentic-common';
 /**
  * Converts a Mastra persisted message into the SDK's {@link Message} type.
  *
@@ -26,12 +26,8 @@ export declare function mapMastraPartToMessagePart(part: MastraMessagePart, logB
  * Converts an SDK {@link Message} into the Mastra persisted message format.
  * The `role` field is normalised: `'tool'` role (which has no Mastra equivalent)
  * is coerced to `'assistant'`.
- *
- * @param clock - Optional clock used for the `createdAt` fallback when the
- *     source message has no timestamp. Defaults to `RealClock`. Tests inject
- *     a stub to make assertions deterministic.
  */
-export declare function mapMessageToMastra(msg: Message, threadId: string, resourceId: string, clock?: Clock): MastraDBMessage;
+export declare function mapMessageToMastra(msg: Message, threadId: string, resourceId: string): MastraDBMessage;
 /**
  * Converts a single SDK {@link MessagePart} into the Mastra message part format.
  */

package/dist/mastra-message-mapper.js

@@ -2,7 +2,6 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
-import { Clock, RealClock } from '@salesforce/agentic-common';
 /**
  * Reads the SDK `fileName` stashed under `providerMetadata.salesforce.fileName` when a file part
  * was persisted via {@link mapMessagePartToMastra}. Returns `undefined` when absent or not a string.
@@ -155,12 +154,8 @@ export function mapMastraPartToMessagePart(part, logBus) {
  * Converts an SDK {@link Message} into the Mastra persisted message format.
  * The `role` field is normalised: `'tool'` role (which has no Mastra equivalent)
  * is coerced to `'assistant'`.
- *
- * @param clock - Optional clock used for the `createdAt` fallback when the
- *     source message has no timestamp. Defaults to `RealClock`. Tests inject
- *     a stub to make assertions deterministic.
  */
-export function mapMessageToMastra(msg, threadId, resourceId, clock = new RealClock()) {
+export function mapMessageToMastra(msg, threadId, resourceId) {
     const parts = [];
     if (typeof msg.content === 'string') {
         parts.push({ type: 'text', text: msg.content });
@@ -171,10 +166,20 @@ export function mapMessageToMastra(msg, threadId, resourceId, clock = new RealCl
         }
     }
     const role = msg.role === 'tool' ? 'assistant' : msg.role;
+    if (!msg.createdAt) {
+        // Internal contract: callers (the harness's `addContext` and
+        // `compactThread`) backfill `createdAt` before reaching this
+        // mapper, so Mastra's non-nullable persisted column always has a
+        // value. Throwing here surfaces the bug at its real call site
+        // instead of producing a silently-wrong row downstream. Include
+        // role + threadId so the failure self-locates if a future caller
+        // forgets to backfill.
+        throw new Error(`mapMessageToMastra: msg.createdAt is required (id="${msg.id}", role="${msg.role}", threadId="${threadId}")`);
+    }
     return {
         id: msg.id,
         role,
-        createdAt: msg.createdAt ?? clock.now(),
+        createdAt: msg.createdAt,
         threadId,
         resourceId,
         content: {

package/dist/mcp-config-mapper.d.ts

@@ -17,6 +17,10 @@ export declare function hasEnabledServers(config: MCPConfiguration | undefined):
  *   Mastra's `timeout` (post-connect request lifetime) and `connectTimeout` (initial transport
  *   handshake) so the configured value covers both phases — Mastra's hardcoded 3s
  *   `connectTimeout` default would otherwise abort cold-start handshakes before `timeout` applied.
+ * - Per-server `reconnectionOptions` is forwarded to Mastra's `HttpServerDefinition.reconnectionOptions`
+ *   (typed as `StreamableHTTPClientTransportOptions['reconnectionOptions']`). Unspecified fields
+ *   are filled from {@link DEFAULT_RECONNECTION_OPTIONS} so partial overrides leave the rest at
+ *   the MCP SDK's built-in defaults.
  * - When `orgJwt` is provided, remote servers get a `fetch` that delegates to
  *   {@link resolveMcpServerHeaders} per-request to inject auth for Salesforce Platform URLs.
  */

package/dist/mcp-config-mapper.js

@@ -12,6 +12,20 @@ export function hasEnabledServers(config) {
         return false;
     return Object.values(config).some((s) => s.enabled !== false);
 }
+/**
+ * MCP SDK's built-in `StreamableHTTPReconnectionOptions` defaults. Mirrored
+ * here so partial `MCPRemoteServerConfig.reconnectionOptions` inputs merge
+ * field-wise with the underlying defaults rather than replacing them — the
+ * underlying transport replaces the entire defaults object when
+ * `reconnectionOptions` is set, so a partial override would otherwise zero
+ * out the unspecified fields.
+ */
+const DEFAULT_RECONNECTION_OPTIONS = {
+    maxRetries: 2,
+    initialReconnectionDelay: 1000,
+    maxReconnectionDelay: 30000,
+    reconnectionDelayGrowFactor: 1.5,
+};
 /**
  * Converts our {@link MCPConfiguration} into the `servers` map expected by Mastra's `MCPClient`.
  *
@@ -23,6 +37,10 @@ export function hasEnabledServers(config) {
  *   Mastra's `timeout` (post-connect request lifetime) and `connectTimeout` (initial transport
  *   handshake) so the configured value covers both phases — Mastra's hardcoded 3s
  *   `connectTimeout` default would otherwise abort cold-start handshakes before `timeout` applied.
+ * - Per-server `reconnectionOptions` is forwarded to Mastra's `HttpServerDefinition.reconnectionOptions`
+ *   (typed as `StreamableHTTPClientTransportOptions['reconnectionOptions']`). Unspecified fields
+ *   are filled from {@link DEFAULT_RECONNECTION_OPTIONS} so partial overrides leave the rest at
+ *   the MCP SDK's built-in defaults.
  * - When `orgJwt` is provided, remote servers get a `fetch` that delegates to
  *   {@link resolveMcpServerHeaders} per-request to inject auth for Salesforce Platform URLs.
  */
@@ -53,6 +71,12 @@ export function mapToMastraMCPServers(config, orgJwt) {
                     timeout: serverConfig.timeout,
                     connectTimeout: serverConfig.timeout,
                 }),
+                ...(serverConfig.reconnectionOptions !== undefined && {
+                    reconnectionOptions: {
+                        ...DEFAULT_RECONNECTION_OPTIONS,
+                        ...serverConfig.reconnectionOptions,
+                    },
+                }),
             };
             result[name] = def;
         }

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

@@ -1,4 +1,5 @@
 import type { MastraModelConfig } from '@mastra/core/llm';
+import type { LogBus } from '@salesforce/agentic-common';
 import type { LLMGatewayClient, MultimodalFile } from '@salesforce/llm-gateway-sdk';
 export interface ResolvedModelConfig {
     model: MastraModelConfig;
@@ -21,8 +22,12 @@ export interface ResolvedModelConfig {
  * Implementations decide how to build a language model from the available
  * context. The LLMGatewayClient is provided for implementations that need
  * Salesforce org-authenticated model access; implementations that use
- * alternative backends (e.g., direct API key auth) may ignore it.
+ * alternative backends (e.g., direct API key auth) may ignore it. The
+ * optional `logBus` is the harness's structured-log sink — implementations
+ * that wrap a streaming gateway (e.g. `SalesforceMastraModelGateway`) use it
+ * to surface non-fatal anomalies (such as missing usage chunks) without
+ * polluting the public `ChatEvent` stream.
  */
 export interface MastraModelConfigFactory {
-    create(llmGatewayClient: LLMGatewayClient): ResolvedModelConfig;
+    create(llmGatewayClient: LLMGatewayClient, logBus?: LogBus): ResolvedModelConfig;
 }

package/dist/salesforce-llm-gateway.d.ts

@@ -1,7 +1,7 @@
 import { MastraModelGateway, type ProviderConfig } from '@mastra/core/llm';
 import type { LanguageModelV3 } from '@ai-sdk/provider';
 import type { LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
-import { type UniqueIDGenerator } from '@salesforce/agentic-common';
+import { type LogBus, type UniqueIDGenerator } from '@salesforce/agentic-common';
 /**
  * Bridges the Salesforce LLM Gateway SDK to Mastra's MastraModelGateway interface.
  *
@@ -12,14 +12,18 @@ import { type UniqueIDGenerator } from '@salesforce/agentic-common';
 export declare class SalesforceMastraModelGateway extends MastraModelGateway {
     private readonly gatewayClient;
     private readonly idGenerator;
+    private readonly logBus?;
     readonly id = "sfdc";
     readonly name = "Salesforce LLM Gateway";
     /**
      * @param gatewayClient - the LLM Gateway client this bridge delegates generation to.
      * @param idGenerator - source of the `fileId` stamped on each translated multimodal file.
      *     Defaults to `UUIDGenerator`; tests inject a stub for deterministic ids.
+     * @param logBus - optional structured-log sink. When supplied, `doStream` emits a `warn`
+     *     log on streams that end without a usage chunk (W-22692131) so operators can correlate
+     *     the upstream condition with downstream missing-usage observations.
      */
-    constructor(gatewayClient: LLMGatewayClient, idGenerator?: UniqueIDGenerator);
+    constructor(gatewayClient: LLMGatewayClient, idGenerator?: UniqueIDGenerator, logBus?: LogBus | undefined);
     getApiKey(_modelId: string): Promise<string>;
     buildUrl(_modelId: string, _envVars: Record<string, string>): string;
     fetchProviders(): Promise<Record<string, ProviderConfig>>;

package/dist/salesforce-llm-gateway.js

@@ -15,17 +15,22 @@ import { UUIDGenerator } from '@salesforce/agentic-common';
 export class SalesforceMastraModelGateway extends MastraModelGateway {
     gatewayClient;
     idGenerator;
+    logBus;
     id = 'sfdc';
     name = 'Salesforce LLM Gateway';
     /**
      * @param gatewayClient - the LLM Gateway client this bridge delegates generation to.
      * @param idGenerator - source of the `fileId` stamped on each translated multimodal file.
      *     Defaults to `UUIDGenerator`; tests inject a stub for deterministic ids.
+     * @param logBus - optional structured-log sink. When supplied, `doStream` emits a `warn`
+     *     log on streams that end without a usage chunk (W-22692131) so operators can correlate
+     *     the upstream condition with downstream missing-usage observations.
      */
-    constructor(gatewayClient, idGenerator = new UUIDGenerator()) {
+    constructor(gatewayClient, idGenerator = new UUIDGenerator(), logBus) {
         super();
         this.gatewayClient = gatewayClient;
         this.idGenerator = idGenerator;
+        this.logBus = logBus;
     }
     async getApiKey(_modelId) {
         return '';
@@ -87,7 +92,9 @@ export class SalesforceMastraModelGateway extends MastraModelGateway {
         const stream = new ReadableStream({
             start: async (controller) => {
                 try {
-                    let lastUsage = mapUsage(undefined);
+                    // V3 requires a `usage` field on `finish`; leave undefined here so we can
+                    // detect a stream that ended without a usage chunk (W-22692131).
+                    let lastUsage;
                     for await (const chunk of response.data) {
                         if (chunk.generatedText && !chunk.done) {
                             if (!textSpanOpen) {
@@ -126,10 +133,16 @@ export class SalesforceMastraModelGateway extends MastraModelGateway {
                                 controller.enqueue({ type: 'text-end', id: `text-${textSpanId}` });
                             }
                             const finishReason = mapFinishReason(chunk.finishReason, sawToolCalls);
+                            if (lastUsage === undefined) {
+                                this.logBus?.warn('LLM Gateway stream ended without a usage chunk', {
+                                    modelId: this.gatewayClient.getModel().name,
+                                    finishReason: chunk.finishReason,
+                                });
+                            }
                             controller.enqueue({
                                 type: 'finish',
                                 finishReason,
-                                usage: lastUsage,
+                                usage: lastUsage ?? mapUsage(undefined),
                             });
                             controller.close();
                             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -34,15 +34,15 @@
     "@mastra/mcp": "^1.8.0",
     "@mastra/memory": "^1.19.0",
     "@mastra/schema-compat": "^1.2.10",
-    "@salesforce/agentic-common": "0.6.0",
-    "@salesforce/llm-gateway-sdk": "0.10.0"
+    "@salesforce/agentic-common": "0.7.0",
+    "@salesforce/llm-gateway-sdk": "0.11.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.14.0"
+    "@salesforce/sfdx-agent-sdk": "0.15.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.14.0",
+    "@salesforce/sfdx-agent-sdk": "0.15.0",
     "@types/node": "^22.19.17",
     "@vitest/coverage-istanbul": "^4.1.7",
     "@vitest/eslint-plugin": "^1.6.17",