@combycode/llm-sdk 1.0.0-rc.0

package/dist/llm/types/response.d.ts

@@ -0,0 +1,36 @@
+/** Universal completion response. */
+import type { ContentPart, MediaOutputPart, ToolCallPart } from './messages';
+export interface CompletionResponse {
+    id: string;
+    model: string;
+    content: ContentPart[];
+    finishReason: FinishReason;
+    usage: Usage;
+    text: string;
+    toolCalls: ToolCallPart[];
+    thinking: string | null;
+    /** Media output parts (images, audio, video generated by model). */
+    media: MediaOutputPart[];
+    latencyMs: number;
+    raw: unknown;
+}
+export type FinishReason = 'stop' | 'tool_use' | 'length' | 'content_filter' | 'error';
+export interface Usage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cachedTokens: number;
+    cacheWriteTokens: number;
+    reasoningTokens: number;
+    /** Audio input/output tokens (realtime / audio models). When set, inputTokens/
+     *  outputTokens count only the TEXT portion so cost prices each at its own rate. */
+    audioInputTokens?: number;
+    audioOutputTokens?: number;
+    /** Service tier the provider actually billed, RAW as it reported it (openai
+     *  `flex|priority|…`, anthropic `standard|priority|batch`). Auditable. */
+    serviceTier?: string;
+    /** The raw tier normalized by the adapter to the catalog's tier key — what cost
+     *  uses for `pricing.tiers[...]`. Set alongside serviceTier; usually identical. */
+    pricingTier?: string;
+}
+export declare function emptyUsage(): Usage;

package/dist/llm/types/schema-utils.d.ts

@@ -0,0 +1,8 @@
+/** Shared JSON Schema utilities for provider-agnostic schema preprocessing. */
+import type { JsonSchema } from './tools';
+/**
+ * Recursively ensure every object-typed schema has `additionalProperties: false`.
+ * Required by OpenAI strict mode and Anthropic structured output — providers
+ * reject schemas without this explicit flag. Safe across all providers.
+ */
+export declare function ensureAdditionalProperties(schema: JsonSchema): JsonSchema;

package/dist/llm/types/stream.d.ts

@@ -0,0 +1,42 @@
+/** Universal streaming event types. */
+import type { Usage } from './response';
+export type MediaStreamType = 'image' | 'audio' | 'video';
+export type StreamEvent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'thinking';
+    text: string;
+} | {
+    type: 'tool_call_start';
+    id: string;
+    name: string;
+    _meta?: Record<string, unknown>;
+} | {
+    type: 'tool_call_delta';
+    id: string;
+    arguments: string;
+} | {
+    type: 'tool_call_end';
+    id: string;
+} | {
+    type: 'usage';
+    usage: Usage;
+} | {
+    type: 'done';
+    finishReason: string;
+} | {
+    type: 'error';
+    error: Error;
+} | {
+    type: 'media_start';
+    mediaType: MediaStreamType;
+    mimeType: string;
+} | {
+    type: 'media_chunk';
+    data: string;
+    progress?: number;
+} | {
+    type: 'media_end';
+    mediaId?: string;
+};

package/dist/llm/types/tiers.d.ts

@@ -0,0 +1,11 @@
+/** Unified service tier for a request. The four named values are the
+ *  cross-provider core; the open `(string & {})` lets callers pass any tier
+ *  (e.g. `'scale'`, or a future internal-optimization label) — each adapter
+ *  decides whether it can honor it (pass through if the provider allows it,
+ *  else fall back to that provider's `auto`).
+ *
+ *  `batch` is intentionally NOT a value here — it's a separate API (the Batch
+ *  endpoint), not a per-request flag on a synchronous call.
+ *
+ *  Tier mapping is provider-specific and lives ENTIRELY in the adapters. */
+export type ServiceTier = 'auto' | 'standard' | 'priority' | 'flex' | (string & {});

package/dist/llm/types/tools.d.ts

