@seanhogg/builderforce-memory 2026.9.29 → 2026.9.31

package/src/bridges/AnthropicBridge.ts

@@ -8,6 +8,7 @@
 import { SSMError } from '../errors/SSMError.js';
 import type { LlmUsage } from '../telemetry/types.js';
 import type { TransformerBridge, BridgeGenerateOptions, BridgeCallInfo } from './TransformerBridge.js';
+import { readSseDataFrames, readUsageFields, AnthropicStreamUsage } from '../wire/index.js';
 
 export interface AnthropicBridgeOptions {
     /** Anthropic API key. */
@@ -110,30 +111,26 @@ export class AnthropicBridge implements TransformerBridge {
             throw new SSMError('BRIDGE_RESPONSE_INVALID', 'Anthropic streaming response has no body.');
         }
 
-        const model = opts.model ?? this._model;
-        let input = 0, output = 0, cacheRead = 0, cacheWrite = 0, reportedModel = model;
-
-        yield* parseAnthropicStream(res.body, (event) => {
-            // `message_start` carries the input split; `message_delta` the running
-            // output count. Both are folded so the final usage is provider-measured.
-            const start = (event as any).message?.usage;
-            const delta = (event as any).usage;
-            const usage = start ?? delta;
-            if (!usage) return;
-            if (typeof (event as any).message?.model === 'string') reportedModel = (event as any).message.model;
-            input      = Math.max(input,      Number(usage.input_tokens) || 0);
-            output     = Math.max(output,     Number(usage.output_tokens) || 0);
-            cacheRead  = Math.max(cacheRead,  Number(usage.cache_read_input_tokens) || 0);
-            cacheWrite = Math.max(cacheWrite, Number(usage.cache_creation_input_tokens) || 0);
-        });
+        // `message_start` carries the input split; `message_delta` the running
+        // output count. Both are folded so the final usage is provider-measured.
+        const usage = new AnthropicStreamUsage();
+        for await (const frame of readSseDataFrames(res.body)) {
+            usage.observe(frame);
+            const ev = frame as { type?: unknown; delta?: { text?: unknown } };
+            // content_block_delta events carry the streamed text
+            if (ev.type === 'content_block_delta' && typeof ev.delta?.text === 'string' && ev.delta.text.length > 0) {
+                yield ev.delta.text;
+            }
+        }
 
+        const totals = usage.result();
         this._lastCall = {
             usage: {
-                model: reportedModel,
-                inputTokens: input,
-                outputTokens: output,
-                cachedInputTokens: cacheRead,
-                cacheWriteTokens: cacheWrite,
+                model: totals.model ?? opts.model ?? this._model,
+                inputTokens: totals.inputTokens,
+                outputTokens: totals.outputTokens,
+                cachedInputTokens: totals.cacheReadTokens,
+                cacheWriteTokens: totals.cacheCreationTokens,
             },
         };
     }
@@ -171,48 +168,6 @@ export class AnthropicBridge implements TransformerBridge {
     }
 }
 
-// ── SSE parser (Anthropic event format) ──────────────────────────────────────
-
-async function* parseAnthropicStream(
-    body: ReadableStream<Uint8Array>,
-    onEvent?: (event: Record<string, unknown>) => void,
-): AsyncIterable<string> {
-    const reader  = body.getReader();
-    const decoder = new TextDecoder();
-    let buffer    = '';
-
-    try {
-        while (true) {
-            const { done, value } = await reader.read();
-            if (done) break;
-
-            buffer += decoder.decode(value, { stream: true });
-            const lines = buffer.split('\n');
-            buffer = lines.pop() as string; // split() always yields ≥1 element → never undefined
-
-            for (const line of lines) {
-                const trimmed = line.trim();
-                if (!trimmed.startsWith('data: ')) continue;
-
-                const data = trimmed.slice(6);
-                try {
-                    const event = JSON.parse(data) as Record<string, unknown>;
-                    onEvent?.(event);
-                    // content_block_delta events carry the streamed text
-                    if (event['type'] === 'content_block_delta') {
-                        const text = (event as any).delta?.text;
-                        if (typeof text === 'string' && text.length > 0) yield text;
-                    }
-                } catch {
-                    // Skip malformed SSE lines
-                }
-            }
-        }
-    } finally {
-        reader.releaseLock();
-    }
-}
-
 /**
  * Maps an Anthropic `usage` object onto the canonical {@link LlmUsage} shape.
  * Absent when the response omits usage (an older gateway shim), in which case
@@ -220,12 +175,13 @@ async function* parseAnthropicStream(
  */
 function readAnthropicUsage(usage: unknown, model: string): LlmUsage | undefined {
     if (!usage || typeof usage !== 'object') return undefined;
-    const u = usage as Record<string, unknown>;
+    // Anthropic's `input_tokens` already excludes both cache counts.
+    const u = readUsageFields(usage);
     return {
         model,
-        inputTokens: Number(u['input_tokens']) || 0,
-        outputTokens: Number(u['output_tokens']) || 0,
-        cachedInputTokens: Number(u['cache_read_input_tokens']) || 0,
-        cacheWriteTokens: Number(u['cache_creation_input_tokens']) || 0,
+        inputTokens: u.promptTokens ?? 0,
+        outputTokens: u.completionTokens ?? 0,
+        cachedInputTokens: u.cacheReadTokens ?? 0,
+        cacheWriteTokens: u.cacheCreationTokens ?? 0,
     };
 }

