@salesforce/sfdx-agent-chat-generations 0.0.1

package/dist/index.js

@@ -0,0 +1,52 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+// W-23560954: GovCloud `chat/generations` fallback exports.
+export { buildChatGenerationsLanguageModel } from './chat-generations-language-model.js';
+export { ChatGenerationsResolver, CHAT_GENERATIONS_PROVIDER_HINT } from './chat-generations-resolver.js';
+import { buildChatGenerationsLanguageModel } from './chat-generations-language-model.js';
+import { ChatGenerationsResolver, CHAT_GENERATIONS_PROVIDER_HINT, } from './chat-generations-resolver.js';
+/**
+ * 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 function createChatGenerationsFallback(options) {
+    return {
+        connectivityResolver: new ChatGenerationsResolver(options),
+        languageModelBuilders: {
+            [CHAT_GENERATIONS_PROVIDER_HINT]: buildChatGenerationsLanguageModel,
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/response-processor.d.ts

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

package/dist/response-processor.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export {};
+//# sourceMappingURL=response-processor.js.map

package/dist/sse-parser.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Filter all events that aren't generations or errors
+ *
+ * See: https://git.soma.salesforce.com/pages/tech-enablement/einstein/docs/gateway/streaming/#how-it-works
+ */
+export declare function shouldSkipEvent(event: string): boolean;
+/**
+ * Check if this is an error event from the gateway.
+ *
+ * See: https://git.soma.salesforce.com/pages/tech-enablement/einstein/docs/gateway/streaming/#error-chunks
+ */
+export declare function isErrorEvent(event: string | undefined): boolean;
+/**
+ * Creates an SSE event handler for parsing LLMG API responses.
+ * This handler is shared between the streaming client and test utilities.
+ *
+ * @param queue - Array to push parsed chunks into
+ * @param onDone - Optional callback when [DONE] sentinel is received
+ * @param onParseError - Optional callback invoked when a chunk fails to parse. The callback
+ *     receives the (truncated) raw chunk and a short reason string so consumers can surface a
+ *     log or metric without the parser depending on a logging bus.
+ * @returns Event handler function for eventsource-parser
+ */
+export declare function createSSEEventHandler<T>(queue: T[], onDone?: () => void, onParseError?: (ctx: {
+    chunk: string;
+    reason: string;
+}) => void): (event: {
+    event?: string;
+    data?: string;
+}) => void;
+/**
+ * Parses raw SSE event strings into array of parsed objects.
+ * Used for testing - synchronous version that processes complete SSE string.
+ *
+ * This function uses the same parsing logic as RealLLMGatewayClient.requestStream()
+ * to ensure tests validate the production parser behavior.
+ *
+ * @param sseString - Raw SSE events (e.g., "event: generation\ndata: {...}\n\n")
+ * @returns Array of parsed objects (RawChatChunk or error objects)
+ *
+ * @example
+ * ```typescript
+ * const chunks = parseSSEString<RawChatChunk>(`
+ * event: generation
+ * data: {"id":"test","generation_details":{"generations":[{"role":"assistant","content":"Hello"}],"parameters":{"provider":"openai"}}}
+ *
+ * event: generation
+ * data: [DONE]
+ *
+ * `);
+ * ```
+ */
+export declare function parseSSEString<T>(sseString: string): T[];

package/dist/sse-parser.js