@@ -0,0 +1,20 @@
+/** Universal tool schema definitions. */
+export interface FunctionTool {
+    type?: 'function';
+    name: string;
+    description: string;
+    parameters: JsonSchema;
+    strict?: boolean;
+    cache?: boolean;
+}
+export interface BuiltinTool {
+    type: 'image_generation' | 'web_search' | 'code_interpreter' | 'file_search' | 'mcp';
+    params?: Record<string, unknown>;
+}
+export type Tool = FunctionTool | BuiltinTool;
+export type ToolChoice = 'auto' | 'none' | 'required' | {
+    name: string;
+};
+export type JsonSchema = Record<string, unknown>;
+export declare function isFunctionTool(tool: Tool): tool is FunctionTool;
+export declare function isBuiltinTool(tool: Tool): tool is BuiltinTool;

package/dist/network/engine.d.ts

@@ -0,0 +1,87 @@
+/** NetworkEngine — multi-queue HTTP router (Layer 1).
+ *
+ *  Holds a Map<queueName, QueueState>. Each queue has its own rate limiter,
+ *  semaphore, retry policy, and request queue. Queues are created lazily on
+ *  first use of a queueName, with default settings (or settings supplied via
+ *  `configureQueue()` BEFORE first use — snapshot semantics).
+ *
+ *  Knows nothing about LLMs, providers, or models. The semantic layer
+ *  (LLMClient) populates `req.provider` and `req.model` for hook payloads
+ *  and decides `queueName` (default formula: "$provider/$model").
+ *
+ *  Public surface:
+ *    - fetch(req, ctx?)        — submit a non-streaming request
+ *    - fetchStream(req, ctx?)  — submit a streaming request (SSE)
+ *    - configureQueue(name, settings) — pre-configure rate limit / retry
+ *    - getQueueState(name)     — introspect a queue (for tests / metrics)
+ *    - destroy()               — drop all queues (for teardown)
+ */
+import { HookBus } from '../bus/hook-bus';
+import type { RequestContext } from '../types/request-context';
+import type { RateLimiterConfig } from './rate-limiter';
+import type { QueueConfig } from './request-queue';
+import { QueueState } from './queue-state';
+import type { RetryConfig } from './queue-state-config';
+import type { ConnectFn, FetchFn, HttpRequest, HttpResponse, RealtimeConnection, SSEEvent, WsRequest } from './types';
+export interface QueueSettings {
+    limits?: Partial<RateLimiterConfig>;
+    retry?: Partial<RetryConfig>;
+    queue?: Partial<QueueConfig>;
+}
+export interface NetworkEngineConfig {
+    /** Bus to share with QueueStates so plugins can subscribe. Default: new HookBus(). */
+    hooks?: HookBus;
+    /** Default fetch function for all queues. Per-call override via ctx not supported
+     *  (queue is bound to its fetch at creation). Default: globalThis.fetch. */
+    fetch?: FetchFn;
+    /** WebSocket factory for `connect()` (realtime). Default wraps globalThis.WebSocket.
+     *  Injectable so tests supply a fake socket and the engine stays transport-agnostic. */
+    connect?: ConnectFn;
+    /** Pre-configured per-queue settings. Looked up by queueName at queue creation. */
+    queues?: Record<string, QueueSettings>;
+}
+/** Optional context for fetch/fetchStream. RequestContext + per-call overrides. */
+export interface FetchOptions {
+    /** Routing key. If omitted, uses `req.provider/req.model` as fallback. */
+    queueName?: string;
+    priority?: number;
+    estimatedTokens?: number;
+    ctx?: Partial<RequestContext>;
+}
+export declare class NetworkEngine {
+    readonly hooks: HookBus;
+    private readonly fetchFn;
+    private readonly connectFn;
+    private readonly settings;
+    private readonly queues;
+    constructor(config?: NetworkEngineConfig);
+    /** Pre-configure (or reconfigure) a queue's settings.
+     *  Throws if the queue already exists — settings are snapshotted at queue
+     *  creation, so changes after that have no effect. To reconfigure an
+     *  existing queue, call `dropQueue(name)` first. */
+    configureQueue(queueName: string, settings: QueueSettings): void;
+    /** Drop a queue (frees its state). In-flight requests on that queue continue
+     *  but the next call with the same queueName creates a fresh queue. */
+    dropQueue(queueName: string): void;
+    /** Whether a queue has been created. */
+    hasQueue(queueName: string): boolean;
+    /** Names of all live queues. */
+    queueNames(): string[];
+    /** Get the underlying QueueState for a queueName (for tests / metrics).
+     *  Returns null if not yet created. */
+    getQueueState(queueName: string): QueueState | null;
+    /** Numeric state of every live queue — for the States panel / metrics. */
+    snapshot(): import('./types').QueueSnapshot[];
+    /** Submit a request. */
+    fetch(req: HttpRequest, options?: FetchOptions): Promise<HttpResponse>;
+    /** Submit a streaming request. Yields SSE events. */
+    fetchStream(req: HttpRequest, options?: FetchOptions): AsyncIterable<SSEEvent>;
+    /** Open a realtime WebSocket connection. Engine-owned (auth via the request's
+     *  protocols/headers, observability hooks) but QUEUE-EXEMPT: a persistent duplex
+     *  socket has no per-call retry / rate-limit / idempotency, so it does not route
+     *  through a QueueState. Sibling primitive to `fetch`. */
+    connect(req: WsRequest): RealtimeConnection;
+    /** Drop all queues. */
+    destroy(): void;
+    private getOrCreateQueue;
+}