package/src/bridges/FetchBridge.ts

@@ -1,9 +1,9 @@
 /**
  * FetchBridge – generic OpenAI-compatible bridge for local or hosted endpoints.
  *
- * Works with Ollama, LM Studio, vLLM, llama.cpp server, or any service that
- * exposes a /chat/completions endpoint compatible with the OpenAI request
- * and response schema.
+ * Works with Ollama, LM Studio, vLLM, llama.cpp server, a routing gateway, or any
+ * service that exposes a /chat/completions endpoint compatible with the OpenAI
+ * request and response schema.
  */
 
 import { OpenAIBridge } from './OpenAIBridge.js';
@@ -14,12 +14,19 @@ export interface FetchBridgeOptions {
     baseUrl       : string;
     /** API key — many local servers require any non-empty string. Default: 'local'. */
     apiKey?       : string;
-    /** Model name understood by the server. Default: 'default'. */
+    /** Model name understood by the server. Default: 'default' (none with `serverDefaults`). */
     model?        : string;
     /** Default system prompt. */
     systemPrompt? : string;
-    /** Default max tokens. Default: 512. */
+    /** Default max tokens. Default: 512 (none with `serverDefaults`). */
     maxTokens?    : number;
+    /**
+     * Send only what a call states, so a routing gateway picks the model and the
+     * sampling settings. Default false.
+     */
+    serverDefaults?: boolean;
+    /** Abort a request after this long. */
+    timeoutMs?    : number;
 }
 
 /**
@@ -30,10 +37,12 @@ export class FetchBridge extends OpenAIBridge {
     constructor(opts: FetchBridgeOptions) {
         super({
             apiKey       : opts.apiKey        ?? 'local',
-            model        : opts.model         ?? 'default',
+            model        : opts.model         ?? (opts.serverDefaults ? undefined : 'default'),
             baseUrl      : opts.baseUrl,
             systemPrompt : opts.systemPrompt,
             maxTokens    : opts.maxTokens,
+            serverDefaults: opts.serverDefaults,
+            timeoutMs    : opts.timeoutMs,
         });
     }
 }

package/src/bridges/OpenAIBridge.ts

@@ -3,11 +3,25 @@
  *
  * Supports both non-streaming and streaming (SSE) completions.
  * Compatible with any OpenAI-compatible endpoint via the `baseUrl` option.
+ *
+ * The request, error mapping and stream reading are the `/wire` chat client's — the
+ * same one a host uses for tool-calling turns — so this class only supplies the
+ * bridge's defaults and maps usage onto {@link LlmUsage}.
  */
 
 import { SSMError } from '../errors/SSMError.js';
 import type { LlmUsage } from '../telemetry/types.js';
 import type { TransformerBridge, BridgeGenerateOptions, BridgeCallInfo } from './TransformerBridge.js';
