@salesforce/sfdx-agent-harness-mastra 0.71.0 → 0.72.0

package/CHANGELOG.md

@@ -3,6 +3,11 @@
 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.72.0] - 2026-09-04
+
+### Features
+- **agent-sdk,harness-claude,harness-mastra,harness-openai**: validate frontend tool-call args @W-24023028@ ([#789](https://github.com/forcedotcom/agentic-dx/pull/789))
+
 ## [0.71.0] - 2026-09-02
 
 _No changes — released alongside dependent packages._

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

@@ -31,7 +31,7 @@ import type { ChatEvent } from '@salesforce/sfdx-agent-sdk';
  * | `reasoning-delta`       | `reasoning-delta`         | `{ text }` from `payload.text`                         |
  * | `tool-call`             | `tool-call`               | `{ toolCallId, toolName, args }`                       |
  * | `tool-call-approval`    | `tool-approval-request`   | `{ toolCall: { toolCallId, toolName, args } }` — stream suspends |
- * | `tool-result`           | `tool-result`             | `{ toolCallId, toolName, result, isError: false }`     |
+ * | `tool-result`           | `tool-result`             | `{ toolCallId, toolName, result, isError }` from `payload.isError` (defaults to `false`) |
  * | `tool-error`            | `tool-result`             | `{ toolCallId, toolName, result: error, isError: true}`|
  * | `tool-output-denied`    | `tool-result`             | `{ toolCallId, toolName, result: reason, isError: true}`|
  * | `tool-output`           | `tool-progress`           | `{ toolCallId, toolName, output }`                     |

package/dist/mastra-event-adapter.js

@@ -3,6 +3,7 @@
  * See LICENSE.txt for license terms.
  */
 import { CONTEXT_LENGTH_EXCEEDED_CODE, createContextLengthExceededError } from '@salesforce/sfdx-agent-sdk';
+import { hasToolArgsValidationErrorMarker } from './tool-args-marker.js';
 import { isClassifiedStreamError } from './stream-errors.js';
 /**
  * Adapts Mastra `ChunkType` stream events to our {@link ChatEvent} discriminated union.
@@ -34,7 +35,7 @@ import { isClassifiedStreamError } from './stream-errors.js';
  * | `reasoning-delta`       | `reasoning-delta`         | `{ text }` from `payload.text`                         |
  * | `tool-call`             | `tool-call`               | `{ toolCallId, toolName, args }`                       |
  * | `tool-call-approval`    | `tool-approval-request`   | `{ toolCall: { toolCallId, toolName, args } }` — stream suspends |
- * | `tool-result`           | `tool-result`             | `{ toolCallId, toolName, result, isError: false }`     |
+ * | `tool-result`           | `tool-result`             | `{ toolCallId, toolName, result, isError }` from `payload.isError` (defaults to `false`) |
  * | `tool-error`            | `tool-result`             | `{ toolCallId, toolName, result: error, isError: true}`|
  * | `tool-output-denied`    | `tool-result`             | `{ toolCallId, toolName, result: reason, isError: true}`|
  * | `tool-output`           | `tool-progress`           | `{ toolCallId, toolName, output }`                     |
@@ -106,7 +107,16 @@ export class MastraEventAdapter {
                     toolCallId: chunk.payload.toolCallId,
                     toolName: chunk.payload.toolName,
                     result: chunk.payload.result,
-                    isError: false,
+                    // A gated (tool-args-validation) consumer tool-call surfaces its
+                    // `tool-call` + error `tool-result` on the LIVE stream just like an
+                    // MCP/built-in tool whose executor rejected bad args (W-24023028) —
+                    // the model already received the error, and the consumer observes
+                    // the failed activity. Mastra's live chunk can drop the `isError`
+                    // flag (its chunk-collection pipeline writes `state: 'result'`
+                    // regardless — the same reason the persisted read path recovers it),
+                    // so OR in the marker to keep the live event's `isError` honest.
+                    isError: (chunk.payload.isError ?? false) ||
+                        hasToolArgsValidationErrorMarker(chunk.payload.providerMetadata),
                 };
             case 'tool-error': {
                 const error = chunk.payload.error instanceof Error ? chunk.payload.error : new Error(String(chunk.payload.error));

package/dist/mastra-harness.d.ts

@@ -297,6 +297,28 @@ export declare class MastraHarness implements MastraAgentHarness {
     private readonly innerFetch;
     private readonly wireObserverAbortController;
     private readonly languageModelBuilders?;
+    /**
+     * Per-turn, per-thread consumer/frontend tool-args retry counters (S1,
+     * W-24023028): `agentId → threadId → (toolName → consecutive-failure count)`.
+     * The agent's `LanguageModel` is built once for its whole lifetime, so a
+     * counter owned by the language model would bleed across turns AND across
+     * concurrent threads; owning it here — the innermost map reset at each
+     * `stream()` (per-turn) and keyed by thread (per-thread) — matches Claude's
+     * per-`stream()` `toolArgFailureCounts` and OpenAI's per-turn
+     * `consumerToolArgsAttempts`, so the exhaustion-clause wording is identical
+     * across all three harnesses. Nested (rather than a `${agentId}::${threadId}`
+     * string key) so a consumer id containing the delimiter can't alias two
+     * distinct scopes, and cleanup is O(1): `destroyThread` deletes the thread
+     * entry, `destroyAgent` deletes the agent entry, `shutdown` clears all.
+     */
+    private readonly toolArgsRetryCounts;
+    /**
+     * Fallback counter for a `doStream` / `doGenerate` with no scope (e.g. the
+     * thread-less `compactThread` summarize, which has no consumer tools). One
+     * stable map — NOT a fresh map per resolve — so repeated same-named calls in
+     * one such request still accumulate rather than resetting to attempt 1.
+     */
+    private readonly unscopedToolArgsRetryCounts;
     constructor(storageRootFolder: string, opts?: MastraHarnessOptions);
     /**
      * @requirements
@@ -480,6 +502,17 @@ export declare class MastraHarness implements MastraAgentHarness {
      * via G8 before any harness work runs (`AgentSDKErrorType.MODEL_NOT_SUPPORTED_BY_HARNESS`),
      * so a hint not handled here is a programming error worth surfacing eagerly.
      */
+    /**
+     * Resolves the per-turn tool-args retry-counter map for a `doStream` /
+     * `doGenerate` call from its `options.providerOptions` scope (S1,
+     * W-24023028). `stream()` pre-seeds a fresh innermost map for the turn's
+     * `(agentId, threadId)` before `agent.stream`, so a resolve during the turn
+     * returns that map; a call with no scope (e.g. the thread-less
+     * `compactThread` summarize, which has no consumer tools) gets the single
+     * stable {@link unscopedToolArgsRetryCounts} map (never a fresh one per
+     * lookup, so repeated same-named calls still accumulate).
+     */
+    private resolveToolArgsRetryCounts;
     private buildLanguageModel;
     private destroyThreadBestEffort;
     /**

package/dist/mastra-harness.js

@@ -27,6 +27,7 @@ import { validateMultimodalFiles } from '@salesforce/sfdx-agent-sdk';
 import { buildAnthropicDirectLanguageModel, buildAnthropicLanguageModel } from './pass-through-anthropic.js';
 import { buildOpenAIChatCompletionsLanguageModel } from './pass-through-openai-chat-completions.js';
 import { buildOpenAILanguageModel } from './pass-through-openai.js';
+import { readToolArgsRetryScope, TOOL_ARGS_RETRY_SCOPE_AGENT_ID, TOOL_ARGS_RETRY_SCOPE_PROVIDER, TOOL_ARGS_RETRY_SCOPE_THREAD_ID, } from './v3-stream-mapping.js';
 import { ToolResultRedactionProcessor } from './mastra-tool-result-redaction-processor.js';
 import { backfillCreatedAt, buildSummaryPrompt, Clock, getErrorMessage, RealClock, splitFrontmatterAndBody, UUIDGenerator, } from '@salesforce/agentic-common';
 import { makeAbortable } from './utils.js';
@@ -468,6 +469,28 @@ export class MastraHarness {
     innerFetch;
     wireObserverAbortController = new AbortController();
     languageModelBuilders;
+    /**
+     * Per-turn, per-thread consumer/frontend tool-args retry counters (S1,
+     * W-24023028): `agentId → threadId → (toolName → consecutive-failure count)`.
+     * The agent's `LanguageModel` is built once for its whole lifetime, so a
+     * counter owned by the language model would bleed across turns AND across
+     * concurrent threads; owning it here — the innermost map reset at each
+     * `stream()` (per-turn) and keyed by thread (per-thread) — matches Claude's
+     * per-`stream()` `toolArgFailureCounts` and OpenAI's per-turn
+     * `consumerToolArgsAttempts`, so the exhaustion-clause wording is identical
+     * across all three harnesses. Nested (rather than a `${agentId}::${threadId}`
+     * string key) so a consumer id containing the delimiter can't alias two
+     * distinct scopes, and cleanup is O(1): `destroyThread` deletes the thread
+     * entry, `destroyAgent` deletes the agent entry, `shutdown` clears all.
+     */
+    toolArgsRetryCounts = new Map();
+    /**
+     * Fallback counter for a `doStream` / `doGenerate` with no scope (e.g. the
+     * thread-less `compactThread` summarize, which has no consumer tools). One
+     * stable map — NOT a fresh map per resolve — so repeated same-named calls in
+     * one such request still accumulate rather than resetting to attempt 1.
+     */
+    unscopedToolArgsRetryCounts = new Map();
     constructor(storageRootFolder, opts = {}) {
         this.storageRootFolder = storageRootFolder;
         this.clock = opts.clock ?? new RealClock();
@@ -530,6 +553,8 @@ export class MastraHarness {
         }));
         this.activeAgents.clear();
         this.modelConnectivityByAgent.clear();
+        this.toolArgsRetryCounts.clear();
+        this.unscopedToolArgsRetryCounts.clear();
         await this.mastra?.shutdown();
         this.buses.dispose();
     }