package/dist/network/errors.d.ts

@@ -0,0 +1,14 @@
+/** Error taxonomy — each error type gets different retry behavior.
+ *  Lives in the network layer so QueueState can classify before hooks fire. */
+export type ErrorKind = 'rate_limit' | 'auth' | 'context_overflow' | 'invalid_request' | 'server_error' | 'timeout' | 'network' | 'content_filter' | 'model_not_found' | 'quota_exceeded' | 'unsupported';
+export declare class LLMError extends Error {
+    readonly kind: ErrorKind;
+    readonly provider: string;
+    readonly status?: number | undefined;
+    readonly retryable: boolean;
+    readonly retryAfterMs?: number | undefined;
+    readonly raw?: unknown | undefined;
+    constructor(message: string, kind: ErrorKind, provider: string, status?: number | undefined, retryable?: boolean, retryAfterMs?: number | undefined, raw?: unknown | undefined);
+}
+/** Map HTTP status + provider error body to our error taxonomy. */
+export declare function classifyError(provider: string, status: number, body: unknown, headers: Record<string, string>): LLMError;

package/dist/network/queue-state-config.d.ts

@@ -0,0 +1,41 @@
+/** QueueState configuration: retry policy, queue priorities, and defaults. */
+import type { HookBus } from '../bus/hook-bus';
+import type { ErrorKind } from './errors';
+import type { RateLimiterConfig } from './rate-limiter';
+import type { QueueConfig } from './request-queue';
+import type { FetchFn } from './types';
+export interface RetryConfig {
+    maxRetries: number;
+    totalTimeoutMs: number;
+    attemptTimeoutMs: number;
+    backoff: BackoffConfig;
+    perKind?: Partial<Record<ErrorKind, ErrorRetryConfig>>;
+}
+export interface BackoffConfig {
+    initialMs: number;
+    maxMs: number;
+    multiplier: number;
+    jitter: number;
+}
+export interface ErrorRetryConfig {
+    retryable?: boolean;
+    maxRetries?: number;
+    fixedBackoffMs?: number;
+}
+export declare const DEFAULT_RETRY: RetryConfig;
+export interface QueueStateConfig {
+    /** Routing identifier this queue is registered under. Carried in hook payloads. */
+    queueName: string;
+    fetch: FetchFn;
+    hooks: HookBus;
+    limits: RateLimiterConfig;
+    retry?: Partial<RetryConfig>;
+    queue?: Partial<QueueConfig>;
+}
+export declare const Priority: {
+    readonly RETRY: 0;
+    readonly INTERACTIVE: 1;
+    readonly BACKGROUND: 2;
+    readonly LOW: 3;
+};
+export declare function mergeRetry(overrides?: Partial<RetryConfig>): RetryConfig;

package/dist/network/queue-state.d.ts

