@salesforce/sfdx-agent-harness-mastra 0.100.0 → 0.101.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.101.0] - 2026-10-13
+
+### Features
+- **harness-mastra**: migrate pass-throughs to LanguageModelV4 and remove chat-generations @W-24224624@ ([#876](https://github.com/forcedotcom/agentic-dx/pull/876))
+
 ## [0.100.0] - 2026-10-09
 
 ### Chores

package/README.md

@@ -59,8 +59,8 @@ Linux and macOS release the handle eagerly; the retry options are no-ops on thos
 | ----------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `MastraHarnessFactory`              | class     | `HarnessFactory` that produces a Mastra-backed `AgentHarness` bound to a storage root.                                                                                                                                                   |
 | `MastraHarnessFactoryConfig`        | interface | Configuration for `MastraHarnessFactory` (`toolApprovalTimeoutMs?`, `languageModelBuilders?`).                                                                                                                                           |
-| `MastraLanguageModelBuilderContext` | type      | Context bag the harness threads into each `LanguageModelV3` builder (`getInfo`, `logBus`, `emitWireCommunication`, `innerFetch`).                                                                                                        |
-| `MastraLanguageModelBuilder`        | type      | Factory function shape for a consumer-injected builder: `(ctx: MastraLanguageModelBuilderContext) => LanguageModelV3`.                                                                                                                   |
+| `MastraLanguageModelBuilderContext` | type      | Context bag the harness threads into each `LanguageModelV4` builder (`getInfo`, `logBus`, `emitWireCommunication`, `innerFetch`).                                                                                                        |
+| `MastraLanguageModelBuilder`        | type      | Factory function shape for a consumer-injected builder: `(ctx: MastraLanguageModelBuilderContext) => LanguageModelV4`.                                                                                                                   |
 | `MASTRA_BUILT_IN_TOOL_POLICIES`     | const     | Frozen `ReadonlyArray<ToolPolicyRule>` the harness feeds the SDK's `resolveToolApprovalPolicy` as the `tiers.harness` slice — `allow` rules for Mastra's built-in `updateWorkingMemory` / `skill` / `skill_search` / `skill_read` tools. |
 | `MASTRA_BUILT_IN_TOOL_NAMES`        | const     | The four built-in tool leaf names `MASTRA_BUILT_IN_TOOL_POLICIES` covers.                                                                                                                                                                |
 
@@ -81,20 +81,14 @@ no `globalThis` mutation. When no proxy env is set, `fetch` runs unwrapped (zero
 
 #### Injecting custom wire shapes
 
-A consumer can register a `LanguageModelV3` builder for a custom `providerHint` via
+A consumer can register a `LanguageModelV4` builder for a custom `providerHint` via
 `MastraHarnessFactoryConfig.languageModelBuilders` without editing the harness's internal switch. Each injected key
-becomes a supported provider hint and a dispatch arm. Used to inject wire shapes the harness does not ship natively
-(e.g., a temporary GovCloud `chat/generations` fallback).
+becomes a supported provider hint and a dispatch arm. Used to inject wire shapes the harness does not ship natively.
 
 ```ts
-import {
-  CHAT_GENERATIONS_PROVIDER_HINT,
-  buildChatGenerationsLanguageModel,
-} from '@salesforce/sfdx-agent-chat-generations';
-
 const factory = new MastraHarnessFactory({
   languageModelBuilders: {
-    [CHAT_GENERATIONS_PROVIDER_HINT]: buildChatGenerationsLanguageModel,
+    'my-custom-wire-shape': (ctx) => buildMyLanguageModel(ctx),
   },
 });
 ```

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 import type { LogBus } from '@salesforce/agentic-common';
 import type { ModelConnectivityInfo, WireCommunicationEvent } from '@salesforce/sfdx-agent-sdk';
-import type { LanguageModelV3 } from '@ai-sdk/provider';
+import type { LanguageModelV4 } from '@ai-sdk/provider';
 export { MastraHarnessFactory, type MastraHarnessFactoryConfig } from './mastra-harness-factory.js';
 export type { MastraAgentHarness } from './mastra-harness.js';
 export { MASTRA_BUILT_IN_TOOL_NAMES, MASTRA_BUILT_IN_TOOL_POLICIES } from './mastra-built-in-policies.js';
 export { type MastraAgentConfig, type MastraSkillSearchConfig, type MastraToolSearchConfig, type SkillSearchHandle, type ToolSearchHandle, } from './tool-search.js';
 /**
- * Context the harness threads into each `LanguageModelV3` builder — both the
+ * Context the harness threads into each `LanguageModelV4` builder — both the
  * built-in builders and any consumer-injected builders registered via
  * `MastraHarnessFactoryConfig.languageModelBuilders`. The shape mirrors what
  * `MastraHarness.buildLanguageModel` currently hands its internal builders, so an
@@ -33,10 +33,10 @@ export type MastraLanguageModelBuilderContext = {
     innerFetch: typeof fetch;
 };
 /**
- * Factory function shape for a consumer-injected `LanguageModelV3` builder.
+ * Factory function shape for a consumer-injected `LanguageModelV4` builder.
  * Registered via `MastraHarnessFactoryConfig.languageModelBuilders` keyed by a custom
  * `providerHint`, used to inject wire shapes the harness does not ship natively
- * (e.g. a temporary GovCloud `chat/generations` fallback). The builder receives the
+ * (e.g. a bespoke gateway wire format). The builder receives the
  * same context bag the harness's built-in pass-through builders get, so an injected
  * builder can emit `WireCommunicationEvent`s and honor `HTTPS_PROXY` routing without
  * duplicating the harness's own fetch wrapper / wire-monitoring plumbing. The
@@ -55,4 +55,4 @@ export type MastraLanguageModelBuilderContext = {
  * });
  * ```
  */
-export type MastraLanguageModelBuilder = (ctx: MastraLanguageModelBuilderContext) => LanguageModelV3;
+export type MastraLanguageModelBuilder = (ctx: MastraLanguageModelBuilderContext) => LanguageModelV4;

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

@@ -12,10 +12,10 @@ export interface MastraHarnessFactoryConfig {
      */
     toolApprovalTimeoutMs?: number;
     /**
-     * Consumer-registered `LanguageModelV3` builders keyed by `providerHint`. Each key
+     * Consumer-registered `LanguageModelV4` builders keyed by `providerHint`. Each key
      * becomes a supported provider hint and a dispatch arm in `buildLanguageModel`. Used
-     * to inject wire shapes the harness does not ship natively (e.g. a temporary
-     * GovCloud `chat/generations` fallback path). Keys MUST NOT collide with the
+     * to inject wire shapes the harness does not ship natively (e.g. a bespoke
+     * gateway wire format). Keys MUST NOT collide with the
      * harness's built-in hints (`anthropic`, `bedrock-anthropic`, `openai`,
      * `openai-responses`, `openai-compatible`) — constructing with a colliding key
      * throws at factory construction time rather than silently shadowing the built-in.

package/dist/mastra-harness.d.ts

@@ -8,7 +8,7 @@ import { MastraApprovalCoordinator } from './mastra-approval-coordinator.js';
 import { type HttpErrorCapture } from './mcp-config-mapper.js';
 import { type MastraAgentConfig, type SkillSearchHandle, type ToolSearchHandle } from './tool-search.js';
 import { type MultimodalFile } from '@salesforce/sfdx-agent-sdk';
-import type { LanguageModelV3 } from '@ai-sdk/provider';
+import type { LanguageModelV4 } from '@ai-sdk/provider';
 import { Clock, type LogRecord, type BackoffRetryerDeps, type UniqueIDGenerator, type Unsubscribe } from '@salesforce/agentic-common';
 import { type ToolsInput } from './utils.js';
 import { Workspace } from '@mastra/core/workspace';
@@ -247,13 +247,13 @@ export interface MastraHarnessOptions {
      */
     innerFetch?: typeof fetch;
     /**
-     * Consumer-registered `LanguageModelV3` builders keyed by `providerHint`.
+     * Consumer-registered `LanguageModelV4` builders keyed by `providerHint`.
      * Forwarded from `MastraHarnessFactoryConfig.languageModelBuilders`. The
      * harness consults this map in `buildLanguageModel`'s `default` arm before
      * throwing `MODEL_NOT_SUPPORTED_BY_HARNESS`, so an injected builder can
      * handle a custom hint without editing the harness's internal switch.
      */
-    languageModelBuilders?: Readonly<Record<string, (ctx: MastraLanguageModelBuilderContext) => LanguageModelV3>>;
+    languageModelBuilders?: Readonly<Record<string, (ctx: MastraLanguageModelBuilderContext) => LanguageModelV4>>;
     /**
      * Clock / sleep / RNG for the pre-first-token LLM retry loop (W-24236393), whose policy is
      * `PRE_FIRST_TOKEN_RETRY_OPTIONS`. Tests inject a no-sleep `sleep`.
@@ -514,7 +514,7 @@ export declare class MastraHarness implements MastraAgentHarness {
      * non-empty paths.
      */
     /**
-     * Dispatches on the bag's `providerHint` and returns a `LanguageModelV3` that
+     * Dispatches on the bag's `providerHint` and returns a `LanguageModelV4` that
      * speaks the provider-native pass-through endpoint. The builder closes over
      * `getInfo` so within-shape `modelId` swaps, JWT rotations, and
      * premium-rate-limit gate flips land on the next outbound call without
@@ -588,8 +588,8 @@ export declare class MastraHarness implements MastraAgentHarness {
      * `agent.stream()` accepts.
      *
      * `text` parts collapse into text content blocks; `image` / `file` parts become v5 `file`
-     * content blocks (`mediaType` + base64 `data` + optional `filename`) that Mastra forwards to the
-     * gateway bridge, which collects them into `ChatMessageIn.files[]`. Pre-stream validation and the
+     * content blocks (`mediaType` + base64 `data` + optional `filename`) that Mastra normalizes to V4
+     * `file` parts for the provider pass-through translators. Pre-stream validation and the
      * input-part guard live in the SDK's {@link lowerStreamInput}, so file caps and the
      * `MULTIMODAL_NOT_SUPPORTED` / `INVALID_MESSAGE_CONTENT` semantics are identical to the Claude
      * harness; this method only supplies the Mastra-specific lowering of each part.

package/dist/mastra-harness.js

@@ -27,7 +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 { readToolArgsRetryScope, TOOL_ARGS_RETRY_SCOPE_AGENT_ID, TOOL_ARGS_RETRY_SCOPE_PROVIDER, TOOL_ARGS_RETRY_SCOPE_THREAD_ID, } from './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 { withPreFirstTokenRetry } from './retry-pre-first-token.js';
@@ -1550,7 +1550,7 @@ export class MastraHarness {
      * non-empty paths.
      */
     /**
-     * Dispatches on the bag's `providerHint` and returns a `LanguageModelV3` that
+     * Dispatches on the bag's `providerHint` and returns a `LanguageModelV4` that
      * speaks the provider-native pass-through endpoint. The builder closes over
      * `getInfo` so within-shape `modelId` swaps, JWT rotations, and
      * premium-rate-limit gate flips land on the next outbound call without
@@ -1671,9 +1671,9 @@ export class MastraHarness {
                 }));
             default: {
                 // Consult the injected builders map before throwing. This is the
-                // extension point for consumer-registered wire shapes (e.g. a temporary
-                // GovCloud chat/generations fallback, W-23560954). The builder receives
-                // the same context bag the built-in builders get.
+                // extension point for consumer-registered wire shapes (e.g. a bespoke
+                // gateway wire format). The builder receives the same context bag the
+                // built-in builders get.
                 const custom = this.languageModelBuilders?.[initial.providerHint];
                 if (custom) {
                     return this.wrapLanguageModel(custom({ getInfo, logBus, emitWireCommunication, innerFetch }));
@@ -1773,8 +1773,8 @@ export class MastraHarness {
      * `agent.stream()` accepts.
      *
      * `text` parts collapse into text content blocks; `image` / `file` parts become v5 `file`
-     * content blocks (`mediaType` + base64 `data` + optional `filename`) that Mastra forwards to the
-     * gateway bridge, which collects them into `ChatMessageIn.files[]`. Pre-stream validation and the
+     * content blocks (`mediaType` + base64 `data` + optional `filename`) that Mastra normalizes to V4
+     * `file` parts for the provider pass-through translators. Pre-stream validation and the
      * input-part guard live in the SDK's {@link lowerStreamInput}, so file caps and the
      * `MULTIMODAL_NOT_SUPPORTED` / `INVALID_MESSAGE_CONTENT` semantics are identical to the Claude
      * harness; this method only supplies the Mastra-specific lowering of each part.

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

@@ -1,10 +1,10 @@
 import Anthropic from '@anthropic-ai/sdk';
-import type { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3Prompt } from '@ai-sdk/provider';
+import type { LanguageModelV4, LanguageModelV4CallOptions, LanguageModelV4Prompt } from '@ai-sdk/provider';
 import type { LogBus } from '@salesforce/agentic-common';
 import type { ModelConnectivityInfo, WireCommunicationEvent } from '@salesforce/sfdx-agent-sdk';
-import { type GatewayFetchWireHooks } from './v3-stream-mapping.js';
+import { type GatewayFetchWireHooks } from './stream-mapping.js';
 /**
- * Builds the in-process `LanguageModelV3` impl for the Salesforce LLM Gateway's
+ * Builds the in-process `LanguageModelV4` impl for the Salesforce LLM Gateway's
  * `/invoke-with-response-stream` (Bedrock-Anthropic pass-through) endpoint.
  * Drives `@anthropic-ai/bedrock-sdk` with `skipAuth: true` so the connectivity
  * resolver's headers (Salesforce JWT, tenant key, etc.) are the single source
@@ -66,12 +66,12 @@ export declare function buildAnthropicLanguageModel(opts: {
      * `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>;
+    getToolArgsRetryCounts?: (options: LanguageModelV4CallOptions) => Map<string, number>;
     /** Per-read idle timeout (ms) for the gateway response body; see `createGatewayFetch`. */
     idleReadTimeoutMs?: number;
-}): LanguageModelV3;
+}): LanguageModelV4;
 /**
- * Builds the in-process `LanguageModelV3` impl for direct-Anthropic API access
+ * Builds the in-process `LanguageModelV4` impl for direct-Anthropic API access
  * (`api.anthropic.com/v1/messages` or any Anthropic-shaped endpoint). Drives
  * `@anthropic-ai/sdk` with the api-key peeled from the resolver's headers.
  *
@@ -101,10 +101,10 @@ export declare function buildAnthropicDirectLanguageModel(opts: {
     /** See {@link buildAnthropicLanguageModel} `getConsumerToolSchemas`. */
     getConsumerToolSchemas?: () => ReadonlyMap<string, Record<string, unknown>>;
     /** See {@link buildAnthropicLanguageModel} `getToolArgsRetryCounts`. */
