@bbclaw/core 0.1.0

package/dist/providers/openai-compat/streamAdapter.js

@@ -0,0 +1,233 @@
+/**
+ * Stream adapter: OpenAI chat/completions SSE → Anthropic RawMessageStreamEvent.
+ *
+ * This is the trickiest piece in the openai-compat provider. The two protocols
+ * model the world differently:
+ *
+ * - OpenAI streams a single "assistant message" whose `content` and
+ *   `tool_calls` are filled in incrementally via deltas. Tool call deltas
+ *   carry an `index` that identifies WHICH tool call in the parallel array
+ *   they belong to.
+ *
+ * - Anthropic models the same response as a sequence of typed CONTENT BLOCKS
+ *   (text / tool_use / thinking), each with its own index and lifecycle:
+ *   content_block_start → content_block_delta* → content_block_stop.
+ *
+ * The mapping rules we use:
+ *   • `delta.content` →  text block, opened lazily, closed when something else starts
+ *   • `delta.reasoning_content` (DeepSeek-R1 dialect) → thinking block, same lifecycle
+ *   • `delta.tool_calls[i]` → one tool_use block per OpenAI index `i`
+ *   • final `usage` → message_delta.usage
+ *   • `finish_reason` → message_delta.stop_reason via mapStopReason()
+ *
+ * Block index allocation: we increment a single counter as we open blocks.
+ * The OpenAI-side `tool_calls.index` is REMAPPED to an Anthropic block index
+ * (they're not the same number — Anthropic counts ALL blocks including text).
+ *
+ * Concurrency: in practice OpenAI streams tool calls sequentially (one finishes
+ * before the next starts), but the spec allows parallel. We handle both cases
+ * by keeping per-OpenAI-index state and only closing when we see clear evidence
+ * the block is done (finish_reason or end of stream).
+ */
+import { randomUUID } from 'node:crypto';
+/**
+ * Adapt an OpenAI SSE chunk iterable into Anthropic stream events.
+ * Yields events; on upstream error, the error propagates (caller decides).
+ */
+export async function* adaptOpenAIStream(upstream, opts) {
+    const state = {
+        messageId: opts.messageId ?? `msg_${randomUUID()}`,
+        model: opts.model,
+        nextBlockIndex: 0,
+        textBlock: null,
+        thinkingBlock: null,
+        toolCalls: new Map(),
+        usage: {
+            input_tokens: 0,
+            output_tokens: 0,
+            cache_creation_input_tokens: null,
+            cache_read_input_tokens: null,
+        },
+        stopReason: null,
+        stopSequence: null,
+    };
+    yield buildMessageStart(state);
+    for await (const chunk of upstream) {
+        yield* handleChunk(chunk, state);
+    }
+    // Close any blocks that are still open. Order: thinking → text → tool_use
+    // (so consumers see a tidy LIFO close sequence).
+    if (state.thinkingBlock) {
+        yield { type: 'content_block_stop', index: state.thinkingBlock.index };
+        state.thinkingBlock = null;
+    }
+    if (state.textBlock) {
+        yield { type: 'content_block_stop', index: state.textBlock.index };
+        state.textBlock = null;
+    }
+    for (const tc of state.toolCalls.values()) {
+        yield { type: 'content_block_stop', index: tc.anthropicIndex };
+    }
+    state.toolCalls.clear();
+    yield {
+        type: 'message_delta',
+        delta: {
+            stop_reason: state.stopReason ?? 'end_turn',
+            stop_sequence: state.stopSequence,
+        },
+        usage: { output_tokens: state.usage.output_tokens },
+    };
+    yield { type: 'message_stop' };
+}
+function buildMessageStart(state) {
+    const message = {
+        id: state.messageId,
+        type: 'message',
+        role: 'assistant',
+        model: state.model,
+        content: [],
+        stop_reason: null,
+        stop_sequence: null,
+        usage: state.usage,
+    };
+    return { type: 'message_start', message };
+}
+function* handleChunk(chunk, state) {
+    const choice = chunk.choices?.[0];
+    if (choice) {
+        yield* handleDelta(choice.delta, state);
+        if (choice.finish_reason) {
+            state.stopReason = mapFinishReason(choice.finish_reason);
+        }
+    }
+    if (chunk.usage)
+        mergeUsage(state.usage, chunk.usage);
+}
+function* handleDelta(delta, state) {
+    if (!delta)
+        return;
+    // Order: reasoning_content first (it always precedes content in DeepSeek-R1),
+    // then content, then tool_calls. Within a single chunk all three could be
+    // present in theory; we handle them in that natural reading order.
+    if (typeof delta.reasoning_content === 'string' && delta.reasoning_content.length > 0) {
+        // Closing text is wrong here — DeepSeek-R1 sends ALL reasoning_content
+        // BEFORE any content. So a thinking block is opened first and stays open
+        // until content arrives. If text was somehow already open, close it.
+        if (state.textBlock) {
+            yield { type: 'content_block_stop', index: state.textBlock.index };
+            state.textBlock = null;
+        }
+        if (!state.thinkingBlock) {
+            const index = state.nextBlockIndex++;
+            state.thinkingBlock = { index };
+            yield {
+                type: 'content_block_start',
+                index,
+                content_block: { type: 'thinking', thinking: '', signature: '' },
+            };
+        }
+        yield {
+            type: 'content_block_delta',
+            index: state.thinkingBlock.index,
+            delta: { type: 'thinking_delta', thinking: delta.reasoning_content },
+        };
+    }
+    if (typeof delta.content === 'string' && delta.content.length > 0) {
+        // First real text → close any thinking block (it's done by definition).
+        if (state.thinkingBlock) {
+            yield { type: 'content_block_stop', index: state.thinkingBlock.index };
+            state.thinkingBlock = null;
+        }
+        if (!state.textBlock) {
+            const index = state.nextBlockIndex++;
+            state.textBlock = { index };
+            yield {
+                type: 'content_block_start',
+                index,
+                content_block: { type: 'text', text: '', citations: null },
+            };
+        }
+        yield {
+            type: 'content_block_delta',
+            index: state.textBlock.index,
+            delta: { type: 'text_delta', text: delta.content },
+        };
+    }
+    if (delta.tool_calls && delta.tool_calls.length > 0) {
+        // Tool calls always come AFTER text/thinking in practice. Close those first.
+        if (state.thinkingBlock) {
+            yield { type: 'content_block_stop', index: state.thinkingBlock.index };
+            state.thinkingBlock = null;
+        }
+        if (state.textBlock) {
+            yield { type: 'content_block_stop', index: state.textBlock.index };
+            state.textBlock = null;
+        }
+        for (const tc of delta.tool_calls) {
+            const openaiIndex = tc.index;
+            let entry = state.toolCalls.get(openaiIndex);
+            if (!entry) {
+                // First time we're seeing this tool call. Allocate an Anthropic block.
+                const anthropicIndex = state.nextBlockIndex++;
+                entry = {
+                    anthropicIndex,
+                    id: tc.id ?? `toolu_${randomUUID().replace(/-/g, '').slice(0, 22)}`,
+                    nameEmitted: false,
+                };
+                state.toolCalls.set(openaiIndex, entry);
+                // We may not have a name yet on the very first delta; if not, defer
+                // emitting content_block_start until we do. (Anthropic's content_block
+                // requires `name` to be set at start time.)
+            }
+            // If we know the name now and haven't emitted start yet, do so.
+            const name = tc.function?.name;
+            if (!entry.nameEmitted && name) {
+                entry.nameEmitted = true;
+                yield {
+                    type: 'content_block_start',
+                    index: entry.anthropicIndex,
+                    content_block: {
+                        type: 'tool_use',
+                        id: entry.id,
+                        name,
+                        input: {},
+                    },
+                };
+            }
+            const args = tc.function?.arguments;
+            if (entry.nameEmitted && typeof args === 'string' && args.length > 0) {
+                yield {
+                    type: 'content_block_delta',
+                    index: entry.anthropicIndex,
+                    delta: { type: 'input_json_delta', partial_json: args },
+                };
+            }
+        }
+    }
+}
+function mapFinishReason(reason) {
+    switch (reason) {
+        case 'stop':
+            return 'end_turn';
+        case 'length':
+            return 'max_tokens';
+        case 'tool_calls':
+        case 'function_call':
+            return 'tool_use';
+        case 'content_filter':
+            // No exact Anthropic equivalent. 'stop_sequence' is the closest semantic
+            // ("model was stopped externally") but it's a stretch. We use 'end_turn'
+            // and rely on telemetry to flag filtered outputs upstream.
+            return 'end_turn';
+        default:
+            return 'end_turn';
+    }
+}
+function mergeUsage(target, src) {
+    target.input_tokens = src.prompt_tokens;
+    target.output_tokens = src.completion_tokens;
+    if (src.prompt_tokens_details?.cached_tokens !== undefined) {
+        target.cache_read_input_tokens = src.prompt_tokens_details.cached_tokens;
+    }
+}
+//# sourceMappingURL=streamAdapter.js.map