@@ -0,0 +1,116 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+// Ported from 3f694898^:packages/llm-gateway-sdk/src/sse-parser.ts (W-23560954).
+import { createParser } from 'eventsource-parser';
+/**
+ * Filter all events that aren't generations or errors
+ *
+ * See: https://git.soma.salesforce.com/pages/tech-enablement/einstein/docs/gateway/streaming/#how-it-works
+ */
+export function shouldSkipEvent(event) {
+    return !['generation', 'error'].includes(event);
+}
+/**
+ * Check if this is an error event from the gateway.
+ *
+ * See: https://git.soma.salesforce.com/pages/tech-enablement/einstein/docs/gateway/streaming/#error-chunks
+ */
+export function isErrorEvent(event) {
+    return event === 'error';
+}
+/**
+ * Creates an SSE event handler for parsing LLMG API responses.
+ * This handler is shared between the streaming client and test utilities.
+ *
+ * @param queue - Array to push parsed chunks into
+ * @param onDone - Optional callback when [DONE] sentinel is received
+ * @param onParseError - Optional callback invoked when a chunk fails to parse. The callback
+ *     receives the (truncated) raw chunk and a short reason string so consumers can surface a
+ *     log or metric without the parser depending on a logging bus.
+ * @returns Event handler function for eventsource-parser
+ */
+export function createSSEEventHandler(queue, onDone, onParseError) {
+    let done = false;
+    return ({ event, data }) => {
+        // Stop processing events after DONE sentinel
+        if (done)
+            return;
+        if (!data || !event)
+            return;
+        if (shouldSkipEvent(event))
+            return;
+        // Handle error events from the gateway - add to queue wrapped in error object
+        if (isErrorEvent(event)) {
+            try {
+                const errorData = JSON.parse(data);
+                queue.push({
+                    error: errorData,
+                });
+            }
+            catch {
+                // Malformed error data - create a parse error event
+                queue.push({
+                    error: {
+                        messageCode: 'E99999',
+                        errorCode: 'PARSE_ERROR',
+                        message: `Failed to parse error event: ${data}`,
+                    },
+                });
+                onParseError?.({ chunk: truncateChunk(data), reason: 'malformed error event JSON' });
+            }
+            return;
+        }
+        const trimmed = data.trim();
+        // Stop parsing when DONE sentinel is received
+        if (trimmed === '[DONE]' || trimmed === 'DONE') {
+            done = true;
+            onDone?.();
+            return;
+        }
+        try {
+            const parsed = JSON.parse(data);
+            queue.push(parsed);
+        }
+        catch {
+            onParseError?.({ chunk: truncateChunk(data), reason: 'unparseable generation chunk' });
+        }
+    };
+}
+function truncateChunk(chunk, max = 200) {
+    return chunk.length > max ? `${chunk.slice(0, max)}…` : chunk;
+}
+/**
+ * Parses raw SSE event strings into array of parsed objects.
+ * Used for testing - synchronous version that processes complete SSE string.
+ *
+ * This function uses the same parsing logic as RealLLMGatewayClient.requestStream()
+ * to ensure tests validate the production parser behavior.
+ *
+ * @param sseString - Raw SSE events (e.g., "event: generation\ndata: {...}\n\n")
+ * @returns Array of parsed objects (RawChatChunk or error objects)
+ *
+ * @example
+ * ```typescript
+ * const chunks = parseSSEString<RawChatChunk>(`
+ * event: generation
+ * data: {"id":"test","generation_details":{"generations":[{"role":"assistant","content":"Hello"}],"parameters":{"provider":"openai"}}}
+ *
+ * event: generation
+ * data: [DONE]
+ *
+ * `);
+ * ```
+ */
+export function parseSSEString(sseString) {
+    const queue = [];
+    // Create the parser using the shared event handler
+    const parser = createParser({
+        onEvent: createSSEEventHandler(queue),
+    });
+    // Feed the entire SSE string to the parser
+    parser.feed(sseString);
+    return queue;
+}
+//# sourceMappingURL=sse-parser.js.map

package/dist/tool-arg-normalize.d.ts

@@ -0,0 +1 @@
+export declare function normalizeToolArguments(args: string | null | undefined): string;

package/dist/tool-arg-normalize.js

@@ -0,0 +1,10 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+// Ported from 3f694898^:packages/llm-gateway-sdk/src/models/tool-arg-normalize.ts (W-23560954).
+// Normalize empty/null/undefined tool-call args to "{}" so consumers can JSON.parse.
+export function normalizeToolArguments(args) {
+    return args ? args : '{}';
+}
+//# sourceMappingURL=tool-arg-normalize.js.map

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@salesforce/sfdx-agent-chat-generations",
+  "version": "0.0.1",
+  "description": "Temporary GovCloud chat/generations fallback for @salesforce/sfdx-agent-harness-mastra",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "tsc --build --clean",
+    "clean:all": "npm run clean && rimraf node_modules",
+    "postclean": "rimraf coverage && rimraf dist",
+    "format": "prettier --write .",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "showcoverage": "open ./coverage/lcov-report/index.html",
+    "test": "tsc --build ./test/tsconfig.json && vitest run --coverage"
+  },
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "!dist/test",
+    "CHANGELOG.md",
+    "LICENSE.txt"
+  ],
+  "dependencies": {
+    "@ai-sdk/provider": "^3.0.10",
+    "eventsource-parser": "^3.0.0"
+  },
+  "peerDependencies": {
+    "@salesforce/sfdx-agent-sdk": "0.37.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.36.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@salesforce/sfdx-agent-sdk": "0.37.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.36.0",
+    "@types/node": "^22.20.0",
+    "@vitest/coverage-istanbul": "^4.1.10",
+    "@vitest/eslint-plugin": "^1.6.22",
+    "eslint": "^10.7.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-typescript": "^4.4.5",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-n": "^18.2.1",
+    "globals": "^17.6.0",
+    "lint-staged": "^17.0.7",
+    "prettier": "^3.9.4",
+    "rimraf": "^6.1.3",
+    "tsx": "^4.23.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.63.0",
+    "vitest": "^4.1.8"
+  },
+  "engines": {
+    "node": ">=22.22.0"
+  },
+  "lint-staged": {
+    "*.{js,jsx,ts,tsx,json,md}": [
+      "prettier --write"
+    ]
+  }
+}