@combycode/llm-sdk 1.0.0-rc.0

package/dist/server/dispatch.d.ts

@@ -0,0 +1,35 @@
+/** dispatch — execute a chat-completion request against a ResolvedTarget.
+ *
+ *  Takes the user message + ConversationHistory (already containing prior
+ *  turns), wraps the target's LLMClient in a transient AgentLoop that
+ *  reuses the history, runs it, and returns the assistant text plus token
+ *  counts. The history is mutated in place: [user, assistant, ...]. */
+import { AgentLoop } from '../agent/loop';
+import type { ConversationHistory } from '../agent/history';
+import type { HookBus } from '../bus/hook-bus';
+import type { OaiToolDefinition } from './oai-types';
+import type { ResolvedTarget } from './router';
+export interface DispatchInput {
+    target: ResolvedTarget;
+    history: ConversationHistory;
+    userText: string;
+    systemPrompt?: string;
+    /** External tools requested by the OAI client. Filtered out when the entry
+     *  has `allowExternalTools: false`. Wrapped as throw-on-execute AgentTools
+     *  (server-side execution of caller-defined tools is not yet supported). */
+    externalTools?: OaiToolDefinition[];
+    maxOutputTokens?: number;
+    temperature?: number;
+    hooks: HookBus;
+    /** When provided, dispatch reuses this AgentLoop instead of building a fresh
+     *  one. Resolved by an AgentLoaderPlugin so server callers can persist agent
+     *  state across requests (system prompt, tools, attached history). */
+    agentLoop?: AgentLoop;
+}
+export interface DispatchResult {
+    text: string;
+    providerResponseId: string | null;
+    inputTokens: number;
+    outputTokens: number;
+}
+export declare function dispatch(input: DispatchInput): Promise<DispatchResult>;

package/dist/server/loaders.d.ts

@@ -0,0 +1,26 @@
+/** Loader plugin slots for OaiServer.
+ *
+ *  AgentLoaderPlugin: dynamically resolves an AgentLoop for a given (userId,
+ *  model) pair, allowing per-user / per-conversation agent instances rather
+ *  than the static ServerEntry registration.
+ *
+ *  ConversationLoaderPlugin: rehydrates a ConversationHistory by
+ *  (userId, conversationId), letting persistence live outside ResponseStore. */
+import type { AgentLoop } from '../agent/loop';
+import type { ConversationHistory } from '../agent/history';
+export interface AgentLoaderContext {
+    userId: string | null;
+    model: string;
+    conversationId?: string;
+}
+export interface AgentLoaderPlugin {
+    load(ctx: AgentLoaderContext): Promise<AgentLoop | null>;
+}
+export interface ConversationLoaderContext {
+    userId: string | null;
+    conversationId: string;
+}
+export interface ConversationLoaderPlugin {
+    load(ctx: ConversationLoaderContext): Promise<ConversationHistory | null>;
+    save(ctx: ConversationLoaderContext, history: ConversationHistory): Promise<void>;
+}

package/dist/server/oai-adapter.d.ts

@@ -0,0 +1,30 @@
+/** Pure mapping functions between OpenAI Chat Completions shapes and SDK types. */
+import type { OaiChatMessage, OaiChatRequest, OaiChatResponse, OaiChatStreamChunk, OaiErrorBody, OaiFinishReason, OaiModelEntry } from './oai-types';
+export declare function oaiContentToText(content: OaiChatMessage['content']): string;
+export declare function extractLastUserText(messages: OaiChatMessage[]): string;
+export declare function extractSystemText(messages: OaiChatMessage[]): string;
+export declare function estimateTokens(text: string): number;
+export interface BuildChatResponseInput {
+    model: string;
+    text: string;
+    promptTokens?: number;
+    completionTokens?: number;
+    finishReason?: OaiFinishReason;
+    id?: string;
+}
+export declare function buildChatResponse(input: BuildChatResponseInput): OaiChatResponse;
+export interface BuildStreamChunkInput {
+    id: string;
+    model: string;
+    delta?: {
+        role?: 'assistant';
+        content?: string;
+    };
+    finishReason?: OaiFinishReason;
+}
+export declare function buildStreamChunk(input: BuildStreamChunkInput): OaiChatStreamChunk;
+export declare function formatSseFrame(data: unknown): string;
+export declare const SSE_TERMINATOR = "data: [DONE]\n\n";
+export declare function buildModelsList(ids: string[]): OaiModelEntry[];
+export declare function buildErrorBody(message: string, type?: string, code?: string): OaiErrorBody;
+export declare function validateChatRequest(req: unknown): OaiChatRequest;