-    getToolArgsRetryCounts?: (options: LanguageModelV3CallOptions) => Map<string, number>;
+    getToolArgsRetryCounts?: (options: LanguageModelV4CallOptions) => Map<string, number>;
     /** Per-read idle timeout (ms) for the gateway response body; see `createGatewayFetch`. */
     idleReadTimeoutMs?: number;
-}): LanguageModelV3;
+}): LanguageModelV4;
 /**
  * Stamps `cache_control: {type:'ephemeral'}` on up to three of Anthropic's four
  * allowed breakpoints: the last tool (caches the constant tools block), the
@@ -115,25 +115,25 @@ export declare function buildAnthropicDirectLanguageModel(opts: {
  * only the turn-constant tools/system cached and forfeit most of the win.
  * Mutates only `commonParams`'s own arrays — which
  * `translate*ToAnthropic` builds fresh per request — never the caller's
- * original `LanguageModelV3` prompt/tool objects.
+ * original `LanguageModelV4` prompt/tool objects.
  */
 export declare function applyCacheBreakpoints(commonParams: Omit<Anthropic.Messages.MessageCreateParamsStreaming, 'stream'>): void;
 /**
- * Translates a V3 `LanguageModelV3Prompt` into Anthropic's Messages API shape
+ * Translates a V4 `LanguageModelV4Prompt` into Anthropic's Messages API shape
  * — top-level `system` string + `MessageParam[]` of role-tagged content blocks.
  *
- * V3 keeps system / user / assistant / tool messages flat. Anthropic combines
+ * V4 keeps system / user / assistant / tool messages flat. Anthropic combines
  * tool results onto a synthetic user-role turn carrying `tool_result` blocks,
- * so we collapse consecutive tool-only V3 messages into the surrounding user
+ * so we collapse consecutive tool-only V4 messages into the surrounding user
  * turn shape.
  */
