@salesforce/sfdx-agent-chat-generations 0.0.1

package/dist/chat-generations-resolver.js

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * Provider hint for the GovCloud `chat/generations` wire shape. Used to dispatch
+ * to the injected builder in the Mastra harness factory.
+ */
+export const CHAT_GENERATIONS_PROVIDER_HINT = 'salesforce-chat-generations';
+/**
+ * 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 class ChatGenerationsResolver {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async resolve(projectRoot, config) {
+        // Delegate to the wrapped resolver to get the base connectivity bag
+        const inner = await this.opts.delegate.resolve(projectRoot, config);
+        // Kill-switch: when disabled, pass through the delegate's result unchanged
+        const enabled = this.opts.enabled ?? process.env['SF_GOVCLOUD_LEGACY_FALLBACK'] === '1';
+        if (!enabled) {
+            return inner;
+        }
+        const innerInfo = inner.modelConnectivityInfo;
+        // Rewrite the connectivity bag: flip `baseUrl` and `providerHint` onto the
+        // GovCloud `chat/generations` path, but leave `model` and `nativeModelId`
+        // untouched (the delegate already resolved the consumer's GPT `modelId` to
+        // the `sfdc_ai__DefaultGPT*` wire id the builder will send in the body).
+        return {
+            ...inner,
+            modelConnectivityInfo: {
+                ...innerInfo,
+                baseUrl: this.opts.baseUrl,
+                providerHint: CHAT_GENERATIONS_PROVIDER_HINT,
+                // Reuse the delegate's getHeaders VERBATIM. This closure re-invokes
+                // `innerInfo.getHeaders()` on every call (per-call freshness contract),
+                // then merges GovCloud-required extras on top (extras win on conflict).
+                // Do NOT snapshot the header map at resolve time — JWT rotation and
+                // feature-id swaps require re-evaluation per request.
+                getHeaders: async () => {
+                    const delegateHeaders = await innerInfo.getHeaders();
+                    return { ...delegateHeaders, ...(this.opts.extraHeaders ?? {}) };
+                },
+            },
+        };
+    }
+}
+//# sourceMappingURL=chat-generations-resolver.js.map

package/dist/chat-request.d.ts

@@ -0,0 +1,117 @@
+export type ChatRequest = {
+    messages: ChatMessageIn[];
+    generation_settings: GenerationSettings;
+    reasoning_settings?: ReasoningSettings;
+    tools?: ChatCompletionFunctionTool[];
+    tool_config?: ToolConfig;
+};
+type ReasoningSettings = {
+    /**
+     * Indicates whether to include thinking/reasoning content in the response. Defaults to `false`.
+     */
+    return_reasoning?: boolean;
+    /**
+     * Parameter that guides the model on the budget to use for reasoning tokens to generate before creating a response to the prompt.
+     *
+     * Only supported in OpenAI and Gemini models.
+     * See: https://git.soma.salesforce.com/pages/tech-enablement/einstein/docs/gateway/reasoning/
+     */
+    reasoning_budget?: ReasoningBudget;
+};
+type ReasoningBudget = {
+    effort: 'minimal' | 'low' | 'medium' | 'high';
+} | {
+    tokens: number;
+};
+export type ChatMessageIn = {
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+    files?: ChatMessageFile[];
+    tool_call_id?: string;
+    tool_call_name?: string;
+    tool_invocations?: ToolInvocationIn[];
+};
+/**
+ * MIME types accepted on the multimodal path.
+ * Any other value triggers a `LLMGClientError('MODEL_DOES_NOT_SUPPORT_FORMAT')` error.
+ */
+export declare const MimeType: {
+    readonly Png: "image/png";
+    readonly Jpeg: "image/jpeg";
+    readonly Pdf: "application/pdf";
+};
+export type MimeType = (typeof MimeType)[keyof typeof MimeType];
+/**
+ * One image or PDF attached to a `ChatMessageIn`.
+ * v1 only supports `dataType: 'base64'`
+ * Allowed `mimeType` values are PNG, JPEG, and PDF — see {@link MimeType}.
+ */
+export type ChatMessageFile = {
+    /** Caller-supplied unique identifier (UUID recommended). */
+    fileId: string;
+    /** MIME type. Only PNG, JPEG, and PDF are accepted by the SDK in v1. */
+    mimeType: MimeType;
+    /** Transport. Only `'base64'` is supported in v1. */
+    dataType: 'base64';
+    /** Base64-encoded file bytes (no `data:` URI prefix). */
+    data: string;
+    /** Optional human-readable filename. Surfaces to providers that display it (e.g. Data Cloud). */
+    fileName?: string;
+};
+export type ToolInvocationIn = {
+    id: string;
+    function: {
+        name: string;
+        arguments: string;
+    };
+};
+export type GenerationSettings = {
+    max_tokens?: number;
+    temperature?: number;
+    /**
+     * An array of stop sequences to be used. The generated text is cut at the end of the earliest occurrence of a stop sequence.
+     */
+    stop_sequences?: string[];
+    /**
+     * The frequency penalty to be used. Min value is 0.0; max value is 1.0. Can reduce the repetitiveness of generated tokens. The higher the value, the stronger a penalty is applied to previously present tokens, proportional to how many times they have already appeared in the prompt or prior generation.
+     */
+    frequency_penalty?: number;
+    /**
+     * The presence penalty to be used. Min value is 0.0; max value is 1.0. Can reduce the repetitiveness of generated tokens. Behaves similarly to frequency_penalty, except that this penalty is applied equally to all tokens that have already appeared, regardless of their exact frequencies.
+     */
+    presence_penalty?: number;
+    /**
+     * Dictionary of any other parameters that are required by the specified provider. Values are passed as is to the provider so that the request can include parameters that are unique to a provider.
+     */
+    parameters?: object;
+};
+export type ChatCompletionFunctionTool = {
+    type?: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters?: {
+            type: 'object';
+            properties?: Record<string, LlmgPropertyDefinition>;
+            required?: string[];
+        };
+        strict?: boolean;
+    };
+};
+export type LlmgPropertyDefinition = ToolPropertyDefinition & {
+    enum?: string[];
+    items?: LlmgPropertyDefinition;
+};
+type ToolPropertyDefinition = {
+    type: string;
+    description?: string;
+    properties?: Record<string, ToolPropertyDefinition>;
+};
+export type ToolConfig = {
+    mode: 'auto' | 'none' | 'tool' | 'any';
+    allowed_tools?: {
+        type: 'function';
+        name: string;
+    }[];
+};
+export {};