package/dist/server/oai-types.d.ts

@@ -0,0 +1,114 @@
+/** OpenAI Chat Completions API types — request/response shapes we accept and emit.
+ *
+ *  V1 scope: the subset real clients (LM Studio, Open WebUI, the official
+ *  openai npm package) actually send. Unused/rare fields are omitted. */
+export type OaiRole = 'system' | 'user' | 'assistant' | 'tool';
+export interface OaiContentPartText {
+    type: 'text';
+    text: string;
+}
+export interface OaiContentPartImageUrl {
+    type: 'image_url';
+    image_url: {
+        url: string;
+        detail?: 'auto' | 'low' | 'high';
+    };
+}
+export type OaiContentPart = OaiContentPartText | OaiContentPartImageUrl;
+export interface OaiToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface OaiChatMessage {
+    role: OaiRole;
+    /** OAI clients use either a string or an array of parts. V1 reads text parts,
+     *  ignores others. `null` appears for assistant messages that are pure tool
+     *  calls — we treat it as empty string. */
+    content: string | OaiContentPart[] | null;
+    name?: string;
+    tool_call_id?: string;
+    tool_calls?: OaiToolCall[];
+}
+export interface OaiToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
+export interface OaiChatRequest {
+    model: string;
+    messages: OaiChatMessage[];
+    stream?: boolean;
+    temperature?: number;
+    max_tokens?: number;
+    top_p?: number;
+    tools?: OaiToolDefinition[];
+    tool_choice?: 'auto' | 'none' | 'required' | {
+        type: 'function';
+        function: {
+            name: string;
+        };
+    };
+    /** Arbitrary per-user identifier. */
+    user?: string;
+}
+export type OaiFinishReason = 'stop' | 'length' | 'tool_calls' | 'content_filter' | null;
+export interface OaiChatChoice {
+    index: number;
+    message: OaiChatMessage;
+    finish_reason: OaiFinishReason;
+}
+export interface OaiUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+export interface OaiChatResponse {
+    id: string;
+    object: 'chat.completion';
+    created: number;
+    model: string;
+    choices: OaiChatChoice[];
+    usage: OaiUsage;
+}
+export interface OaiChatStreamDelta {
+    role?: OaiRole;
+    content?: string;
+    tool_calls?: OaiToolCall[];
+}
+export interface OaiChatStreamChoice {
+    index: number;
+    delta: OaiChatStreamDelta;
+    finish_reason: OaiFinishReason;
+}
+export interface OaiChatStreamChunk {
+    id: string;
+    object: 'chat.completion.chunk';
+    created: number;
+    model: string;
+    choices: OaiChatStreamChoice[];
+}
+export interface OaiModelEntry {
+    id: string;
+    object: 'model';
+    created: number;
+    owned_by: string;
+}
+export interface OaiModelsResponse {
+    object: 'list';
+    data: OaiModelEntry[];
+}
+export interface OaiErrorBody {
+    error: {
+        message: string;
+        type: string;
+        code?: string;
+        param?: string;
+    };
+}

package/dist/server/response-store.d.ts