@@ -0,0 +1,45 @@
+/** QueueState — owns queue + rate limiter + semaphore + retry for ONE queue.
+ *
+ *  This is the per-queue body that NetworkEngine creates lazily. Today's
+ *  llm-sdk packed all this inside ProviderExecutor (one executor per LLMClient,
+ *  hence one queue per LLMClient); we extract it so a single NetworkEngine
+ *  can host many queues keyed by `queueName` (e.g. "anthropic/claude-3-5",
+ *  "openai/gpt-4o", "shared/cheap"). */
+import type { QueueStateConfig } from './queue-state-config';
+import type { HttpRequest, HttpResponse, SSEEvent } from './types';
+export declare class QueueState {
+    readonly queueName: string;
+    private readonly fetchFn;
+    private readonly hooks;
+    private readonly rateLimiter;
+    private readonly semaphore;
+    private readonly queue;
+    private readonly retry;
+    private running;
+    /** Lifetime HTTP round-trips completed (bumped on each onRequestComplete). */
+    private processed;
+    /** Greatest depth ever observed (raised on enqueue). */
+    private peakDepth;
+    constructor(config: QueueStateConfig);
+    /** Point-in-time numeric state — depth, in-flight, rate-limit pressure. */
+    snapshot(): import('./types').QueueSnapshot;
+    /** Submit a request. Returns when the request completes (may wait in queue). */
+    submit(req: HttpRequest, priority?: number, estimatedTokens?: number): Promise<HttpResponse>;
+    /** Submit a streaming request. Yields SSE events. */
+    submitStream(req: HttpRequest, _priority?: number, estimatedTokens?: number): AsyncIterable<SSEEvent>;
+    private ensureProcessing;
+    private processLoop;
+    /** Last-resort safety net: executeWithRetry settles every entry itself, but if
+     *  it ever throws from its pre-`try` setup (before releasing the semaphore),
+     *  the entry's promise would otherwise NEVER settle — a silent hang. Release
+     *  the slot so the queue can't deadlock, surface the bug via the existing error
+     *  hook (V1 telemetry), and reject the caller so it fails fast and visibly. */
+    private settleOnWorkerCrash;
+    private executeWithRetry;
+    private handleRetry;
+    private calculateBackoff;
+    private executeOnce;
+    private waitForCapacity;
+    private emitRateLimitUpdate;
+    private emitErrorHooks;
+}

package/dist/network/rate-limiter.d.ts

@@ -0,0 +1,49 @@
+/** Token bucket rate limiter for RPM/TPM/RPD tracking. */
+export interface TokenBucketConfig {
+    /** Max tokens in bucket (e.g. 60 for 60 RPM). */
+    capacity: number;
+    /** Refill interval in ms. For RPM: 60_000 / capacity. */
+    refillIntervalMs: number;
+}
+export declare class TokenBucket {
+    private tokens;
+    private lastRefill;
+    private capacity;
+    private refillRate;
+    constructor(config: TokenBucketConfig);
+    /** Try to consume n tokens. Returns true if successful. */
+    tryConsume(n?: number): boolean;
+    /** How long to wait (ms) until n tokens are available. 0 if available now. */
+    waitTimeMs(n?: number): number;
+    /** Force-set tokens remaining (e.g. from rate limit headers). */
+    setRemaining(remaining: number): void;
+    /** Update capacity (e.g. discovered from headers). */
+    setCapacity(capacity: number): void;
+    /** Pause until a specific timestamp (e.g. from retry-after/reset headers). */
+    drainUntil(resetAt: number): void;
+    get available(): number;
+    private refill;
+}
+export interface RateLimiterConfig {
+    rpm: number | null;
+    tpm: number | null;
+    rpd: number | null;
+    concurrent: number;
+}
+/** Composite rate limiter managing RPM + TPM + RPD buckets. */
+export declare class RateLimiter {
+    private rpmBucket;
+    private tpmBucket;
+    private rpdBucket;
+    constructor(config: RateLimiterConfig);
+    /** Check if a request with estimated tokens can proceed now. */
+    canProceed(estimatedTokens?: number): boolean;
+    /** How long to wait before a request can proceed (ms). */
+    waitTimeMs(estimatedTokens?: number): number;
+    /** Update state from provider response headers. */
+    updateFromHeaders(headers: Record<string, string>): void;
+    /** Mark as rate-limited for a duration (from 429 + retry-after). */
+    pause(durationMs: number): void;
+    get rpmAvailable(): number;
+    get tpmAvailable(): number;
+}

package/dist/network/realtime-connection.d.ts

