rebellm-bridge 0.1.0

package/dist/openai.js

@@ -0,0 +1,265 @@
+import { randomBytes } from 'node:crypto';
+import { HttpError, clientGone, pathOf, readJson, sendJson } from './http.js';
+/** Well inside the read timeouts of common clients (Node's fetch: 300 s). */
+export const KEEPALIVE_MS = 15_000;
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const isStr = (v) => typeof v === 'string';
+/** OpenAI's error shape, which its SDKs turn into readable messages. */
+export function sendError(res, status, message, type, code) {
+    sendJson(res, status, { error: { message, type, code: code ?? null } });
+}
+const ROLES = {
+    system: 'system',
+    developer: 'system',
+    user: 'user',
+    assistant: 'assistant',
+    tool: 'tool',
+};
+/** Text of a message's content; parts the tab cannot take become a note. */
+function contentText(c) {
+    if (c === undefined || c === null)
+        return '';
+    if (isStr(c))
+        return c;
+    if (!Array.isArray(c))
+        return null;
+    const parts = [];
+    for (const p of c) {
+        if (!isObj(p) || !isStr(p.type))
+            return null;
+        parts.push(p.type === 'text' && isStr(p.text) ? p.text : `[${p.type} omitted]`);
+    }
+    return parts.join('\n');
+}
+function toolArgs(a) {
+    if (a === undefined || a === null || a === '')
+        return {};
+    if (isObj(a))
+        return a;
+    if (!isStr(a))
+        return null;
+    try {
+        const o = JSON.parse(a);
+        return isObj(o) ? o : null;
+    }
+    catch {
+        return null;
+    }
+}
+function toolSchemas(tools) {
+    if (!Array.isArray(tools))
+        return '`tools` must be an array';
+    const out = [];
+    for (const [i, t] of tools.entries()) {
+        const f = isObj(t) ? t.function : undefined;
+        if (!isObj(t) || t.type !== 'function' || !isObj(f) || !isStr(f.name) || !f.name)
+            return `tools[${i}] must be { type: 'function', function: { name, ... } }`;
+        if (f.description !== undefined && !isStr(f.description))
+            return `tools[${i}].function.description must be a string`;
+        if (f.parameters !== undefined && !isObj(f.parameters))
+            return `tools[${i}].function.parameters must be an object`;
+        out.push({
+            type: 'function',
+            function: {
+                name: f.name,
+                description: f.description ?? '',
+                parameters: f.parameters ?? { type: 'object', properties: {} },
+            },
+        });
+    }
+    return out;
+}
+/** An OpenAI chat completion request as the tab's `chat`; the error says what is wrong with it. */
+export function toChatInput(body) {
+    if (!isObj(body))
+        return { error: 'the body must be a JSON object' };
+    if (!Array.isArray(body.messages) || !body.messages.length)
+        return { error: '`messages` must be a non-empty array' };
+    // A tool result names the call it answers only by id; the tab wants the tool's name.
+    const callNames = new Map();
+    const messages = [];
+    for (const [i, m] of body.messages.entries()) {
+        if (!isObj(m))
+            return { error: `messages[${i}] must be an object` };
+        const role = isStr(m.role) ? ROLES[m.role] : undefined;
+        if (!role)
+            return { error: `messages[${i}].role ${JSON.stringify(m.role)} is not supported` };
+        const content = contentText(m.content);
+        if (content === null)
+            return { error: `messages[${i}].content must be a string or an array of parts` };
+        const out = { role, content };
+        if (role === 'assistant' && m.tool_calls !== undefined && m.tool_calls !== null) {
+            if (!Array.isArray(m.tool_calls))
+                return { error: `messages[${i}].tool_calls must be an array` };
+            const calls = [];
+            for (const c of m.tool_calls) {
+                const f = isObj(c) ? c.function : undefined;
+                const args = isObj(f) ? toolArgs(f.arguments) : null;
+                if (!isObj(c) || !isObj(f) || !isStr(f.name) || !args)
+                    return { error: `messages[${i}].tool_calls needs a function name and JSON object arguments` };
+                if (isStr(c.id))
+                    callNames.set(c.id, f.name);
+                calls.push({ ...(isStr(c.id) ? { id: c.id } : {}), function: { name: f.name, arguments: args } });
+            }
+            if (calls.length)
+                out.tool_calls = calls;
+        }
+        if (role === 'tool') {
+            const name = isStr(m.name) ? m.name : isStr(m.tool_call_id) ? callNames.get(m.tool_call_id) : undefined;
+            if (name)
+                out.name = name;
+        }
+        messages.push(out);
+    }
+    const input = { messages };
+    if (body.tools !== undefined && body.tools !== null && body.tool_choice !== 'none') {
+        const tools = toolSchemas(body.tools);
+        if (isStr(tools))
+            return { error: tools };
+        if (tools.length)
+            input.tools = tools;
+    }
+    const max = body.max_completion_tokens ?? body.max_tokens;
+    if (max !== undefined && max !== null) {
+        if (!Number.isInteger(max) || max < 1)
+            return { error: '`max_tokens` must be a positive integer' };
+        input.maxTokens = max;
+    }
+    const temp = body.temperature;
+    if (temp !== undefined && temp !== null) {
+        if (typeof temp !== 'number' || !Number.isFinite(temp) || temp < 0)
+            return { error: '`temperature` must be a number of at least 0' };
+        input.temperature = temp;
+    }
+    const includeUsage = isObj(body.stream_options) && body.stream_options.include_usage === true;
+    return { input, stream: body.stream === true, includeUsage };
+}
+const finishReason = (r) => r.calls.length || r.stop === 'tool_call' ? 'tool_calls' : r.stop === 'length' ? 'length' : 'stop';
+const usage = (u) => ({
+    prompt_tokens: u.prompt,
+    completion_tokens: u.completion,
+    total_tokens: u.prompt + u.completion,
+});
+const newId = () => randomBytes(12).toString('hex');
+const toolCall = (c) => ({
+    id: c.id ?? `call_${newId()}`,
+    type: 'function',
+    function: { name: c.function.name, arguments: JSON.stringify(c.function.arguments) },
+});
+/** A non-streamed answer in OpenAI's shape. */
+export function completion(r, meta) {
+    const calls = r.calls.map(toolCall);
+    return {
+        ...meta,
+        object: 'chat.completion',
+        choices: [
+            {
+                index: 0,
+                message: {
+                    role: 'assistant',
+                    // OpenAI sends null content beside tool calls when there is no text.
+                    content: calls.length && !r.text ? null : r.text,
+                    ...(calls.length ? { tool_calls: calls } : {}),
+                },
+                finish_reason: finishReason(r),
+            },
+        ],
+        usage: usage(r.usage),
+    };
+}
+/** The HTTP routes for OpenAI-style clients: completions, models and health. */
+export function openaiRoutes(tab, o) {
+    async function completions(req, res) {
+        let body;
+        try {
+            body = await readJson(req);
+        }
+        catch (e) {
+            return sendError(res, e instanceof HttpError ? e.status : 400, e.message, 'invalid_request_error');
+        }
+        const parsed = toChatInput(body);
+        if ('error' in parsed)
+            return sendError(res, 400, parsed.error, 'invalid_request_error');
+        const gone = clientGone(res);
+        const missing = await tab.waitReady(o.waitMs, gone);
+        if (gone.aborted)
+            return;
+        if (missing)
+            return sendError(res, 503, missing.message, 'service_unavailable', missing.code);
+        const meta = { id: `chatcmpl-${newId()}`, created: Math.floor(Date.now() / 1000), model: tab.modelName };
+        if (parsed.stream)
+            return stream(res, parsed.input, parsed.includeUsage, meta, gone);
+        try {
+            sendJson(res, 200, completion(await tab.chat(parsed.input, { signal: gone }), meta));
+        }
+        catch (e) {
+            if (gone.aborted)
+                return;
+            const err = e;
+            if (err.kind === 'no_tab')
+                return sendError(res, 503, err.message, 'service_unavailable', 'no_tab');
+            sendError(res, 502, err.message, 'api_error', err.kind === 'disconnected' ? 'tab_disconnected' : 'tab_error');
+        }
+    }
+    async function stream(res, input, includeUsage, meta, signal) {
+        res.writeHead(200, { 'Content-Type': 'text/event-stream; charset=utf-8', 'Cache-Control': 'no-cache' });
+        res.socket?.setNoDelay(true);
+        const write = (o) => res.write(`data: ${JSON.stringify(o)}\n\n`);
+        const chunk = (delta, finish = null) => write({ ...meta, object: 'chat.completion.chunk', choices: [{ index: 0, delta, finish_reason: finish }] });
+        chunk({ role: 'assistant', content: '' });
+        // The tab may take minutes before its first token; a comment keeps clients from giving up.
+        const beat = setInterval(() => res.write(': keep-alive\n\n'), o.keepAliveMs ?? KEEPALIVE_MS);
+        let calls = 0;
+        try {
+            const r = await tab.chat(input, {
+                signal,
+                onEvent: (e) => {
+                    if (e.t === 'token')
+                        chunk({ content: e.text });
+                    else if (e.t === 'tool_call') {
+                        chunk({ tool_calls: e.calls.map((c, i) => ({ index: calls + i, ...toolCall(c) })) });
+                        calls += e.calls.length;
+                    }
+                },
+            });
+            chunk({}, finishReason(r));
+            if (includeUsage)
+                write({ ...meta, object: 'chat.completion.chunk', choices: [], usage: usage(r.usage) });
+            res.end('data: [DONE]\n\n');
+        }
+        catch (e) {
+            if (signal.aborted)
+                return;
+            // OpenAI's SDKs raise an error for a data chunk that carries one.
+            write({ error: { message: e.message, type: 'api_error', code: null } });
+            res.end();
+        }
+        finally {
+            clearInterval(beat);
+        }
+    }
+    return function route(req, res) {
+        const path = pathOf(req);
+        const get = req.method === 'GET' || req.method === 'HEAD';
+        if (path === '/health' && get)
+            return sendJson(res, 200, { service: 'rebellm-bridge', ...tab.health() });
+        if (path === '/v1/models' && get) {
+            const model = tab.health().model;
+            return sendJson(res, 200, {
+                object: 'list',
+                data: model ? [{ id: model, object: 'model', created: 0, owned_by: 'rebellm' }] : [],
+            });
+        }
+        if (path === '/v1/chat/completions') {
+            if (req.method !== 'POST')
+                return sendError(res, 405, 'use POST', 'invalid_request_error');
+            return void completions(req, res).catch((e) => {
+                if (!res.headersSent)
+                    sendError(res, 500, e.message, 'api_error');
+                else
+                    res.end();
+            });
+        }
+        sendError(res, 404, `no route for ${req.method} ${path}`, 'invalid_request_error', 'not_found');
+    };
+}