@@ -0,0 +1,59 @@
+/** ResponseStore — persistent registry keyed by `(userId, response_id)` for
+ *  multi-user mode, or just by response_id when unauthenticated.
+ *
+ *  Used by the OAI server to continue stateful conversations across requests.
+ *  Backing store is the generic Persistence interface — in-memory for tests,
+ *  FilePersistence on disk by default. */
+import { ConversationHistory } from '../agent/history';
+import type { Persistence } from '../plugins/persistence/types';
+export interface ResponseTarget {
+    /** 'direct' (registered LLMClient) — server-side AgentLoop wraps it. */
+    kind: 'direct';
+    /** Human-readable model name (what the client asked for, before resolution). */
+    model: string;
+    /** Routing tag (provider/model for direct entries). */
+    id: string;
+}
+export interface ResponseStoreEntryMeta {
+    localResponseId: string;
+    /** Owner — set when AuthPlugin is attached. null for unauthenticated. */
+    userId: string | null;
+    createdAt: number;
+    updatedAt: number;
+    target: ResponseTarget;
+    /** Provider-side response id (OpenAI / xAI) for chain passthrough. */
+    providerResponseId: string | null;
+    providerStateExpiresAt: number | null;
+}
+export interface ResponseStoreEntry extends ResponseStoreEntryMeta {
+    history: ConversationHistory;
+}
+export interface ResponseStoreConfig {
+    persistence?: Persistence;
+    /** Key prefix used when writing to the Persistence backend. Default 'response:'. */
+    keyPrefix?: string;
+    /** Max entries kept in-memory. Default 10_000. */
+    memoryCapacity?: number;
+}
+export declare class ResponseStore {
+    private readonly persistence;
+    private readonly keyPrefix;
+    private readonly memoryCapacity;
+    private readonly cache;
+    constructor(config?: ResponseStoreConfig);
+    get(localResponseId: string, userId?: string | null): Promise<ResponseStoreEntry | null>;
+    put(entry: Omit<ResponseStoreEntry, 'createdAt' | 'updatedAt'> & {
+        createdAt?: number;
+        updatedAt?: number;
+    }): Promise<ResponseStoreEntry>;
+    delete(localResponseId: string, userId?: string | null): Promise<void>;
+    /** List response ids for a given user (or all unauthenticated entries). */
+    list(userId?: string | null): Promise<string[]>;
+    static newId(): string;
+    static hasFreshProviderState(entry: Pick<ResponseStoreEntry, 'providerResponseId' | 'providerStateExpiresAt'>, now?: number): boolean;
+    private cacheKey;
+    private cacheKeyPrefix;
+    private persistKey;
+    private persistKeyPrefix;
+    private putInCache;
+}

package/dist/server/router.d.ts

@@ -0,0 +1,59 @@
+/** ModelRouter — resolves model names to registered ServerEntry targets. */
+import type { AgentTool } from '../agent/types';
+import type { LLMClient } from '../llm/client';
+export interface ServerEntry {
+    /** Model id as it appears in OAI requests. */
+    model: string;
+    /** Pre-configured LLMClient for this model. */
+    client: LLMClient;
+    /** Internal tools (executable on the server) that this entry exposes. */
+    internalTools?: AgentTool[];
+    /** When false, client-supplied tools in the OAI request are dropped. Default true. */
+    allowExternalTools?: boolean;
+    /** Optional capability metadata exposed in /v1/models. */
+    capabilities?: {
+        supportsPreviousResponseId?: boolean;
+        stateRetentionDays?: number | null;
+        tools?: boolean;
+        vision?: boolean;
+        reasoning?: boolean;
+        maxContext?: number;
+    };
+}
+export interface ResolvedTarget {
+    entry: ServerEntry;
+    client: LLMClient;
+    model: string;
+    internalTools: AgentTool[];
+    allowExternalTools: boolean;
+    supportsPreviousResponseId: boolean;
+    stateRetentionDays: number | null;
+}
+export interface ModelListing {
+    id: string;
+    object: 'model';
+    created: number;
+    owned_by: string;
+    orxa?: {
+        routing: 'direct';
+        apis: Array<'responses' | 'chat.completions'>;
+        supports_previous_response_id?: boolean;
+        state_retention_days?: number | null;
+        capabilities?: {
+            tools?: boolean;
+            vision?: boolean;
+            reasoning?: boolean;
+            max_context?: number;
+        };
+    };
+}
+export declare class ModelRouter {
+    private readonly byModel;
+    constructor(config: {
+        entries: ServerEntry[];
+    });
+    register(e: ServerEntry): void;
+    unregister(model: string): boolean;
+    list(): ModelListing[];
+    resolve(modelName: string): ResolvedTarget;
+}