@@ -612,6 +637,7 @@ export class MastraHarness {
         // race the consumer-tool bridge call, so we resolve the coordinator
         // each time rather than capturing it once at agent-creation.
         const consumerToolNames = new Set((config.tools ?? []).map((t) => t.name));
+        const consumerToolSchemas = new Map((config.tools ?? []).map((t) => [t.name, t.inputSchema]));
         const parkerLookup = (threadId) => this.activeAgents.get(agentId)?.coordinators.get(threadId)?.parkConsumerToolCall;
         const customTools = config.tools?.length ? mapToolDefinitionsToMastraTools(config.tools, parkerLookup) : {};
         // Build the language model from the live ModelConnectivityInfo bag. The
@@ -628,7 +654,7 @@ export class MastraHarness {
             }
             return info;
         };
-        const resolvedModel = this.buildLanguageModel(getInfoForAgent);
+        const resolvedModel = this.buildLanguageModel(getInfoForAgent, () => consumerToolNames, () => consumerToolSchemas);
         const validateFiles = (files) => validateMultimodalFiles(files, getInfoForAgent().model);
         let mastraWorkspace;
         let agent;
@@ -800,6 +826,8 @@ export class MastraHarness {
         }));
         state.skillSearchProcessor?.dispose();
         await state.mastraWorkspace?.destroy();
+        // Drop every per-turn tool-args retry counter for this agent's threads (S1).
+        this.toolArgsRetryCounts.delete(agentId);
         // The store is separate from Mastra's thread rows, so it needs its own
         // teardown — remove every thread's stored context for this agent.
         await this.sessionContextStore.deleteAgent(agentId);
@@ -1107,6 +1135,7 @@ export class MastraHarness {
         }
         // ── Phase 2: non-MCP rebuild ──────────────────────────────────────
         const consumerToolNames = new Set((config.tools ?? []).map((t) => t.name));
+        const consumerToolSchemas = new Map((config.tools ?? []).map((t) => [t.name, t.inputSchema]));
         const parkerLookup = (threadId) => this.activeAgents.get(agentId)?.coordinators.get(threadId)?.parkConsumerToolCall;
         const customTools = config.tools?.length ? mapToolDefinitionsToMastraTools(config.tools, parkerLookup) : {};
         // Same shape as createAgent's getter — reads the live bag on every call so
