@seanhogg/builderforce-memory 2026.9.30 → 2026.9.31

package/dist/wire/sse.d.ts

@@ -2,28 +2,36 @@
  * 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 declare function sseDataPayload(line: string): string | undefined;
+/** True for the `data: [DONE]` line that ends an OpenAI-style stream. */
+export declare function isSseDoneLine(line: string): boolean;
 /**
  * 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 declare function parseSseDataLine(line: string): unknown | undefined;
-/** True for the `data: [DONE]` line that ends an OpenAI-style stream. */
-export declare function isSseDoneLine(line: string): boolean;
 /** Every parsed `data:` frame of a whole, already-buffered SSE body, up to `[DONE]`. */
 export declare 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 declare function readSseDataFrames(body: ReadableStream<Uint8Array>): AsyncGenerator<unknown>;
+export declare function readSseDataPayloads(body: ReadableStream<Uint8Array> | null | undefined): AsyncGenerator<string>;
+/** Every parsed JSON `data:` frame of a live SSE byte stream, up to `[DONE]`. */
+export declare function readSseDataFrames(body: ReadableStream<Uint8Array> | null | undefined): AsyncGenerator<unknown>;
 //# sourceMappingURL=sse.d.ts.map

package/dist/wire/sse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/wire/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAUlE;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGnD;AAED,wFAAwF;AACxF,wBAAiB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,CAMnE;AAED;;;;GAIG;AACH,wBAAuB,iBAAiB,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC,CAuBlG"}
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/wire/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI/D;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAQlE;AAED,wFAAwF;AACxF,wBAAiB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,CAMnE;AAED;;;;GAIG;AACH,wBAAuB,mBAAmB,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,cAAc,CAAC,MAAM,CAAC,CAyBtH;AAED,iFAAiF;AACjF,wBAAuB,iBAAiB,CAAC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,cAAc,CAAC,OAAO,CAAC,CASrH"}

package/dist/wire/sse.js