package/dist/server/server.d.ts

@@ -0,0 +1,61 @@
+/** OaiServer — OpenAI-compatible HTTP front-end for registered LLM clients.
+ *
+ *  Endpoints:
+ *    POST /v1/chat/completions   — primary chat surface
+ *    GET  /v1/models             — lists registered model entries
+ *    GET  /health                — liveness probe
+ *
+ *  Plugin slots:
+ *    - AuthPlugin: per-request authentication (Bearer keys, OAuth, etc.)
+ *    - AgentLoaderPlugin: dynamic AgentLoop resolution (per-user agents)
+ *    - ConversationLoaderPlugin: history hydration from external storage
+ *
+ *  Bun.serve is the runtime; tests can avoid binding a port by calling
+ *  `handle(request)` directly. */
+import { HookBus } from '../bus/hook-bus';
+import type { AuthPlugin } from './auth';
+import type { AgentLoaderPlugin, ConversationLoaderPlugin } from './loaders';
+import { type ServerEntry } from './router';
+import { ResponseStore } from './response-store';
+import type { Persistence } from '../plugins/persistence/types';
+export interface OaiServerConfig {
+    entries?: ServerEntry[];
+    port?: number;
+    hostname?: string;
+    hooks?: HookBus;
+    auth?: AuthPlugin;
+    agentLoader?: AgentLoaderPlugin;
+    conversationLoader?: ConversationLoaderPlugin;
+    responseStore?: ResponseStore;
+    responseStorePersistence?: Persistence;
+    /** Fake-streaming chunk size for /v1/chat/completions stream:true. Default 40. */
+    streamChunkChars?: number;
+}
+export declare class OaiServer {
+    readonly id: string;
+    readonly hooks: HookBus;
+    private readonly router;
+    private readonly store;
+    private readonly auth;
+    private readonly agentLoader;
+    private readonly conversationLoader;
+    private readonly port;
+    private readonly hostname;
+    private server;
+    constructor(config?: OaiServerConfig);
+    register(entry: ServerEntry): void;
+    unregister(model: string): boolean;
+    start(): {
+        port: number;
+        hostname: string;
+    };
+    stop(): Promise<void>;
+    handle(request: Request): Promise<Response>;
+    private handleChatCompletions;
+    private emitResponse;
+    get responseStore(): ResponseStore;
+    /** @internal */
+    get _agentLoader(): AgentLoaderPlugin | null;
+    /** @internal */
+    get _conversationLoader(): ConversationLoaderPlugin | null;
+}

package/dist/types/request-context.d.ts