package/dist/chat-request.js

@@ -0,0 +1,14 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * MIME types accepted on the multimodal path.
+ * Any other value triggers a `LLMGClientError('MODEL_DOES_NOT_SUPPORT_FORMAT')` error.
+ */
+export const MimeType = {
+    Png: 'image/png',
+    Jpeg: 'image/jpeg',
+    Pdf: 'application/pdf',
+};
+//# sourceMappingURL=chat-request.js.map

package/dist/chat-response.d.ts

@@ -0,0 +1,119 @@
+type Response<T> = {
+    status: number;
+    data: T;
+};
+export type ChatResponse = Response<ChatResponseData>;
+/**
+ * Union of all known finish reasons across supported models.
+ * GPT-5 uses: 'stop', 'length', 'tool_calls'
+ */
+export type FinishReason = 'stop' | 'length' | 'tool_calls';
+export type ChatResponseData = {
+    generatedText?: string;
+    finishReason?: FinishReason;
+    error?: LLMGError;
+    toolInvocations?: ToolInvocation[];
+    usage?: TokenUsage;
+};
+export type ChatStreamResponse = Response<AsyncGenerator<ChatStreamChunk>>;
+export type TokenUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    reasoningTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+};
+export type ChatStreamChunk = {
+    generatedText: string;
+    done: boolean;
+    finishReason?: FinishReason;
+    error?: LLMGError;
+    toolInvocations?: ToolInvocation[];
+    usage?: TokenUsage;
+};
+export type ToolInvocation = {
+    id: string;
+    function: {
+        name: string;
+        arguments: string;
+    };
+};
+export type RawToolInvocation = {
+    id: string;
+    function: {
+        name: string;
+        arguments: string;
+    };
+    thought_signature?: string | null;
+};
+export type LLMGErrorParameter = {
+    name: string;
+    value: unknown;
+};
+export type LLMGExtendedErrorDetails = {
+    providerStatusCode?: number;
+    [key: string]: unknown;
+};
+export type LLMGError = {
+    /**
+     * See: https://git.soma.salesforce.com/pages/tech-enablement/einstein/docs/gateway/error-codes/
+     */
+    messageCode: string;
+    errorCode: string;
+    message: string;
+    extendedErrorDetails?: LLMGExtendedErrorDetails[];
+    parameters?: LLMGErrorParameter[];
+};
+type GPT5TokenUsageDetails = {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    completion_tokens_details?: {
+        reasoning_tokens?: number;
+    };
+};
+type GPT5Generation = {
+    id?: string;
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+    thought_signature?: string | null;
+    contents?: Array<{
+        type: 'thinking_summary' | 'redacted_thinking' | 'text';
+        content: string;
+    }> | null;
+    timestamp?: number;
+    parameters?: {
+        finish_reason?: 'stop' | 'length' | 'tool_calls' | null;
+        refusal?: string | null;
+        index?: number;
+    };
+    tool_invocations?: RawToolInvocation[] | null;
+};
+type GPT5GenerationParameters = {
+    provider: 'openai';
+    created?: number;
+    model?: string;
+    usage?: GPT5TokenUsageDetails;
+};
+type GPT5RawChatChunk = {
+    id: string;
+    generation_details: {
+        generations: GPT5Generation[];
+        parameters: GPT5GenerationParameters;
+    };
+    other_details?: unknown | null;
+};
+export type LLMGErrorEvent = {
+    error: LLMGError;
+};
+export type RawChatChunk = GPT5RawChatChunk | LLMGErrorEvent;
+/**
+ * Type guard to check if a raw chunk is an error event.
+ */
+export declare function isLLMGErrorEvent(chunk: RawChatChunk): chunk is LLMGErrorEvent;
+/**
+ * Type guard to check if a raw response is from GPT-5.
+ */
+export declare function isGPT5Response(response: RawChatChunk): response is GPT5RawChatChunk;
+export {};

