@fgv/ts-extras 5.1.0-16 → 5.1.0-18

package/lib/packlets/ai-assist/streamingAdapters/common.js

@@ -0,0 +1,81 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openSseConnection = openSseConnection;
+exports.validateEventPayload = validateEventPayload;
+/**
+ * Shared infrastructure for the per-format streaming adapters: HTTP connection
+ * helper, common config and request-params types, and a typed-validation
+ * helper for SSE event payloads.
+ *
+ * @packageDocumentation
+ */
+const ts_utils_1 = require("@fgv/ts-utils");
+/**
+ * Opens an SSE-style POST connection. Returns the underlying Response on a
+ * 2xx; failures (network, non-2xx, missing body) surface as Result.fail
+ * carrying the body text.
+ *
+ * @internal
+ */
+async function openSseConnection(url, headers, body, logger, signal) {
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.detail(`AI streaming request: POST ${url}`);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers: Object.assign({ 'Content-Type': 'application/json', Accept: 'text/event-stream' }, headers),
+            body: JSON.stringify(body),
+            signal
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error(`AI streaming request failed: ${detail}`);
+        return (0, ts_utils_1.fail)(`AI streaming request failed: ${detail}`);
+    }
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => 'unknown error');
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error(`AI streaming API returned ${response.status}: ${errorText}`);
+        return (0, ts_utils_1.fail)(`AI streaming API returned ${response.status}: ${errorText}`);
+    }
+    if (!response.body) {
+        return (0, ts_utils_1.fail)('AI streaming API returned an empty body');
+    }
+    return (0, ts_utils_1.succeed)(response);
+}
+/**
+ * Validates a parsed SSE event payload against a typed shape, returning the
+ * validated value or `undefined` if validation fails. Adapters use the
+ * `undefined` return to skip unrecognized event shapes — the same lenient
+ * behavior the inline casts had, but with a real type-checked path on the
+ * happy case.
+ *
+ * @internal
+ */
+function validateEventPayload(json, validator) {
+    const result = validator.validate(json);
+    return result.isSuccess() ? result.value : undefined;
+}
+//# sourceMappingURL=common.js.map

package/lib/packlets/ai-assist/streamingAdapters/gemini.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Streaming adapter for Gemini's `streamGenerateContent` endpoint. Gemini
+ * emits no explicit tool-progress events even when `google_search` is
+ * enabled — grounding metadata arrives attached to text chunks — so this
+ * adapter never yields `tool-event`s.
+ *
+ * @packageDocumentation
+ */
+import { type Logging, Result } from '@fgv/ts-utils';
+import { AiPrompt, type AiServerToolConfig, type IAiStreamEvent, type IChatMessage } from '../model';
+import { IStreamApiConfig } from './common';
+/**
+ * Issues a streaming Gemini request and returns the unified-event iterable
+ * on success.
+ *
+ * @internal
+ */
+export declare function callGeminiStream(config: IStreamApiConfig, prompt: AiPrompt, messagesBefore: ReadonlyArray<IChatMessage> | undefined, temperature: number, tools: ReadonlyArray<AiServerToolConfig> | undefined, logger?: Logging.ILogger, signal?: AbortSignal): Promise<Result<AsyncIterable<IAiStreamEvent>>>;
+//# sourceMappingURL=gemini.d.ts.map

package/lib/packlets/ai-assist/streamingAdapters/gemini.js