@@ -0,0 +1,46 @@
+/** RequestContext — propagates accumulating IDs and routing keys across the
+ *  4 layers (network → llm → agent → server) and through plugin handlers.
+ *
+ *  Mint-if-absent rule: each layer fills in what's missing.
+ *    - server mints requestId        (or agent mints if no server)
+ *    - agent mints callId            (or LLM mints if no agent)
+ *    - LLM mints clientId            (per construction, persistent)
+ *    - LLM computes queueName/cacheKey/configName (formula defaults)
+ *
+ *  Override semantics:
+ *    - agent MAY override cacheKey, configName (semantic)
+ *    - agent MUST NOT override queueName (infrastructure)
+ *
+ *  See reports/016 §RequestContext for full lifetime table. */
+export interface RequestContext {
+    /** Minted by the HOLDER (engine/server/orchestrator) once, lives for its
+     *  lifetime (a CLI process / browser page). Shared by every request under it.
+     *  A bare standalone client mints its own. `sessionId:requestId` forms the
+     *  OTel trace id. */
+    sessionId?: string;
+    /** Set by AuthPlugin on authenticated request. Identifies the user across
+     *  requests. Used to scope ResponseStore + ConversationLoader. */
+    userId?: string;
+    /** Per-request id — minted at each request starting point (mint-if-absent:
+     *  server/agent set it, else the LLM client mints in buildContext). Follows
+     *  the whole chain; the request half of the trace id. */
+    requestId?: string;
+    /** = `history.id`. Stable for the lifetime of the conversation. */
+    conversationId?: string;
+    /** Unique per `.complete()` / `.stream()` call. */
+    callId?: string;
+    /** UUID per LLMClient instance. Set in client ctor. */
+    clientId?: string;
+    /** Routing key for the network engine's queues. Default formula:
+     *  `"$provider/$model"`. NOT overridable from agent (infrastructure). */
+    queueName?: string;
+    /** Cache key. Computed as content hash by default. Agent MAY override. */
+    cacheKey?: string;
+    /** Cache namespace. Default: `"default"`. */
+    cacheName?: string;
+    /** Settings registry key for ConfigurationPlugin. Default formula:
+     *  `"$provider/$model"`. Agent MAY override. */
+    configName?: string;
+    providerResponseId?: string;
+    previousResponseId?: string;
+}

package/dist/util/async.d.ts

@@ -0,0 +1,3 @@
+/** Async primitives shared across the SDK. */
+/** Resolve after `ms` milliseconds. */
+export declare function sleep(ms: number): Promise<void>;

package/dist/util/base64.d.ts

@@ -0,0 +1,8 @@
+/** Base64 <-> bytes helpers — the single source of truth across the SDK. */
+/** Decode a base64 string to raw bytes. */
+export declare function base64ToBytes(b64: string): Uint8Array;
+/** Encode bytes as a base64 string. Uses Node/Bun `Buffer` when present
+ *  (fastest), else a browser-safe `btoa`. */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/** Decode a base64 payload to a UTF-8 string. */
+export declare function base64ToUtf8(b64: string): string;

package/dist/util/duration.d.ts

@@ -0,0 +1,12 @@
+/** Compact duration strings — a reusable pattern across the SDK (server-state
+ *  retention, cache TTLs, timeouts, etc.).
+ *
+ *  Format: `<number><unit>` where unit is one of s/m/h/d/w. Examples:
+ *    "30s", "5m", "72h", "3d", "2w"
+ *
+ *  parseDuration("72h") -> 259_200_000 (ms)
+ */
+/** Parse a duration string to milliseconds. Throws on malformed input. */
+export declare function parseDuration(value: string): number;
+/** Parse to milliseconds, or return null for null/undefined/empty (not for malformed). */
+export declare function parseDurationOrNull(value: string | null | undefined): number | null;

package/dist/util/http.d.ts

@@ -0,0 +1,9 @@
+/** Small HTTP header helpers shared across network + server layers. */
+/** Lowercase-keyed plain record from a WHATWG `Headers`. */
+export declare function headersToRecord(headers: Headers): Record<string, string>;
+/** Parse an integer header value, or null if absent / not a number. */
+export declare function parseIntHeader(headers: Record<string, string>, key: string): number | null;
+/** Combine multiple AbortSignals into one that aborts when any of them does. */
+export declare function anySignal(...signals: AbortSignal[]): AbortSignal;
+/** Parse a fetch Response body by declared type. */
+export declare function parseResponseBody(response: Response, type: 'json' | 'arraybuffer' | 'text'): Promise<unknown>;

package/dist/util/image-mime.d.ts