@@ -1125,7 +1154,7 @@ export class MastraHarness {
         // `Agent` unconditionally on every `updateAgent` (instructions, tools,
         // processors all flow through), so we always rebuild the language model
         // here too. Allocation cost is negligible compared to the Agent rebuild.
-        const resolvedModel = this.buildLanguageModel(getInfoForAgent);
+        const resolvedModel = this.buildLanguageModel(getInfoForAgent, () => consumerToolNames, () => consumerToolSchemas);
         const validateFiles = (files) => validateMultimodalFiles(files, getInfoForAgent().model);
         // Capture the live mcpServers map by reference — the new Agent's
         // tools() closure will read it on every step, so preserved clients'
@@ -1271,6 +1300,7 @@ export class MastraHarness {
             coordinator.dispose();
             state.coordinators.delete(threadId);
         }
+        this.toolArgsRetryCounts.get(agentId)?.delete(threadId);
         const memory = await this.getMemoryOrThrow(agentId);
         await memory.deleteThread(threadId);
         // The store is separate from Mastra's thread row, so delete it too or a
@@ -1477,7 +1507,34 @@ export class MastraHarness {
      * via G8 before any harness work runs (`AgentSDKErrorType.MODEL_NOT_SUPPORTED_BY_HARNESS`),
      * so a hint not handled here is a programming error worth surfacing eagerly.
      */
-    buildLanguageModel(getInfo) {
+    /**
+     * Resolves the per-turn tool-args retry-counter map for a `doStream` /
+     * `doGenerate` call from its `options.providerOptions` scope (S1,
+     * W-24023028). `stream()` pre-seeds a fresh innermost map for the turn's
+     * `(agentId, threadId)` before `agent.stream`, so a resolve during the turn
+     * returns that map; a call with no scope (e.g. the thread-less
+     * `compactThread` summarize, which has no consumer tools) gets the single
+     * stable {@link unscopedToolArgsRetryCounts} map (never a fresh one per
+     * lookup, so repeated same-named calls still accumulate).
+     */
+    resolveToolArgsRetryCounts(options) {
+        const scope = readToolArgsRetryScope(options);
+        if (scope === undefined)
+            return this.unscopedToolArgsRetryCounts;
+        let byThread = this.toolArgsRetryCounts.get(scope.agentId);
+        if (!byThread) {
+            byThread = new Map();
+            this.toolArgsRetryCounts.set(scope.agentId, byThread);
+        }
+        let counts = byThread.get(scope.threadId);
+        if (!counts) {
+            counts = new Map();
+            byThread.set(scope.threadId, counts);
+        }
+        return counts;
+    }
+    buildLanguageModel(getInfo, getConsumerToolNames, getConsumerToolSchemas) {
+        const getToolArgsRetryCounts = (options) => this.resolveToolArgsRetryCounts(options);
         const initial = getInfo();
         const logBus = this.buses.getLogBus();
         // The fetch wrapper emits one WireCommunicationEvent pair per HTTP call. Forward
@@ -1507,17 +1564,44 @@ export class MastraHarness {
         switch (initial.providerHint) {
             case 'bedrock-anthropic':
                 // Salesforce LLM Gateway's `/invoke-with-response-stream` (Bedrock pass-through).
-                return buildAnthropicLanguageModel({ getInfo, logBus, wireHooks, innerFetch, idleReadTimeoutMs });
+                return buildAnthropicLanguageModel({
+                    getInfo,
+                    logBus,
+                    wireHooks,
+                    innerFetch,
+                    getConsumerToolNames,
+                    getConsumerToolSchemas,
+                    getToolArgsRetryCounts,
+                    idleReadTimeoutMs,
+                });
             case 'anthropic':
                 // Direct Anthropic Messages API (`api.anthropic.com/v1/messages`) —
                 // different wire shape (`x-api-key` auth, body without `anthropic_version`).
-                return buildAnthropicDirectLanguageModel({ getInfo, logBus, wireHooks, innerFetch, idleReadTimeoutMs });
+                return buildAnthropicDirectLanguageModel({
+                    getInfo,
+                    logBus,
+                    wireHooks,
+                    innerFetch,
+                    getConsumerToolNames,
+                    getConsumerToolSchemas,
+                    getToolArgsRetryCounts,
+                    idleReadTimeoutMs,
+                });
             case 'openai-responses':
             case 'openai':
                 // OpenAI Responses API. Salesforce LLM Gateway's `/responses` pass-through
                 // for `'openai-responses'`; `api.openai.com/v1/responses` for `'openai'` direct.
                 // Same wire shape; the only difference is the `baseUrl` the resolver supplies.
-                return buildOpenAILanguageModel({ getInfo, logBus, wireHooks, innerFetch, idleReadTimeoutMs });
+                return buildOpenAILanguageModel({
+                    getInfo,
+                    logBus,
+                    wireHooks,
+                    innerFetch,
+                    getConsumerToolNames,
+                    getConsumerToolSchemas,
+                    getToolArgsRetryCounts,
+                    idleReadTimeoutMs,
+                });
             case 'openai-compatible':
                 // OpenAI-compatible Chat Completions API (LLMG Express, LiteLLM, etc.).
                 // Different wire shape from Responses — `/v1/chat/completions` with
@@ -1527,6 +1611,9 @@ export class MastraHarness {
                     logBus,
                     wireHooks,
                     innerFetch,
+                    getConsumerToolNames,
+                    getConsumerToolSchemas,
+                    getToolArgsRetryCounts,
                     idleReadTimeoutMs,
                 });
             default: {
@@ -1688,6 +1775,17 @@ export class MastraHarness {
         // failing the turn rather than silently dropping context for it.
         const sessionContext = await this.sessionContextStore.read(agentId, threadId);
         const systemContext = renderSessionContextSystemText(sessionContext);
+        // S1 (W-24023028): reset this turn's consumer/frontend tool-args retry
+        // counter (a fresh innermost map for this thread) and stamp its scope so
+        // every `doStream` step of this one streamed run resolves the SAME
+        // per-turn, per-thread counter (the `LanguageModel` is agent-lifetime, so
+        // it cannot scope this itself).
+        let retryCountsByThread = this.toolArgsRetryCounts.get(agentId);
+        if (!retryCountsByThread) {
+            retryCountsByThread = new Map();
+            this.toolArgsRetryCounts.set(agentId, retryCountsByThread);
+        }
+        retryCountsByThread.set(threadId, new Map());
         const output = await agentState.agent.stream(streamInput, {
             memory: {
                 thread: threadId,
@@ -1696,6 +1794,12 @@ export class MastraHarness {
             requestContext: this.buildRequestContext(agentId, threadId),
             maxSteps: options?.maxSteps ?? DEFAULT_MAX_STEPS,
             abortSignal: options?.abortSignal,
+            providerOptions: {
+                [TOOL_ARGS_RETRY_SCOPE_PROVIDER]: {
+                    [TOOL_ARGS_RETRY_SCOPE_AGENT_ID]: agentId,
+                    [TOOL_ARGS_RETRY_SCOPE_THREAD_ID]: threadId,
+                },
+            },
             ...(systemContext.length > 0 ? { system: systemContext } : {}),
             // Pass `requireToolApproval: true` to Mastra iff the gate is active
             // so Mastra suspends every non-consumer tool with a

package/dist/mastra-message-mapper.js

@@ -2,6 +2,7 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
+import { hasToolArgsValidationErrorMarker } from './tool-args-marker.js';
 /**
  * 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.
@@ -166,9 +167,21 @@ export function mapMastraPartToMessagePart(part, logBus) {
             // that shape itself; it's an accepted edge of accepting arbitrary
             // caller-supplied history.
             if (inv.state === 'result') {
+                // A gated consumer-tool call (W-24023028) is persisted by Mastra's own
+                // live-stream pipeline as a plain `state: 'result'` invocation — Mastra
+                // drops the stream chunk's `isError` flag before it ever reaches storage
+                // (see `hasToolArgsValidationErrorMarker`'s doc comment). Recover it from
+                // the marker `buildValidatedToolCallChunk` stamps in `providerMetadata`.
+                const isError = hasToolArgsValidationErrorMarker(part.providerMetadata);
                 return [
                     toolCall,
-                    { type: 'tool-result', toolCallId: inv.toolCallId, toolName: inv.toolName, result: inv.result },
+                    {
+                        type: 'tool-result',
+                        toolCallId: inv.toolCallId,
+                        toolName: inv.toolName,
+                        result: inv.result,
+                        ...(isError ? { isError: true } : {}),
+                    },
                 ];
             }
             if (inv.state === 'output-error' || inv.state === 'output-denied') {

package/dist/mastra-tool-mapper.js

@@ -3,6 +3,7 @@
  * See LICENSE.txt for license terms.
  */
 import { MASTRA_THREAD_ID_KEY } from '@mastra/core/request-context';
+import { toStandardSchema } from '@mastra/schema-compat';
 /**
  * Converts SDK {@link ToolDefinition} objects into Mastra-compatible
  * {@link ToolAction} entries.
@@ -37,7 +38,27 @@ export function mapToolDefinitionsToMastraTools(tools, parkerLookup) {
         const mastraTool = {
             id: tool.name,
             description: tool.description ?? '',
-            inputSchema: ensureJsonSchemaMarker(tool.inputSchema),
+            // Register the consumer's declared JSON Schema as a Standard Schema
+            // (`toStandardSchema`) rather than a bare JSON object (W-24023028).
+            // A bare object is neither a Zod type nor a StandardSchemaWithJSON, so
+            // Mastra's `CoreToolBuilder` sends it through
+            // `applyCompatLayer(mode:'aiSdkSchema')` — a JSON→Zod→AI-SDK round-trip
+            // (`convertSchemaToZod`) that SILENTLY DROPS `additionalProperties:true`
+            // and strictifies every nested object (proven: a valid `show_widget`
+            // Mosaic tree failed the gate with "must NOT have additional
+            // properties"). A StandardSchemaWithJSON instead takes the builder's
+            // preserving branch (`jsonSchema(standardSchemaToJSONSchema(...))`), so
+            // the declared schema — `additionalProperties` and all — reaches the
+            // wire `input_schema` (what the model sees), `options.tools` (what the
+            // args-gate validates against), and AI-SDK arg parsing intact.
+            inputSchema: toStandardSchema(ensureJsonSchemaMarker(tool.inputSchema)),
+            // `strict: false` keeps a provider compat-layer (OpenAI/Anthropic
+            // strict-mode) from RE-degrading the preserved schema on the way to the
+            // wire — arbitrary consumer schemas aren't structured-output schemas
+            // (the OpenAI harness sets `strict: false` on consumer tools for the
+            // same reason). Without it, `CoreToolBuilder.build` applies a matching
+            // compat layer that reintroduces `additionalProperties:false`.
+            strict: false,
             // Issue #529 step 2c (Path A) — consumer tools bypass the
             // approval gate by construction. With `requireApproval: false`,
             // Mastra parks the agentic run on the parker Promise without

package/dist/pass-through-anthropic.d.ts

@@ -29,6 +29,44 @@ export declare function buildAnthropicLanguageModel(opts: {
      * don't need to thread it.
      */
     innerFetch?: typeof fetch;
+    /**
+     * Getter for the names of the agent's consumer/frontend tools
+     * (W-24023028), invoked on every tool-call emission. This is NOT the
+     * `getInfo`-style live getter that reads mutating agent state — freshness
+     * across `updateAgentConfig` comes from the harness REBUILDING the whole
+     * language model (a new closure) when tools change; the getter captures a
+     * per-config snapshot, so re-reading it per call only matters within the
+     * lifetime of one built model (it costs nothing and keeps the call sites
+     * uniform with the true live getters). Defaults to an empty set (no arg
+     * validation) for callers that don't thread it (e.g. tests exercising this
+     * builder in isolation).
+     */
+    getConsumerToolNames?: () => ReadonlySet<string>;
+    /**
+     * Getter for the consumer/frontend tools' PRISTINE declared `inputSchema`
+     * map (bare tool name → schema, from `AgentConfig.tools`). The args-gate
+     * validates against THIS rather than `options.tools[].inputSchema` — Mastra's
+     * tool-prep re-serializes the latter (`toStandardSchema` →
+     * `standardSchemaToJSONSchema`), which injects `additionalProperties: false`
+     * onto any object node that declared none (JSON Schema's default is open).
+     * Gating against that closed schema would reject extra keys on an
+     * implicitly-open nested object and diverge from Claude/OpenAI (which gate
+     * the pristine declared schema); validating the declared schema keeps the
+     * gate verdict identical across all three harnesses (W-24023028). Same
+     * per-config-snapshot freshness caveat as `getConsumerToolNames`. Defaults to
+     * an empty map (no schema → the gate treats every consumer tool as
+     * unvalidatable-`ok`) for callers that don't thread it.
+     */
+    getConsumerToolSchemas?: () => ReadonlyMap<string, Record<string, unknown>>;
+    /**
+     * Resolver for the per-turn, per-thread tool-args retry-counter map (S1,
+     * W-24023028). Read fresh per `doStream` / `doGenerate` from that call's
+     * `options.providerOptions` scope key, so the counter resets per turn and is
+     * isolated per thread rather than accumulating for the whole agent-lifetime
+     * `LanguageModel`. Defaults to a single per-instance map for callers that
+     * don't thread it (tests / consumer-injected builders).
+     */
+    getToolArgsRetryCounts?: (options: LanguageModelV3CallOptions) => Map<string, number>;
     /** Per-read idle timeout (ms) for the gateway response body; see `createGatewayFetch`. */
     idleReadTimeoutMs?: number;
 }): LanguageModelV3;
@@ -58,6 +96,12 @@ export declare function buildAnthropicDirectLanguageModel(opts: {
     wireHooks?: GatewayFetchWireHooks;
     /** See {@link buildAnthropicLanguageModel} `innerFetch`. */
     innerFetch?: typeof fetch;
+    /** See {@link buildAnthropicLanguageModel} `getConsumerToolNames`. */
+    getConsumerToolNames?: () => ReadonlySet<string>;
+    /** See {@link buildAnthropicLanguageModel} `getConsumerToolSchemas`. */
+    getConsumerToolSchemas?: () => ReadonlyMap<string, Record<string, unknown>>;
+    /** See {@link buildAnthropicLanguageModel} `getToolArgsRetryCounts`. */
+    getToolArgsRetryCounts?: (options: LanguageModelV3CallOptions) => Map<string, number>;
     /** Per-read idle timeout (ms) for the gateway response body; see `createGatewayFetch`. */
     idleReadTimeoutMs?: number;
 }): LanguageModelV3;

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, createGatewayFetch, isEmptyUsage, isParameterExcluded, mapAnthropicFinishReason, mapAnthropicUsage, normalizeToolArgsString, toolResultOutputToString, } from './v3-stream-mapping.js';
+import { TextSpanLifecycle, 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.
@@ -21,13 +21,17 @@ import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, isParameterExclude
  * the next request.
  */
 export function buildAnthropicLanguageModel(opts) {
-    const { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch, idleReadTimeoutMs } = opts;
+    const { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch, getConsumerToolNames, getConsumerToolSchemas, getToolArgsRetryCounts, idleReadTimeoutMs, } = opts;
     const initialInfo = getInfo();
+    const fallbackRetryCounts = new Map();
     const ctx = {
         getInfo,
         logBus,
         emitWireCommunication,
         wireHooks,
+        getConsumerToolNames: getConsumerToolNames ?? (() => EMPTY_TOOL_NAMES),
+        getConsumerToolSchemas: getConsumerToolSchemas ?? (() => EMPTY_TOOL_SCHEMAS),
+        getToolArgsRetryCounts: getToolArgsRetryCounts ?? (() => fallbackRetryCounts),
         buildClient: (info) => new AnthropicBedrock({
             baseURL: info.baseUrl,
             skipAuth: true,
@@ -70,13 +74,17 @@ export function buildAnthropicLanguageModel(opts) {
  * language model.
  */
 export function buildAnthropicDirectLanguageModel(opts) {
-    const { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch, idleReadTimeoutMs } = opts;
+    const { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch, getConsumerToolNames, getConsumerToolSchemas, getToolArgsRetryCounts, idleReadTimeoutMs, } = opts;
     const initialInfo = getInfo();
+    const fallbackRetryCounts = new Map();
     const ctx = {
         getInfo,
         logBus,
         emitWireCommunication,
         wireHooks,
+        getConsumerToolNames: getConsumerToolNames ?? (() => EMPTY_TOOL_NAMES),
+        getConsumerToolSchemas: getConsumerToolSchemas ?? (() => EMPTY_TOOL_SCHEMAS),
+        getToolArgsRetryCounts: getToolArgsRetryCounts ?? (() => fallbackRetryCounts),
         buildClient: (info) => 
         // Anthropic SDK constructor takes `apiKey` and writes `x-api-key` itself.
         // We use a non-empty placeholder here because the SDK requires `apiKey`
@@ -121,6 +129,8 @@ async function translateBearerToXApiKey(info) {
     }
     return out;
 }
+const EMPTY_TOOL_NAMES = new Set();
+const EMPTY_TOOL_SCHEMAS = new Map();
 /**
  * Builds the optional `wireHooks` arg for `createGatewayFetch` — only set when
  * the harness has wired a `WireCommunicationEvent` callback. Reads the model id
@@ -144,6 +154,7 @@ async function buildAnthropicRequest(ctx, options) {
     const client = ctx.buildClient(info);
     const { system, messages } = translatePromptToAnthropic(options.prompt);
     const tools = translateToolsToAnthropic(options);
+    const toolSchemas = ctx.getConsumerToolSchemas();
     const commonParams = {
         model: info.nativeModelId,
         // Precedence: an explicit per-request `maxOutputTokens` wins; otherwise
@@ -166,10 +177,10 @@ async function buildAnthropicRequest(ctx, options) {
     }
     if (options.stopSequences !== undefined)
         commonParams.stop_sequences = [...options.stopSequences];
-    return { client, commonParams };
+    return { client, commonParams, toolSchemas };
 }
 async function doGenerate(ctx, options) {
-    const { client, commonParams } = await buildAnthropicRequest(ctx, options);
+    const { client, commonParams, toolSchemas } = await buildAnthropicRequest(ctx, options);
     // Forward the turn's AbortSignal into the SDK's RequestOptions so firing the
     // controller (POST /cancel, idle timeout, shutdown abortAll) actually aborts
     // the outbound gateway fetch, not just harness bookkeeping (W-23988781).
@@ -189,12 +200,8 @@ async function doGenerate(ctx, options) {
         }
         else if (block.type === 'tool_use') {
             sawToolCalls = true;
-            content.push({
-                type: 'tool-call',
-                toolCallId: block.id,
-                toolName: block.name,
-                input: typeof block.input === 'string' ? block.input : JSON.stringify(block.input ?? {}),
-            });
+            const argsBuffer = typeof block.input === 'string' ? block.input : JSON.stringify(block.input ?? {});
+            content.push(...buildValidatedToolCallChunk(block.id, block.name, argsBuffer, toolSchemas.get(block.name), ctx.getConsumerToolNames().has(block.name), { retryCounts: ctx.getToolArgsRetryCounts(options), logBus: ctx.logBus }));
         }
         // Other block types (thinking, server-tool-result, etc.) are not in
         // the V3 ChatEvent surface — same posture as doStream.
@@ -210,7 +217,7 @@ async function doGenerate(ctx, options) {
     return { content, finishReason, usage, warnings: [] };
 }
 async function doStream(ctx, options) {
-    const { client, commonParams } = await buildAnthropicRequest(ctx, options);
+    const { client, commonParams, toolSchemas } = await buildAnthropicRequest(ctx, options);
     // See doGenerate: thread the AbortSignal into the SDK so a mid-stream abort
     // tears down the live gateway socket (W-23988781).
     let sdkStream;
@@ -313,14 +320,9 @@ async function doStream(ctx, options) {
                             if (tu) {
                                 sawToolCalls = true;
                                 sawContentOrUsage = true;
-                                controller.enqueue({
-                                    type: 'tool-call',
-                                    toolCallId: tu.id,
-                                    toolName: tu.name,
-                                    // No-arg tool → empty argsBuffer; normalize to '{}'.
-                                    // See normalizeToolArgsString (W-23789221).
-                                    input: normalizeToolArgsString(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);
+                                }
                                 toolUseByIndex.delete(event.index);
                             }
                             break;

package/dist/pass-through-openai-chat-completions.d.ts

@@ -30,6 +30,12 @@ export declare function buildOpenAIChatCompletionsLanguageModel(opts: {
     wireHooks?: GatewayFetchWireHooks;
     /** See `buildAnthropicLanguageModel` `innerFetch`. */
     innerFetch?: typeof fetch;
+    /** See `buildAnthropicLanguageModel` `getConsumerToolNames`. */
+    getConsumerToolNames?: () => ReadonlySet<string>;
+    /** See `buildAnthropicLanguageModel` `getConsumerToolSchemas`. */
+    getConsumerToolSchemas?: () => ReadonlyMap<string, Record<string, unknown>>;
+    /** See `buildAnthropicLanguageModel` `getToolArgsRetryCounts`. */
+    getToolArgsRetryCounts?: (options: LanguageModelV3CallOptions) => Map<string, number>;
     /** Per-read idle timeout (ms) for the gateway response body; see `createGatewayFetch`. */
     idleReadTimeoutMs?: number;
 }): LanguageModelV3;

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

@@ -4,7 +4,7 @@
  */
 import OpenAI from 'openai';
 import { EmptyStreamError } from './stream-errors.js';
-import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, isParameterExcluded, mapOpenAIUsage, normalizeToolArgsString, toolResultOutputToString, } from './v3-stream-mapping.js';
+import { TextSpanLifecycle, 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
@@ -26,9 +26,20 @@ import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, isParameterExclude
  * without rebuilding the language model.
  */
 export function buildOpenAIChatCompletionsLanguageModel(opts) {
-    const { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch, idleReadTimeoutMs } = opts;
+    const { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch, getConsumerToolNames, getConsumerToolSchemas, getToolArgsRetryCounts, idleReadTimeoutMs, } = opts;
     const initialInfo = getInfo();
-    const ctx = { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch, idleReadTimeoutMs };
+    const fallbackRetryCounts = new Map();
+    const ctx = {
+        getInfo,
+        logBus,
+        emitWireCommunication,
+        wireHooks,
+        innerFetch,
+        getConsumerToolNames: getConsumerToolNames ?? (() => EMPTY_TOOL_NAMES),
+        getConsumerToolSchemas: getConsumerToolSchemas ?? (() => EMPTY_TOOL_SCHEMAS),
+        getToolArgsRetryCounts: getToolArgsRetryCounts ?? (() => fallbackRetryCounts),
+        idleReadTimeoutMs,
+    };
     return {
         specificationVersion: 'v3',
         provider: 'openai-compatible-chat-completions-pass-through',
@@ -38,6 +49,8 @@ export function buildOpenAIChatCompletionsLanguageModel(opts) {
         doStream: (options) => doStream(ctx, options),
     };
 }
+const EMPTY_TOOL_NAMES = new Set();
+const EMPTY_TOOL_SCHEMAS = new Map();
 /**
  * Reads the live `ModelConnectivityInfo`, builds an `OpenAI` client pointed at
  * the OpenAI-compatible endpoint, and constructs the request body shape both
@@ -60,6 +73,7 @@ async function buildRequest(ctx, options) {
     });
     const messages = translatePromptToChatCompletions(options.prompt);
     const tools = translateToolsToChatCompletions(options);
+    const toolSchemas = ctx.getConsumerToolSchemas();
     const commonParams = {
         model: info.nativeModelId,
         messages,
@@ -74,10 +88,10 @@ async function buildRequest(ctx, options) {
             ? { stop: [...options.stopSequences] }
             : {}),
     };
-    return { client, commonParams };
+    return { client, commonParams, toolSchemas };
 }
 async function doGenerate(ctx, options) {
-    const { client, commonParams } = await buildRequest(ctx, options);
+    const { client, commonParams, toolSchemas } = await buildRequest(ctx, options);
     const params = { ...commonParams };
     // Forward the turn's AbortSignal into the SDK's RequestOptions so firing the
     // controller (POST /cancel, idle timeout, shutdown abortAll) actually aborts
@@ -94,13 +108,7 @@ async function doGenerate(ctx, options) {
             if (tc.type !== 'function')
                 continue;
             sawToolCalls = true;
-            content.push({
-                type: 'tool-call',
-                toolCallId: tc.id,
-                toolName: tc.function.name,
-                // No-arg tool → empty arguments; normalize to '{}' (W-23789221).
-                input: normalizeToolArgsString(tc.function.arguments),
-            });
+            content.push(...buildValidatedToolCallChunk(tc.id, tc.function.name, tc.function.arguments, toolSchemas.get(tc.function.name), ctx.getConsumerToolNames().has(tc.function.name), { retryCounts: ctx.getToolArgsRetryCounts(options), logBus: ctx.logBus }));
         }
     }
     const finishReason = mapChatCompletionFinishReason(choice?.finish_reason ?? null, sawToolCalls);
@@ -114,7 +122,7 @@ async function doGenerate(ctx, options) {
     return { content, finishReason, usage, warnings: [] };
 }
 async function doStream(ctx, options) {
-    const { client, commonParams } = await buildRequest(ctx, options);
+    const { client, commonParams, toolSchemas } = await buildRequest(ctx, options);
     const params = {
         ...commonParams,
         stream: true,
@@ -224,13 +232,9 @@ async function doStream(ctx, options) {
                                 continue;
                             }
                             sawToolCalls = true;
-                            controller.enqueue({
-                                type: 'tool-call',
-                                toolCallId: acc.id,
-                                toolName: acc.name,
-                                // No-arg tool → empty argsBuffer; normalize to '{}' (W-23789221).
-                                input: normalizeToolArgsString(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);
+                            }
                         }
                         toolCallsByIndex.clear();
                     }

package/dist/pass-through-openai.d.ts

@@ -22,6 +22,12 @@ export declare function buildOpenAILanguageModel(opts: {
     wireHooks?: GatewayFetchWireHooks;
     /** See `buildAnthropicLanguageModel` `innerFetch`. */
     innerFetch?: typeof fetch;
+    /** See `buildAnthropicLanguageModel` `getConsumerToolNames`. */
+    getConsumerToolNames?: () => ReadonlySet<string>;
+    /** See `buildAnthropicLanguageModel` `getConsumerToolSchemas`. */
+    getConsumerToolSchemas?: () => ReadonlyMap<string, Record<string, unknown>>;
+    /** See `buildAnthropicLanguageModel` `getToolArgsRetryCounts`. */
+    getToolArgsRetryCounts?: (options: LanguageModelV3CallOptions) => Map<string, number>;
     /** Per-read idle timeout (ms) for the gateway response body; see `createGatewayFetch`. */
     idleReadTimeoutMs?: number;
 }): LanguageModelV3;

package/dist/pass-through-openai.js

@@ -4,7 +4,7 @@
  */
 import OpenAI from 'openai';
 import { EmptyStreamError, GatewayResponseError } from './stream-errors.js';
-import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, isParameterExcluded, mapOpenAIFinishReason, mapOpenAIUsage, normalizeToolArgsString, toolResultOutputToString, } from './v3-stream-mapping.js';
+import { TextSpanLifecycle, 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
@@ -18,9 +18,20 @@ import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, isParameterExclude
  * next request.
  */
 export function buildOpenAILanguageModel(opts) {
-    const { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch, idleReadTimeoutMs } = opts;
+    const { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch, getConsumerToolNames, getConsumerToolSchemas, getToolArgsRetryCounts, idleReadTimeoutMs, } = opts;
     const initialInfo = getInfo();
-    const ctx = { getInfo, logBus, emitWireCommunication, wireHooks, innerFetch, idleReadTimeoutMs };
+    const fallbackRetryCounts = new Map();
+    const ctx = {
+        getInfo,
+        logBus,
+        emitWireCommunication,
+        wireHooks,
+        innerFetch,
+        getConsumerToolNames: getConsumerToolNames ?? (() => EMPTY_TOOL_NAMES),
+        getConsumerToolSchemas: getConsumerToolSchemas ?? (() => EMPTY_TOOL_SCHEMAS),
+        getToolArgsRetryCounts: getToolArgsRetryCounts ?? (() => fallbackRetryCounts),
+        idleReadTimeoutMs,
+    };
     return {
         specificationVersion: 'v3',
         provider: 'salesforce-llm-gateway-pass-through-openai',
@@ -33,6 +44,8 @@ export function buildOpenAILanguageModel(opts) {
         doStream: (options) => doStream(ctx, options),
     };
 }
+const EMPTY_TOOL_NAMES = new Set();
+const EMPTY_TOOL_SCHEMAS = new Map();
 /**
  * Reads the live `ModelConnectivityInfo`, builds an `OpenAI` client pointed at
  * the gateway, and constructs the request body shape both `doStream` and
@@ -60,6 +73,7 @@ async function buildOpenAIRequest(ctx, options) {
     });
     const { input, instructions } = translatePromptToOpenAI(options.prompt);
     const tools = translateToolsToOpenAI(options);
+    const toolSchemas = ctx.getConsumerToolSchemas();
     const commonParams = {
         model: info.nativeModelId,
         input,
@@ -72,10 +86,10 @@ async function buildOpenAIRequest(ctx, options) {
             : {}),
         ...(options.maxOutputTokens !== undefined ? { max_output_tokens: options.maxOutputTokens } : {}),
     };
-    return { client, commonParams };
+    return { client, commonParams, toolSchemas };
 }
 async function doGenerate(ctx, options) {
-    const { client, commonParams } = await buildOpenAIRequest(ctx, options);
+    const { client, commonParams, toolSchemas } = await buildOpenAIRequest(ctx, options);
     const params = { ...commonParams };
     // Forward the turn's AbortSignal into the SDK's RequestOptions so firing the
     // controller (POST /cancel, idle timeout, shutdown abortAll) actually aborts
@@ -89,13 +103,7 @@ async function doGenerate(ctx, options) {
     for (const item of response.output) {
         if (item.type === 'function_call') {
             sawToolCalls = true;
-            content.push({
-                type: 'tool-call',
-                toolCallId: item.call_id,
-                toolName: item.name,
-                // No-arg tool → empty arguments; normalize to '{}' (W-23789221).
-                input: normalizeToolArgsString(item.arguments),
-            });
+            content.push(...buildValidatedToolCallChunk(item.call_id, item.name, item.arguments, toolSchemas.get(item.name), ctx.getConsumerToolNames().has(item.name), { retryCounts: ctx.getToolArgsRetryCounts(options), logBus: ctx.logBus }));
         }
         // Other output-item variants (reasoning, web/file/code search, MCP) are
         // not in the V3 ChatEvent surface — same posture as doStream.
@@ -105,7 +113,7 @@ async function doGenerate(ctx, options) {
     return { content, finishReason, usage, warnings: [] };
 }
 async function doStream(ctx, options) {
-    const { client, commonParams } = await buildOpenAIRequest(ctx, options);
+    const { client, commonParams, toolSchemas } = await buildOpenAIRequest(ctx, options);
     const params = { ...commonParams, stream: true };
     // See doGenerate: thread the AbortSignal into the SDK so a mid-stream abort
     // tears down the live gateway socket (W-23988781).
@@ -161,13 +169,9 @@ async function doStream(ctx, options) {
                                 const finalArgs = item.arguments ?? tc?.argsBuffer ?? '';
                                 sawToolCalls = true;
                                 sawContent = true;
-                                controller.enqueue({
-                                    type: 'tool-call',
-                                    toolCallId: item.call_id,
-                                    toolName: item.name,
-                                    // No-arg tool → empty finalArgs; normalize to '{}' (W-23789221).
-                                    input: normalizeToolArgsString(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);
+                                }
                                 if (item.id)
                                     toolCallById.delete(item.id);
                                 toolCallById.delete(item.call_id);

package/dist/tool-args-marker.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Marker the tool-args-validation gate (W-24023028) stamps on the synthetic
+ * error `tool-result` part it emits for a gated (malformed / schema-violating)
+ * consumer/frontend tool call. It rides on the AI-SDK `providerMetadata`
+ * channel because that is one of the few fields Mastra's own chunk-collection /
+ * persistence pipeline carries through onto both the live stream chunk
+ * (`ToolResultPayload`) AND the persisted `tool-invocation` part. Its SOLE job
+ * is to recover the `tool-result`'s `isError` flag — `buildMessagesFromChunks`
+ * unconditionally persists `state: 'result'` and drops `isError`, and the live
+ * chunk shape has no isError field either, so the read mapper
+ * (`mastra-message-mapper.ts`) and the event adapter (`mastra-event-adapter.ts`)
+ * OR this marker into `isError` on the persisted read and the live event
+ * respectively. (An earlier S4 design ALSO used it to suppress the
+ * consumer-visible `tool-call` ChatEvent; that suppression was removed —
+ * gated calls now surface a live `tool-call` + error `tool-result` on all three
+ * harnesses — so the marker no longer gates any event emission.)
+ *
+ * Single-sourced here so the writer (`v3-stream-mapping.ts`), the read mapper
+ * (`mastra-message-mapper.ts`), and the event adapter (`mastra-event-adapter.ts`)
+ * can never drift on the metadata key.
+ */
+export declare const TOOL_ARGS_VALIDATION_ERROR_METADATA: {
+    readonly salesforce: {
+        readonly toolArgsValidationError: true;
+    };
+};
+/** True iff `providerMetadata` carries the {@link TOOL_ARGS_VALIDATION_ERROR_METADATA} marker. */
+export declare function hasToolArgsValidationErrorMarker(providerMetadata: unknown): boolean;

package/dist/tool-args-marker.js

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * Marker the tool-args-validation gate (W-24023028) stamps on the synthetic
+ * error `tool-result` part it emits for a gated (malformed / schema-violating)
+ * consumer/frontend tool call. It rides on the AI-SDK `providerMetadata`
+ * channel because that is one of the few fields Mastra's own chunk-collection /
+ * persistence pipeline carries through onto both the live stream chunk
+ * (`ToolResultPayload`) AND the persisted `tool-invocation` part. Its SOLE job
+ * is to recover the `tool-result`'s `isError` flag — `buildMessagesFromChunks`
+ * unconditionally persists `state: 'result'` and drops `isError`, and the live
+ * chunk shape has no isError field either, so the read mapper
+ * (`mastra-message-mapper.ts`) and the event adapter (`mastra-event-adapter.ts`)
+ * OR this marker into `isError` on the persisted read and the live event
+ * respectively. (An earlier S4 design ALSO used it to suppress the
+ * consumer-visible `tool-call` ChatEvent; that suppression was removed —
+ * gated calls now surface a live `tool-call` + error `tool-result` on all three
+ * harnesses — so the marker no longer gates any event emission.)
+ *
+ * Single-sourced here so the writer (`v3-stream-mapping.ts`), the read mapper
+ * (`mastra-message-mapper.ts`), and the event adapter (`mastra-event-adapter.ts`)
+ * can never drift on the metadata key.
+ */
+export const TOOL_ARGS_VALIDATION_ERROR_METADATA = {
+    salesforce: { toolArgsValidationError: true },
+};
+/** True iff `providerMetadata` carries the {@link TOOL_ARGS_VALIDATION_ERROR_METADATA} marker. */
+export function hasToolArgsValidationErrorMarker(providerMetadata) {
+    if (typeof providerMetadata !== 'object' || providerMetadata === null)
+        return false;
+    const salesforce = providerMetadata['salesforce'];
+    if (typeof salesforce !== 'object' || salesforce === null)
+        return false;
+    return salesforce['toolArgsValidationError'] === true;
+}
+//# sourceMappingURL=tool-args-marker.js.map

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

@@ -1,4 +1,4 @@
-import type { LanguageModelV3FinishReason, LanguageModelV3StreamPart, LanguageModelV3ToolResultOutput, LanguageModelV3Usage } from '@ai-sdk/provider';
+import type { LanguageModelV3CallOptions, LanguageModelV3FinishReason, LanguageModelV3StreamPart, LanguageModelV3ToolCall, LanguageModelV3ToolResult, LanguageModelV3ToolResultOutput, LanguageModelV3Usage } from '@ai-sdk/provider';
 import { type Clock, type LogBus, type UniqueIDGenerator } from '@salesforce/agentic-common';
 import type { Model } from '@salesforce/sfdx-agent-sdk';
 /**
@@ -288,33 +288,73 @@ type WireCommunicationLikeEvent = {
  */
 export declare function toolResultOutputToString(output: LanguageModelV3ToolResultOutput): string;
 /**
- * Normalize a streamed/returned tool-call arguments STRING to a
- * schema-conforming stringified JSON object.
- *
- * A no-argument tool (input schema `{ type:'object', properties:{} }`) accrues
- * no argument fragments on the wire — Anthropic streams no `input_json_delta`,
- * the OpenAI Responses/Chat-Completions APIs send no arg deltas — so the
- * accumulated buffer is the empty string `''`. `''` is NOT a schema-conforming
- * stringified JSON object: a strict consumer (Mastra `secureJsonParse`, any
- * `JSON.parse`) throws "the provided JSON could not be parsed" and the model
- * retries, producing the empty-args retry loop (W-23789221; same class as the
- * closed gateway-processor defect W-22696051). `'{}'` is the only valid no-arg
- * value.
+ * Provider-options namespace + keys the harness uses to carry the per-turn
+ * tool-args retry-counter scope down to a pass-through's `doStream` /
+ * `doGenerate` (S1, W-24023028). The Mastra `LanguageModel` is built once per
+ * agent (agent-lifetime), and each `doStream` is one internal model STEP — not
+ * a turn — so the pass-through cannot know the turn/thread on its own. The
+ * harness stamps the agent id + thread id onto `agent.stream({ providerOptions })`;
+ * AI-SDK forwards `providerOptions` to `LanguageModelV3CallOptions.providerOptions`
+ * UNCHANGED across every step of that one streamed run (verified empirically), so
+ * the pass-through reads them here to resolve a per-turn, per-thread counter
+ * instead of an agent-lifetime one. They ride as TWO discrete fields (not one
+ * concatenated string) so a consumer id containing the delimiter can't alias two
+ * distinct `(agentId, threadId)` scopes. The `salesforce` namespace is our
+ * pass-through's own provider slot; it is never forwarded onto the upstream
+ * request body (the pass-through builds the wire params from `options.prompt` /
+ * `tools`, not `providerOptions`).
+ */
+export declare const TOOL_ARGS_RETRY_SCOPE_PROVIDER = "salesforce";
+export declare const TOOL_ARGS_RETRY_SCOPE_AGENT_ID = "toolArgsRetryAgentId";
+export declare const TOOL_ARGS_RETRY_SCOPE_THREAD_ID = "toolArgsRetryThreadId";
+/** The per-turn retry-counter scope (agent + thread) stamped by the harness, if present. */
+export declare function readToolArgsRetryScope(options: LanguageModelV3CallOptions): {
+    agentId: string;
+    threadId: string;
+} | undefined;
+/**
+ * Builds the `LanguageModelV3StreamPart`(s) for one tool-call emission site
+ * (W-24023028), replacing the bare `normalizeToolArgsString` seam.
  *
- * Empty (including whitespace-only) → `'{}'`. Every non-empty buffer — even a
- * malformed partial like `'{"q":'` — is returned VERBATIM: we never re-parse or
- * re-stringify real content, so a genuinely bad payload still reaches the
- * consumer and is still rejected. Applied at every provider's tool-call
- * emission seam so the rule lives in one auditable place.
+ * - Not a consumer/frontend tool (MCP, built-in) → returns the single
+ *   `tool-call` part, byte-for-byte the same shape `normalizeToolArgsString`
+ *   produced (AC7 — these tool types already validate by executing and
+ *   returning a per-tool `isError`, so this path is untouched).
+ * - A consumer/frontend tool (an `AgentConfig.tools` entry with no `execute` —
+ *   the harness parks the call and forwards args to the SDK consumer) → the
+ *   raw `argsBuffer` is validated via `validateToolArgs` BEFORE Mastra's own
+ *   tool pipeline (`safeParseToolArgs`) can mask a malformed buffer into
+ *   `{ value: '<raw>' }`.
+ *   - `'ok'` → the normal `tool-call` part, using the *validated* (re-stringified)
+ *     args rather than the raw buffer.
+ *   - `'unparseable'` / `'schema'` → the malformed/schema-violating buffer must
+ *     never reach the SDK consumer. Returns the `tool-call` part (so the
+ *     model's own turn history stays coherent) immediately followed by a
+ *     synthetic `tool-result` part carrying `isError: true` and the message
+ *     from `describeToolArgsFailure`. The `tool-call` part carries
+ *     `providerExecuted: true` — Mastra's own orchestration
+ *     (`inferProviderExecuted`) treats a provider-executed tool call as
+ *     already resolved and never invokes the consumer-tool bridge's
+ *     `execute()` for it, so the bad buffer never parks waiting on
+ *     `ChatSession.submitToolResult`. (`LanguageModelV3ToolResult` has no
+ *     `providerExecuted` field, so the paired `tool-result` doesn't carry one.)
  *
- * Sibling to `sfdx-agent-chat-generations`'s `normalizeToolArguments` (the
- * gpt5-processor path). This one additionally coerces a whitespace-only buffer
- * — the pass-through streaming paths accumulate raw wire fragments that could in
- * principle be whitespace, whereas the chat-generations processor normalizes
- * earlier. The packages share no dependency, so the rule is duplicated rather
- * than imported; keep the two in sync if the empty-definition changes.
+ * `opts.retryCounts`, when supplied, is a per-tool-name consecutive-failure
+ * counter this function owns: incremented on `'unparseable'`/`'schema'`, reset
+ * on `'ok'`. Callers own the Map's lifetime (one per `LanguageModelV3`
+ * instance here — see each pass-through builder) — keyed by tool NAME because
+ * every model retry mints a brand-new `toolCallId`, so there is no stable id to
+ * key a per-attempt counter across attempts. Known, accepted tradeoff: two
+ * independent calls to the same tool name share a counter — cosmetic only
+ * (it only affects whether the "will not be retried further" clause appears),
+ * never a correctness issue, since a failure is always a normal isError
+ * tool-result and the turn is never terminated.
  */
-export declare function normalizeToolArgsString(args: string | null | undefined): string;
+export declare function buildValidatedToolCallChunk(toolCallId: string, toolName: string, argsBuffer: string | null | undefined, schema: Record<string, unknown> | undefined, isConsumerTool: boolean, opts?: {
+    retryCounts?: Map<string, number>;
+    maxAttempts?: number;
+    logBus?: LogBus;
+}): Array<LanguageModelV3ToolCall | LanguageModelV3ToolResult>;
 /**
  * Predicate the missing-usage faithfulness invariant (W-22692131) enforces at
  * every terminal `finish` site: when every input/output token field on the

package/dist/v3-stream-mapping.js

@@ -4,6 +4,8 @@
  */
 import { RealClock, UUIDGenerator } from '@salesforce/agentic-common';
 import { EventStreamCodec } from '@smithy/eventstream-codec';
+import { describeToolArgsFailure, recordToolArgsFailure, validateToolArgs, TOOL_ARGS_MAX_ATTEMPTS, } from '@salesforce/sfdx-agent-sdk/harness';
+import { TOOL_ARGS_VALIDATION_ERROR_METADATA } from './tool-args-marker.js';
 import { IdleReadTimeoutError } from './stream-errors.js';
 /**
  * Shared V3 helpers for the Mastra harness's `LanguageModelV3` implementations
@@ -736,8 +738,7 @@ export function toolResultOutputToString(output) {
     }
 }
 /**
- * Normalize a streamed/returned tool-call arguments STRING to a
- * schema-conforming stringified JSON object.
+ * Coerces an empty/whitespace-only tool-call argument buffer to `'{}'`.
  *
  * A no-argument tool (input schema `{ type:'object', properties:{} }`) accrues
  * no argument fragments on the wire — Anthropic streams no `input_json_delta`,
@@ -749,11 +750,11 @@ export function toolResultOutputToString(output) {
  * closed gateway-processor defect W-22696051). `'{}'` is the only valid no-arg
  * value.
  *
- * Empty (including whitespace-only) → `'{}'`. Every non-empty buffer — even a
- * malformed partial like `'{"q":'` — is returned VERBATIM: we never re-parse or
- * re-stringify real content, so a genuinely bad payload still reaches the
- * consumer and is still rejected. Applied at every provider's tool-call
- * emission seam so the rule lives in one auditable place.
+ * Used only for the non-consumer-tool (MCP / built-in) passthrough in
+ * {@link buildValidatedToolCallChunk} — those tool types are explicitly out of
+ * scope for arg validation (W-24023028 AC7) and must see byte-for-byte
+ * unchanged behavior, so a non-empty buffer — even a malformed partial like
+ * `'{"q":'` — is still returned VERBATIM here.
  *
  * Sibling to `sfdx-agent-chat-generations`'s `normalizeToolArguments` (the
  * gpt5-processor path). This one additionally coerces a whitespace-only buffer
@@ -762,9 +763,151 @@ export function toolResultOutputToString(output) {
  * earlier. The packages share no dependency, so the rule is duplicated rather
  * than imported; keep the two in sync if the empty-definition changes.
  */
-export function normalizeToolArgsString(args) {
+function coerceEmptyArgsBuffer(args) {
     return args && args.trim() !== '' ? args : '{}';
 }
+/**
+ * Provider-options namespace + keys the harness uses to carry the per-turn
+ * tool-args retry-counter scope down to a pass-through's `doStream` /
+ * `doGenerate` (S1, W-24023028). The Mastra `LanguageModel` is built once per
+ * agent (agent-lifetime), and each `doStream` is one internal model STEP — not
+ * a turn — so the pass-through cannot know the turn/thread on its own. The
+ * harness stamps the agent id + thread id onto `agent.stream({ providerOptions })`;
+ * AI-SDK forwards `providerOptions` to `LanguageModelV3CallOptions.providerOptions`
+ * UNCHANGED across every step of that one streamed run (verified empirically), so
+ * the pass-through reads them here to resolve a per-turn, per-thread counter
+ * instead of an agent-lifetime one. They ride as TWO discrete fields (not one
+ * concatenated string) so a consumer id containing the delimiter can't alias two
+ * distinct `(agentId, threadId)` scopes. The `salesforce` namespace is our
+ * pass-through's own provider slot; it is never forwarded onto the upstream
+ * request body (the pass-through builds the wire params from `options.prompt` /
+ * `tools`, not `providerOptions`).
+ */
+export const TOOL_ARGS_RETRY_SCOPE_PROVIDER = 'salesforce';
+export const TOOL_ARGS_RETRY_SCOPE_AGENT_ID = 'toolArgsRetryAgentId';
+export const TOOL_ARGS_RETRY_SCOPE_THREAD_ID = 'toolArgsRetryThreadId';
+/** The per-turn retry-counter scope (agent + thread) stamped by the harness, if present. */
+export function readToolArgsRetryScope(options) {
+    const scope = options.providerOptions?.[TOOL_ARGS_RETRY_SCOPE_PROVIDER];
+    const agentId = scope?.[TOOL_ARGS_RETRY_SCOPE_AGENT_ID];
+    const threadId = scope?.[TOOL_ARGS_RETRY_SCOPE_THREAD_ID];
+    return typeof agentId === 'string' && typeof threadId === 'string' ? { agentId, threadId } : undefined;
+}
+/**
+ * Builds the `LanguageModelV3StreamPart`(s) for one tool-call emission site
+ * (W-24023028), replacing the bare `normalizeToolArgsString` seam.
+ *
+ * - Not a consumer/frontend tool (MCP, built-in) → returns the single
+ *   `tool-call` part, byte-for-byte the same shape `normalizeToolArgsString`
+ *   produced (AC7 — these tool types already validate by executing and
+ *   returning a per-tool `isError`, so this path is untouched).
+ * - A consumer/frontend tool (an `AgentConfig.tools` entry with no `execute` —
+ *   the harness parks the call and forwards args to the SDK consumer) → the
+ *   raw `argsBuffer` is validated via `validateToolArgs` BEFORE Mastra's own
+ *   tool pipeline (`safeParseToolArgs`) can mask a malformed buffer into
+ *   `{ value: '<raw>' }`.
+ *   - `'ok'` → the normal `tool-call` part, using the *validated* (re-stringified)
+ *     args rather than the raw buffer.
+ *   - `'unparseable'` / `'schema'` → the malformed/schema-violating buffer must
+ *     never reach the SDK consumer. Returns the `tool-call` part (so the
+ *     model's own turn history stays coherent) immediately followed by a
+ *     synthetic `tool-result` part carrying `isError: true` and the message
+ *     from `describeToolArgsFailure`. The `tool-call` part carries
+ *     `providerExecuted: true` — Mastra's own orchestration
+ *     (`inferProviderExecuted`) treats a provider-executed tool call as
+ *     already resolved and never invokes the consumer-tool bridge's
+ *     `execute()` for it, so the bad buffer never parks waiting on
+ *     `ChatSession.submitToolResult`. (`LanguageModelV3ToolResult` has no
+ *     `providerExecuted` field, so the paired `tool-result` doesn't carry one.)
+ *
+ * `opts.retryCounts`, when supplied, is a per-tool-name consecutive-failure
+ * counter this function owns: incremented on `'unparseable'`/`'schema'`, reset
+ * on `'ok'`. Callers own the Map's lifetime (one per `LanguageModelV3`
+ * instance here — see each pass-through builder) — keyed by tool NAME because
+ * every model retry mints a brand-new `toolCallId`, so there is no stable id to
+ * key a per-attempt counter across attempts. Known, accepted tradeoff: two
+ * independent calls to the same tool name share a counter — cosmetic only
+ * (it only affects whether the "will not be retried further" clause appears),
+ * never a correctness issue, since a failure is always a normal isError
+ * tool-result and the turn is never terminated.
+ */
+export function buildValidatedToolCallChunk(toolCallId, toolName, argsBuffer, schema, isConsumerTool, opts) {
+    if (!isConsumerTool) {
+        return [{ type: 'tool-call', toolCallId, toolName, input: coerceEmptyArgsBuffer(argsBuffer) }];
+    }
+    const result = validateToolArgs(argsBuffer, schema);
+    if (result.outcome === 'ok') {
+        opts?.retryCounts?.delete(toolName);
+        opts?.logBus?.debug('Tool arg validation: ok', { toolName });
+        return [{ type: 'tool-call', toolCallId, toolName, input: JSON.stringify(result.args) }];
+    }
+    if (result.outcome === 'invalid-schema') {
+        // B1 fail-open: the consumer's declared `inputSchema` did not compile,
+        // so this tool degrades to no-validation rather than throwing mid-stream.
+        // Emit the ordinary (NON-provider-executed) `tool-call` part exactly as
+        // the `'ok'` path does, so Mastra's own pipeline invokes the consumer-tool
+        // bridge with the parsed args — the model is never told to fix a schema it
+        // didn't author. Log the misconfiguration for the operator.
+        opts?.retryCounts?.delete(toolName);
+        opts?.logBus?.warn('Tool arg validation: schema did not compile, passing args through', {
+            toolName,
+            schemaError: result.schemaError,
+        });
+        return [{ type: 'tool-call', toolCallId, toolName, input: JSON.stringify(result.args) }];
+    }
+    const maxAttempts = opts?.maxAttempts ?? TOOL_ARGS_MAX_ATTEMPTS;
+    // A standalone / consumer-injected builder may thread no `retryCounts`
+    // resolver; a throwaway map then yields attempt 1 every call (no
+    // accumulation), matching the pre-helper `?.` fallback behavior.
+    const { attempt, exhausted } = recordToolArgsFailure(opts?.retryCounts ?? new Map(), toolName, maxAttempts);
+    // Per-outcome detail on the failure warn — schema violation paths, or the
+    // unparseable reason (`not-json` vs `not-object`) — so an operator can tell a
+    // syntax failure from a wrong-shape one, carried on the exhausted warn too (N2).
+    const failureDetail = result.outcome === 'schema'
+        ? { violationPaths: result.violations.map((v) => v.path) }
+        : { reason: result.reason };
+    opts?.logBus?.warn(exhausted
+        ? 'Tool arg validation: retries exhausted, final error'
+        : `Tool arg validation: fed back (${result.outcome})`, {
+        toolName,
+        attempt,
+        maxAttempts,
+        ...failureDetail,
+    });
+    const message = describeToolArgsFailure(toolName, result, exhausted ? { exhausted: true, maxAttempts } : undefined);
+    return [
+        {
+            type: 'tool-call',
+            toolCallId,
+            toolName,
+            input: coerceEmptyArgsBuffer(argsBuffer),
+            // `providerExecuted: true` stops Mastra's `inferProviderExecuted` from ever
+            // invoking the consumer-tool bridge's `execute()` for this call, so the bad
+            // buffer never parks waiting on `submitToolResult`. The `tool-call` ChatEvent
+            // IS surfaced to the consumer (W-24023028) — a gated call is observable on the
+            // live stream just like an MCP/built-in tool whose executor rejected bad args
+            // — but the consumer's own tool HANDLER is never invoked for it, and it should
+            // key its rendering off the paired error `tool-result` below.
+            providerExecuted: true,
+        },
+        {
+            type: 'tool-result',
+            toolCallId,
+            toolName,
+            result: message,
+            isError: true,
+            // Mastra's own chunk-collection pipeline (`buildMessagesFromChunks`, bundled in
+            // @mastra/core) drops the `isError` flag on a provider-executed tool-result chunk
+            // when persisting the run's assistant message — it always writes `state: 'result'`
+            // regardless of `isError`. `providerMetadata` is one of the few fields that pipeline
+            // DOES carry through onto the persisted `tool-invocation` part (see
+            // `mapMastraPartToMessagePart` in `mastra-message-mapper.ts`), and `MastraEventAdapter`
+            // ORs it into the LIVE `tool-result` event's `isError` too — so the error signal
+            // survives on both the live stream and the persisted read path.
+            providerMetadata: TOOL_ARGS_VALIDATION_ERROR_METADATA,
+        },
+    ];
+}
 /**
  * Predicate the missing-usage faithfulness invariant (W-22692131) enforces at
  * every terminal `finish` site: when every input/output token field on the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.71.0",
+  "version": "0.72.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.72.0"
+    "@salesforce/sfdx-agent-sdk": "0.73.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@salesforce/harness-conformance": "0.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.72.0",
+    "@salesforce/sfdx-agent-sdk": "0.73.0",
     "@types/node": "^22.20.1",
     "@vitest/coverage-istanbul": "^4.1.11",
     "@vitest/eslint-plugin": "^1.6.27",