@@ -0,0 +1,40 @@
+/** RealtimeConnectionImpl — wraps a raw RealtimeSocket into the engine-owned
+ *  RealtimeConnection: normalizes inbound frames (string → text, binary → bytes),
+ *  fans out to adapter listeners, and emits observability hooks. This is the
+ *  realtime sibling of QueueState's HTTP handling — except there is no queue: a
+ *  live socket has no per-call retry / rate-limit / idempotency.
+ *
+ *  Knows nothing about provider protocols. A RealtimeProviderAdapter sits on top
+ *  and maps normalized frames ↔ provider event JSON. */
+import type { HookBus } from '../bus/hook-bus';
+import type { RealtimeConnection, RealtimeFrame, RealtimeSocket, WsRequest } from './types';
+type FrameCb = (f: RealtimeFrame) => void;
+type VoidCb = () => void;
+type ErrCb = (e: Error) => void;
+export interface RealtimeConnectionDeps {
+    socket: RealtimeSocket;
+    req: WsRequest;
+    hooks: HookBus;
+}
+export declare class RealtimeConnectionImpl implements RealtimeConnection {
+    private readonly socket;
+    private readonly req;
+    private readonly hooks;
+    private readonly messageCbs;
+    private readonly openCbs;
+    private readonly closeCbs;
+    private readonly errorCbs;
+    constructor(deps: RealtimeConnectionDeps);
+    get readyState(): number;
+    send(data: string | ArrayBufferLike | ArrayBufferView): void;
+    on(type: 'message', cb: FrameCb): () => void;
+    on(type: 'open' | 'close', cb: VoidCb): () => void;
+    on(type: 'error', cb: ErrCb): () => void;
+    close(code?: number, reason?: string): void;
+    private handleOpen;
+    private handleMessage;
+    private handleClose;
+    private handleError;
+    private emitFrameHook;
+}
+export {};

package/dist/network/request-queue.d.ts

@@ -0,0 +1,40 @@
+/** Priority request queue (min-heap). Lower priority = higher urgency.
+ *  Same priority = FIFO. */
+import type { HttpRequest, HttpResponse } from './types';
+export interface QueueEntry {
+    id: string;
+    request: HttpRequest;
+    priority: number;
+    enqueuedAt: number;
+    deadline: number;
+    estimatedTokens: number;
+    attempt: number;
+    resolve: (res: HttpResponse) => void;
+    reject: (err: Error) => void;
+}
+export interface QueueConfig {
+    /** Max pending requests. Reject new ones if exceeded. */
+    maxSize: number;
+    /** Max time (ms) a request can wait in queue. */
+    timeoutMs: number;
+}
+export declare class RequestQueue {
+    private heap;
+    private readonly config;
+    private drainWaiters;
+    constructor(config?: Partial<QueueConfig>);
+    enqueue(request: HttpRequest, priority: number, estimatedTokens: number, attempt?: number): Promise<HttpResponse>;
+    dequeue(): QueueEntry | null;
+    peek(): QueueEntry | null;
+    waitForItem(): Promise<void>;
+    get length(): number;
+    private purgeExpired;
+    private notifyDrain;
+    private push;
+    private pop;
+    private bubbleUp;
+    private sinkDown;
+    private rebuildHeap;
+    /** Compare: lower priority first, then earlier enqueue time. */
+    private compare;
+}

package/dist/network/semaphore.d.ts

@@ -0,0 +1,12 @@
+/** Counting semaphore for concurrency control. */
+export declare class Semaphore {
+    private readonly max;
+    private current;
+    private readonly waiters;
+    constructor(max: number);
+    acquire(): Promise<void>;
+    release(): void;
+    get inFlight(): number;
+    get waiting(): number;
+    get available(): number;
+}

package/dist/network/sse.d.ts

@@ -0,0 +1,3 @@
+/** Server-Sent Events parser. One implementation for all providers. */
+import type { SSEEvent } from './types';
+export declare function parseSSEStream(body: ReadableStream<Uint8Array>): AsyncIterable<SSEEvent>;

package/dist/network/types.d.ts