package/dist/chat-response.js

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+// =====================================================================================================================
+// ==== TYPE GUARDS
+// =====================================================================================================================
+/**
+ * Type guard to check if a raw chunk is an error event.
+ */
+export function isLLMGErrorEvent(chunk) {
+    return 'error' in chunk && typeof chunk.error === 'object' && 'errorCode' in chunk.error;
+}
+/**
+ * Type guard to check if a raw response is from GPT-5.
+ */
+export function isGPT5Response(response) {
+    const params = 'generation_details' in response ? response.generation_details?.parameters : undefined;
+    return params !== undefined && 'provider' in params && params.provider === 'openai';
+}
+//# sourceMappingURL=chat-response.js.map

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+export declare class LLMGClientError extends Error {
+    code: string;
+    httpStatus?: number;
+    constructor(message: string, code: string, options?: ErrorOptions & {
+        httpStatus?: number;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,18 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+// Ported from 3f694898^:packages/llm-gateway-sdk/src/errors.ts (W-23560954).
+// Minimal subset: the LLMGError shape lives in chat-response.ts; this file is currently
+// a placeholder for future error-handling needs.
+export class LLMGClientError extends Error {
+    code;
+    httpStatus;
+    constructor(message, code, options) {
+        super(message, options);
+        this.name = 'LLMGatewayClientError';
+        this.code = code;
+        this.httpStatus = options?.httpStatus;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/gpt5-response-processor.d.ts

@@ -0,0 +1,6 @@
+import type { ChatResponseData, ChatStreamChunk, RawChatChunk } from './chat-response.js';
+import type { ResponseProcessor } from './response-processor.js';
+export declare class GPT5ResponseProcessor implements ResponseProcessor {
+    processRawChatStream(rawStream: AsyncGenerator<RawChatChunk>): AsyncGenerator<ChatStreamChunk>;
+    processRawChatResponse(raw: RawChatChunk): ChatResponseData;
+}

package/dist/gpt5-response-processor.js

@@ -0,0 +1,189 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { isLLMGErrorEvent, isGPT5Response } from './chat-response.js';
+import { normalizeToolArguments } from './tool-arg-normalize.js';
+// Detect if this is the start of a new tool call (has id and name)
+function isToolCallStart(inv) {
+    return !!(inv.id && inv.function?.name);
+}
+// Convert accumulated tool call to normalized ToolInvocation
+function toToolInvocation(pending) {
+    return {
+        id: pending.id,
+        function: {
+            name: pending.name,
+            arguments: normalizeToolArguments(pending.argumentsBuffer),
+        },
+    };
+}
+export class GPT5ResponseProcessor {
+    async *processRawChatStream(rawStream) {
+        let pendingToolCall = null;
+        let capturedUsage;
+        let bufferedFinalChunk = null;
+        for await (const raw of rawStream) {
+            // Check for error events first
+            if (isLLMGErrorEvent(raw)) {
+                yield {
+                    generatedText: '',
+                    done: true,
+                    error: raw.error,
+                };
+                return; // Error events are terminal - stop processing
+            }
+            // Type guard ensures we have GPT5RawChatChunk from here on
+            if (!isGPT5Response(raw)) {
+                // This should never happen in practice, but we need to handle it for type safety
+                continue;
+            }
+            const generation = raw.generation_details?.generations?.[0];
+            // Check for usage chunk (empty generations with usage in parameters)
+            // Usage info comes in the final chunk.
+            //
+            // See: https://platform.openai.com/docs/api-reference/completions/object#completions-object-usage
+            if (!generation) {
+                const usage = raw.generation_details?.parameters.usage;
+                if (usage) {
+                    const inputTokens = usage.prompt_tokens ?? 0;
+                    const outputTokens = usage.completion_tokens ?? 0;
+                    const reasoningTokens = usage.completion_tokens_details?.reasoning_tokens;
+                    capturedUsage = {
+                        inputTokens,
+                        outputTokens,
+                        totalTokens: usage.total_tokens,
+                        ...(reasoningTokens ? { reasoningTokens } : {}),
+                    };
+                }
+                continue;
+            }
+            const finishReason = generation.parameters?.finish_reason;
+            const isDone = !!finishReason;
+            const content = generation.content || '';
+            const toolInvocation = generation.tool_invocations?.[0];
+            // NOTE (cristian):
+            // I haven't found any LLMG/OpenAI doc about this being a possible case,
+            // we are handling it just to be safe.
+            //
+            // If chunk has BOTH content and tool invocations, yield text first
+            if (content && toolInvocation) {
+                yield {
+                    generatedText: content,
+                    done: false,
+                };
+                // Continue to process tool invocation below
+            }
+            // Check for tool invocations
+            if (toolInvocation) {
+                if (isToolCallStart(toolInvocation)) {
+                    // Flush any pending tool call first
+                    if (pendingToolCall) {
+                        yield {
+                            generatedText: '',
+                            done: false,
+                            toolInvocations: [toToolInvocation(pendingToolCall)],
+                        };
+                    }
+                    // Start accumulating new tool call
+                    pendingToolCall = {
+                        id: toolInvocation.id,
+                        name: toolInvocation.function.name,
+                        argumentsBuffer: toolInvocation.function.arguments || '',
+                    };
+                }
+                else if (pendingToolCall) {
+                    // Continuation - append arguments
+                    pendingToolCall.argumentsBuffer += toolInvocation.function.arguments || '';
+                }
+                continue;
+            }
+            // Handle done signal - may come in a separate chunk without tool_invocations
+            // (e.g., finish_reason: "tool_calls" arrives after all tool fragments)
+            if (isDone && pendingToolCall) {
+                bufferedFinalChunk = {
+                    generatedText: '',
+                    done: true,
+                    finishReason: finishReason ?? undefined,
+                    toolInvocations: [toToolInvocation(pendingToolCall)],
+                };
+                pendingToolCall = null;
+                continue;
+            }
+            // Text content - yield immediately for low latency
+            // Note: If text content + toolInvocation was present, we already continued above,
+            // so this only handles text-only chunks or done signals without tools.
+            if (content || isDone) {
+                // For text content with done signal, buffer to capture usage later
+                if (isDone) {
+                    bufferedFinalChunk = {
+                        generatedText: content,
+                        done: true,
+                        finishReason: finishReason ?? undefined,
+                    };
+                }
+                else if (content) {
+                    yield {
+                        generatedText: content,
+                        done: false,
+                    };
+                }
+            }
+        }
+        // Stream ended - yield buffered final chunk WITHOUT usage, then usage chunk separately
+        if (bufferedFinalChunk) {
+            // Yield the content chunk first with done=false
+            yield {
+                ...bufferedFinalChunk,
+                done: false, // NOT the final chunk - usage chunk comes next
+            };
+        }
+        else if (pendingToolCall) {
+            // Stream ended with pending tool call (no finish_reason received)
+            yield {
+                generatedText: '',
+                done: false,
+                toolInvocations: [toToolInvocation(pendingToolCall)],
+            };
+        }
+        // ALWAYS yield a final usage chunk with done=true (even if usage is undefined)
+        // This ensures there's always exactly ONE chunk with done=true at the end
+        yield {
+            generatedText: '',
+            done: true, // This is the FINAL chunk
+            finishReason: bufferedFinalChunk?.finishReason,
+            usage: capturedUsage, // May be undefined if API didn't send usage
+        };
+    }
+    processRawChatResponse(raw) {
+        if (isLLMGErrorEvent(raw)) {
+            throw new Error(raw.error.message);
+        }
+        if (!isGPT5Response(raw)) {
+            throw new Error('Invalid response type for GPT-5 processor');
+        }
+        const generation = raw.generation_details?.generations?.[0];
+        const generatedText = generation?.content ?? '';
+        const finishReason = generation?.parameters?.finish_reason ?? undefined;
+        const toolInvocations = (generation?.tool_invocations ?? []).map((inv) => ({
+            id: inv.id,
+            function: {
+                name: inv.function.name,
+                arguments: normalizeToolArguments(inv.function.arguments),
+            },
+        }));
+        let usage;
+        const rawUsage = raw.generation_details?.parameters.usage;
+        if (rawUsage) {
+            const reasoningTokens = rawUsage.completion_tokens_details?.reasoning_tokens;
+            usage = {
+                inputTokens: rawUsage.prompt_tokens ?? 0,
+                outputTokens: rawUsage.completion_tokens ?? 0,
+                totalTokens: rawUsage.total_tokens,
+                ...(reasoningTokens ? { reasoningTokens } : {}),
+            };
+        }
+        return { generatedText, finishReason, toolInvocations, usage };
+    }
+}
+//# sourceMappingURL=gpt5-response-processor.js.map

package/dist/index.d.ts

@@ -0,0 +1,91 @@
+export { buildChatGenerationsLanguageModel } from './chat-generations-language-model.js';
+export { ChatGenerationsResolver, CHAT_GENERATIONS_PROVIDER_HINT } from './chat-generations-resolver.js';
+export type { ChatGenerationsResolverOptions } from './chat-generations-resolver.js';
+import type { MastraLanguageModelBuilder } from '@salesforce/sfdx-agent-harness-mastra';
+import { ChatGenerationsResolver, CHAT_GENERATIONS_PROVIDER_HINT, type ChatGenerationsResolverOptions } from './chat-generations-resolver.js';
+/**
+ * The return value of {@link createChatGenerationsFallback}, carrying a connectivity
+ * resolver decorator and a language-model builder ready to spread into
+ * `createAgentManager` and `MastraHarnessFactory`.
+ *
+ * @remarks
+ * Consumers wire the fallback at construction time, either explicitly (construct
+ * `ChatGenerationsResolver` and pass `languageModelBuilders` separately) or via the
+ * convenience factory (destructure its return and spread both fields). Both forms produce
+ * identical runtime wiring.
+ *
+ * @example Explicit construction
+ * ```ts
+ * const factory = new MastraHarnessFactory({
+ *   languageModelBuilders: {
+ *     [CHAT_GENERATIONS_PROVIDER_HINT]: buildChatGenerationsLanguageModel,
+ *   },
+ * });
+ * 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 });
+ * ```
+ *
+ * @example Convenience factory (preferred)
+ * ```ts
+ * const { connectivityResolver, languageModelBuilders } = createChatGenerationsFallback({
+ *   delegate: myExistingResolver,
+ *   baseUrl: 'https://dev.api.gov.salesforce.com/ai/gpt/v1',
+ *   extraHeaders: { 'x-salesforce-region': 'us-gov-east-1' },
+ * });
+ * const factory = new MastraHarnessFactory({ languageModelBuilders });
+ * const manager = await createAgentManager(storageRoot, factory, { connectivityResolver });
+ * ```
+ */
+export type ChatGenerationsFallback = {
+    /**
+     * The connectivity resolver decorator wrapping the consumer's delegate. Passes to
+     * `createAgentManager`'s `options.connectivityResolver` parameter.
+     */
+    connectivityResolver: ChatGenerationsResolver;
+    /**
+     * Language-model builder map keyed by `CHAT_GENERATIONS_PROVIDER_HINT`, ready to spread
+     * into `MastraHarnessFactory`'s `languageModelBuilders` constructor option. The value is
+     * typed explicitly as `MastraLanguageModelBuilder` so TS assignability checks succeed
+     * without widening.
+     */
+    languageModelBuilders: Record<typeof CHAT_GENERATIONS_PROVIDER_HINT, MastraLanguageModelBuilder>;
+};
+/**
+ * Convenience factory for constructing the GovCloud `chat/generations` fallback wiring.
+ * Returns a `{ connectivityResolver, languageModelBuilders }` object ready to spread into
+ * `createAgentManager` and `MastraHarnessFactory` constructors (W-23560954).
+ *
+ * @remarks
+ * This fallback routes all model traffic through the legacy GovCloud `chat/generations`
+ * wire shape. 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. The resolver decorator flips the delegate's `baseUrl` and
+ * `providerHint` onto the GovCloud path, and the injected language-model builder speaks
+ * the Salesforce-proprietary `chat/generations` wire contract.
+ *
+ * **This package is temporary** and will be deleted once the Responses API is onboarded
+ * in GovCloud (expected within a few weeks).
+ *
+ * @param options - Configuration for the resolver decorator (delegate + GovCloud base URL +
+ *   optional extra headers + optional enabled gate).
+ * @returns A `ChatGenerationsFallback` bag carrying both the resolver and builder map,
+ *   typed for direct assignability to the manager + factory.
+ *
+ * @example
+ * ```ts
+ * 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
+ * });
+ * const factory = new MastraHarnessFactory({ languageModelBuilders });
+ * const manager = await createAgentManager(storageRoot, factory, { connectivityResolver });
+ * // Agent MUST bind a GovCloud-provisioned GPT model:
+ * const agent = await manager.createAgent(projectRoot, { modelId: 'sfdc_ai__DefaultGPT4_8', ... });
+ * ```
+ */
+export declare function createChatGenerationsFallback(options: ChatGenerationsResolverOptions): ChatGenerationsFallback;