@@ -0,0 +1,163 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callGeminiStream = callGeminiStream;
+/**
+ * Streaming adapter for Gemini's `streamGenerateContent` endpoint. Gemini
+ * emits no explicit tool-progress events even when `google_search` is
+ * enabled — grounding metadata arrives attached to text chunks — so this
+ * adapter never yields `tool-event`s.
+ *
+ * @packageDocumentation
+ */
+const ts_utils_1 = require("@fgv/ts-utils");
+const chatRequestBuilders_1 = require("../chatRequestBuilders");
+const sseParser_1 = require("../sseParser");
+const toolFormats_1 = require("../toolFormats");
+const common_1 = require("./common");
+const geminiStreamPart = ts_utils_1.Validators.object({ text: ts_utils_1.Validators.string.optional() }, { options: { optionalFields: ['text'] } });
+const geminiStreamContent = ts_utils_1.Validators.object({ parts: ts_utils_1.Validators.arrayOf(geminiStreamPart).optional() }, { options: { optionalFields: ['parts'] } });
+const geminiStreamCandidate = ts_utils_1.Validators.object({
+    content: geminiStreamContent.optional(),
+    finishReason: ts_utils_1.Validators.string.optional()
+}, { options: { optionalFields: ['content', 'finishReason'] } });
+const geminiStreamChunk = ts_utils_1.Validators.object({
+    candidates: ts_utils_1.Validators.arrayOf(geminiStreamCandidate)
+});
+// ============================================================================
+// Stream translator
+// ============================================================================
+/**
+ * Translates a Gemini streamGenerateContent SSE stream into unified events.
+ *
+ * @internal
+ */
+function translateGeminiStream(response) {
+    return __asyncGenerator(this, arguments, function* translateGeminiStream_1() {
+        var _a, e_1, _b, _c;
+        var _d;
+        let fullText = '';
+        let truncated = false;
+        let receivedFinishReason = false;
+        try {
+            /* c8 ignore next - body is non-null at this point per openSseConnection */
+            if (!response.body)
+                return yield __await(void 0);
+            try {
+                for (var _e = true, _f = __asyncValues((0, sseParser_1.readSseEvents)(response.body)), _g; _g = yield __await(_f.next()), _a = _g.done, !_a; _e = true) {
+                    _c = _g.value;
+                    _e = false;
+                    const message = _c;
+                    const json = (0, sseParser_1.parseSseEventJson)(message.data);
+                    if (json === undefined) {
+                        continue;
+                    }
+                    const chunk = (0, common_1.validateEventPayload)(json, geminiStreamChunk);
+                    const candidate = chunk === null || chunk === void 0 ? void 0 : chunk.candidates[0];
+                    if (!candidate) {
+                        continue;
+                    }
+                    const parts = (_d = candidate.content) === null || _d === void 0 ? void 0 : _d.parts;
+                    if (parts) {
+                        for (const part of parts) {
+                            if (typeof part.text === 'string' && part.text.length > 0) {
+                                fullText += part.text;
+                                yield yield __await({ type: 'text-delta', delta: part.text });
+                            }
+                        }
+                    }
+                    const finishReason = candidate.finishReason;
+                    if (typeof finishReason === 'string' && finishReason.length > 0) {
+                        truncated = finishReason === 'MAX_TOKENS';
+                        receivedFinishReason = true;
+                    }
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (!_e && !_a && (_b = _f.return)) yield __await(_b.call(_f));
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+        }
+        catch (err) {
+            yield yield __await({ type: 'error', message: err instanceof Error ? err.message : String(err) });
+            return yield __await(void 0);
+        }
+        if (receivedFinishReason) {
+            yield yield __await({ type: 'done', truncated, fullText });
+        }
+        else {
+            yield yield __await({ type: 'error', message: 'Gemini stream ended without a finishReason' });
+        }
+    });
+}
+// ============================================================================
+// Per-format request caller
+// ============================================================================
+/**
+ * Issues a streaming Gemini request and returns the unified-event iterable
+ * on success.
+ *
+ * @internal
+ */
+async function callGeminiStream(config, prompt, messagesBefore, temperature, tools, logger, signal) {
+    const url = `${config.baseUrl}/models/${config.model}:streamGenerateContent?alt=sse`;
+    const contents = (0, chatRequestBuilders_1.buildGeminiContents)(prompt, { head: messagesBefore });
+    const body = {
+        systemInstruction: { parts: [{ text: prompt.system }] },
+        contents,
+        generationConfig: { temperature }
+    };
+    if (tools && tools.length > 0) {
+        body.tools = (0, toolFormats_1.toGeminiTools)(tools);
+    }
+    const headers = { 'x-goog-api-key': config.apiKey };
+    /* c8 ignore next 3 - optional logger diagnostic output */
+    if (logger) {
+        const toolTypes = tools && tools.length > 0 ? tools.map((t) => t.type).join(',') : 'none';
+        logger.info(`Gemini streaming: model=${config.model}, tools=${toolTypes}`);
+    }
+    const conn = await (0, common_1.openSseConnection)(url, headers, body, logger, signal);
+    return conn.onSuccess((response) => (0, ts_utils_1.succeed)(translateGeminiStream(response)));
+}
+//# sourceMappingURL=gemini.js.map

package/lib/packlets/ai-assist/streamingAdapters/openaiChat.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Streaming adapter for OpenAI Chat Completions (also used for Groq, Mistral,
+ * and other Chat-Completions-compatible providers when no tools are
+ * requested).
+ *
+ * @packageDocumentation
+ */
+import { type Logging, Result } from '@fgv/ts-utils';
+import { AiPrompt, type IAiStreamEvent, type IChatMessage } from '../model';
+import { IStreamApiConfig } from './common';
+/**
+ * Issues a streaming Chat Completions request and returns the unified-event
+ * iterable on success.
+ *
+ * @internal
+ */
+export declare function callOpenAiChatStream(config: IStreamApiConfig, prompt: AiPrompt, messagesBefore: ReadonlyArray<IChatMessage> | undefined, temperature: number, logger?: Logging.ILogger, signal?: AbortSignal): Promise<Result<AsyncIterable<IAiStreamEvent>>>;
+//# sourceMappingURL=openaiChat.d.ts.map

package/lib/packlets/ai-assist/streamingAdapters/openaiChat.js

@@ -0,0 +1,152 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callOpenAiChatStream = callOpenAiChatStream;
+/**
+ * Streaming adapter for OpenAI Chat Completions (also used for Groq, Mistral,
+ * and other Chat-Completions-compatible providers when no tools are
+ * requested).
+ *
+ * @packageDocumentation
+ */
+const ts_utils_1 = require("@fgv/ts-utils");
+const chatRequestBuilders_1 = require("../chatRequestBuilders");
+const sseParser_1 = require("../sseParser");
+const common_1 = require("./common");
+// eslint-disable-next-line @rushstack/no-new-null
+const stringOrNull = ts_utils_1.Validators.isA('string-or-null', 
+// eslint-disable-next-line @rushstack/no-new-null
+(v) => typeof v === 'string' || v === null);
+const openAiChatStreamChoice = ts_utils_1.Validators.object({
+    delta: ts_utils_1.Validators.object({ content: ts_utils_1.Validators.string }, { options: { optionalFields: ['content'] } }).optional(),
+    finish_reason: stringOrNull.optional()
+}, { options: { optionalFields: ['delta', 'finish_reason'] } });
+const openAiChatStreamChunk = ts_utils_1.Validators.object({
+    choices: ts_utils_1.Validators.arrayOf(openAiChatStreamChoice)
+});
+// ============================================================================
+// Stream translator
+// ============================================================================
+/**
+ * Translates an OpenAI Chat Completions SSE stream into unified events.
+ *
+ * @internal
+ */
+function translateOpenAiChatStream(response) {
+    return __asyncGenerator(this, arguments, function* translateOpenAiChatStream_1() {
+        var _a, e_1, _b, _c;
+        var _d;
+        let fullText = '';
+        let truncated = false;
+        let receivedDone = false;
+        try {
+            /* c8 ignore next - body is non-null at this point per openSseConnection */
+            if (!response.body)
+                return yield __await(void 0);
+            try {
+                for (var _e = true, _f = __asyncValues((0, sseParser_1.readSseEvents)(response.body)), _g; _g = yield __await(_f.next()), _a = _g.done, !_a; _e = true) {
+                    _c = _g.value;
+                    _e = false;
+                    const message = _c;
+                    const json = (0, sseParser_1.parseSseEventJson)(message.data);
+                    if (json === undefined) {
+                        // [DONE] sentinel or unparseable; skip
+                        continue;
+                    }
+                    const chunk = (0, common_1.validateEventPayload)(json, openAiChatStreamChunk);
+                    const choice = chunk === null || chunk === void 0 ? void 0 : chunk.choices[0];
+                    if (!choice) {
+                        continue;
+                    }
+                    const delta = (_d = choice.delta) === null || _d === void 0 ? void 0 : _d.content;
+                    if (typeof delta === 'string' && delta.length > 0) {
+                        fullText += delta;
+                        yield yield __await({ type: 'text-delta', delta });
+                    }
+                    const finish = choice.finish_reason;
+                    if (typeof finish === 'string' && finish.length > 0) {
+                        truncated = finish === 'length';
+                        receivedDone = true;
+                    }
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (!_e && !_a && (_b = _f.return)) yield __await(_b.call(_f));
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+        }
+        catch (err) {
+            yield yield __await({ type: 'error', message: err instanceof Error ? err.message : String(err) });
+            return yield __await(void 0);
+        }
+        if (receivedDone) {
+            yield yield __await({ type: 'done', truncated, fullText });
+        }
+        else {
+            yield yield __await({ type: 'error', message: 'OpenAI stream ended without a finish_reason' });
+        }
+    });
+}
+// ============================================================================
+// Per-format request caller
+// ============================================================================
+/**
+ * Issues a streaming Chat Completions request and returns the unified-event
+ * iterable on success.
+ *
+ * @internal
+ */
+async function callOpenAiChatStream(config, prompt, messagesBefore, temperature, logger, signal) {
+    const url = `${config.baseUrl}/chat/completions`;
+    const messages = (0, chatRequestBuilders_1.buildMessages)(prompt.system, (0, chatRequestBuilders_1.buildOpenAiChatUserContent)(prompt), {
+        head: messagesBefore
+    });
+    const body = { model: config.model, messages, temperature, stream: true };
+    const headers = { Authorization: `Bearer ${config.apiKey}` };
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`OpenAI streaming completion: model=${config.model}`);
+    const conn = await (0, common_1.openSseConnection)(url, headers, body, logger, signal);
+    return conn.onSuccess((response) => (0, ts_utils_1.succeed)(translateOpenAiChatStream(response)));
+}
+//# sourceMappingURL=openaiChat.js.map

package/lib/packlets/ai-assist/streamingAdapters/openaiResponses.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Streaming adapter for the OpenAI / xAI Responses API. This is the format
+ * used when server-side tools (e.g. web_search) are requested — Chat
+ * Completions doesn't support tool progress events, but the Responses API
+ * does.
+ *
+ * @packageDocumentation
+ */
+import { type Logging, Result } from '@fgv/ts-utils';
+import { AiPrompt, type AiServerToolConfig, type IAiStreamEvent, type IChatMessage } from '../model';
+import { IStreamApiConfig } from './common';
+/**
+ * Issues a streaming Responses API request (with tools) and returns the
+ * unified-event iterable on success.
+ *
+ * @internal
+ */
+export declare function callOpenAiResponsesStream(config: IStreamApiConfig, prompt: AiPrompt, tools: ReadonlyArray<AiServerToolConfig>, messagesBefore: ReadonlyArray<IChatMessage> | undefined, temperature: number, logger?: Logging.ILogger, signal?: AbortSignal): Promise<Result<AsyncIterable<IAiStreamEvent>>>;
+//# sourceMappingURL=openaiResponses.d.ts.map

package/lib/packlets/ai-assist/streamingAdapters/openaiResponses.js

@@ -0,0 +1,166 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callOpenAiResponsesStream = callOpenAiResponsesStream;
+/**
+ * Streaming adapter for the OpenAI / xAI Responses API. This is the format
+ * used when server-side tools (e.g. web_search) are requested — Chat
+ * Completions doesn't support tool progress events, but the Responses API
+ * does.
+ *
+ * @packageDocumentation
+ */
+const ts_utils_1 = require("@fgv/ts-utils");
+const chatRequestBuilders_1 = require("../chatRequestBuilders");
+const sseParser_1 = require("../sseParser");
+const toolFormats_1 = require("../toolFormats");
+const common_1 = require("./common");
+const responsesDeltaPayload = ts_utils_1.Validators.object({
+    delta: ts_utils_1.Validators.string
+});
+const responsesCompletedPayload = ts_utils_1.Validators.object({
+    response: ts_utils_1.Validators.object({ status: ts_utils_1.Validators.string.optional() }, { options: { optionalFields: ['status'] } })
+});
+const responsesErrorInner = ts_utils_1.Validators.object({ message: ts_utils_1.Validators.string.optional() }, { options: { optionalFields: ['message'] } });
+const responsesErrorPayload = ts_utils_1.Validators.object({
+    error: responsesErrorInner.optional(),
+    message: ts_utils_1.Validators.string.optional()
+}, { options: { optionalFields: ['error', 'message'] } });
+// ============================================================================
+// Stream translator
+// ============================================================================
+/**
+ * Translates an OpenAI Responses API SSE stream into unified events.
+ *
+ * @internal
+ */
+function translateOpenAiResponsesStream(response) {
+    return __asyncGenerator(this, arguments, function* translateOpenAiResponsesStream_1() {
+        var _a, e_1, _b, _c;
+        var _d, _e, _f;
+        let fullText = '';
+        let truncated = false;
+        let completed = false;
+        try {
+            /* c8 ignore next - body is non-null at this point per openSseConnection */
+            if (!response.body)
+                return yield __await(void 0);
+            try {
+                for (var _g = true, _h = __asyncValues((0, sseParser_1.readSseEvents)(response.body)), _j; _j = yield __await(_h.next()), _a = _j.done, !_a; _g = true) {
+                    _c = _j.value;
+                    _g = false;
+                    const message = _c;
+                    const eventName = message.event;
+                    if (eventName === 'response.output_text.delta') {
+                        const payload = (0, common_1.validateEventPayload)((0, sseParser_1.parseSseEventJson)(message.data), responsesDeltaPayload);
+                        const delta = payload === null || payload === void 0 ? void 0 : payload.delta;
+                        if (typeof delta === 'string' && delta.length > 0) {
+                            fullText += delta;
+                            yield yield __await({ type: 'text-delta', delta });
+                        }
+                    }
+                    else if (eventName === 'response.web_search_call.in_progress') {
+                        yield yield __await({ type: 'tool-event', toolType: 'web_search', phase: 'started' });
+                    }
+                    else if (eventName === 'response.web_search_call.completed') {
+                        yield yield __await({ type: 'tool-event', toolType: 'web_search', phase: 'completed' });
+                    }
+                    else if (eventName === 'response.completed') {
+                        const payload = (0, common_1.validateEventPayload)((0, sseParser_1.parseSseEventJson)(message.data), responsesCompletedPayload);
+                        truncated = (payload === null || payload === void 0 ? void 0 : payload.response.status) === 'incomplete';
+                        completed = true;
+                    }
+                    else if (eventName === 'response.failed' || eventName === 'error') {
+                        const payload = (0, common_1.validateEventPayload)((0, sseParser_1.parseSseEventJson)(message.data), responsesErrorPayload);
+                        const errMsg = (_f = (_e = (_d = payload === null || payload === void 0 ? void 0 : payload.error) === null || _d === void 0 ? void 0 : _d.message) !== null && _e !== void 0 ? _e : payload === null || payload === void 0 ? void 0 : payload.message) !== null && _f !== void 0 ? _f : 'Responses API stream failed';
+                        yield yield __await({ type: 'error', message: errMsg });
+                        return yield __await(void 0);
+                    }
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (!_g && !_a && (_b = _h.return)) yield __await(_b.call(_h));
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+        }
+        catch (err) {
+            yield yield __await({ type: 'error', message: err instanceof Error ? err.message : String(err) });
+            return yield __await(void 0);
+        }
+        if (completed) {
+            yield yield __await({ type: 'done', truncated, fullText });
+        }
+        else {
+            yield yield __await({ type: 'error', message: 'Responses API stream ended without a completed event' });
+        }
+    });
+}
+// ============================================================================
+// Per-format request caller
+// ============================================================================
+/**
+ * Issues a streaming Responses API request (with tools) and returns the
+ * unified-event iterable on success.
+ *
+ * @internal
+ */
+async function callOpenAiResponsesStream(config, prompt, tools, messagesBefore, temperature, logger, signal) {
+    const url = `${config.baseUrl}/responses`;
+    const input = (0, chatRequestBuilders_1.buildMessages)(prompt.system, (0, chatRequestBuilders_1.buildOpenAiResponsesUserContent)(prompt), {
+        head: messagesBefore
+    });
+    const body = {
+        model: config.model,
+        input,
+        tools: (0, toolFormats_1.toResponsesApiTools)(tools),
+        temperature,
+        stream: true
+    };
+    const headers = { Authorization: `Bearer ${config.apiKey}` };
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`OpenAI Responses streaming: model=${config.model}, tools=${tools.map((t) => t.type).join(',')}`);
+    const conn = await (0, common_1.openSseConnection)(url, headers, body, logger, signal);
+    return conn.onSuccess((response) => (0, ts_utils_1.succeed)(translateOpenAiResponsesStream(response)));
+}
+//# sourceMappingURL=openaiResponses.js.map

package/lib/packlets/ai-assist/streamingAdapters/proxy.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Streaming adapter for a caller-provided proxy server. Unlike the
+ * provider-specific adapters, the proxy speaks our own unified vocabulary
+ * directly: each `data:` line is a JSON-serialized {@link AiAssist.IAiStreamEvent},
+ * so this adapter only validates the event-type discriminator and forwards.
+ *
+ * @packageDocumentation
+ */
+import { Result } from '@fgv/ts-utils';
+import { type IAiStreamEvent } from '../model';
+import { IProviderCompletionStreamParams } from './common';
+/**
+ * Calls the streaming chat endpoint on a proxy server instead of calling
+ * the provider directly from the browser.
+ *
+ * @remarks
+ * Proxy contract:
+ * - Endpoint: `POST ${proxyUrl}/api/ai/completion-stream`
+ * - Request body: same JSON as `/api/ai/completion` plus `"stream": true`
+ * - Response: `Content-Type: text/event-stream`; body is the unified
+ *   {@link AiAssist.IAiStreamEvent} JSON-serialized one event per SSE `data:` line
+ *   (no `event:` line needed since the type discriminator is in the JSON).
+ * - Error response (when the proxy can't even start): JSON `{error: string}`
+ *   with a non-2xx status, surfaced as `proxy: ${error}`.
+ *
+ * The proxy server is responsible for opening the upstream SSE connection,
+ * translating provider-native events to the unified vocabulary, and
+ * forwarding events as they arrive (no buffering). The library does not
+ * ship a proxy implementation.
+ *
+ * @public
+ */
+export declare function callProxiedCompletionStream(proxyUrl: string, params: IProviderCompletionStreamParams): Promise<Result<AsyncIterable<IAiStreamEvent>>>;
+//# sourceMappingURL=proxy.d.ts.map