@@ -2,24 +2,36 @@
  * 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) {
+    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) {
+    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) {
-    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 {
@@ -29,11 +41,6 @@ export function parseSseDataLine(line) {
         return undefined;
     }
 }
-/** True for the `data: [DONE]` line that ends an OpenAI-style stream. */
-export function isSseDoneLine(line) {
-    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) {
     for (const line of raw.split('\n')) {
@@ -45,11 +52,13 @@ export function* parseSseDataFrames(raw) {
     }
 }
 /**
- * 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) {
+export async function* readSseDataPayloads(body) {
+    if (!body)
+        return;
     const reader = body.getReader();
     const decoder = new TextDecoder();
     let buffer = '';
@@ -62,20 +71,34 @@ export async function* readSseDataFrames(body) {
             const lines = buffer.split('\n');
             buffer = lines.pop(); // split() always yields ≥1 element
             for (const line of lines) {
-                if (isSseDoneLine(line))
+                const data = sseDataPayload(line);
+                if (data === undefined)
+                    continue;
+                if (data === '[DONE]')
                     return;
-                const parsed = parseSseDataLine(line);
-                if (parsed !== undefined)
-                    yield parsed;
+                yield data;
             }
         }
         buffer += decoder.decode();
-        const tail = parseSseDataLine(buffer);
-        if (tail !== undefined)
+        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) {
+    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.
+        }
+    }
+}
 //# sourceMappingURL=sse.js.map

package/dist/wire/sse.js.map

@@ -1 +1 @@
-{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../src/wire/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IACzC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IACnD,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACrC,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACjD,IAAI,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,SAAS,CAAC;IACrB,CAAC;AACL,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,aAAa,CAAC,IAAY;IACtC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,OAAO,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,QAAQ,CAAC;AAC/E,CAAC;AAED,wFAAwF;AACxF,MAAM,SAAS,CAAC,CAAC,kBAAkB,CAAC,GAAW;IAC3C,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACjC,IAAI,aAAa,CAAC,IAAI,CAAC;YAAE,OAAO;QAChC,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM,MAAM,CAAC;IAC3C,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,SAAS,CAAC,CAAC,iBAAiB,CAAC,IAAgC;IACrE,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;IAChC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,CAAC;QACD,OAAO,IAAI,EAAE,CAAC;YACV,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,IAAI;gBAAE,MAAM;YAChB,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YAClD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACjC,MAAM,GAAG,KAAK,CAAC,GAAG,EAAY,CAAC,CAAC,mCAAmC;YACnE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACvB,IAAI,aAAa,CAAC,IAAI,CAAC;oBAAE,OAAO;gBAChC,MAAM,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;gBACtC,IAAI,MAAM,KAAK,SAAS;oBAAE,MAAM,MAAM,CAAC;YAC3C,CAAC;QACL,CAAC;QACD,MAAM,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;QACtC,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM,IAAI,CAAC;IACvC,CAAC;YAAS,CAAC;QACP,MAAM,CAAC,WAAW,EAAE,CAAC;IACzB,CAAC;AACL,CAAC"}
+{"version":3,"file":"sse.js","sourceRoot":"","sources":["../../src/wire/sse.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanhogg/builderforce-memory",
-  "version": "2026.9.30",
+  "version": "2026.9.31",
   "description": "BuilderForce Agent Memory — runtime layer. SSM execution, Transformer orchestration, online distillation, enterprise RAG (ingestion pipelines, vector-store adapters, tenant/ACL-scoped hybrid retrieval), multi-agent graph orchestration, LLM telemetry and cost accounting, and persistent agent memory for BuilderForce.ai agents.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -95,7 +95,7 @@
   },
   "homepage": "https://github.com/SeanHogg/builderforce-memory/tree/main/packages/memory#readme",
   "peerDependencies": {
-    "@seanhogg/builderforce-memory-engine": "^2026.9.30"
+    "@seanhogg/builderforce-memory-engine": "^2026.9.31"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
@@ -109,7 +109,7 @@
     "ts-jest": "^29.2.0",
     "typescript": "^6.0.3",
     "@typescript/native-preview": "7.0.0-dev.20260627.2",
-    "@seanhogg/builderforce-memory-engine": "2026.9.30"
+    "@seanhogg/builderforce-memory-engine": "2026.9.31"
   },
   "jest": {
     "preset": "ts-jest/presets/default-esm",

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,12 +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 { readSseDataFrames, readUsageFields } from '../wire/index.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). */
@@ -21,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 {
@@ -28,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}. */
@@ -48,88 +72,74 @@ 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}`,
-            );
-        }
-
-        if (!res.body) {
-            throw new SSMError('BRIDGE_RESPONSE_INVALID', 'OpenAI streaming response has no body.');
+        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);
+    }
 
-        const model = opts.model ?? this._model;
-        let usage: LlmUsage | undefined;
-
-        for await (const chunk of readSseDataFrames(res.body)) {
-            // Usage is 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((chunk as any).usage, (chunk as any).model ?? model);
-            if (reported) usage = reported;
-            const delta = (chunk as any).choices?.[0]?.delta?.content;
-            if (typeof delta === 'string' && delta.length > 0) yield delta;
+    /** 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 } : {};
         }
-
-        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 } } : {}),
-        });
+            ...(model ? { model } : {}),
+            ...(maxTokens !== undefined ? { maxTokens } : {}),
+            ...(temperature !== undefined ? { temperature } : {}),
+            ...(topP !== undefined ? { topP } : {}),
+            ...(opts.extra ? { extra: opts.extra } : {}),
+        };
     }
 
-    private _fetch(body: string): Promise<Response> {
-        return fetch(`${this._baseUrl}/chat/completions`, {
-            method : 'POST',
-            headers: {
-                'Content-Type' : 'application/json',
-                'Authorization': `Bearer ${this._apiKey}`,
-            },
-            body,
-        });
+    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}`);
+        }
+        return new SSMError('BRIDGE_REQUEST_FAILED', `${what} request failed: ${err instanceof Error ? err.message : String(err)}`, err);
     }
 }
 

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 {