+import {
+    chatComplete,
+    chatStream,
+    ChatCompletionError,
+    readUsageFields,
+    type ChatClient,
+    type ChatMessage,
+    type ChatRequest,
+    type ChatStreamEvent,
+} from '../wire/index.js';
 
 export interface OpenAIBridgeOptions {
     /** OpenAI API key (or compatible service key). */
@@ -20,6 +34,13 @@ export interface OpenAIBridgeOptions {
     systemPrompt? : string;
     /** Default max tokens. Default: 512. */
     maxTokens?    : number;
+    /**
+     * Send only what a call states — no model, max-tokens, temperature or top-p
+     * defaults — so a routing gateway picks them. Default false.
+     */
+    serverDefaults?: boolean;
+    /** Abort a request after this long. */
+    timeoutMs?    : number;
 }
 
 export class OpenAIBridge implements TransformerBridge {
@@ -27,18 +48,22 @@ export class OpenAIBridge implements TransformerBridge {
 
     readonly supportsStreaming = true as const;
 
-    private readonly _apiKey      : string;
-    private readonly _model       : string;
-    private readonly _baseUrl     : string;
+    private readonly _client      : ChatClient;
+    private readonly _model       : string | undefined;
     private readonly _systemPrompt: string;
-    private readonly _maxTokens   : number;
+    private readonly _maxTokens   : number | undefined;
+    private readonly _serverDefaults: boolean;
 
     constructor(opts: OpenAIBridgeOptions) {
-        this._apiKey       = opts.apiKey;
-        this._model        = opts.model        ?? 'gpt-4o-mini';
-        this._baseUrl      = (opts.baseUrl     ?? 'https://api.openai.com/v1').replace(/\/$/, '');
+        this._serverDefaults = opts.serverDefaults ?? false;
+        this._client = {
+            apiKey: opts.apiKey,
+            baseUrl: opts.baseUrl ?? 'https://api.openai.com/v1',
+            ...(opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}),
+        };
+        this._model        = opts.model ?? (this._serverDefaults ? undefined : 'gpt-4o-mini');
         this._systemPrompt = opts.systemPrompt ?? '';
-        this._maxTokens    = opts.maxTokens    ?? 512;
+        this._maxTokens    = opts.maxTokens ?? (this._serverDefaults ? undefined : 512);
     }
 
     /** Provider-reported usage for the last call — see {@link BridgeCallInfo}. */
@@ -47,142 +72,88 @@ export class OpenAIBridge implements TransformerBridge {
     }
 
     async generate(prompt: string, opts: BridgeGenerateOptions = {}): Promise<string> {
-        const body = this._buildBody(prompt, opts, false);
-        const res  = await this._fetch(body);
-
-        if (!res.ok) {
-            const text = await res.text().catch(() => '');
-            throw new SSMError(
-                'BRIDGE_REQUEST_FAILED',
-                `OpenAI API returned ${res.status}: ${text}`,
-            );
+        let result;
+        try {
+            result = await chatComplete(this._client, this._request(prompt, opts));
+        } catch (err) {
+            throw this._requestError('OpenAI API', err);
         }
-
-        const json = await res.json() as Record<string, unknown>;
-        const content = (json as any).choices?.[0]?.message?.content;
-        if (typeof content !== 'string') {
+        if (!result.hasTextContent) {
             throw new SSMError('BRIDGE_RESPONSE_INVALID', 'Unexpected OpenAI response shape.');
         }
         this._lastCall = {
-            usage: readOpenAIUsage((json as any).usage, (json as any).model ?? opts.model ?? this._model),
+            usage: readOpenAIUsage(result.usage, result.model ?? opts.model ?? this._model ?? ''),
         };
-        return content;
+        return result.content;
     }
 
     async *stream(prompt: string, opts: BridgeGenerateOptions = {}): AsyncIterable<string> {
-        const body = this._buildBody(prompt, opts, true);
-        const res  = await this._fetch(body);
-
-        if (!res.ok) {
-            const text = await res.text().catch(() => '');
-            throw new SSMError(
-                'BRIDGE_REQUEST_FAILED',
-                `OpenAI streaming API returned ${res.status}: ${text}`,
-            );
+        let events;
+        try {
+            events = chatStream(this._client, { ...this._request(prompt, opts), includeUsage: true });
+            // The request is sent on the first pull; surface a failed request as a bridge error.
+            const first = await events.next();
+            if (first.done) return;
+            yield* this._text(first.value);
+        } catch (err) {
+            throw this._requestError('OpenAI streaming API', err);
         }
+        for await (const event of events) yield* this._text(event);
+    }
 
-        if (!res.body) {
-            throw new SSMError('BRIDGE_RESPONSE_INVALID', 'OpenAI streaming response has no body.');
+    /** Text deltas out; the closing event records usage (sent because of `includeUsage`). */
+    private *_text(event: ChatStreamEvent): Generator<string> {
+        if (event.type === 'text-delta') yield event.delta;
+        else if (event.type === 'done') {
+            const usage = readOpenAIUsage(event.result.usage, event.result.model ?? this._model ?? '');
+            this._lastCall = usage ? { usage } : {};
         }
-
-        const model = opts.model ?? this._model;
-        let usage: LlmUsage | undefined;
-
-        yield* parseOpenAIStream(res.body, (event) => {
-            // Only emitted because `_buildBody` sets `stream_options.include_usage`;
-            // without it OpenAI streams no usage at all and cost would be a guess.
-            const reported = readOpenAIUsage((event as any).usage, (event as any).model ?? model);
-            if (reported) usage = reported;
-        });
-
-        this._lastCall = usage ? { usage } : {};
     }
 
-    private _buildBody(prompt: string, opts: BridgeGenerateOptions, stream: boolean): string {
+    private _request(prompt: string, opts: BridgeGenerateOptions): ChatRequest {
         const sys = opts.systemPrompt ?? this._systemPrompt;
-        const messages: { role: string; content: string }[] = [];
+        const messages: ChatMessage[] = [];
         if (sys) messages.push({ role: 'system', content: sys });
         messages.push({ role: 'user', content: prompt });
-
-        return JSON.stringify({
-            model      : opts.model     ?? this._model,
+        const d = !this._serverDefaults;
+        const model = opts.model ?? this._model;
+        const maxTokens = opts.maxTokens ?? this._maxTokens;
+        const temperature = opts.temperature ?? (d ? 0.7 : undefined);
+        const topP = opts.topP ?? (d ? 0.9 : undefined);
+        return {
             messages,
-            max_tokens : opts.maxTokens ?? this._maxTokens,
-            temperature: opts.temperature ?? 0.7,
-            top_p      : opts.topP        ?? 0.9,
-            stream,
-            // Without this the streaming response carries no usage block, so
-            // cost-per-request on streamed calls would silently fall back to an
-            // estimate. Non-streaming requests reject the field, hence the guard.
-            ...(stream ? { stream_options: { include_usage: true } } : {}),
-        });
-    }
-
-    private _fetch(body: string): Promise<Response> {
-        return fetch(`${this._baseUrl}/chat/completions`, {
-            method : 'POST',
-            headers: {
-                'Content-Type' : 'application/json',
-                'Authorization': `Bearer ${this._apiKey}`,
-            },
-            body,
-        });
+            ...(model ? { model } : {}),
+            ...(maxTokens !== undefined ? { maxTokens } : {}),
+            ...(temperature !== undefined ? { temperature } : {}),
+            ...(topP !== undefined ? { topP } : {}),
+            ...(opts.extra ? { extra: opts.extra } : {}),
+        };
     }
-}
-
-// ── SSE parser ────────────────────────────────────────────────────────────────
-
-async function* parseOpenAIStream(
-    body: ReadableStream<Uint8Array>,
-    onEvent?: (event: Record<string, unknown>) => void,
-): AsyncIterable<string> {
-    const reader  = body.getReader();
-    const decoder = new TextDecoder();
-    let buffer    = '';
-
-    try {
-        while (true) {
-            const { done, value } = await reader.read();
-            if (done) break;
-
-            buffer += decoder.decode(value, { stream: true });
-            const lines = buffer.split('\n');
-            buffer = lines.pop() as string;   // keep the last (possibly partial) line; split() always yields ≥1 element
-
-            for (const line of lines) {
-                const trimmed = line.trim();
-                if (!trimmed.startsWith('data: ')) continue;
-
-                const data = trimmed.slice(6);
-                if (data === '[DONE]') return;
 
-                try {
-                    const chunk = JSON.parse(data) as Record<string, unknown>;
-                    onEvent?.(chunk);
-                    const delta = (chunk as any).choices?.[0]?.delta?.content;
-                    if (typeof delta === 'string' && delta.length > 0) yield delta;
-                } catch {
-                    // Malformed JSON in stream — skip silently
-                }
+    private _requestError(what: string, err: unknown): SSMError {
+        if (err instanceof SSMError) return err;
+        if (err instanceof ChatCompletionError) {
+            // A 2xx that still failed is a stream with no body: the server answered, badly.
+            if (err.status >= 200 && err.status < 300) {
+                return new SSMError('BRIDGE_RESPONSE_INVALID', `${what} returned no response body.`);
             }
+            return new SSMError('BRIDGE_REQUEST_FAILED', `${what} returned ${err.status}: ${err.body}`);
         }
-    } finally {
-        reader.releaseLock();
+        return new SSMError('BRIDGE_REQUEST_FAILED', `${what} request failed: ${err instanceof Error ? err.message : String(err)}`, err);
     }
 }
 
 /** Maps an OpenAI `usage` object onto the canonical {@link LlmUsage} shape. */
 function readOpenAIUsage(usage: unknown, model: string): LlmUsage | undefined {
     if (!usage || typeof usage !== 'object') return undefined;
-    const u = usage as Record<string, unknown>;
-    const cached = Number((u['prompt_tokens_details'] as Record<string, unknown> | undefined)?.['cached_tokens']) || 0;
-    const prompt = Number(u['prompt_tokens']) || 0;
+    const u = readUsageFields(usage);
+    const cached = u.cacheReadTokens ?? 0;
     return {
         model,
         // OpenAI reports `prompt_tokens` INCLUSIVE of cached tokens; the canonical
         // shape keeps them disjoint so the two rates are applied exactly once each.
-        inputTokens: Math.max(0, prompt - cached),
-        outputTokens: Number(u['completion_tokens']) || 0,
+        inputTokens: Math.max(0, (u.promptTokens ?? 0) - cached),
+        outputTokens: u.completionTokens ?? 0,
         cachedInputTokens: cached,
     };
 }

package/src/bridges/TransformerBridge.ts

@@ -22,6 +22,12 @@ export interface BridgeGenerateOptions {
     systemPrompt? : string;
     /** Model string, overriding the adapter's default. */
     model?        : string;
+    /**
+     * Vendor extras merged into an OpenAI-compatible request body (a gateway's
+     * routing `provider`, `response_format`, …). Bridges that do not speak that
+     * wire format ignore it.
+     */
+    extra?        : Record<string, unknown>;
 }
 
 export interface TransformerBridge {

package/src/bridges/VertexAIBridge.ts

@@ -25,6 +25,7 @@
 import { SSMError } from '../errors/SSMError.js';
 import type { LlmUsage } from '../telemetry/types.js';
 import type { TransformerBridge, BridgeGenerateOptions, BridgeCallInfo } from './TransformerBridge.js';
+import { readSseDataFrames } from '../wire/index.js';
 
 export interface VertexAIBridgeOptions {
     /** GCP project id. */
@@ -101,7 +102,8 @@ export class VertexAIBridge implements TransformerBridge {
         }
 
         let usage: LlmUsage | undefined;
-        for await (const event of parseSseJson(res.body)) {
+        for await (const frame of readSseDataFrames(res.body)) {
+            const event = frame as Record<string, unknown>;
             const text = readCandidateText(event);
             if (text) yield text;
             // Vertex repeats cumulative usage on each chunk; the last one wins.
@@ -264,34 +266,3 @@ function readVertexUsage(usage: unknown, model: string): LlmUsage | undefined {
         cachedInputTokens: cached,
     };
 }
-
-/** Parses an `alt=sse` stream into JSON events. */
-async function* parseSseJson(body: ReadableStream<Uint8Array>): AsyncIterable<Record<string, unknown>> {
-    const reader = body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = '';
-
-    try {
-        while (true) {
-            const { done, value } = await reader.read();
-            if (done) break;
-            buffer += decoder.decode(value, { stream: true });
-
-            const lines = buffer.split('\n');
-            buffer = lines.pop() as string;
-            for (const line of lines) {
-                const trimmed = line.trim();
-                if (!trimmed.startsWith('data:')) continue;
-                const payload = trimmed.slice(5).trim();
-                if (!payload || payload === '[DONE]') continue;
-                try {
-                    yield JSON.parse(payload) as Record<string, unknown>;
-                } catch {
-                    // Skip malformed SSE frames rather than failing the stream.
-                }
-            }
-        }
-    } finally {
-        reader.releaseLock();
-    }
-}