@salesforce/sfdx-agent-chat-generations 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to `@salesforce/sfdx-agent-chat-generations` are documented in this file.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.0.1] - 2026-07-27
+
+### Features
+- **chat-generations**: GovCloud chat/generations fallback @W-23560954@ ([#695](https://github.com/forcedotcom/agentic-dx/pull/695))
+

package/LICENSE.txt

@@ -0,0 +1,21 @@
+Terms of Use
+
+Copyright 2026 Salesforce, Inc. All rights reserved.
+
+These Terms of Use govern the download, installation, and/or use of this software provided by Salesforce, Inc. ("Salesforce") (the "Software"), were last updated on March 24, 2026, and constitute a legally binding agreement between you and Salesforce. If you do not agree to these Terms of Use, do not install or use the Software. The Software may link to third-party software components licensed under various open source licenses ("Open Source Components"). These Terms of Use pertain solely to Salesforce's proprietary code in the Software. It does not alter or extend any rights or obligations regarding the Open Source Components. For clarity, your use of the Open Source Components is governed by the terms of the applicable open source license(s). You are solely responsible for complying with the terms and conditions of those open source licenses.
+
+Salesforce grants you a worldwide, non-exclusive, no-charge, royalty-free copyright license to reproduce, revocable, publicly display, publicly perform, sublicense, and distribute the Software and derivative works subject to these Terms. These Terms shall be included in all copies or substantial portions of the Software.
+
+Subject to the limited rights expressly granted hereunder, Salesforce reserves all rights, title, and interest in and to all intellectual property subsisting in the Software. No rights are granted to you hereunder other than as expressly set forth herein. Users residing in countries on the United States Office of Foreign Assets Control sanction list, or which are otherwise subject to a US export embargo, may not use the Software.
+
+Implementation of the Software may require development work, for which you are responsible. The Software may contain bugs, errors and incompatibilities and is made available on an AS IS basis without support, updates, or service level commitments.
+
+Salesforce reserves the right at any time to modify, suspend, or discontinue, the Software (or any part thereof) with or without notice. You agree that Salesforce shall not be liable to you or to any third party for any modification, suspension, or discontinuance.
+
+You agree to defend Salesforce against any claim, demand, suit or proceeding made or brought against Salesforce by a third party arising out of or accruing from (a) your use of the Software, and (b) any application you develop with the Software that infringes any copyright, trademark, trade secret, trade dress, patent, or other intellectual property right of any person or defames any person or violates their rights of publicity or privacy (each a "Claim Against Salesforce"), and will indemnify Salesforce from any damages, attorney fees, and costs finally awarded against Salesforce as a result of, or for any amounts paid by Salesforce under a settlement approved by you in writing of, a Claim Against Salesforce, provided Salesforce (x) promptly gives you written notice of the Claim Against Salesforce, (y) gives you sole control of the defense and settlement of the Claim Against Salesforce (except that you may not settle any Claim Against Salesforce unless it unconditionally releases Salesforce of all liability), and (z) gives you all reasonable assistance, at your expense.
+
+WITHOUT LIMITING THE GENERALITY OF THE FOREGOING, THE SOFTWARE IS NOT SUPPORTED AND IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN NO EVENT SHALL SALESFORCE HAVE ANY LIABILITY FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO, DIRECT, INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE, OR CONSEQUENTIAL DAMAGES, OR DAMAGES BASED ON LOST PROFITS, DATA, OR USE, IN CONNECTION WITH THE SOFTWARE, HOWEVER CAUSED AND WHETHER IN CONTRACT, TORT, OR UNDER ANY OTHER THEORY OF LIABILITY, WHETHER OR NOT YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+These Terms of Use shall be governed exclusively by the internal laws of the State of California, without regard to its conflicts of laws rules. Each party hereby consents to the exclusive jurisdiction of the state and federal courts located in San Francisco County, California to adjudicate any dispute arising out of or relating to these Terms of Use and the download, installation, and/or use of the Software. Except as expressly stated herein, these Terms of Use constitute the entire agreement between the parties, and supersede all prior and contemporaneous agreements, proposals, or representations, written or oral, concerning their subject matter. No modification, amendment, or waiver of any provision of these Terms of Use shall be effective unless it is by an update to these Terms of Use that Salesforce makes available, or is in writing and signed by the party against whom the modification, amendment, or waiver is to be asserted.
+
+Data Privacy: Salesforce may collect, process, and store device, system, and other information related to your use of the Software. This information includes, but is not limited to, IP address, user metrics, and other data ("Usage Data"). Salesforce may use Usage Data for analytics, product development, and marketing purposes. You acknowledge that files generated in conjunction with the Software may contain sensitive or confidential data, and you are solely responsible for anonymizing and protecting such data.

package/README.md

@@ -0,0 +1,133 @@
+# @salesforce/sfdx-agent-chat-generations
+
+Temporary GovCloud `chat/generations` fallback for
+[`@salesforce/sfdx-agent-harness-mastra`](../sfdx-agent-harness-mastra). **This package is slated for removal** once the
+Responses API is onboarded in GovCloud.
+
+> **Closed source.** This package is published to npm under the [Salesforce Public Code License](../../LICENSE.txt) and
+> is for use by Salesforce only.
+
+## Overview
+
+This package provides a temporary fallback for GovCloud deployments where the Responses API is not yet available. It
+implements the legacy Salesforce LLM Gateway `chat/generations` wire shape — the only LLM path onboarded in GovCloud
+(GIA2H) — and is injected into the Mastra harness via the generic `languageModelBuilders` seam and a
+connectivity-resolver decorator. GPT-5 is the only supported model family. The fallback is expected to be deleted within
+a few weeks once the Responses API is SFAP-onboarded in GovCloud (W-23560954).
+
+## Install
+
+```bash
+npm install @salesforce/sfdx-agent-sdk @salesforce/sfdx-agent-harness-mastra @salesforce/sfdx-agent-chat-generations
+```
+
+## Usage
+
+### Bootstrap
+
+Wire the GovCloud `chat/generations` fallback by injecting the resolver and language-model builder at construction time.
+Two forms are supported:
+
+#### Explicit construction
+
+```ts
+import { MastraHarnessFactory } from '@salesforce/sfdx-agent-harness-mastra';
+import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
+import {
+  buildChatGenerationsLanguageModel,
+  ChatGenerationsResolver,
+  CHAT_GENERATIONS_PROVIDER_HINT,
+} from '@salesforce/sfdx-agent-chat-generations';
+
+const factory = new MastraHarnessFactory({
+  languageModelBuilders: {
+    [CHAT_GENERATIONS_PROVIDER_HINT]: buildChatGenerationsLanguageModel,
+  },
+});
+
+const connectivityResolver = new ChatGenerationsResolver({
+  delegate: myExistingResolver, // e.g., VibesAgentConnectivityResolver
+  baseUrl: 'https://dev.api.gov.salesforce.com/ai/gpt/v1',
+  extraHeaders: { 'x-salesforce-region': 'us-gov-east-1' }, // VERIFY: region header requirement TBD
+});
+
+const manager = await createAgentManager(storageRoot, factory, { connectivityResolver });
+```
+
+#### Convenience factory (preferred)
+
+```ts
+import { MastraHarnessFactory } from '@salesforce/sfdx-agent-harness-mastra';
+import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
+import { createChatGenerationsFallback } from '@salesforce/sfdx-agent-chat-generations';
+
+const { connectivityResolver, languageModelBuilders } = createChatGenerationsFallback({
+  delegate: myExistingResolver,
+  baseUrl: 'https://dev.api.gov.salesforce.com/ai/gpt/v1',
+  extraHeaders: { 'x-salesforce-region': 'us-gov-east-1' }, // VERIFY: region header requirement TBD
+});
+
+const factory = new MastraHarnessFactory({ languageModelBuilders });
+const manager = await createAgentManager(storageRoot, factory, { connectivityResolver });
+```
+
+**Important:** The consumer MUST set `AgentConfig.modelId` to a GovCloud-provisioned GPT model (e.g.,
+`sfdc_ai__DefaultGPT4_8`). The SDK default (Claude Sonnet 4.6) will not resolve in GovCloud.
+
+```ts
+const agent = await manager.createAgent(projectRoot, {
+  modelId: 'sfdc_ai__DefaultGPT4_8', // Required: must be a GPT model provisioned in GovCloud
+  instructions: '...',
+});
+```
+
+The `x-salesforce-region` header requirement and value (`us-gov-east-1`) are unconfirmed pending live endpoint
+validation. Consumers should verify these against the live GovCloud gateway.
+
+## Public API
+
+- **`buildChatGenerationsLanguageModel`** — `MastraLanguageModelBuilder` that produces a `LanguageModelV3` speaking the
+  `chat/generations` wire shape. Injects into
+  `MastraHarnessFactory.languageModelBuilders[CHAT_GENERATIONS_PROVIDER_HINT]`.
+- **`ChatGenerationsResolver`** — Connectivity resolver decorator that wraps the consumer's real resolver and rewrites
+  its `ModelConnectivityInfo` bag onto the GovCloud `chat/generations` path (flips `baseUrl` + `providerHint`, merges
+  `extraHeaders`, reuses the delegate's `getHeaders()` verbatim).
+- **`ChatGenerationsResolverOptions`** — Configuration type for `ChatGenerationsResolver`:
+  - `delegate: AgentConnectivityResolver` — the consumer's real resolver (e.g., `VibesAgentConnectivityResolver`).
+  - `baseUrl: string` — GovCloud gateway base URL (e.g., `'https://dev.api.gov.salesforce.com/ai/gpt/v1'`).
+  - `extraHeaders?: Record<string, string>` — optional extra headers required by GovCloud `chat/generations` (e.g.,
+    `{ 'x-salesforce-region': 'us-gov-east-1' }`). Unconfirmed.
+  - `enabled?: boolean` — kill-switch; when `false`, the resolver passes the delegate's result through unchanged.
+    Defaults to reading `process.env.SF_GOVCLOUD_LEGACY_FALLBACK === '1'`.
+- **`CHAT_GENERATIONS_PROVIDER_HINT`** — Provider hint constant (`'salesforce-chat-generations'`) keying the injected
+  builder.
+- **`createChatGenerationsFallback`** — Convenience factory returning `{ connectivityResolver, languageModelBuilders }`
+  ready to spread into `createAgentManager` and `MastraHarnessFactory` constructors.
+- **`ChatGenerationsFallback`** — Return type of `createChatGenerationsFallback`
+  (`{ connectivityResolver: ChatGenerationsResolver, languageModelBuilders: Record<...> }`).
+
+## Deletion
+
+**This package is temporary.** When the Responses API is onboarded in GovCloud (expected within a few weeks):
+
+1. Remove the consumer bootstrap wiring (stop passing `languageModelBuilders` to `MastraHarnessFactory` and stop
+   wrapping the resolver in `ChatGenerationsResolver`), or set `SF_GOVCLOUD_LEGACY_FALLBACK` unset / `enabled: false` to
+   disable at runtime.
+2. Delete this package directory entirely.
+3. Remove `sfdx-agent-chat-generations` from `.github/workflows/version-bump.yml` and the root `README.md` monorepo
+   index, then run `npm install` to drop it from the lockfile.
+
+See [`DELETION.md`](DELETION.md) for the full deletion runbook.
+
+## Development
+
+```bash
+# Build
+npm run build -w @salesforce/sfdx-agent-chat-generations
+
+# Test
+npm run test -w @salesforce/sfdx-agent-chat-generations
+
+# Lint
+npm run lint -w @salesforce/sfdx-agent-chat-generations
+```

package/dist/chat-generations-language-model.d.ts

@@ -0,0 +1,16 @@
+import type { LanguageModelV3 } from '@ai-sdk/provider';
+import type { MastraLanguageModelBuilderContext } from '@salesforce/sfdx-agent-harness-mastra';
+/**
+ * Builds a bare `LanguageModelV3` that speaks the Salesforce LLM Gateway's legacy
+ * `chat/generations` wire shape (the only LLM path onboarded in GovCloud). The model
+ * POSTs `{ messages, generation_settings, model, system_prompt_strategy }` to
+ * `${baseUrl}/chat/generations{,/stream}`, reads the SSE / JSON `generation_details`
+ * envelope through {@link GPT5ResponseProcessor}, and maps the result to V3
+ * content / stream parts. GPT-5 is the only ported processor.
+ *
+ * The wire loop is inlined here (no gateway-client delegate): request-body assembly,
+ * the `/chat/generations{,/stream}` endpoint paths, and the SSE read loop are the
+ * pieces the deleted `RealLLMGatewayClient` owned; the V3 mapping is the piece the
+ * deleted `SalesforceMastraModelGateway` owned.
+ */
+export declare function buildChatGenerationsLanguageModel(ctx: MastraLanguageModelBuilderContext): LanguageModelV3;

package/dist/chat-generations-language-model.js

@@ -0,0 +1,402 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { createParser } from 'eventsource-parser';
+import { MimeType } from './chat-request.js';
+import { GPT5ResponseProcessor } from './gpt5-response-processor.js';
+import { createSSEEventHandler } from './sse-parser.js';
+/**
+ * Builds a bare `LanguageModelV3` that speaks the Salesforce LLM Gateway's legacy
+ * `chat/generations` wire shape (the only LLM path onboarded in GovCloud). The model
+ * POSTs `{ messages, generation_settings, model, system_prompt_strategy }` to
+ * `${baseUrl}/chat/generations{,/stream}`, reads the SSE / JSON `generation_details`
+ * envelope through {@link GPT5ResponseProcessor}, and maps the result to V3
+ * content / stream parts. GPT-5 is the only ported processor.
+ *
+ * The wire loop is inlined here (no gateway-client delegate): request-body assembly,
+ * the `/chat/generations{,/stream}` endpoint paths, and the SSE read loop are the
+ * pieces the deleted `RealLLMGatewayClient` owned; the V3 mapping is the piece the
+ * deleted `SalesforceMastraModelGateway` owned.
+ */
+export function buildChatGenerationsLanguageModel(ctx) {
+    return {
+        specificationVersion: 'v3',
+        provider: 'salesforce-chat-generations',
+        get modelId() {
+            return ctx.getInfo().nativeModelId;
+        },
+        supportedUrls: {},
+        doGenerate: (options) => doGenerate(options, ctx),
+        doStream: (options) => doStream(options, ctx),
+    };
+}
+async function doGenerate(options, ctx) {
+    const { getInfo, innerFetch } = ctx;
+    const info = getInfo();
+    const body = buildRequestBody(options, info.nativeModelId);
+    const response = await innerFetch(`${info.baseUrl}/chat/generations`, {
+        method: 'POST',
+        headers: await buildHeaders(info.getHeaders),
+        body: JSON.stringify(body),
+        signal: options.abortSignal,
+    });
+    if (!response.ok) {
+        throw await gatewayError(response);
+    }
+    const raw = (await response.json());
+    const { generatedText, toolInvocations, usage: responseUsage, finishReason: rawFinishReason, } = new GPT5ResponseProcessor().processRawChatResponse(raw);
+    const content = [];
+    if (generatedText) {
+        content.push({ type: 'text', text: generatedText });
+    }
+    for (const tool of toolInvocations ?? []) {
+        content.push({
+            type: 'tool-call',
+            toolCallId: tool.id,
+            toolName: tool.function.name,
+            input: tool.function.arguments,
+        });
+    }
+    const sawToolCalls = (toolInvocations ?? []).length > 0;
+    return {
+        content,
+        finishReason: mapFinishReason(rawFinishReason, sawToolCalls),
+        usage: mapUsage(responseUsage),
+        warnings: [],
+    };
+}
+async function doStream(options, ctx) {
+    const { getInfo, logBus, innerFetch } = ctx;
+    const info = getInfo();
+    const body = buildRequestBody(options, info.nativeModelId);
+    const response = await innerFetch(`${info.baseUrl}/chat/generations/stream`, {
+        method: 'POST',
+        headers: await buildHeaders(info.getHeaders),
+        body: JSON.stringify(body),
+        signal: options.abortSignal,
+    });
+    if (!response.ok) {
+        throw await gatewayError(response);
+    }
+    // Stage 1 — read the response body (a ReadableStream<Uint8Array>) through
+    // eventsource-parser into RawChatChunks. Faithfully mirrors the deleted
+    // RealLLMGatewayClient.requestStream: feed each decoded chunk to the parser and
+    // drain the shared queue as an async generator.
+    const responseBody = response.body;
+    const modelId = info.nativeModelId;
+    async function* rawChunks() {
+        if (!responseBody) {
+            return;
+        }
+        const decoder = new TextDecoder();
+        const queue = [];
+        const parser = createParser({
+            onEvent: createSSEEventHandler(queue, undefined, ({ chunk, reason }) => {
+                logBus?.warn('SSE parse error', { modelId, chunk, reason });
+            }),
+        });
+        for await (const bytes of responseBody) {
+            parser.feed(decoder.decode(bytes, { stream: true }));
+            while (queue.length > 0) {
+                yield queue.shift();
+            }
+        }
+    }
+    // Stage 2 — the GPT-5 processor turns RawChatChunks into normalized ChatStreamChunks
+    // (tool-call accumulation + the trailing usage-only chunk).
+    const processed = new GPT5ResponseProcessor().processRawChatStream(rawChunks());
+    // Stage 3 — map each ChatStreamChunk onto the V3 text-start / text-delta / text-end /
+    // tool-call / finish lifecycle (lifted verbatim from the deleted bridge's doStream).
+    let sawToolCalls = false;
+    let textSpanOpen = false;
+    let textSpanId = 0;
+    const stream = new ReadableStream({
+        start: async (controller) => {
+            try {
+                // V3 requires a `usage` field on `finish`; leave undefined here so we can
+                // detect a stream that ended without a usage chunk (W-22692131).
+                let lastUsage;
+                for await (const chunk of processed) {
+                    if (chunk.generatedText && !chunk.done) {
+                        if (!textSpanOpen) {
+                            controller.enqueue({ type: 'text-start', id: `text-${textSpanId}` });
+                            textSpanOpen = true;
+                        }
+                        controller.enqueue({
+                            type: 'text-delta',
+                            delta: chunk.generatedText,
+                            id: `text-${textSpanId}`,
+                        });
+                    }
+                    if (chunk.toolInvocations?.length) {
+                        // Close any open text span before emitting tool calls so text after
+                        // tools gets a new span id (AI SDK v5 lifecycle).
+                        if (textSpanOpen) {
+                            controller.enqueue({ type: 'text-end', id: `text-${textSpanId}` });
+                            textSpanOpen = false;
+                            textSpanId++;
+                        }
+                        sawToolCalls = true;
+                        for (const tool of chunk.toolInvocations) {
+                            controller.enqueue({
+                                type: 'tool-call',
+                                toolCallId: tool.id,
+                                toolName: tool.function.name,
+                                input: tool.function.arguments,
+                            });
+                        }
+                    }
+                    if (chunk.usage) {
+                        lastUsage = mapUsage(chunk.usage);
+                    }
+                    if (chunk.done) {
+                        if (textSpanOpen) {
+                            controller.enqueue({ type: 'text-end', id: `text-${textSpanId}` });
+                        }
+                        const finishReason = mapFinishReason(chunk.finishReason, sawToolCalls);
+                        if (lastUsage === undefined) {
+                            logBus?.warn('chat/generations stream ended without a usage chunk', {
+                                modelId,
+                                finishReason: chunk.finishReason,
+                            });
+                        }
+                        controller.enqueue({
+                            type: 'finish',
+                            finishReason,
+                            usage: lastUsage ?? mapUsage(undefined),
+                        });
+                        controller.close();
+                        return;
+                    }
+                }
+                controller.close();
+            }
+            catch (error) {
+                // Mid-stream failures are yielded, not thrown (harness contract + deleted bridge).
+                controller.enqueue({ type: 'error', error });
+                controller.close();
+            }
+        },
+    });
+    return { stream };
+}
+/**
+ * Assembles the outbound request body: the translated `ChatRequest` plus the
+ * `model` + `system_prompt_strategy` augmentation the gateway requires (from the
+ * deleted client's `chat` / `chatStream`).
+ */
+function buildRequestBody(options, nativeModelId) {
+    return {
+        ...buildChatRequest(options),
+        model: nativeModelId,
+        system_prompt_strategy: 'use_model_parameter',
+    };
+}
+function buildChatRequest(options) {
+    const messages = translatePrompt(options.prompt);
+    const tools = translateTools(options);
+    const chatRequest = {
+        messages,
+        generation_settings: {
+            max_tokens: options.maxOutputTokens,
+            temperature: options.temperature,
+            stop_sequences: options.stopSequences,
+            frequency_penalty: options.frequencyPenalty,
+            presence_penalty: options.presencePenalty,
+        },
+    };
+    if (tools.length > 0) {
+        chatRequest.tools = tools;
+    }
+    return chatRequest;
+}
+function translatePrompt(prompt) {
+    return prompt.flatMap((message) => {
+        switch (message.role) {
+            case 'system':
+                return { role: 'system', content: message.content };
+            case 'user': {
+                const content = message.content
+                    .filter((p) => p.type === 'text')
+                    .map((p) => p.text)
+                    .join('');
+                const files = message.content
+                    .filter((p) => p.type === 'file')
+                    .map((p) => toChatMessageFile(p));
+                const msg = { role: 'user', content };
+                if (files.length > 0) {
+                    msg.files = files;
+                }
+                return msg;
+            }
+            case 'assistant': {
+                const textParts = message.content
+                    .filter((p) => p.type === 'text')
+                    .map((p) => p.text)
+                    .join('');
+                const toolInvocations = message.content
+                    .filter((p) => p.type === 'tool-call')
+                    .map((tc) => ({
+                    id: tc.toolCallId,
+                    function: {
+                        name: tc.toolName,
+                        arguments: typeof tc.input === 'string' ? tc.input : JSON.stringify(tc.input ?? {}),
+                    },
+                }));
+                const msg = { role: 'assistant', content: textParts };
+                if (toolInvocations.length > 0) {
+                    msg.tool_invocations = toolInvocations;
+                }
+                return msg;
+            }
+            case 'tool':
+                // V3's `tool` role content can carry `tool-approval-response` parts alongside
+                // `tool-result` parts. We never surface tool-approval-request to consumers, so
+                // approval-response parts don't arrive in practice — filter defensively so the
+                // wire stays forward-compatible with future approval flows.
+                return message.content
+                    .filter((part) => part.type === 'tool-result')
+                    .map((part) => ({
+                    role: 'tool',
+                    content: toolResultOutputToString(part.output),
+                    tool_call_id: part.toolCallId,
+                    tool_call_name: part.toolName,
+                }));
+        }
+    });
+}
+/**
+ * Translates an AI SDK V3 user file part into the gateway's {@link ChatMessageFile}.
+ * v1 only supports base64-string `data`; non-string data (`Uint8Array` / `URL`) and
+ * MIME types outside the gateway allowlist are rejected — both indicate a caller that
+ * bypassed the harness input mapping (which validates caps pre-stream).
+ */
+function toChatMessageFile(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.`);
+    }
+    if (!isSupportedMimeType(part.mediaType)) {
+        throw new Error(`Unsupported file media type "${part.mediaType}". Supported types: ${Object.values(MimeType).join(', ')}.`);
+    }
+    const file = {
+        // The gateway wants a per-file handle; it is wire-opaque, so a direct Web Crypto
+        // UUID is sufficient here (W-23560954: temporary fallback, id is a wire-opaque handle).
+        fileId: globalThis.crypto.randomUUID(),
+        mimeType: part.mediaType,
+        dataType: 'base64',
+        data: part.data,
+    };
+    if (part.filename !== undefined) {
+        file.fileName = part.filename;
+    }
+    return file;
+}
+function toolResultOutputToString(output) {
+    switch (output.type) {
+        case 'text':
+        case 'error-text':
+            return output.value;
+        case 'json':
+        case 'error-json':
+            return JSON.stringify(output.value);
+        case 'content':
+            return output.value
+                .filter((v) => v.type === 'text')
+                .map((v) => v.text)
+                .join('');
+        case 'execution-denied':
+            return output.reason ?? 'tool execution denied';
+    }
+}
+function translateTools(options) {
+    if (!options.tools)
+        return [];
+    return options.tools
+        .filter((t) => t.type === 'function')
+        .map((tool) => ({
+        type: 'function',
+        function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.inputSchema,
+        },
+    }));
+}
+/** Narrows an arbitrary media-type string to the gateway's {@link MimeType} allowlist. */
+function isSupportedMimeType(mediaType) {
+    return Object.values(MimeType).includes(mediaType);
+}
+/**
+ * Builds the outbound header set. The resolver's `getHeaders()` already carries the
+ * full set (Authorization, tenant, feature id, …); we only default `Content-Type` and
+ * let a resolver-supplied `Content-Type` win. Called per request so JWT rotation lands
+ * on the next call (never cached at builder construction).
+ */
+async function buildHeaders(getHeaders) {
+    const resolved = await getHeaders();
+    return { 'Content-Type': 'application/json;charset=utf-8', ...resolved };
+}
+/**
+ * Reads a non-2xx response and produces a clear error carrying the status and a
+ * bounded snippet of the body. Pre-stream failure: thrown from `doGenerate` /
+ * rejected from `doStream` (matches the deleted client, which threw on non-2xx before
+ * any stream was returned).
+ */
+async function gatewayError(response) {
+    let snippet;
+    try {
+        snippet = (await response.text()).slice(0, 500);
+    }
+    catch {
+        snippet = '<unreadable body>';
+    }
+    return new Error(`chat/generations request failed with status ${response.status}: ${snippet}`);
+}
+/**
+ * Maps a gateway raw finish-reason string to the V3 `LanguageModelV3FinishReason`
+ * (a `{ unified, raw }` object). When `sawToolCalls` is true, `unified` is forced to
+ * `'tool-calls'` regardless of what the gateway returned — the gateway can report a
+ * non-tool reason even with tool invocations present, and Mastra's downstream loop
+ * relies on `'tool-calls'` to schedule the next step. Handles both GPT
+ * (`stop` / `length` / `tool_calls`) and legacy Claude (`max_tokens` / `tool_use`)
+ * vocabularies for robustness.
+ */
+function mapFinishReason(rawFinishReason, sawToolCalls) {
+    const unified = sawToolCalls
+        ? 'tool-calls'
+        : rawFinishReason === 'length' || rawFinishReason === 'max_tokens'
+            ? 'length'
+            : rawFinishReason === 'tool_calls' || rawFinishReason === 'tool_use'
+                ? 'tool-calls'
+                : 'stop';
+    return { unified, raw: rawFinishReason };
+}
+/**
+ * Maps the gateway's flat `TokenUsage` to the V3 nested `LanguageModelV3Usage`.
+ * Reasoning tokens roll up into `outputTokens.total` (V3 spec:
+ * `outputTokens.total = text + reasoning`) so GPT-5 reasoning tokens survive Mastra's
+ * recomputed flat `totalTokens`. Cache tokens populate `inputTokens.cacheRead` /
+ * `cacheWrite` without rolling into `inputTokens.total`.
+ */
+function mapUsage(responseUsage) {
+    const outputTokens = responseUsage?.outputTokens;
+    const reasoningTokens = responseUsage?.reasoningTokens;
+    const outputTotal = outputTokens === undefined && reasoningTokens === undefined
+        ? undefined
+        : (outputTokens ?? 0) + (reasoningTokens ?? 0);
+    return {
+        inputTokens: {
+            total: responseUsage?.inputTokens,
+            noCache: undefined,
+            cacheRead: responseUsage?.cacheReadTokens,
+            cacheWrite: responseUsage?.cacheWriteTokens,
+        },
+        outputTokens: {
+            total: outputTotal,
+            text: outputTokens,
+            reasoning: reasoningTokens,
+        },
+    };
+}
+//# sourceMappingURL=chat-generations-language-model.js.map

package/dist/chat-generations-resolver.d.ts

@@ -0,0 +1,72 @@
+import type { AgentConfig, AgentConnectivityResolver, ResolvedConnectivity } from '@salesforce/sfdx-agent-sdk';
+/**
+ * Provider hint for the GovCloud `chat/generations` wire shape. Used to dispatch
+ * to the injected builder in the Mastra harness factory.
+ */
+export declare const CHAT_GENERATIONS_PROVIDER_HINT = "salesforce-chat-generations";
+/**
+ * Configuration options for the GovCloud `chat/generations` resolver decorator.
+ */
+export interface ChatGenerationsResolverOptions {
+    /**
+     * The consumer's real connectivity resolver (e.g., AFV's VibesAgentConnectivityResolver
+     * or DefaultAgentConnectivityResolver). The decorator wraps this delegate and rewrites
+     * its connectivity bag onto the GovCloud `chat/generations` path.
+     */
+    delegate: AgentConnectivityResolver;
+    /**
+     * GovCloud gateway base URL, e.g., `'https://dev.api.gov.salesforce.com/ai/gpt/v1'`.
+     * This replaces the delegate's `baseUrl` when the resolver is enabled.
+     */
+    baseUrl: string;
+    /**
+     * Optional extra headers required by GovCloud `chat/generations`
+     * (e.g., `{ 'x-salesforce-region': 'us-gov-east-1' }`). These are merged
+     * on top of the delegate's headers, with extras winning on key conflict.
+     * Verify with live GovCloud endpoint whether any headers beyond standard
+     * gateway headers are required (W-23560954).
+     */
+    extraHeaders?: Record<string, string>;
+    /**
+     * Kill-switch: when `false`, the resolver passes the delegate's result through
+     * unchanged (zero behavior change). When unset, defaults to reading
+     * `process.env.SF_GOVCLOUD_LEGACY_FALLBACK === '1'`.
+     */
+    enabled?: boolean;
+}
+/**
+ * Decorator over a consumer's real `AgentConnectivityResolver` that flips an existing
+ * connectivity bag onto the GovCloud `chat/generations` path. Reuses the delegate's
+ * `getHeaders()` verbatim (JWT rotation + tenant/feature headers for free), merging
+ * any GovCloud-required extras on top.
+ *
+ * **Why a decorator, not a subclass:** `DefaultAgentConnectivityResolver` and
+ * `buildSalesforceGatewayHeaders` are not on the SDK's public surface — subclassing
+ * would force new public exports. This decorator wraps the consumer's existing
+ * resolver (e.g., AFV's `VibesAgentConnectivityResolver`) and reuses its `getHeaders()`
+ * without needing SDK-internal header helpers.
+ *
+ * **Gating is explicit, not auto-detected.** Do not sniff `instanceUrl` for `.gov` —
+ * domain research showed that's unreliable (org instanceUrl differs from gateway host,
+ * and civilian gov is `*.salesforce.com`, indistinguishable from commercial). The
+ * consumer knows they're deploying to GovCloud; they wire this decorator at construction.
+ *
+ * **Consumer must set a GPT `modelId`.** The SDK default (Claude Sonnet 4.6) will not
+ * resolve in GovCloud. AFV must bind `AgentConfig.modelId` to a GovCloud-provisioned
+ * `sfdc_ai__DefaultGPT*` model id.
+ *
+ * @example
+ * ```ts
+ * const resolver = new ChatGenerationsResolver({
+ *   delegate: myExistingResolver,
+ *   baseUrl: 'https://dev.api.gov.salesforce.com/ai/gpt/v1',
+ *   extraHeaders: { 'x-salesforce-region': 'us-gov-east-1' },
+ * });
+ * const manager = await createAgentManager(storageRoot, factory, { connectivityResolver: resolver });
+ * ```
+ */
+export declare class ChatGenerationsResolver implements AgentConnectivityResolver {
+    private readonly opts;
+    constructor(opts: ChatGenerationsResolverOptions);
+    resolve(projectRoot: string, config: AgentConfig): Promise<ResolvedConnectivity>;
+}