-export declare function translatePromptToAnthropic(prompt: LanguageModelV3Prompt): {
+export declare function translatePromptToAnthropic(prompt: LanguageModelV4Prompt): {
     system?: string;
     messages: Anthropic.Messages.MessageParam[];
 };
 /**
- * Translates V3 function-tool definitions into Anthropic's `Tool[]` shape.
+ * Translates V4 function-tool definitions into Anthropic's `Tool[]` shape.
  * Skips non-function variants (provider-defined / dynamic) — the pass-through
  * path supports only the function-tool subset that Mastra's tool mapper produces.
  */
-export declare function translateToolsToAnthropic(options: LanguageModelV3CallOptions): Anthropic.Messages.Tool[];
+export declare function translateToolsToAnthropic(options: LanguageModelV4CallOptions): Anthropic.Messages.Tool[];

package/dist/pass-through-anthropic.js

@@ -5,9 +5,9 @@
 import { AnthropicBedrock } from '@anthropic-ai/bedrock-sdk';
 import Anthropic from '@anthropic-ai/sdk';
 import { EmptyStreamError, NetworkStreamError, isStreamTransportError, recognizeBedrockValidationError, } from './stream-errors.js';
-import { SpanLifecycle, ToolInputSpanLifecycle, buildValidatedToolCallChunk, createGatewayFetch, isEmptyUsage, isParameterExcluded, mapAnthropicFinishReason, mapAnthropicUsage, toolResultOutputToString, } from './v3-stream-mapping.js';
+import { SpanLifecycle, ToolInputSpanLifecycle, buildValidatedToolCallChunk, createGatewayFetch, isEmptyUsage, isParameterExcluded, mapAnthropicFinishReason, mapAnthropicUsage, toolResultOutputToString, v4FileDataToBase64, } from './stream-mapping.js';
 /**
- * Builds the in-process `LanguageModelV3` impl for the Salesforce LLM Gateway's
+ * Builds the in-process `LanguageModelV4` impl for the Salesforce LLM Gateway's
  * `/invoke-with-response-stream` (Bedrock-Anthropic pass-through) endpoint.
  * Drives `@anthropic-ai/bedrock-sdk` with `skipAuth: true` so the connectivity
  * resolver's headers (Salesforce JWT, tenant key, etc.) are the single source
@@ -44,7 +44,7 @@ export function buildAnthropicLanguageModel(opts) {
         }),
     };
     return {
-        specificationVersion: 'v3',
+        specificationVersion: 'v4',
         provider: 'salesforce-llm-gateway-pass-through-anthropic',
         // Mastra captures `modelId` once at construction. The actual wire id
         // sent on every call is read from the live bag via `commonParams.model`
@@ -57,7 +57,7 @@ export function buildAnthropicLanguageModel(opts) {
     };
 }
 /**
- * Builds the in-process `LanguageModelV3` impl for direct-Anthropic API access
+ * Builds the in-process `LanguageModelV4` impl for direct-Anthropic API access
  * (`api.anthropic.com/v1/messages` or any Anthropic-shaped endpoint). Drives
  * `@anthropic-ai/sdk` with the api-key peeled from the resolver's headers.
  *
@@ -104,7 +104,7 @@ export function buildAnthropicDirectLanguageModel(opts) {
         }),
     };
     return {
-        specificationVersion: 'v3',
+        specificationVersion: 'v4',
         provider: 'anthropic-direct-pass-through',
         modelId: initialInfo.nativeModelId,
         supportedUrls: {},
@@ -231,7 +231,7 @@ const CACHE_CONTROL_EPHEMERAL = Object.freeze({ type: 'ephemeral' });
  * only the turn-constant tools/system cached and forfeit most of the win.
  * Mutates only `commonParams`'s own arrays — which
  * `translate*ToAnthropic` builds fresh per request — never the caller's
- * original `LanguageModelV3` prompt/tool objects.
+ * original `LanguageModelV4` prompt/tool objects.
  */
 export function applyCacheBreakpoints(commonParams) {
     const tools = commonParams.tools;
@@ -348,7 +348,7 @@ async function doGenerate(ctx, options) {
             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 (redacted_thinking, server-tool-result, etc.) are
-        // not in the V3 ChatEvent surface — same posture as doStream.
+        // not in the V4 ChatEvent surface — same posture as doStream.
     }
     const finishReason = mapAnthropicFinishReason(message.stop_reason, sawToolCalls);
     const usage = mapAnthropicUsage(message.usage);
@@ -398,7 +398,7 @@ async function doStream(ctx, options) {
     const stream = new ReadableStream({
         start: async (controller) => {
             const textSpan = new SpanLifecycle();
-            // Extended-thinking narration streams on its own V3 reasoning span,
+            // Extended-thinking narration streams on its own V4 reasoning span,
             // so it surfaces as `reasoning-delta` (→ AG-UI REASONING_MESSAGE_CONTENT)
             // rather than bleeding into the answer's `text-delta`.
             const reasoningSpan = new SpanLifecycle('reasoning');
@@ -432,7 +432,7 @@ async function doStream(ctx, options) {
                         case 'content_block_start': {
                             const block = event.content_block;
                             if (block.type === 'text') {
-                                // Open the V3 text span on the first text block of the message
+                                // Open the V4 text span on the first text block of the message
                                 // (or after a tool_use rotated us forward).
                                 textSpan.openIfNeeded(controller);
                             }
@@ -460,7 +460,7 @@ async function doStream(ctx, options) {
                                 });
                             }
                             // Other block types (redacted_thinking, server-tool result, etc.)
-                            // are intentionally ignored — they're not in the V3 ChatEvent surface.
+                            // are intentionally ignored — they're not in the V4 ChatEvent surface.
                             break;
                         }
                         case 'content_block_delta': {
@@ -481,7 +481,7 @@ async function doStream(ctx, options) {
                                 }
                             }
                             // signature_delta / citations_delta are not surfaced — the
-                            // encrypted thinking signature has no V3 stream-part and no
+                            // encrypted thinking signature has no V4 stream-part and no
                             // consumer surface (AG-UI ReasoningEncryptedValue is deferred).
                             break;
                         }
@@ -526,7 +526,7 @@ async function doStream(ctx, options) {
                 }
                 // Stream ended without an explicit `message_stop`. If we saw at least
                 // one recognized content / usage event, close out the span and
-                // synthesize a terminal `finish` so V3 consumers see exactly one. If
+                // synthesize a terminal `finish` so V4 consumers see exactly one. If
                 // we saw NONE — a clean-but-empty body — surface a classified `error`
                 // instead of a false-success empty `finish` (8a). A cancelled turn is
                 // exempt: an aborted stream ends cleanly here too (the SDK `Stream`
@@ -556,7 +556,7 @@ async function doStream(ctx, options) {
                     // Trailing-JSON #396: the gateway sometimes appends a JSON error envelope
                     // after the terminal eventstream frame on otherwise-successful responses,
                     // which the Anthropic SDK's parser surfaces as a late throw. Drop it
-                    // silently — V3 consumers must see exactly one terminal `finish`.
+                    // silently — V4 consumers must see exactly one terminal `finish`.
                     controller.close();
                     return;
                 }
@@ -574,7 +574,7 @@ async function doStream(ctx, options) {
     });
     return { stream };
 }
-/** Default Anthropic `max_tokens` when V3 doesn't supply one. The Bedrock invoke
+/** Default Anthropic `max_tokens` when V4 doesn't supply one. The Bedrock invoke
  * API requires the field; Mastra leaves it unset for many turns. 4096 mirrors
  * the `@ai-sdk/anthropic` provider's default. */
 const DEFAULT_MAX_TOKENS = 4096;
@@ -590,12 +590,12 @@ const DEFAULT_MAX_TOKENS = 4096;
  */
 const SUMMARY_MAX_OUTPUT_TOKENS = 16384;
 /**
- * Translates a V3 `LanguageModelV3Prompt` into Anthropic's Messages API shape
+ * Translates a V4 `LanguageModelV4Prompt` into Anthropic's Messages API shape
  * — top-level `system` string + `MessageParam[]` of role-tagged content blocks.
  *
- * V3 keeps system / user / assistant / tool messages flat. Anthropic combines
+ * V4 keeps system / user / assistant / tool messages flat. Anthropic combines
  * tool results onto a synthetic user-role turn carrying `tool_result` blocks,
- * so we collapse consecutive tool-only V3 messages into the surrounding user
+ * so we collapse consecutive tool-only V4 messages into the surrounding user
  * turn shape.
  */
 export function translatePromptToAnthropic(prompt) {
@@ -669,7 +669,7 @@ export function translatePromptToAnthropic(prompt) {
     return system !== undefined ? { system, messages } : { messages };
 }
 /**
- * Translates V3 function-tool definitions into Anthropic's `Tool[]` shape.
+ * Translates V4 function-tool definitions into Anthropic's `Tool[]` shape.
  * Skips non-function variants (provider-defined / dynamic) — the pass-through
  * path supports only the function-tool subset that Mastra's tool mapper produces.
  */
@@ -685,13 +685,11 @@ export function translateToolsToAnthropic(options) {
     }));
 }
 function toAnthropicFileBlock(part) {
-    if (typeof part.data !== 'string') {
-        throw new Error(`Unsupported file data for "${part.mediaType}": expected a base64 string, got ${part.data instanceof URL ? 'a URL' : 'binary data'}. Only base64-encoded file data is supported.`);
-    }
+    const base64 = v4FileDataToBase64(part.data, part.mediaType);
     if (part.mediaType === 'application/pdf') {
         return {
             type: 'document',
-            source: { type: 'base64', media_type: 'application/pdf', data: part.data },
+            source: { type: 'base64', media_type: 'application/pdf', data: base64 },
         };
     }
     if (part.mediaType === 'image/png' ||
@@ -700,7 +698,7 @@ function toAnthropicFileBlock(part) {
         part.mediaType === 'image/webp') {
         return {
             type: 'image',
-            source: { type: 'base64', media_type: part.mediaType, data: part.data },
+            source: { type: 'base64', media_type: part.mediaType, data: base64 },
         };
     }
     throw new Error(`Unsupported file media type "${part.mediaType}". Anthropic supports image/png, image/jpeg, image/gif, image/webp, application/pdf.`);

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

@@ -1,10 +1,10 @@
 import type { ChatCompletionMessageParam, ChatCompletionTool } from 'openai/resources/chat/completions';
-import type { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3FinishReason, LanguageModelV3Prompt } from '@ai-sdk/provider';
+import type { LanguageModelV4, LanguageModelV4CallOptions, LanguageModelV4FinishReason, LanguageModelV4Prompt } from '@ai-sdk/provider';
 import type { LogBus } from '@salesforce/agentic-common';
 import type { ModelConnectivityInfo, WireCommunicationEvent } from '@salesforce/sfdx-agent-sdk';
-import { type GatewayFetchWireHooks } from './v3-stream-mapping.js';
+import { type GatewayFetchWireHooks } from './stream-mapping.js';
 /**
- * Builds the in-process `LanguageModelV3` impl that drives the `openai` SDK's
+ * Builds the in-process `LanguageModelV4` impl that drives the `openai` SDK's
  * `chat.completions.create({ stream: true })` against an OpenAI-compatible
  * endpoint (LLM Gateway Express, LiteLLM, vLLM, etc. — anything that speaks
  * `/v1/chat/completions`).
@@ -15,7 +15,7 @@ import { type GatewayFetchWireHooks } from './v3-stream-mapping.js';
  * `input` split); (3) streaming events are `ChatCompletionChunk` objects with
  * `choices[0].delta` text/tool-call deltas and the terminal `finish_reason`
  * landing on the same chunk shape rather than a discrete `response.completed`
- * event. The V3 mapping output is identical — same `text-delta` / `tool-call` /
+ * event. The V4 mapping output is identical — same `text-delta` / `tool-call` /
  * `finish` parts the Responses builder produces.
  *
  * Per-call freshness contract is the same as the other builders: every HTTP
@@ -35,28 +35,28 @@ export declare function buildOpenAIChatCompletionsLanguageModel(opts: {
     /** See `buildAnthropicLanguageModel` `getConsumerToolSchemas`. */
     getConsumerToolSchemas?: () => ReadonlyMap<string, Record<string, unknown>>;
     /** See `buildAnthropicLanguageModel` `getToolArgsRetryCounts`. */
-    getToolArgsRetryCounts?: (options: LanguageModelV3CallOptions) => Map<string, number>;
+    getToolArgsRetryCounts?: (options: LanguageModelV4CallOptions) => Map<string, number>;
     /** Per-read idle timeout (ms) for the gateway response body; see `createGatewayFetch`. */
     idleReadTimeoutMs?: number;
-}): LanguageModelV3;
+}): LanguageModelV4;
 /**
- * Translates a V3 `LanguageModelV3Prompt` into the OpenAI Chat Completions
+ * Translates a V4 `LanguageModelV4Prompt` into the OpenAI Chat Completions
  * `messages` array shape. System messages stay as `system` role; user / tool
  * follow naturally. Assistant text + tool-calls collapse onto a single
  * assistant message carrying a `content` string (when text is present) plus
  * `tool_calls` (when calls are present). Tool results land on `tool` role
  * with `tool_call_id`.
  */