@@ -0,0 +1,8 @@
+/** Detect an image's MIME type from its leading magic bytes.
+ *
+ *  Providers sometimes return a generated image with the WRONG declared mime
+ *  (e.g. xAI hands back JPEG bytes labeled "image/png"). When that image is then
+ *  forwarded as a source for image-to-video / image-edit, strict validators like
+ *  Google Veo compare the declared mime against the actual bytes and reject the
+ *  request with a 400. Sniffing the bytes lets us self-correct the label. */
+export declare function sniffImageMime(b: Uint8Array): string | undefined;

package/dist/util/json-schema.d.ts

@@ -0,0 +1,7 @@
+/** Minimal JSON Schema validator (zero-dep). Covers the common keywords —
+ *  type, required, properties, items, enum, const, additionalProperties — which
+ *  is enough to validate MCP tool `structuredContent` against its `outputSchema`.
+ *  Not a full Draft 2020-12 implementation (no $ref, allOf/anyOf, formats, …). */
+/** Validate `value` against `schema`; returns a list of human-readable errors
+ *  (empty = valid). */
+export declare function validateJsonSchema(schema: Record<string, unknown>, value: unknown, path?: string): string[];

package/dist/util/wav.d.ts

@@ -0,0 +1,20 @@
+/** WAV (RIFF) container helpers.
+ *
+ *  Some providers return raw, header-less PCM samples — notably Google TTS,
+ *  which emits `audio/l16; rate=24000; channels=1`. Players that expect a
+ *  container (browsers' <audio>, most audio libraries) can't read bare PCM,
+ *  so we wrap it in a minimal 44-byte WAV header. */
+/** True for raw PCM mime types that need a WAV container (e.g. Google's L16). */
+export declare function isRawPcmMime(mime: string): boolean;
+/** Parse `rate=` / `channels=` params out of an L16 mime, with sane defaults. */
+export declare function parsePcmParams(mime: string): {
+    sampleRate: number;
+    channels: number;
+};
+/** Prepend a 44-byte WAV header to little-endian 16-bit PCM samples. */
+export declare function pcmToWav(pcm: Uint8Array, sampleRate: number, channels: number): Uint8Array;
+/** If `mime` is raw PCM, return WAV-wrapped bytes + `audio/wav`; else unchanged. */
+export declare function ensurePlayableAudio(data: Uint8Array, mime: string): {
+    data: Uint8Array;
+    mimeType: string;
+};

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@combycode/llm-sdk",
+  "version": "1.0.0-rc.0",
+  "description": "Unified, pluggable AI SDK for accessing the LLMs of every major provider (Anthropic, OpenAI, Google, xAI, OpenRouter) through one API. Cross-environment: Node, Bun, and the browser.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "browser": {
+    "./src/bus/async-context.ts": "./src/bus/async-context.browser.ts"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/index.browser.js",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun run clean && bun run build:js && bun run build:types",
+    "build:js": "bun run scripts/build.ts",
+    "build:types": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "test:unit": "bun test tests/unit",
+    "test:integration": "bun test tests/integration",
+    "test:helpers": "bun test tests/helpers",
+    "test:live": "bun test tests/live",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint src tests",
+    "lint:fix": "biome lint --write src tests",
+    "format": "biome format --write src tests",
+    "check": "biome check src tests",
+    "check:fix": "biome check --write src tests"
+  },
+  "optionalDependencies": {
+    "tiktoken": "^1.0.22"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.13",
+    "@types/bun": "latest",
+    "esbuild": "0.28.1",
+    "typescript": "^5.6.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/combycode/llm-sdk-ts.git"
+  },
+  "homepage": "https://llm-sdk.combycode.com",
+  "bugs": {
+    "url": "https://github.com/combycode/llm-sdk-ts/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "llm",
+    "agent",
+    "anthropic",
+    "openai",
+    "google",
+    "xai",
+    "openrouter",
+    "agentic",
+    "tools",
+    "streaming",
+    "openai-compatible",
+    "browser",
+    "bun"
+  ],
+  "license": "MIT",
+  "author": "CombyCode"
+}