@salesforce/sfdx-agent-chat-generations

Temporary GovCloud chat/generations fallback for @salesforce/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 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

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

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)

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.

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 for the full deletion runbook.

Development

# 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