-export declare function translatePromptToChatCompletions(prompt: LanguageModelV3Prompt): ChatCompletionMessageParam[];
+export declare function translatePromptToChatCompletions(prompt: LanguageModelV4Prompt): ChatCompletionMessageParam[];
 /**
- * Translates V3 function-tool definitions into the Chat Completions `tools[]`
+ * Translates V4 function-tool definitions into the Chat Completions `tools[]`
  * shape. Skips non-function variants — same posture as the Responses builder.
  */
-export declare function translateToolsToChatCompletions(options: LanguageModelV3CallOptions): ChatCompletionTool[];
+export declare function translateToolsToChatCompletions(options: LanguageModelV4CallOptions): ChatCompletionTool[];
 /**
- * Maps Chat Completions `finish_reason` onto V3's unified shape. The Chat
+ * Maps Chat Completions `finish_reason` onto V4's unified shape. The Chat
  * Completions API uses `'stop' | 'length' | 'tool_calls' | 'content_filter' |
  * 'function_call' | null`. `function_call` is the legacy shape from before
  * `tool_calls` existed; modern endpoints emit `'tool_calls'`.
  */
-export declare function mapChatCompletionFinishReason(raw: string | null, sawToolCalls: boolean): LanguageModelV3FinishReason;
+export declare function mapChatCompletionFinishReason(raw: string | null, sawToolCalls: boolean): LanguageModelV4FinishReason;

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