@@ -0,0 +1,127 @@
+/** Network layer shared types. */
+export type FetchFn = typeof globalThis.fetch;
+/** Request submitted to NetworkEngine. The semantic layer (LLMClient) sets
+ *  `provider` and `model` purely for hook observability; the routing key is
+ *  `queueName` (set by LLMClient via formula or RequestContext override). */
+export interface HttpRequest {
+    url: string;
+    method?: string;
+    headers: Record<string, string>;
+    body: unknown;
+    timeout?: number;
+    signal?: AbortSignal;
+    stream?: boolean;
+    provider: string;
+    model: string;
+    /** How to parse the response body. Default 'json' (LLM responses, image-gen
+     *  with b64_json, video-status JSON). Use 'arraybuffer' for binary downloads
+     *  (TTS audio bytes, video file bytes). 'text' for plain-text responses. */
+    responseType?: 'json' | 'arraybuffer' | 'text';
+    /** When the request body is already a Uint8Array / ArrayBuffer (binary
+     *  upload like multipart) the queue should NOT JSON.stringify it. Default
+     *  false → body is JSON.stringify'd. */
+    rawBody?: boolean;
+    /** Trace correlation — set by the caller (LLM client / media op) from the
+     *  RequestContext so every network event can echo `sessionId:requestId`. */
+    trace?: TraceContext;
+}
+/** Raw HTTP response (post-fetch, pre-provider-parse). */
+export interface HttpResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: unknown;
+}
+/** SSE event passed up from streaming response. */
+export interface SSEEvent {
+    event?: string;
+    data: string;
+    /** SSE `id:` field — used for resumption (Last-Event-ID). */
+    id?: string;
+}
+/** Correlation ids carried on a request so network events can be stitched to the
+ *  LLM call end-to-end. `sessionId:requestId` is the OTel trace id. */
+export interface TraceContext {
+    sessionId?: string;
+    requestId?: string;
+    callId?: string;
+}
+/** Point-in-time numeric state of one queue (for metrics / observability). */
+export interface QueueSnapshot {
+    queueName: string;
+    /** Requests queued, not yet started. */
+    depth: number;
+    /** Requests currently executing (semaphore held). */
+    inFlight: number;
+    /** Requests blocked waiting for a concurrency slot. */
+    waiting: number;
+    /** ms until the next request may proceed under the rate limit (0 = free now). */
+    rateLimitWaitMs: number;
+    /** Whether the queue's process loop is active. */
+    running: boolean;
+    /** Lifetime count of HTTP round-trips completed on this queue. A persistent
+     *  counter so an idle queue still shows evidence of past activity (depth /
+     *  inFlight are instantaneous and read 0 between bursts). */
+    processed: number;
+    /** High-water mark: the greatest depth this queue has reached. */
+    peakDepth: number;
+}
+/** Per-call fetch options accepted by NetworkEngine.fetch / fetchStream.
+ *  Re-declared here (vs. importing from engine.ts) to avoid a cycle when
+ *  consumers (LLMClient) only need the function shape. */
+export interface FetchOptionsLite {
+    queueName?: string;
+    priority?: number;
+    estimatedTokens?: number;
+    ctx?: Record<string, unknown>;
+}
+/** Function shape consumed by LLMClient. NetworkEngine.fetch.bind(engine)
+ *  satisfies this; tests may provide simpler stubs. */
+export type EngineFetch = (req: HttpRequest, options?: FetchOptionsLite) => Promise<HttpResponse>;
+/** Streaming variant. */
+export type EngineFetchStream = (req: HttpRequest, options?: FetchOptionsLite) => AsyncIterable<SSEEvent>;
+/** A WebSocket open request. The semantic layer (a RealtimeProviderAdapter)
+ *  builds `url` (including any `?key=` auth) and `protocols` (e.g. OpenAI's
+ *  `openai-insecure-api-key.<key>` subprotocol). `provider`/`model` are carried
+ *  for hook observability. */
+export interface WsRequest {
+    url: string;
+    protocols?: string | string[];
+    /** Header auth, where the underlying socket impl supports it (Node `ws`, Bun).
+     *  Browsers cannot set WS headers — providers that must run in a browser use
+     *  subprotocol or query-param auth instead. */
+    headers?: Record<string, string>;
+    provider: string;
+    model: string;
+}
+/** Minimal WHATWG-WebSocket shape the engine depends on. Injectable so tests
+ *  can supply a fake socket and the engine stays transport-agnostic. */
+export interface RealtimeSocket {
+    send(data: string | ArrayBufferLike | ArrayBufferView): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: 'open' | 'close' | 'error' | 'message', cb: (ev: unknown) => void): void;
+    readonly readyState: number;
+}
+/** Factory that opens a RealtimeSocket. Default wraps `globalThis.WebSocket`. */
+export type ConnectFn = (url: string, opts?: {
+    protocols?: string | string[];
+    headers?: Record<string, string>;
+}) => RealtimeSocket;
+/** A normalized inbound frame surfaced to adapters: text or binary, never raw. */
+export type RealtimeFrame = {
+    text: string;
+} | {
+    binary: Uint8Array;
+};
+/** Engine-owned connection: normalized frames + lifecycle + hook emission.
+ *  `on()` returns an unsubscribe function. */
+export interface RealtimeConnection {
+    send(data: string | ArrayBufferLike | ArrayBufferView): void;
+    on(type: 'message', cb: (f: RealtimeFrame) => void): () => void;
+    on(type: 'open' | 'close', cb: () => void): () => void;
+    on(type: 'error', cb: (e: Error) => void): () => void;
+    close(code?: number, reason?: string): void;
+    readonly readyState: number;
+}
+/** Function shape consumed by RealtimeProviderAdapters. NetworkEngine.connect
+ *  satisfies this. */
+export type EngineConnect = (req: WsRequest) => RealtimeConnection;

