@seanhogg/builderforce-memory 2026.9.30 → 2026.9.31

package/src/wire/chatClient.ts

@@ -0,0 +1,196 @@
+/**
+ * The OpenAI-compatible chat-completions client — ONE request builder, error mapping
+ * and stream reader for every caller that speaks `/chat/completions`: this package's
+ * `OpenAIBridge` / `FetchBridge`, and any host that reaches models through an
+ * OpenAI-compatible gateway (tools, streamed tool-call deltas, vendor extras).
+ *
+ * The body carries exactly what the request states — no sampling defaults are added
+ * here, so a routing gateway that picks the model and limits can be called with none.
+ * Callers that want defaults (the bridges) state them.
+ *
+ * Zero-dependency and engine-free (part of the `/wire` subpath).
+ */
+
+import { readSseDataFrames } from './sse.js';
+
+/** An OpenAI-compatible chat message. */
+export interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    /** Text, or an OpenAI multi-part array (text + `image_url`, …). */
+    content?: string | null | unknown[];
+    tool_calls?: unknown;
+    tool_call_id?: string;
+    [k: string]: unknown;
+}
+
+/** An OpenAI-compatible function-tool schema. */
+export interface ChatToolSchema {
+    type: 'function';
+    function: { name: string; description: string; parameters: Record<string, unknown> };
+}
+
+export interface ChatRequest {
+    messages: ChatMessage[];
+    tools?: ChatToolSchema[];
+    model?: string;
+    maxTokens?: number;
+    temperature?: number;
+    topP?: number;
+    /**
+     * On a stream, ask for the closing usage block (`stream_options.include_usage`).
+     * Opt-in: not every OpenAI-compatible server accepts the field.
+     */
+    includeUsage?: boolean;
+    /** Vendor extras merged into the body last (a routing `provider`, `response_format`, …). */
+    extra?: Record<string, unknown>;
+}
+
+export interface ChatToolCall {
+    id?: string;
+    type?: string;
+    function?: { name?: string; arguments?: string };
+}
+
+export interface ChatResult {
+    /** The reply text ('' when there was none — e.g. a tool-call-only turn). */
+    content: string;
+    /** True when the server sent text content (a string), false when it sent none. */
+    hasTextContent: boolean;
+    toolCalls: ChatToolCall[];
+    finishReason?: string;
+    /** The model the server reports having used. */
+    model?: string;
+    /** The raw `usage` object, when the server sent one — read it with `readUsageFields`. */
+    usage?: unknown;
+}
+
+/** Incremental events of a streamed completion. */
+export type ChatStreamEvent =
+    | { type: 'text-delta'; delta: string }
+    | { type: 'tool-call'; index: number; id?: string; name?: string; argsDelta?: string }
+    | { type: 'done'; result: ChatResult };
+
+export interface ChatClient {
+    /** The OpenAI-style base, e.g. `https://api.openai.com/v1`; `/chat/completions` is appended. */
+    baseUrl: string;
+    apiKey: string;
+    /** Abort a request after this long. Default: no limit beyond the caller's signal. */
+    timeoutMs?: number;
+}
+
+/** A non-2xx answer, with the status and (bounded) body kept apart for the caller's message. */
+export class ChatCompletionError extends Error {
+    constructor(readonly status: number, readonly body: string) {
+        super(`chat completion failed with HTTP ${status}: ${body}`);
+        this.name = 'ChatCompletionError';
+    }
+}
+
+const ERROR_BODY_CHARS = 300;
+
+function chatBody(req: ChatRequest, stream: boolean): string {
+    return JSON.stringify({
+        ...(req.model ? { model: req.model } : {}),
+        messages: req.messages,
+        ...(req.tools?.length ? { tools: req.tools, tool_choice: 'auto' } : {}),
+        ...(typeof req.maxTokens === 'number' ? { max_tokens: req.maxTokens } : {}),
+        ...(typeof req.temperature === 'number' ? { temperature: req.temperature } : {}),
+        ...(typeof req.topP === 'number' ? { top_p: req.topP } : {}),
+        ...(stream ? { stream: true } : {}),
+        // Without include_usage a streamed response carries no usage block at all.
+        ...(stream && req.includeUsage ? { stream_options: { include_usage: true } } : {}),
+        ...(req.extra ?? {}),
+    });
+}
+
+async function post(client: ChatClient, req: ChatRequest, stream: boolean, signal?: AbortSignal): Promise<Response> {
+    const timeout = client.timeoutMs ? AbortSignal.timeout(client.timeoutMs) : undefined;
+    const res = await fetch(`${client.baseUrl.replace(/\/$/, '')}/chat/completions`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${client.apiKey}`,
+            ...(stream ? { Accept: 'text/event-stream' } : {}),
+        },
+        body: chatBody(req, stream),
+        signal: signal && timeout ? AbortSignal.any([signal, timeout]) : (signal ?? timeout),
+    });
+    if (!res.ok || (stream && !res.body)) {
+        const body = await res.text().catch(() => '');
+        throw new ChatCompletionError(res.status, body.slice(0, ERROR_BODY_CHARS));
+    }
+    return res;
+}
+
+/** One non-streamed completion. Throws {@link ChatCompletionError} on a non-2xx answer. */
+export async function chatComplete(client: ChatClient, req: ChatRequest, signal?: AbortSignal): Promise<ChatResult> {
+    const res = await post(client, req, false, signal);
+    const json = (await res.json().catch(() => null)) as {
+        model?: unknown;
+        usage?: unknown;
+        choices?: Array<{ message?: { content?: unknown; tool_calls?: unknown }; finish_reason?: string }>;
+    } | null;
+    const choice = json?.choices?.[0];
+    const msg = choice?.message;
+    return {
+        content: typeof msg?.content === 'string' ? msg.content : '',
+        hasTextContent: typeof msg?.content === 'string',
+        toolCalls: Array.isArray(msg?.tool_calls) ? (msg.tool_calls as ChatToolCall[]) : [],
+        finishReason: choice?.finish_reason,
+        ...(typeof json?.model === 'string' ? { model: json.model } : {}),
+        ...(json?.usage !== undefined ? { usage: json.usage } : {}),
+    };
+}
+
+/**
+ * A streamed completion as events: text and tool-call deltas as they arrive, then one
+ * `done` carrying the assembled result (tool-call arguments concatenated per index).
+ */
+export async function* chatStream(client: ChatClient, req: ChatRequest, signal?: AbortSignal): AsyncGenerator<ChatStreamEvent> {
+    const res = await post(client, req, true, signal);
+    let content = '';
+    let finishReason: string | undefined;
+    let model: string | undefined;
+    let usage: unknown;
+    const calls: Array<{ id?: string; name?: string; args: string }> = [];
+
+    for await (const frame of readSseDataFrames(res.body!)) {
+        const chunk = frame as {
+            model?: unknown;
+            usage?: unknown;
+            choices?: Array<{
+                delta?: { content?: unknown; tool_calls?: Array<{ index?: number; id?: string; function?: { name?: string; arguments?: string } }> };
+                finish_reason?: string;
+            }>;
+        };
+        if (typeof chunk.model === 'string') model = chunk.model;
+        if (chunk.usage) usage = chunk.usage;
+        const choice = chunk.choices?.[0];
+        if (!choice) continue;
+        if (choice.finish_reason) finishReason = choice.finish_reason;
+        const delta = choice.delta;
+        if (typeof delta?.content === 'string' && delta.content) {
+            content += delta.content;
+            yield { type: 'text-delta', delta: delta.content };
+        }
+        for (const tc of Array.isArray(delta?.tool_calls) ? delta.tool_calls : []) {
+            const index = typeof tc.index === 'number' ? tc.index : 0;
+            const acc = (calls[index] ??= { args: '' });
+            if (tc.id) acc.id = tc.id;
+            if (tc.function?.name) acc.name = tc.function.name;
+            const argsDelta = tc.function?.arguments;
+            if (typeof argsDelta === 'string') acc.args += argsDelta;
+            yield { type: 'tool-call', index, id: tc.id, name: tc.function?.name, argsDelta };
+        }
+    }
+
+    const result: ChatResult = {
+        content,
+        hasTextContent: content !== '',
+        finishReason,
+        toolCalls: calls.filter(Boolean).map((t) => ({ id: t.id, type: 'function', function: { name: t.name, arguments: t.args } })),
+        ...(model ? { model } : {}),
+        ...(usage !== undefined ? { usage } : {}),
+    };
+    yield { type: 'done', result };
+}

package/src/wire/index.ts

@@ -13,6 +13,8 @@
  * Zero-dependency and engine-free: the `@seanhogg/builderforce-memory/wire` subpath.
  */
 
-export { parseSseDataLine, parseSseDataFrames, readSseDataFrames, isSseDoneLine } from './sse.js';
+export { sseDataPayload, parseSseDataLine, parseSseDataFrames, readSseDataPayloads, readSseDataFrames, isSseDoneLine } from './sse.js';
 export { finiteNumber, readUsageFields, AnthropicStreamUsage } from './usage.js';
 export type { UsageFields, AnthropicUsageTotals } from './usage.js';
+export { chatComplete, chatStream, ChatCompletionError } from './chatClient.js';
+export type { ChatClient, ChatMessage, ChatToolSchema, ChatRequest, ChatToolCall, ChatResult, ChatStreamEvent } from './chatClient.js';

package/src/wire/sse.ts

@@ -2,24 +2,38 @@
  * Server-Sent-Events `data:` framing.
  *
  * Every consumer of an SSE LLM stream does the same line-level dance: trim the line,
- * keep only `data:` frames, skip empty payloads, `JSON.parse` the rest and skip
- * anything malformed — and stop at the `[DONE]` sentinel, which ends an
- * OpenAI-style stream (anything after it is not part of the response).
+ * keep only `data:` frames, and stop at the `[DONE]` sentinel, which ends an
+ * OpenAI-style stream (anything after it is not part of the response). JSON streams
+ * then parse each payload and skip empty or malformed ones.
  *
  * The line rule is `slice(5).trim()`, which accepts both `data: {…}` and the
  * spaceless `data:{…}` some providers emit — `slice(6)` silently drops the latter.
  *
+ * Two levels, one rule: {@link readSseDataPayloads} yields payload TEXT (for callers
+ * whose frames are not all JSON, or that parse per wire shape), and
+ * {@link readSseDataFrames} yields parsed JSON on top of it.
+ *
  * Pure and defensive: a malformed frame is skipped, never thrown.
  */
 
+/** The payload text of a `data:` line, or `undefined` for any other line. */
+export function sseDataPayload(line: string): string | undefined {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('data:')) return undefined;
+    return trimmed.slice(5).trim();
+}
+
+/** True for the `data: [DONE]` line that ends an OpenAI-style stream. */
+export function isSseDoneLine(line: string): boolean {
+    return sseDataPayload(line) === '[DONE]';
+}
+
 /**
  * One SSE line's decoded JSON payload, or `undefined` when the line is not a usable
  * data frame (not a `data:` line, the `[DONE]` sentinel, empty, or malformed JSON).
  */
 export function parseSseDataLine(line: string): unknown | undefined {
-    const trimmed = line.trim();
-    if (!trimmed.startsWith('data:')) return undefined;
-    const data = trimmed.slice(5).trim();
+    const data = sseDataPayload(line);
     if (!data || data === '[DONE]') return undefined;
     try {
         return JSON.parse(data);
@@ -28,12 +42,6 @@ export function parseSseDataLine(line: string): unknown | undefined {
     }
 }
 
-/** True for the `data: [DONE]` line that ends an OpenAI-style stream. */
-export function isSseDoneLine(line: string): boolean {
-    const trimmed = line.trim();
-    return trimmed.startsWith('data:') && trimmed.slice(5).trim() === '[DONE]';
-}
-
 /** Every parsed `data:` frame of a whole, already-buffered SSE body, up to `[DONE]`. */
 export function* parseSseDataFrames(raw: string): Generator<unknown> {
     for (const line of raw.split('\n')) {
@@ -44,11 +52,12 @@ export function* parseSseDataFrames(raw: string): Generator<unknown> {
 }
 
 /**
- * Every parsed `data:` frame of a live SSE byte stream, as it arrives, up to `[DONE]`.
- * A frame split across chunks is held until its line completes; the reader lock is
- * released however iteration ends.
+ * Every `data:` payload of a live SSE byte stream, as text, as it arrives, up to
+ * `[DONE]`. A line split across chunks is held until its newline arrives; the reader
+ * lock is released however iteration ends. A missing body yields nothing.
  */
-export async function* readSseDataFrames(body: ReadableStream<Uint8Array>): AsyncGenerator<unknown> {
+export async function* readSseDataPayloads(body: ReadableStream<Uint8Array> | null | undefined): AsyncGenerator<string> {
+    if (!body) return;
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let buffer = '';
@@ -60,15 +69,28 @@ export async function* readSseDataFrames(body: ReadableStream<Uint8Array>): Asyn
             const lines = buffer.split('\n');
             buffer = lines.pop() as string; // split() always yields ≥1 element
             for (const line of lines) {
-                if (isSseDoneLine(line)) return;
-                const parsed = parseSseDataLine(line);
-                if (parsed !== undefined) yield parsed;
+                const data = sseDataPayload(line);
+                if (data === undefined) continue;
+                if (data === '[DONE]') return;
+                yield data;
             }
         }
         buffer += decoder.decode();
-        const tail = parseSseDataLine(buffer);
-        if (tail !== undefined) yield tail;
+        const tail = sseDataPayload(buffer);
+        if (tail !== undefined && tail !== '[DONE]') yield tail;
     } finally {
         reader.releaseLock();
     }
 }
+
+/** Every parsed JSON `data:` frame of a live SSE byte stream, up to `[DONE]`. */
+export async function* readSseDataFrames(body: ReadableStream<Uint8Array> | null | undefined): AsyncGenerator<unknown> {
+    for await (const data of readSseDataPayloads(body)) {
+        if (!data) continue;
+        try {
+            yield JSON.parse(data);
+        } catch {
+            // Skip malformed SSE frames rather than failing the stream.
+        }
+    }
+}