@@ -4,9 +4,9 @@
  */
 import OpenAI from 'openai';
 import { EmptyStreamError } from './stream-errors.js';
-import { SpanLifecycle, ToolInputSpanLifecycle, buildValidatedToolCallChunk, createGatewayFetch, isEmptyUsage, isParameterExcluded, mapOpenAIUsage, toolResultOutputToString, } from './v3-stream-mapping.js';
+import { SpanLifecycle, ToolInputSpanLifecycle, buildValidatedToolCallChunk, createGatewayFetch, isEmptyUsage, isParameterExcluded, mapOpenAIUsage, toolResultOutputToString, v4FileDataToBase64, } from './stream-mapping.js';
 /**
- * Builds the in-process `LanguageModelV3` impl that drives the `openai` SDK's
+ * Builds the in-process `LanguageModelV4` impl that drives the `openai` SDK's
  * `chat.completions.create({ stream: true })` against an OpenAI-compatible
  * endpoint (LLM Gateway Express, LiteLLM, vLLM, etc. — anything that speaks
  * `/v1/chat/completions`).
@@ -17,7 +17,7 @@ import { SpanLifecycle, ToolInputSpanLifecycle, buildValidatedToolCallChunk, cre
  * `input` split); (3) streaming events are `ChatCompletionChunk` objects with
  * `choices[0].delta` text/tool-call deltas and the terminal `finish_reason`
  * landing on the same chunk shape rather than a discrete `response.completed`
- * event. The V3 mapping output is identical — same `text-delta` / `tool-call` /
+ * event. The V4 mapping output is identical — same `text-delta` / `tool-call` /
  * `finish` parts the Responses builder produces.
  *
  * Per-call freshness contract is the same as the other builders: every HTTP
@@ -41,7 +41,7 @@ export function buildOpenAIChatCompletionsLanguageModel(opts) {
         idleReadTimeoutMs,
     };
     return {
-        specificationVersion: 'v3',
+        specificationVersion: 'v4',
         provider: 'openai-compatible-chat-completions-pass-through',
         modelId: initialInfo.nativeModelId,
         supportedUrls: {},
@@ -131,7 +131,7 @@ async function doStream(ctx, options) {
         // `stream_options.include_usage` opts the upstream into emitting a final
         // chunk with cumulative usage on `usage`. Many OpenAI-compatible gateways
         // honor this; those that don't simply omit the field, which we degrade
-        // to `undefined` `LanguageModelV3Usage` per the missing-usage contract.
+        // to `undefined` `LanguageModelV4Usage` per the missing-usage contract.
         stream_options: { include_usage: true },
     };
     // See doGenerate: thread the AbortSignal into the SDK so a mid-stream abort
@@ -174,11 +174,11 @@ async function doStream(ctx, options) {
                         sawContentOrUsage = true;
                     }
                     if (delta.tool_calls) {
-                        // V3 ordering: any open text span must close BEFORE tool-call parts
+                        // V4 ordering: any open text span must close BEFORE tool-call parts
                         // land. Without this rotate, a `delta.content` chunk followed by a
                         // `delta.tool_calls` chunk in the same stream produces
                         // `text-start → text-delta → tool-call → text-end → finish`, which
-                        // violates the V3 lifecycle (peer builders pass-through-anthropic.ts
+                        // violates the V4 lifecycle (peer builders pass-through-anthropic.ts
                         // and pass-through-openai.ts both rotate eagerly at the same moment).
                         // `rotate` is a no-op when no text span is open.
                         textSpan.rotate(controller);
@@ -297,7 +297,7 @@ async function doStream(ctx, options) {
                 if (terminalEmitted) {
                     // Symmetric defense with the Anthropic / OpenAI Responses builders —
                     // a trailing-JSON throw after the terminal `finish` is enqueued must
-                    // not corrupt the V3 stream contract.
+                    // not corrupt the V4 stream contract.
                     controller.close();
                     return;
                 }
@@ -309,7 +309,7 @@ async function doStream(ctx, options) {
     return { stream };
 }
 /**
- * Translates a V3 `LanguageModelV3Prompt` into the OpenAI Chat Completions
+ * Translates a V4 `LanguageModelV4Prompt` into the OpenAI Chat Completions
  * `messages` array shape. System messages stay as `system` role; user / tool
  * follow naturally. Assistant text + tool-calls collapse onto a single
  * assistant message carrying a `content` string (when text is present) plus
@@ -378,7 +378,7 @@ export function translatePromptToChatCompletions(prompt) {
     return messages;
 }
 /**
- * Translates V3 function-tool definitions into the Chat Completions `tools[]`
+ * Translates V4 function-tool definitions into the Chat Completions `tools[]`
  * shape. Skips non-function variants — same posture as the Responses builder.
  */
 export function translateToolsToChatCompletions(options) {
@@ -396,16 +396,14 @@ export function translateToolsToChatCompletions(options) {
     }));
 }
 function toChatCompletionsFilePart(part) {
-    if (typeof part.data !== 'string') {
-        throw new Error(`Unsupported file data for "${part.mediaType}": expected a base64 string, got ${part.data instanceof URL ? 'a URL' : 'binary data'}. Only base64-encoded file data is supported.`);
-    }
+    const base64 = v4FileDataToBase64(part.data, part.mediaType);
     if (part.mediaType === 'image/png' ||
         part.mediaType === 'image/jpeg' ||
         part.mediaType === 'image/gif' ||
         part.mediaType === 'image/webp') {
         return {
             type: 'image_url',
-            image_url: { url: `data:${part.mediaType};base64,${part.data}`, detail: 'auto' },
+            image_url: { url: `data:${part.mediaType};base64,${base64}`, detail: 'auto' },
         };
     }
     // Chat Completions doesn't accept inline file (PDF) parts the way Anthropic
@@ -414,7 +412,7 @@ function toChatCompletionsFilePart(part) {
     // PDF support should use the Responses API path.
     if (part.mediaType === 'application/pdf') {
         const filename = part.filename ?? 'attachment.pdf';
-        const sizeKb = Math.round((part.data.length * 0.75) / 1024);
+        const sizeKb = Math.round((base64.length * 0.75) / 1024);
         return {
             type: 'text',
             text: `[file: ${filename} (application/pdf, ~${sizeKb} KB) — file content not supported by /chat/completions; consider switching to providerHint: 'openai-responses' for PDF support]`,
@@ -424,7 +422,7 @@ function toChatCompletionsFilePart(part) {
         `Supported: image/png, image/jpeg, image/gif, image/webp.`);
 }
 /**
- * Maps Chat Completions usage onto the V3 `LanguageModelV3Usage` shape via the
+ * Maps Chat Completions usage onto the V4 `LanguageModelV4Usage` shape via the
  * shared OpenAI usage mapper — Chat Completions and Responses surface the same
  * post-normalisation shape (`prompt_tokens` / `completion_tokens` /
  * `*_tokens_details`).
@@ -433,7 +431,7 @@ function mapChatCompletionUsage(usage) {
     return mapOpenAIUsage(usage ?? undefined);
 }
 /**
- * Maps Chat Completions `finish_reason` onto V3's unified shape. The Chat
+ * Maps Chat Completions `finish_reason` onto V4's unified shape. The Chat
  * Completions API uses `'stop' | 'length' | 'tool_calls' | 'content_filter' |
  * 'function_call' | null`. `function_call` is the legacy shape from before
  * `tool_calls` existed; modern endpoints emit `'tool_calls'`.