package/dist/plugins/batch/batcher.d.ts

@@ -0,0 +1,45 @@
+/** Batcher — transparent batch optimization layer.
+ *  Intercepts batchable requests via onBeforeSubmit, collects into batches,
+ *  polls via Scheduler, delivers results back through the intercepted Promise. */
+import type { HookBus } from '../../bus/hook-bus';
+import type { EngineFetch } from '../../network/types';
+import type { Persistence } from '../persistence/types';
+import type { Scheduler } from '../scheduler/scheduler';
+import type { BatchProviderAdapter, BatchStrategy } from './types';
+export interface BatcherConfig {
+    hooks: HookBus;
+    persistence: Persistence;
+    scheduler: Scheduler;
+    strategy: BatchStrategy;
+    providers: Map<string, BatchProviderAdapter>;
+    /** Engine fetch — every adapter HTTP call dispatches through this so it
+     *  inherits NetworkEngine queue semantics (rate limits, retry, hooks). */
+    fetch: EngineFetch;
+}
+export declare class Batcher {
+    private hooks;
+    private persistence;
+    private scheduler;
+    private strategy;
+    private providers;
+    private fetch;
+    /** Tracking requestors (agents + standalone LLMs) for shouldBatch decisions. */
+    private requestors;
+    /** Per-provider collection buffer with optional flush timer. */
+    private collecting;
+    /** Resolvers awaiting batch results. Lost on restart — restored runs route
+     *  results to conversations via hooks instead of resolving Promises. */
+    private pendingResolvers;
+    private unsubs;
+    constructor(config: BatcherConfig);
+    destroy(): void;
+    /** Restore pending batches from persistence. Call on startup after scheduler.start(). */
+    restore(): Promise<void>;
+    poll(batchId: string): Promise<void>;
+    private handleBeforeSubmit;
+    private addToCollection;
+    private flushCollection;
+    private handleBatchComplete;
+    private countBatchableRequestors;
+    private getPendingCount;
+}

package/dist/plugins/batch/strategy.d.ts

@@ -0,0 +1,20 @@
+/** Default batch strategy. */
+import type { BatchStrategy } from './types';
+export declare class DefaultBatchStrategy implements BatchStrategy {
+    collectionWindowMs: number;
+    minBatchSize: number;
+    maxBatchSize: number;
+    pollIntervalMs: number;
+    constructor(opts?: Partial<{
+        collectionWindowMs: number;
+        minBatchSize: number;
+        maxBatchSize: number;
+        pollIntervalMs: number;
+    }>);
+    shouldBatch(ctx: {
+        provider: string;
+        markedRequestorsCount: number;
+        pendingCount: number;
+    }): boolean;
+    estimateFirstPoll(batchSize: number): number;
+}