package/dist/providers/openai-compat/streamAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamAdapter.js","sourceRoot":"","sources":["../../../src/providers/openai-compat/streamAdapter.ts"],"names":[],"mappings":"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"}

package/dist/providers/openai-compat/types.d.ts

@@ -0,0 +1,126 @@
+/**
+ * OpenAI chat/completions wire types — a small subset of the v1 schema, just
+ * enough to send a streaming request and decode the SSE responses. We don't
+ * pull in `openai` as a dependency because we want to support arbitrary
+ * compatible servers (Ollama, Groq, OpenRouter, LM Studio, self-hosted),
+ * not all of which match the official SDK's strict shape.
+ *
+ * Reference: https://platform.openai.com/docs/api-reference/chat/streaming
+ */
+export interface OpenAIToolFunction {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+}
+export interface OpenAIToolDef {
+    type: 'function';
+    function: OpenAIToolFunction;
+}
+export type OpenAIToolChoice = 'auto' | 'none' | 'required' | {
+    type: 'function';
+    function: {
+        name: string;
+    };
+};
+export interface OpenAIContentPartText {
+    type: 'text';
+    text: string;
+}
+export interface OpenAIContentPartImage {
+    type: 'image_url';
+    image_url: {
+        url: string;
+        detail?: 'auto' | 'low' | 'high';
+    };
+}
+export type OpenAIContentPart = OpenAIContentPartText | OpenAIContentPartImage;
+export interface OpenAIToolCall {
+    /** Stable identifier set on first delta, used to match `tool` role results. */
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface OpenAIMessageSystem {
+    role: 'system';
+    content: string;
+}
+export interface OpenAIMessageUser {
+    role: 'user';
+    content: string | OpenAIContentPart[];
+}
+export interface OpenAIMessageAssistant {
+    role: 'assistant';
+    content?: string | null;
+    tool_calls?: OpenAIToolCall[];
+}
+export interface OpenAIMessageTool {
+    role: 'tool';
+    tool_call_id: string;
+    content: string;
+}
+export type OpenAIMessage = OpenAIMessageSystem | OpenAIMessageUser | OpenAIMessageAssistant | OpenAIMessageTool;
+export interface OpenAIRequest {
+    model: string;
+    messages: OpenAIMessage[];
+    tools?: OpenAIToolDef[];
+    tool_choice?: OpenAIToolChoice;
+    stream: true;
+    stream_options?: {
+        include_usage?: boolean;
+    };
+    max_tokens?: number;
+    temperature?: number;
+    top_p?: number;
+    stop?: string | string[];
+    user?: string;
+    /**
+     * Some providers (DeepSeek, Together) accept extra fields here without
+     * complaining; we pass them through as an escape hatch.
+     */
+    [key: string]: unknown;
+}
+export interface OpenAIDeltaToolCall {
+    /** Index in the streamed assistant message's tool_calls array. */
+    index: number;
+    /** Set on the first chunk that introduces this tool call. */
+    id?: string;
+    type?: 'function';
+    function?: {
+        name?: string;
+        arguments?: string;
+    };
+}
+export interface OpenAIStreamDelta {
+    role?: 'assistant';
+    content?: string | null;
+    tool_calls?: OpenAIDeltaToolCall[];
+    /** Some providers (DeepSeek-R1) emit reasoning as a sibling field. */
+    reasoning_content?: string | null;
+}
+export type OpenAIFinishReason = 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'function_call' | null;
+export interface OpenAIStreamChoice {
+    index: number;
+    delta: OpenAIStreamDelta;
+    finish_reason: OpenAIFinishReason;
+}
+export interface OpenAIUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    prompt_tokens_details?: {
+        cached_tokens?: number;
+    };
+}
+export interface OpenAIStreamChunk {
+    id: string;
+    object: 'chat.completion.chunk';
+    created: number;
+    model: string;
+    choices: OpenAIStreamChoice[];
+    /** Only present when stream_options.include_usage = true and only on the final chunk. */
+    usage?: OpenAIUsage;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/providers/openai-compat/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/providers/openai-compat/types.ts"],"names":[],"mappings":"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"}

package/dist/providers/openai-compat/types.js

@@ -0,0 +1,11 @@
+/**
+ * OpenAI chat/completions wire types — a small subset of the v1 schema, just
+ * enough to send a streaming request and decode the SSE responses. We don't
+ * pull in `openai` as a dependency because we want to support arbitrary
+ * compatible servers (Ollama, Groq, OpenRouter, LM Studio, self-hosted),
+ * not all of which match the official SDK's strict shape.
+ *
+ * Reference: https://platform.openai.com/docs/api-reference/chat/streaming
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/providers/openai-compat/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/providers/openai-compat/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/providers/selector.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Provider registry / selector.
+ *
+ * The selector keeps a map of registered providers and picks one by id, by
+ * default rule, or by a fallback chain. It does NOT instantiate providers
+ * itself — callers register pre-built instances. This keeps the selector
+ * dependency-light and makes testing easy.
+ *
+ * Selection precedence at lookup time:
+ *   1. Explicit id passed to pick()
+ *   2. Per-process default (set via setDefault)
+ *   3. First provider in the registry that passes healthCheck
+ */
+import type { Logger } from '@bbclaw/shared';
+import type { Provider } from './types.js';
+export interface ProviderRegistryOptions {
+    logger?: Logger;
+}
+export declare class ProviderRegistry {
+    private readonly providers;
+    private defaultId;
+    private readonly logger;
+    constructor(opts?: ProviderRegistryOptions);
+    register(provider: Provider): this;
+    unregister(id: string): boolean;
+    has(id: string): boolean;
+    get(id: string): Provider | undefined;
+    list(): Provider[];
+    setDefault(id: string): void;
+    getDefault(): Provider | undefined;
+    /**
+     * Pick a provider. Lookup order:
+     *   - explicit id
+     *   - default
+     *   - first registered (deterministic — Map preserves insertion order)
+     * Throws if the registry is empty or the requested id doesn't exist.
+     */
+    pick(id?: string): Provider;
+    /**
+     * Probe every registered provider in parallel and return the results.
+     * Useful for the `/provider health` UX and for surfacing config issues at
+     * startup.
+     */
+    healthCheckAll(): Promise<Array<{
+        id: string;
+        ok: boolean;
+        latencyMs?: number;
+        reason?: string;
+    }>>;
+    closeAll(): Promise<void>;
+}
+//# sourceMappingURL=selector.d.ts.map

package/dist/providers/selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../../src/providers/selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAE1C,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IACxD,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;gBAEnB,IAAI,GAAE,uBAA4B;IAK9C,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IASlC,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAM/B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAIrC,IAAI,IAAI,QAAQ,EAAE;IAIlB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAO5B,UAAU,IAAI,QAAQ,GAAG,SAAS;IAIlC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,QAAQ;IAa3B;;;;OAIG;IACG,cAAc,IAAI,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAclG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAWhC"}

package/dist/providers/selector.js

@@ -0,0 +1,101 @@
+/**
+ * Provider registry / selector.
+ *
+ * The selector keeps a map of registered providers and picks one by id, by
+ * default rule, or by a fallback chain. It does NOT instantiate providers
+ * itself — callers register pre-built instances. This keeps the selector
+ * dependency-light and makes testing easy.
+ *
+ * Selection precedence at lookup time:
+ *   1. Explicit id passed to pick()
+ *   2. Per-process default (set via setDefault)
+ *   3. First provider in the registry that passes healthCheck
+ */
+export class ProviderRegistry {
+    providers = new Map();
+    defaultId = null;
+    logger;
+    constructor(opts = {}) {
+        this.logger =
+            opts.logger ?? { debug: () => { }, info: () => { }, warn: () => { }, error: () => { } };
+    }
+    register(provider) {
+        if (this.providers.has(provider.id)) {
+            throw new Error(`Provider already registered with id "${provider.id}"`);
+        }
+        this.providers.set(provider.id, provider);
+        if (this.defaultId === null)
+            this.defaultId = provider.id;
+        return this;
+    }
+    unregister(id) {
+        const removed = this.providers.delete(id);
+        if (this.defaultId === id)
+            this.defaultId = this.providers.keys().next().value ?? null;
+        return removed;
+    }
+    has(id) {
+        return this.providers.has(id);
+    }
+    get(id) {
+        return this.providers.get(id);
+    }
+    list() {
+        return [...this.providers.values()];
+    }
+    setDefault(id) {
+        if (!this.providers.has(id)) {
+            throw new Error(`Cannot set default to unknown provider id "${id}"`);
+        }
+        this.defaultId = id;
+    }
+    getDefault() {
+        return this.defaultId ? this.providers.get(this.defaultId) : undefined;
+    }
+    /**
+     * Pick a provider. Lookup order:
+     *   - explicit id
+     *   - default
+     *   - first registered (deterministic — Map preserves insertion order)
+     * Throws if the registry is empty or the requested id doesn't exist.
+     */
+    pick(id) {
+        if (id) {
+            const p = this.providers.get(id);
+            if (!p)
+                throw new Error(`No provider registered with id "${id}"`);
+            return p;
+        }
+        const def = this.getDefault();
+        if (def)
+            return def;
+        const first = this.providers.values().next().value;
+        if (!first)
+            throw new Error('ProviderRegistry is empty');
+        return first;
+    }
+    /**
+     * Probe every registered provider in parallel and return the results.
+     * Useful for the `/provider health` UX and for surfacing config issues at
+     * startup.
+     */
+    async healthCheckAll() {
+        const entries = [...this.providers.values()];
+        const results = await Promise.all(entries.map(async (p) => {
+            const r = await p.healthCheck().catch((e) => ({
+                ok: false,
+                reason: e instanceof Error ? e.message : String(e),
+            }));
+            return { id: p.id, ...r };
+        }));
+        return results;
+    }
+    async closeAll() {
+        await Promise.all(this.list().map((p) => p.close().catch((e) => {
+            this.logger.warn(`[registry] close failed for ${p.id}:`, e);
+        })));
+        this.providers.clear();
+        this.defaultId = null;
+    }
+}
+//# sourceMappingURL=selector.js.map

package/dist/providers/selector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector.js","sourceRoot":"","sources":["../../src/providers/selector.ts"],"names":[],"mappings":"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"}