@salesforce/sfdx-agent-harness-mastra 0.80.0 → 0.82.0

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 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.82.0] - 2026-09-16
+
+### Features
+- **harness-mastra**: stream tool-call argument deltas from pass-through builders @W-23954558@ ([#824](https://github.com/forcedotcom/agentic-dx/pull/824))
+
+## [0.81.0] - 2026-09-15
+
+_No changes — released alongside dependent packages._
+
 ## [0.80.0] - 2026-09-15
 
 ### Chores

package/dist/pass-through-anthropic.js

@@ -5,7 +5,7 @@
 import { AnthropicBedrock } from '@anthropic-ai/bedrock-sdk';
 import Anthropic from '@anthropic-ai/sdk';
 import { EmptyStreamError, NetworkStreamError, isStreamTransportError, recognizeBedrockValidationError, } from './stream-errors.js';
-import { TextSpanLifecycle, buildValidatedToolCallChunk, createGatewayFetch, isEmptyUsage, isParameterExcluded, mapAnthropicFinishReason, mapAnthropicUsage, toolResultOutputToString, } from './v3-stream-mapping.js';
+import { TextSpanLifecycle, ToolInputSpanLifecycle, buildValidatedToolCallChunk, createGatewayFetch, isEmptyUsage, isParameterExcluded, mapAnthropicFinishReason, mapAnthropicUsage, toolResultOutputToString, } from './v3-stream-mapping.js';
 /**
  * Builds the in-process `LanguageModelV3` impl for the Salesforce LLM Gateway's
  * `/invoke-with-response-stream` (Bedrock-Anthropic pass-through) endpoint.
@@ -357,10 +357,14 @@ async function doStream(ctx, options) {
                                 // A tool_use block follows any open text — close that span and
                                 // bump the id so post-tool text lands in a fresh span.
                                 textSpan.rotate(controller);
+                                // Stream incremental tool-call arg deltas alongside the
+                                // unchanged terminal `tool-call` (W-23954558); see
+                                // ToolInputSpanLifecycle.
                                 toolUseByIndex.set(event.index, {
                                     id: block.id,
                                     name: block.name,
                                     argsBuffer: '',
+                                    input: new ToolInputSpanLifecycle(block.id, block.name, ctx.logBus),
                                 });
                             }
                             // Other block types (thinking, server-tool result, etc.) are
@@ -375,8 +379,10 @@ async function doStream(ctx, options) {
                             }
                             else if (delta.type === 'input_json_delta') {
                                 const tu = toolUseByIndex.get(event.index);
-                                if (tu)
+                                if (tu) {
                                     tu.argsBuffer += delta.partial_json;
+                                    tu.input.delta(controller, delta.partial_json);
+                                }
                             }
                             // thinking_delta / signature_delta / citations_delta are not
                             // currently surfaced — Mastra has no V3 stream-part for them in
@@ -388,6 +394,9 @@ async function doStream(ctx, options) {
                             if (tu) {
                                 sawToolCalls = true;
                                 sawContentOrUsage = true;
+                                // Close the tool-input span before the unchanged terminal
+                                // `tool-call` (wire order start → delta* → end → call).
+                                tu.input.close(controller, tu.argsBuffer);
                                 for (const part of buildValidatedToolCallChunk(tu.id, tu.name, tu.argsBuffer, toolSchemas.get(tu.name), ctx.getConsumerToolNames().has(tu.name), { retryCounts: ctx.getToolArgsRetryCounts(options), logBus: ctx.logBus })) {
                                     controller.enqueue(part);
                                 }

package/dist/pass-through-openai-chat-completions.js

@@ -4,7 +4,7 @@
  */
 import OpenAI from 'openai';
 import { EmptyStreamError } from './stream-errors.js';
-import { TextSpanLifecycle, buildValidatedToolCallChunk, createGatewayFetch, isEmptyUsage, isParameterExcluded, mapOpenAIUsage, toolResultOutputToString, } from './v3-stream-mapping.js';
+import { TextSpanLifecycle, ToolInputSpanLifecycle, buildValidatedToolCallChunk, createGatewayFetch, isEmptyUsage, isParameterExcluded, mapOpenAIUsage, toolResultOutputToString, } from './v3-stream-mapping.js';
 /**
  * Builds the in-process `LanguageModelV3` impl that drives the `openai` SDK's
  * `chat.completions.create({ stream: true })` against an OpenAI-compatible
@@ -202,6 +202,28 @@ async function doStream(ctx, options) {
                                 if (tc.function?.arguments)
                                     acc.argsBuffer += tc.function.arguments;
                             }
+                            // Stream incremental tool-call arg deltas alongside the
+                            // unchanged terminal `tool-call` (W-23954558; see
+                            // ToolInputSpanLifecycle). Chat Completions has no discrete
+                            // start/done event, so the span opens lazily once an `id` is
+                            // known (OpenAI-compatible servers send it on the first delta)
+                            // and closes at the flush.
+                            if (!acc.input) {
+                                if (acc.id) {
+                                    acc.input = new ToolInputSpanLifecycle(acc.id, acc.name, ctx.logBus);
+                                    // Stream whatever accrued before the id was known
+                                    // (normally just this chunk's fragment) so the deltas
+                                    // still concatenate to the terminal input.
+                                    acc.input.delta(controller, acc.argsBuffer);
+                                }
+                                // No id yet: args stay buffered; the catch-up delta above
+                                // flushes them once the id arrives (OpenAI-compatible servers
+                                // send `id` on the first delta, so this only defers the
+                                // pathological id-less-first-delta case).
+                            }
+                            else if (tc.function?.arguments) {
+                                acc.input.delta(controller, tc.function.arguments);
+                            }
                         }
                     }
                     if (choice.finish_reason !== null && choice.finish_reason !== undefined) {
@@ -232,6 +254,10 @@ async function doStream(ctx, options) {
                                 continue;
                             }
                             sawToolCalls = true;
+                            // Close the tool-input span before the unchanged terminal
+                            // `tool-call`. `acc.id` is non-empty here (the guard above
+                            // `continue`s otherwise), so `acc.input` was constructed.
+                            acc.input?.close(controller, acc.argsBuffer);
                             for (const part of buildValidatedToolCallChunk(acc.id, acc.name, acc.argsBuffer, toolSchemas.get(acc.name), ctx.getConsumerToolNames().has(acc.name), { retryCounts: ctx.getToolArgsRetryCounts(options), logBus: ctx.logBus })) {
                                 controller.enqueue(part);
                             }

package/dist/pass-through-openai.js

@@ -4,7 +4,7 @@
  */
 import OpenAI from 'openai';
 import { EmptyStreamError, GatewayResponseError } from './stream-errors.js';
-import { TextSpanLifecycle, buildValidatedToolCallChunk, createGatewayFetch, isEmptyUsage, isParameterExcluded, mapOpenAIFinishReason, mapOpenAIUsage, toolResultOutputToString, } from './v3-stream-mapping.js';
+import { TextSpanLifecycle, ToolInputSpanLifecycle, buildValidatedToolCallChunk, createGatewayFetch, isEmptyUsage, isParameterExcluded, mapOpenAIFinishReason, mapOpenAIUsage, toolResultOutputToString, } from './v3-stream-mapping.js';
 /**
  * Builds the in-process `LanguageModelV3` impl that drives the `openai` SDK's
  * `responses.create({ stream: true })` against the Salesforce LLM Gateway's
@@ -148,18 +148,30 @@ async function doStream(ctx, options) {
                                 // A tool_call follows any open text — close that span and bump
                                 // the id so post-tool text lands in a fresh span.
                                 textSpan.rotate(controller);
+                                const argsBuffer = item.arguments ?? '';
+                                // Stream incremental tool-call arg deltas alongside the
+                                // unchanged terminal `tool-call` (W-23954558); see
+                                // ToolInputSpanLifecycle.
+                                const input = new ToolInputSpanLifecycle(item.call_id, item.name, ctx.logBus);
                                 toolCallById.set(item.id ?? item.call_id, {
                                     id: item.call_id,
                                     name: item.name,
-                                    argsBuffer: item.arguments ?? '',
+                                    argsBuffer,
+                                    input,
                                 });
+                                // Responses streams args via function_call_arguments.delta,
+                                // so `arguments` is normally empty here; forward any
+                                // pre-populated buffer as a fragment.
+                                input.delta(controller, argsBuffer);
                             }
                             break;
                         }
                         case 'response.function_call_arguments.delta': {
                             const tc = toolCallById.get(event.item_id);
-                            if (tc)
+                            if (tc) {
                                 tc.argsBuffer += event.delta;
+                                tc.input.delta(controller, event.delta);
+                            }
                             break;
                         }
                         case 'response.output_item.done': {
@@ -169,6 +181,10 @@ async function doStream(ctx, options) {
                                 const finalArgs = item.arguments ?? tc?.argsBuffer ?? '';
                                 sawToolCalls = true;
                                 sawContent = true;
+                                // Close the tool-input span before the unchanged terminal
+                                // `tool-call` (handles the atomic case where args arrive
+                                // only here, with no incremental deltas).
+                                tc?.input.close(controller, finalArgs);
                                 for (const part of buildValidatedToolCallChunk(item.call_id, item.name, finalArgs, toolSchemas.get(item.name), ctx.getConsumerToolNames().has(item.name), { retryCounts: ctx.getToolArgsRetryCounts(options), logBus: ctx.logBus })) {
                                     controller.enqueue(part);
                                 }

package/dist/v3-stream-mapping.d.ts

@@ -63,6 +63,55 @@ export declare class TextSpanLifecycle {
     }): void;
     private spanId;
 }
+/**
+ * Encodes the AI SDK V3 tool-input streaming lifecycle (`tool-input-start` /
+ * `tool-input-delta` / `tool-input-end`) that surfaces incremental tool-call
+ * argument fragments to consumers (W-23954558). One instance per tool call.
+ *
+ * These parts are emitted IN ADDITION TO — never instead of — the authoritative
+ * terminal `tool-call` part (built by {@link buildValidatedToolCallChunk}), in
+ * real wire order: `start → delta* → end → tool-call`.
+ *
+ * Load-bearing invariant: `@mastra/core`'s stream pipeline, once it sees a
+ * `tool-input-start`, derives the final tool call's `args` from the ACCUMULATED
+ * `tool-input-delta` fragments — NOT from the terminal `tool-call.input`. So the
+ * concatenation of the deltas this class emits MUST reproduce the argument
+ * string the terminal `tool-call` carries, or Mastra surfaces truncated/empty
+ * args. This class enforces that:
+ *
+ * - The span is opened LAZILY on the first non-empty fragment, so a genuinely
+ *   no-argument call (zero fragments) never opens a span and Mastra falls back
+ *   to the terminal `input` (`'{}'`). An empty fragment is dropped (Mastra drops
+ *   a zero-length `tool-call-delta` anyway).
+ * - {@link close} reconciles before the terminal part: if fragments streamed
+ *   incrementally, it emits any un-streamed tail of `finalArgs`; if the args
+ *   arrived atomically (some providers deliver the complete args only on the
+ *   terminal event, with no incremental deltas — e.g. the OpenAI Responses
+ *   `output_item.done`), it opens the span and streams the whole buffer as one
+ *   delta so the accumulator still matches. Either way the emitted deltas
+ *   concatenate to exactly `finalArgs`.
+ */
+export declare class ToolInputSpanLifecycle {
+    private readonly id;
+    private readonly toolName;
+    private readonly logBus?;
+    private started;
+    private streamed;
+    constructor(id: string, toolName: string, logBus?: LogBus | undefined);
+    /** Forward one raw argument fragment as a `tool-input-delta`, opening the span on first use. Empty fragments are dropped. */
+    delta(controller: {
+        enqueue: (part: LanguageModelV3StreamPart) => void;
+    }, fragment: string): void;
+    /**
+     * Reconcile the streamed deltas against the authoritative `finalArgs` (the
+     * exact string handed to the terminal `tool-call`) and close the span. Call
+     * immediately BEFORE emitting the terminal `tool-call`. No-op emission for a
+     * never-opened, empty-args span so a no-arg call stays span-free.
+     */
+    close(controller: {
+        enqueue: (part: LanguageModelV3StreamPart) => void;
+    }, finalArgs: string): void;
+}
 /**
  * Maps a Salesforce LLM Gateway raw finish-reason string (the gateway-normalized
  * vocabulary that spans GPT-5 and Claude — `stop`, `length`, `tool_calls`,

package/dist/v3-stream-mapping.js

@@ -81,6 +81,92 @@ export class TextSpanLifecycle {
         return `text-${this.id}`;
     }
 }
+/**
+ * Encodes the AI SDK V3 tool-input streaming lifecycle (`tool-input-start` /
+ * `tool-input-delta` / `tool-input-end`) that surfaces incremental tool-call
+ * argument fragments to consumers (W-23954558). One instance per tool call.
+ *
+ * These parts are emitted IN ADDITION TO — never instead of — the authoritative
+ * terminal `tool-call` part (built by {@link buildValidatedToolCallChunk}), in
+ * real wire order: `start → delta* → end → tool-call`.
+ *
+ * Load-bearing invariant: `@mastra/core`'s stream pipeline, once it sees a
+ * `tool-input-start`, derives the final tool call's `args` from the ACCUMULATED
+ * `tool-input-delta` fragments — NOT from the terminal `tool-call.input`. So the
+ * concatenation of the deltas this class emits MUST reproduce the argument
+ * string the terminal `tool-call` carries, or Mastra surfaces truncated/empty
+ * args. This class enforces that:
+ *
+ * - The span is opened LAZILY on the first non-empty fragment, so a genuinely
+ *   no-argument call (zero fragments) never opens a span and Mastra falls back
+ *   to the terminal `input` (`'{}'`). An empty fragment is dropped (Mastra drops
+ *   a zero-length `tool-call-delta` anyway).
+ * - {@link close} reconciles before the terminal part: if fragments streamed
+ *   incrementally, it emits any un-streamed tail of `finalArgs`; if the args
+ *   arrived atomically (some providers deliver the complete args only on the
+ *   terminal event, with no incremental deltas — e.g. the OpenAI Responses
+ *   `output_item.done`), it opens the span and streams the whole buffer as one
+ *   delta so the accumulator still matches. Either way the emitted deltas
+ *   concatenate to exactly `finalArgs`.
+ */
+export class ToolInputSpanLifecycle {
+    id;
+    toolName;
+    logBus;
+    started = false;
+    streamed = '';
+    constructor(id, toolName, logBus) {
+        this.id = id;
+        this.toolName = toolName;
+        this.logBus = logBus;
+    }
+    /** Forward one raw argument fragment as a `tool-input-delta`, opening the span on first use. Empty fragments are dropped. */
+    delta(controller, fragment) {
+        if (fragment.length === 0)
+            return;
+        if (!this.started) {
+            controller.enqueue({ type: 'tool-input-start', id: this.id, toolName: this.toolName });
+            this.started = true;
+        }
+        controller.enqueue({ type: 'tool-input-delta', id: this.id, delta: fragment });
+        this.streamed += fragment;
+    }
+    /**
+     * Reconcile the streamed deltas against the authoritative `finalArgs` (the
+     * exact string handed to the terminal `tool-call`) and close the span. Call
+     * immediately BEFORE emitting the terminal `tool-call`. No-op emission for a
+     * never-opened, empty-args span so a no-arg call stays span-free.
+     */
+    close(controller, finalArgs) {
+        if (!this.started) {
+            // Atomic-args case: the provider delivered the complete args only on the
+            // terminal event (no incremental fragments). Stream the whole buffer once
+            // so Mastra's accumulator reproduces the args. A truly empty buffer leaves
+            // the span unopened and Mastra uses the terminal `input`.
+            this.delta(controller, finalArgs);
+        }
+        else if (this.streamed !== finalArgs) {
+            if (finalArgs.startsWith(this.streamed)) {
+                // Incremental fragments under-covered the final buffer (e.g. a terminal
+                // event carried a more-complete `arguments` than the streamed deltas).
+                // Emit the un-streamed tail so the accumulator still equals `finalArgs`.
+                this.delta(controller, finalArgs.slice(this.streamed.length));
+            }
+            else {
+                // Genuine divergence: the streamed deltas are NOT a prefix of the terminal
+                // args (a provider that re-normalized the JSON on the terminal event). We
+                // can't un-emit, so the delta-derived args (Mastra accumulator, AG-UI
+                // TOOL_CALL_ARGS) will be wrong with no terminal ARGS to correct them.
+                // Real providers stream prefixes, so this is unreachable in practice —
+                // field a signal so a future provider quirk surfaces instead of silently
+                // corrupting args. Lengths only (args may carry PII).
+                this.logBus?.warn('Tool-call arg deltas diverged from the terminal args; streamed deltas do not reconstruct the full arguments downstream', { toolName: this.toolName, streamedLength: this.streamed.length, finalLength: finalArgs.length });
+            }
+        }
+        if (this.started)
+            controller.enqueue({ type: 'tool-input-end', id: this.id });
+    }
+}
 /**
  * Maps a Salesforce LLM Gateway raw finish-reason string (the gateway-normalized
  * vocabulary that spans GPT-5 and Claude — `stop`, `length`, `tool_calls`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.80.0",
+  "version": "0.82.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -42,12 +42,12 @@
     "openai": "^7.0.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.81.0"
+    "@salesforce/sfdx-agent-sdk": "0.83.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@salesforce/harness-conformance": "0.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.81.0",
+    "@salesforce/sfdx-agent-sdk": "0.83.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^4.1.11",
     "@vitest/eslint-plugin": "^1.6.27",