package/dist/protocol.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Protocol v1 between the RebeLLM tab (client) and this bridge (server): JSON text frames
+ * over one WebSocket. The RebeLLM app's `local-bridge` spec owns it; this is the copy.
+ */
+export declare const PROTOCOL_VERSION = 1;
+export type Role = 'system' | 'user' | 'assistant' | 'tool';
+export interface ToolCall {
+    id?: string;
+    function: {
+        name: string;
+        arguments: Record<string, unknown>;
+    };
+}
+export interface ChatMessage {
+    role: Role;
+    content: string;
+    name?: string;
+    tool_calls?: ToolCall[];
+}
+export interface ToolSchema {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+export type StopReason = 'eos' | 'length' | 'tool_call' | 'abort';
+export type ModelState = 'loading' | 'ready' | 'unavailable';
+export interface Usage {
+    prompt: number;
+    completion: number;
+    tokensPerSec: number;
+}
+/** Tab → bridge. */
+export type TabMessage = {
+    t: 'hello';
+    v: number;
+    token: string;
+    model: string;
+    contextTokens: number;
+    app: string;
+} | {
+    t: 'token';
+    id: string;
+    text: string;
+} | {
+    t: 'tool_call';
+    id: string;
+    calls: ToolCall[];
+} | {
+    t: 'done';
+    id: string;
+    stop: StopReason;
+    usage: Usage;
+} | {
+    t: 'error';
+    id?: string;
+    message: string;
+} | {
+    t: 'queued';
+    id: string;
+    position: number;
+} | {
+    t: 'status';
+    state: ModelState;
+    model?: string;
+    detail?: string;
+} | {
+    t: 'ping';
+} | {
+    t: 'pong';
+};
+export interface ChatRequest {
+    t: 'chat';
+    id: string;
+    messages: ChatMessage[];
+    tools?: ToolSchema[];
+    maxTokens?: number;
+    temperature?: number;
+}
+/** Bridge → tab. */
+export type BridgeMessage = {
+    t: 'ok';
+} | {
+    t: 'error';
+    code: 'auth' | 'version' | 'busy';
+    message?: string;
+} | ChatRequest | {
+    t: 'abort';
+    id: string;
+} | {
+    t: 'ping';
+} | {
+    t: 'pong';
+};
+/** Parses one frame from the tab; null for anything that is not a v1 message. */
+export declare function parseTabMessage(raw: string): TabMessage | null;
+export declare const encode: (m: BridgeMessage) => string;

package/dist/protocol.js

@@ -0,0 +1,53 @@
+/**
+ * Protocol v1 between the RebeLLM tab (client) and this bridge (server): JSON text frames
+ * over one WebSocket. The RebeLLM app's `local-bridge` spec owns it; this is the copy.
+ */
+export const PROTOCOL_VERSION = 1;
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const isStr = (v) => typeof v === 'string';
+const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+const optStr = (v) => v === undefined || isStr(v);
+const STOPS = new Set(['eos', 'length', 'tool_call', 'abort']);
+const STATES = new Set(['loading', 'ready', 'unavailable']);
+const isCall = (c) => isObj(c) && optStr(c.id) && isObj(c.function) && isStr(c.function.name) && isObj(c.function.arguments);
+const isUsage = (u) => isObj(u) && isNum(u.prompt) && isNum(u.completion) && isNum(u.tokensPerSec);
+function valid(m) {
+    switch (m.t) {
+        // Any numeric version parses, so the bridge can answer `version` instead of dropping it.
+        case 'hello':
+            return isNum(m.v) && isStr(m.token) && optStr(m.model) && optStr(m.app);
+        case 'token':
+            return isStr(m.id) && isStr(m.text);
+        case 'tool_call':
+            return isStr(m.id) && Array.isArray(m.calls) && m.calls.every(isCall);
+        case 'done':
+            return isStr(m.id) && STOPS.has(m.stop) && isUsage(m.usage);
+        case 'error':
+            return optStr(m.id) && isStr(m.message);
+        case 'queued':
+            return isStr(m.id) && isNum(m.position);
+        case 'status':
+            return STATES.has(m.state) && optStr(m.model) && optStr(m.detail);
+        case 'ping':
+        case 'pong':
+            return true;
+        default:
+            return false;
+    }
+}
+/** Parses one frame from the tab; null for anything that is not a v1 message. */
+export function parseTabMessage(raw) {
+    let o;
+    try {
+        o = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isObj(o) || !valid(o))
+        return null;
+    if (o.t === 'hello')
+        return { model: '', contextTokens: 0, app: '', ...o, t: 'hello' };
+    return o;
+}
+export const encode = (m) => JSON.stringify(m);

package/dist/server.d.ts

@@ -0,0 +1,24 @@
+import { TabLink } from './tab.js';
+export declare const DEFAULT_PORT = 7343;
+export declare const DEFAULT_HOST = "127.0.0.1";
+export interface ServerOptions {
+    host: string;
+    port: number;
+    token: string;
+    waitMs: number;
+    keepAliveMs?: number;
+    log?: (line: string) => void;
+    pingMs?: number;
+    silenceMs?: number;
+}
+export interface BridgeServer {
+    tab: TabLink;
+    host: string;
+    port: number;
+    close(): Promise<void>;
+}
+export declare const isLoopback: (host: string) => boolean;
+/** The name in a Host header, without the port. */
+export declare function hostName(header: string): string;
+/** The tab (WebSocket upgrade) and the HTTP clients on one port. */
+export declare function startServer(o: ServerOptions): Promise<BridgeServer>;

package/dist/server.js

@@ -0,0 +1,70 @@
+import { createServer } from 'node:http';
+import { WebSocketServer } from 'ws';
+import { isMessagesPath, messagesRoutes, sendApiError } from './anthropic/routes.js';
+import { pathOf } from './http.js';
+import { openaiRoutes, sendError } from './openai.js';
+import { TabLink } from './tab.js';
+export const DEFAULT_PORT = 7343;
+export const DEFAULT_HOST = '127.0.0.1';
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '::1']);
+export const isLoopback = (host) => LOOPBACK.has(host.replace(/^\[(.*)\]$/, '$1').toLowerCase());
+/** The name in a Host header, without the port. */
+export function hostName(header) {
+    if (header.startsWith('['))
+        return header.slice(1, header.indexOf(']'));
+    return header.split(':')[0] ?? '';
+}
+/** The tab (WebSocket upgrade) and the HTTP clients on one port. */
+export async function startServer(o) {
+    const tab = new TabLink({
+        token: o.token,
+        ...(o.log ? { log: o.log } : {}),
+        ...(o.pingMs ? { pingMs: o.pingMs } : {}),
+        ...(o.silenceMs ? { silenceMs: o.silenceMs } : {}),
+    });
+    const routes = openaiRoutes(tab, { waitMs: o.waitMs, ...(o.keepAliveMs ? { keepAliveMs: o.keepAliveMs } : {}) });
+    const messages = messagesRoutes(tab, { waitMs: o.waitMs, ...(o.keepAliveMs ? { pingMs: o.keepAliveMs } : {}) });
+    // On loopback, a foreign Host means a DNS-rebinding page; bound wider, the user chose it.
+    const strictHost = isLoopback(o.host);
+    const hostOk = (req) => !strictHost || req.headers.host === undefined || isLoopback(hostName(req.headers.host));
+    const server = createServer((req, res) => {
+        // Anthropic clients read only Anthropic's error shape, OpenAI clients only OpenAI's.
+        const anthropic = isMessagesPath(pathOf(req));
+        // Web pages have no business here; local clients send no Origin.
+        if (req.headers.origin !== undefined || !hostOk(req)) {
+            const why = 'the bridge answers local clients only';
+            return anthropic ? sendApiError(res, 403, 'permission_error', why) : sendError(res, 403, why, 'forbidden');
+        }
+        if (anthropic)
+            return messages(req, res);
+        routes(req, res);
+    });
+    const wss = new WebSocketServer({ noServer: true });
+    server.on('upgrade', (req, socket, head) => {
+        if (!hostOk(req)) {
+            socket.end('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n');
+            return;
+        }
+        wss.handleUpgrade(req, socket, head, (ws) => tab.accept(ws));
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(o.port, o.host, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    return {
+        tab,
+        host: o.host,
+        port: server.address().port,
+        async close() {
+            tab.close();
+            for (const c of wss.clients)
+                c.terminate();
+            wss.close();
+            server.closeAllConnections();
+            await new Promise((resolve) => server.close(() => resolve()));
+        },
+    };
+}

package/dist/tab.d.ts

@@ -0,0 +1,102 @@
+import { EventEmitter } from 'node:events';
+import type { WebSocket } from 'ws';
+import { type ChatMessage, type ModelState, type StopReason, type ToolCall, type ToolSchema, type Usage } from './protocol.js';
+export declare const PING_MS = 20000;
+export declare const SILENCE_MS = 50000;
+/** Close codes for a refused `hello`, as the app's stand-in bridge uses them. */
+export declare const CLOSE: {
+    readonly auth: 4000;
+    readonly version: 4001;
+    readonly busy: 4002;
+    readonly helloFirst: 4003;
+};
+export interface ChatInput {
+    messages: ChatMessage[];
+    tools?: ToolSchema[];
+    maxTokens?: number;
+    temperature?: number;
+}
+export type ChatEvent = {
+    t: 'token';
+    text: string;
+} | {
+    t: 'queued';
+    position: number;
+} | {
+    t: 'tool_call';
+    calls: ToolCall[];
+};
+export interface ChatResult {
+    id: string;
+    text: string;
+    calls: ToolCall[];
+    stop: StopReason;
+    usage: Usage;
+}
+export interface ChatOptions {
+    onEvent?: (e: ChatEvent) => void;
+    /** Aborting sends `abort` to the tab and rejects the chat. */
+    signal?: AbortSignal;
+}
+export type ChatErrorKind = 'no_tab' | 'tab' | 'disconnected' | 'aborted';
+export declare class ChatError extends Error {
+    readonly kind: ChatErrorKind;
+    constructor(message: string, kind: ChatErrorKind);
+}
+/** What `/health` and the MCP `status` tool report. */
+export interface Health {
+    tab: boolean;
+    state: ModelState | 'none';
+    model?: string;
+    detail?: string;
+    contextTokens?: number;
+    app?: string;
+}
+export interface Unavailable {
+    code: 'no_tab' | 'model_loading' | 'model_unavailable';
+    message: string;
+}
+export interface TabLinkOptions {
+    token: string;
+    pingMs?: number;
+    silenceMs?: number;
+    log?: (line: string) => void;
+}
+/** Constant-time comparison; hashing first makes the lengths equal. */
+export declare const sameToken: (a: string, b: string) => boolean;
+/**
+ * The one RebeLLM tab connected to this bridge: its `hello`, its model state, and the chats
+ * sent to it, each settled by the tab's `done` or `error` or by the connection closing.
+ * Emits `change` when a tab connects, disconnects or reports a new status.
+ */
+export declare class TabLink extends EventEmitter {
+    private readonly token;
+    private readonly pingMs;
+    private readonly silenceMs;
+    private readonly log;
+    private ws;
+    private hello;
+    private status;
+    private pinger;
+    private pending;
+    private seq;
+    private readonly prefix;
+    constructor(o: TabLinkOptions);
+    get connected(): boolean;
+    /** Takes a new WebSocket; it becomes the tab after a valid `hello`. */
+    accept(ws: WebSocket): void;
+    health(): Health;
+    /** The tab's model name for responses. */
+    get modelName(): string;
+    /** Why a chat cannot start now, or null when the tab's model is ready. */
+    unavailable(): Unavailable | null;
+    /** Resolves null once the model is ready, or the reason it is not after `ms` or an abort. */
+    waitReady(ms: number, signal?: AbortSignal): Promise<Unavailable | null>;
+    /** Sends one chat to the tab; resolves with its answer when the tab says `done`. */
+    chat(input: ChatInput, opts?: ChatOptions): Promise<ChatResult>;
+    /** Drops the tab, failing its open chats. */
+    close(): void;
+    private attach;
+    private detach;
+    private receive;
+}