@combycode/llm-sdk 1.0.0-rc.0

package/dist/plugins/mcp/transport-http.d.ts

@@ -0,0 +1,50 @@
+/** Streamable-HTTP MCP transport — each call is a POST through the engine's
+ *  `fetch` (so it rides the central queue + network telemetry, never side-fetch).
+ *  Cross-env (works in the browser when the server allows CORS). Handles a
+ *  single request/response per call: the response body is either one JSON-RPC
+ *  message (`application/json`) or an SSE batch (`text/event-stream`). The
+ *  long-lived server->client GET stream reconnects with backoff + Last-Event-ID
+ *  for resumption. */
+import type { EngineFetch, EngineFetchStream } from '../../network/types';
+import type { McpTransport } from './transport';
+import type { McpHttpConfig } from './types';
+import { BaseJsonRpcTransport } from './base-transport';
+export interface HttpTransportDeps {
+    fetch: EngineFetch;
+    /** Streaming fetch for the server->client GET SSE channel. */
+    fetchStream: EngineFetchStream;
+    queueName?: string;
+    timeoutMs?: number;
+    /** Authorization headers (Bearer) to attach to every request. */
+    getAuthHeaders?: () => Promise<Record<string, string>>;
+    /** Called on a 401; return true to retry the request once (after re-auth). */
+    onUnauthorized?: () => Promise<boolean>;
+}
+export declare class HttpTransport extends BaseJsonRpcTransport implements McpTransport {
+    private readonly config;
+    private readonly deps;
+    private nextHttpId;
+    private sessionId;
+    private protocolVersion;
+    private eventAbort;
+    private lastEventId;
+    constructor(config: McpHttpConfig, deps: HttpTransportDeps);
+    start(): Promise<void>;
+    setProtocolVersion(version: string): void;
+    /** Open the server->client GET SSE stream (best-effort: a 405 means the server
+     *  is request/response only). Reconnects with backoff + Last-Event-ID until
+     *  close(). Runs in the background. */
+    listen(): void;
+    private eventLoop;
+    /** Run one GET SSE session. Returns whether the stream opened (vs 405/error). */
+    private runEventStream;
+    request(method: string, params?: unknown): Promise<unknown>;
+    notify(method: string, params?: unknown): Promise<void>;
+    close(): Promise<void>;
+    /** Send a JSON-RPC response back via POST (used by handleRequest from base). */
+    protected sendMessage(obj: unknown): Promise<void>;
+    private headers;
+    /** Base headers + any OAuth bearer + per-call extras. */
+    private authedHeaders;
+    private post;
+}

package/dist/plugins/mcp/transport-stdio.d.ts

@@ -0,0 +1,23 @@
+/** Stdio MCP transport — spawns the server as a child process and exchanges
+ *  newline-delimited JSON-RPC over stdin/stdout. Node/Bun only (browser callers
+ *  get a friendly error via the lazy `node:child_process` loader). */
+import type { McpTransport } from './transport';
+import type { McpStdioConfig } from './types';
+import { BaseJsonRpcTransport } from './base-transport';
+export declare class StdioTransport extends BaseJsonRpcTransport implements McpTransport {
+    private readonly config;
+    private proc;
+    private buffer;
+    private readonly timeoutMs;
+    constructor(config: McpStdioConfig, opts?: {
+        timeoutMs?: number;
+    });
+    start(): Promise<void>;
+    setProtocolVersion(): void;
+    request(method: string, params?: unknown): Promise<unknown>;
+    notify(method: string, params?: unknown): Promise<void>;
+    close(): Promise<void>;
+    protected sendMessage(obj: unknown): void;
+    private onData;
+    private parseAndRoute;
+}

package/dist/plugins/mcp/transport-ws.d.ts

@@ -0,0 +1,32 @@
+/** WebSocket MCP transport — JSON-RPC messages as text frames over a duplex
+ *  socket (naturally bidirectional). Uses the engine's `connect` so it shares
+ *  the engine's WebSocket factory + hooks. Cross-env (browser + Node/Bun). */
+import type { EngineConnect } from '../../network/types';
+import type { McpTransport } from './transport';
+import { BaseJsonRpcTransport } from './base-transport';
+export interface McpWsConfig {
+    /** ws:// or wss:// MCP endpoint. */
+    url: string;
+    protocols?: string | string[];
+    headers?: Record<string, string>;
+    name?: string;
+}
+export interface WsTransportDeps {
+    connect: EngineConnect;
+    timeoutMs?: number;
+}
+export declare class WsTransport extends BaseJsonRpcTransport implements McpTransport {
+    private readonly config;
+    private readonly deps;
+    private conn;
+    private readonly timeoutMs;
+    constructor(config: McpWsConfig, deps: WsTransportDeps);
+    setProtocolVersion(): void;
+    listen(): void;
+    start(): Promise<void>;
+    request(method: string, params?: unknown): Promise<unknown>;
+    notify(method: string, params?: unknown): Promise<void>;
+    close(): Promise<void>;
+    protected sendMessage(obj: unknown): void;
+    private onFrame;
+}

package/dist/plugins/mcp/transport.d.ts

@@ -0,0 +1,29 @@
+/** A transport carries JSON-RPC messages to/from an MCP server over a wire
+ *  (stdio or Streamable HTTP). It is BIDIRECTIONAL: besides our requests, it
+ *  routes incoming server->client requests (sampling/elicitation/roots/ping)
+ *  and notifications (logging, *_changed, progress) to the registered handlers.
+ *  The McpClient speaks methods; the transport speaks the wire + correlation. */
+/** Handlers for messages the server initiates toward us. */
+export interface IncomingMcpHandlers {
+    /** Server->client request — return the result, or throw McpError. */
+    onRequest?: (method: string, params: unknown) => Promise<unknown>;
+    /** Server->client notification (no reply). */
+    onNotification?: (method: string, params: unknown) => void;
+}
+export interface McpTransport {
+    /** Open the connection (spawn the process / no-op for HTTP). */
+    start(): Promise<void>;
+    /** Send a request and resolve its `result`; throws McpError on a JSON-RPC error. */
+    request(method: string, params?: unknown): Promise<unknown>;
+    /** Fire-and-forget notification (no response). */
+    notify(method: string, params?: unknown): Promise<void>;
+    /** Register handlers for server-initiated messages. */
+    setHandlers(handlers: IncomingMcpHandlers): void;
+    /** Record the negotiated protocol version (HTTP sets a header; stdio ignores). */
+    setProtocolVersion?(version: string): void;
+    /** Open the server->client channel (HTTP GET SSE stream). Stdio is already
+     *  duplex, so this is a no-op there. Call after the initialize handshake. */
+    listen?(): Promise<void> | void;
+    /** Close the connection (kill the process / DELETE the HTTP session). */
+    close(): Promise<void>;
+}

package/dist/plugins/mcp/types.d.ts

@@ -0,0 +1,202 @@
+/** MCP (Model Context Protocol) wire types + client config for protocol
+ *  v2025-11-25. See docs/design/mcp.md. Hand-rolled (no `@modelcontextprotocol/sdk`)
+ *  to stay zero-dep and browser-capable. */
+/** Protocol version we advertise in `initialize`. */
+export declare const MCP_PROTOCOL_VERSION = "2025-11-25";
+export interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: number | string | null;
+    result?: unknown;
+    error?: JsonRpcError;
+}
+export interface McpToolDef {
+    name: string;
+    description?: string;
+    title?: string;
+    /** JSON Schema (object at root) for the tool's arguments. */
+    inputSchema: Record<string, unknown>;
+    /** JSON Schema for the tool's `structuredContent` output (optional). */
+    outputSchema?: Record<string, unknown>;
+}
+/** A content block in a `tools/call` result. Open union — unknown types ignored. */
+export type McpContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    data: string;
+    mimeType: string;
+} | {
+    type: 'audio';
+    data: string;
+    mimeType: string;
+} | {
+    type: 'resource';
+    resource: {
+        uri: string;
+        mimeType?: string;
+        text?: string;
+        blob?: string;
+    };
+} | {
+    type: 'resource_link';
+    uri: string;
+    mimeType?: string;
+    title?: string;
+} | {
+    type: string;
+    [k: string]: unknown;
+};
+export interface McpCallResult {
+    content: McpContentBlock[];
+    isError?: boolean;
+    structuredContent?: Record<string, unknown>;
+}
+export interface McpResource {
+    uri: string;
+    name?: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+}
+export interface McpResourceTemplate {
+    uriTemplate: string;
+    name?: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+}
+export interface McpResourceContent {
+    uri: string;
+    mimeType?: string;
+    text?: string;
+    blob?: string;
+}
+export interface McpPromptArg {
+    name: string;
+    description?: string;
+    required?: boolean;
+}
+export interface McpPrompt {
+    name: string;
+    title?: string;
+    description?: string;
+    arguments?: McpPromptArg[];
+}
+export interface McpPromptMessage {
+    role: 'user' | 'assistant';
+    content: McpContentBlock;
+}
+export interface McpGetPromptResult {
+    description?: string;
+    messages: McpPromptMessage[];
+}
+export type McpLogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'critical' | 'alert' | 'emergency';
+/** Reference for argument autocompletion (`completion/complete`). */
+export type McpCompletionRef = {
+    type: 'ref/prompt';
+    name: string;
+} | {
+    type: 'ref/resource';
+    uri: string;
+};
+export interface McpCompletionResult {
+    values: string[];
+    total?: number;
+    hasMore?: boolean;
+}
+export interface McpSamplingMessage {
+    role: 'user' | 'assistant';
+    content: McpContentBlock;
+}
+/** Params of a server-initiated `sampling/createMessage` (the server asks us to
+ *  run an LLM completion on its behalf). */
+export interface McpCreateMessageParams {
+    messages: McpSamplingMessage[];
+    systemPrompt?: string;
+    maxTokens: number;
+    temperature?: number;
+    stopSequences?: string[];
+    modelPreferences?: {
+        hints?: Array<{
+            name?: string;
+        }>;
+        costPriority?: number;
+        speedPriority?: number;
+        intelligencePriority?: number;
+    };
+    includeContext?: 'none' | 'thisServer' | 'allServers';
+    metadata?: Record<string, unknown>;
+}
+export interface McpCreateMessageResult {
+    role: 'assistant';
+    content: McpContentBlock;
+    model: string;
+    stopReason?: string;
+}
+/** Params of a server-initiated `elicitation/create` (ask the user for input). */
+export interface McpElicitRequestParams {
+    message: string;
+    requestedSchema: Record<string, unknown>;
+}
+export interface McpElicitResult {
+    action: 'accept' | 'decline' | 'cancel';
+    content?: Record<string, unknown>;
+}
+/** A filesystem root we expose to the server (`roots/list`). */
+export interface McpRoot {
+    uri: string;
+    name?: string;
+}
+export type McpTaskStatus = 'working' | 'input_required' | 'completed' | 'failed' | 'cancelled';
+export interface McpTask {
+    taskId: string;
+    status: McpTaskStatus;
+    /** ms to keep results after completion; null = unlimited. */
+    ttl: number | null;
+    createdAt: string;
+    lastUpdatedAt: string;
+    /** Suggested poll interval (ms). */
+    pollInterval?: number;
+    statusMessage?: string;
+}
+/** Request augmentation: include on a `tools/call` to run it as a task. */
+export interface McpTaskMetadata {
+    ttl?: number;
+}
+export interface McpServerInfo {
+    name: string;
+    version: string;
+    title?: string;
+}
+export interface McpInitializeResult {
+    protocolVersion: string;
+    capabilities: Record<string, unknown>;
+    serverInfo: McpServerInfo;
+    instructions?: string;
+}
+export interface McpHttpConfig {
+    /** Streamable-HTTP MCP endpoint URL. Cross-env (browser needs server CORS). */
+    url: string;
+    /** Extra headers (e.g. `Authorization: Bearer …`). */
+    headers?: Record<string, string>;
+    /** Short label for tool namespacing + telemetry. Default: the URL host. */
+    name?: string;
+}
+export interface McpStdioConfig {
+    /** Command to spawn (stdio transport — Node/Bun only). */
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    /** Short label for tool namespacing. Default: the command basename. */
+    name?: string;
+}
+export type McpServerConfig = McpHttpConfig | McpStdioConfig;
+/** Discriminate the two config variants by the presence of `url`. */
+export declare function isHttpConfig(c: McpServerConfig): c is McpHttpConfig;

package/dist/plugins/mcp/url-guard.d.ts

@@ -0,0 +1,70 @@
+/** SSRF guard for OAuth/MCP discovered endpoints.
+ *
+ *  All URLs derived from server-controlled discovery metadata (authorization_endpoint,
+ *  token_endpoint, registration_endpoint, the issuer URL itself) MUST pass
+ *  `assertSafeAuthUrl` before any fetch is made through the engine.
+ *
+ *  Secure by default:
+ *  - Only `https:` is allowed (opt-in `allowInsecureHttp` for explicit local-dev only).
+ *  - Loopback / link-local / private / reserved hosts are blocked by default
+ *    (opt-in `allowLoopback` for explicit local-dev only).
+ *  - The discovered endpoint must be same-origin as the issuer unless the caller
+ *    supplies an explicit `allowedHosts` allowlist.
+ *
+ *  Cross-env: pure URL / IP-literal parsing only — no DNS, no node: imports. */
+/** Options that relax the SSRF guard. All fields default to the most restrictive
+ *  posture. Escape hatches are intentionally verbose to signal risk at the call site. */
+export interface SsrfGuardOptions {
+    /**
+     * When set, a discovered endpoint is accepted if its hostname matches ANY entry
+     * in this list (case-insensitive, exact match on the registered domain / host).
+     * Without this, same-origin with the issuer is enforced.
+     *
+     * Use this for real IdPs hosted on a separate domain from the MCP server
+     * (e.g. issuer = `https://api.example.com`, auth server = `https://auth.example.com`).
+     */
+    allowedHosts?: readonly string[];
+    /**
+     * Set to `true` ONLY for explicit local development to allow `http:` scheme.
+     * NEVER set in production. Defaults to `false`.
+     */
+    allowInsecureHttp?: boolean;
+    /**
+     * Set to `true` ONLY for explicit local development to allow loopback addresses
+     * (localhost, 127.x, ::1) and private/reserved ranges.
+     * NEVER set in production. Defaults to `false`.
+     */
+    allowLoopback?: boolean;
+}
+/** Thrown when a server-controlled URL fails the SSRF safety check. */
+export declare class McpSsrfError extends Error {
+    /** The offending URL (as a string). */
+    readonly url: string;
+    /** Human-readable reason the URL was blocked. */
+    readonly reason: string;
+    constructor(url: string, reason: string);
+}
+/** Canonical IPv4 parser: accepts 1-, 2-, 3-, and 4-part forms with each part
+ *  in decimal, octal (0-prefix), or hex (0x-prefix). Converts to 4 octets.
+ *
+ *  RFC 3986 / POSIX inet_aton support these short forms:
+ *    1-part:  entire address as a 32-bit integer (e.g. 2130706433 = 127.0.0.1)
+ *    2-part:  first octet + 24-bit remainder  (e.g. 127.1 = 127.0.0.1)
+ *    3-part:  first two octets + 16-bit remainder
+ *    4-part:  standard dotted-decimal / hex / octal
+ *
+ *  Returns null if the host is not a parseable IPv4 literal (e.g. a hostname). */
+export declare function parseCanonicalIpv4(host: string): [number, number, number, number] | null;
+/**
+ * Assert that `url` is safe to use as a server-controlled OAuth endpoint.
+ *
+ * Throws `McpSsrfError` if any check fails:
+ * 1. Scheme must be `https:` (unless `opts.allowInsecureHttp` is explicitly `true`).
+ * 2. Host must not be loopback / private / reserved (unless `opts.allowLoopback` is explicitly `true`).
+ * 3. Host must be same-origin as `issuerUrl` OR match one of `opts.allowedHosts`.
+ *
+ * @param url         The discovered/auth endpoint URL to validate.
+ * @param issuerUrl   The MCP server's base URL (the trusted origin anchor).
+ * @param opts        Security options — all default to the most restrictive posture.
+ */
+export declare function assertSafeAuthUrl(url: string, issuerUrl: string, opts?: SsrfGuardOptions): void;

package/dist/plugins/mcp/win-spawn.d.ts

@@ -0,0 +1,20 @@
+/** Windows command resolution + escaping for spawning stdio MCP servers.
+ *
+ *  Bare commands like `npx`/`uvx` are `.cmd` shims on Windows; spawning them
+ *  directly throws ENOENT, and a blanket `shell:true` is a quoting/injection
+ *  risk. This replicates the essential `cross-spawn` behavior (zero-dep):
+ *  resolve the real file via PATH+PATHEXT, and route `.cmd`/`.bat` through
+ *  `cmd.exe /d /s /c "<escaped command line>"` with verbatim args. No-op off
+ *  Windows. The pure functions take an `exists` probe so they're testable. */
+export interface SpawnPlan {
+    file: string;
+    args: string[];
+    /** -> spawn options.windowsVerbatimArguments. */
+    verbatim: boolean;
+}
+/** Quote one argument per Windows `CommandLineToArgvW` rules. */
+export declare function quoteWinArg(arg: string): string;
+/** Caret-escape cmd.exe metacharacters. */
+export declare function escapeCmdMeta(s: string): string;
+/** Plan how to spawn `command args` on Windows. */
+export declare function windowsSpawnPlan(command: string, args: string[], env: Record<string, string | undefined>, exists: (p: string) => boolean): SpawnPlan;

package/dist/plugins/media/file-store.d.ts

@@ -0,0 +1,24 @@
+/** FileMediaStore — stores media binary files + JSON metadata on disk. */
+import type { MediaMeta, MediaStore, MediaType } from './types';
+export interface FileMediaStoreConfig {
+    /** Directory under which media files + meta JSON go. */
+    dir: string;
+}
+export declare class FileMediaStore implements MediaStore {
+    private ready;
+    private readonly dir;
+    constructor(config: FileMediaStoreConfig);
+    save(id: string, data: Uint8Array, meta: MediaMeta): Promise<void>;
+    load(id: string): Promise<{
+        data: Uint8Array;
+        meta: MediaMeta;
+    } | null>;
+    getMeta(id: string): Promise<MediaMeta | null>;
+    delete(id: string): Promise<void>;
+    list(filter?: {
+        type?: MediaType;
+        provider?: string;
+    }): Promise<string[]>;
+    has(id: string): Promise<boolean>;
+    private ensureDir;
+}

package/dist/plugins/media/memory-store.d.ts

@@ -0,0 +1,17 @@
+/** In-memory MediaStore. Test default; data is lost on process exit. */
+import type { MediaMeta, MediaStore, MediaType } from './types';
+export declare class MemoryMediaStore implements MediaStore {
+    private entries;
+    save(id: string, data: Uint8Array, meta: MediaMeta): Promise<void>;
+    load(id: string): Promise<{
+        data: Uint8Array;
+        meta: MediaMeta;
+    } | null>;
+    getMeta(id: string): Promise<MediaMeta | null>;
+    delete(id: string): Promise<void>;
+    list(filter?: {
+        type?: MediaType;
+        provider?: string;
+    }): Promise<string[]>;
+    has(id: string): Promise<boolean>;
+}

package/dist/plugins/media/output.d.ts

@@ -0,0 +1,44 @@
+/** MediaOutput — separate-endpoint media generation (images, audio, video).
+ *
+ *  All HTTP calls flow through an injected EngineFetch (NetworkEngine queue).
+ *  Persists raw bytes to MediaStore, emits onMediaGenerated (which carries
+ *  cost-relevant metadata for CostCollector to price). Inline media (e.g.
+ *  Google generateContent images, OpenAI image_generation tool) is handled
+ *  by core LLM adapters + an onCompletion subscriber, NOT this class. */
+import type { HookBus } from '../../bus/hook-bus';
+import type { EngineFetch } from '../../network/types';
+import type { ModelCatalog } from '../model-catalog/catalog';
+import { type AudioGenRequest, type ImageEditRequest, type ImageGenRequest, type MediaOutputConfig, type MediaProviderAdapter, type MediaResult, type MediaStore, type VideoGenRequest } from './types';
+export interface MediaOutputInit {
+    hooks: HookBus;
+    mediaStore: MediaStore;
+    /** Network fetch — all adapter HTTP goes through this so calls flow through
+     *  the NetworkEngine queue (rate-limit, retry, hooks). Typically engine.fetch. */
+    fetch: EngineFetch;
+    providers?: Map<string, MediaProviderAdapter>;
+    catalog?: ModelCatalog;
+    config?: MediaOutputConfig;
+    /** Trace session id (engine.sessionId); each op mints its own requestId. */
+    sessionId?: string;
+}
+export declare class MediaOutput {
+    private hooks;
+    private mediaStore;
+    private fetch;
+    private providers;
+    private catalog;
+    private pollIntervalMs;
+    private maxPollWaitMs;
+    private sessionId?;
+    constructor(init: MediaOutputInit);
+    /** Mint a trace + a fetch that stamps it onto every request this op makes. */
+    private tracedOp;
+    registerProvider(name: string, adapter: MediaProviderAdapter): void;
+    generateImage(req: ImageGenRequest): Promise<MediaResult[]>;
+    editImage(req: ImageEditRequest): Promise<MediaResult[]>;
+    generateAudio(req: AudioGenRequest): Promise<MediaResult>;
+    generateVideo(req: VideoGenRequest): Promise<MediaResult>;
+    private getAdapter;
+    private saveResults;
+    private pollVideoCompletion;
+}

package/dist/plugins/media/source-image.d.ts

@@ -0,0 +1,36 @@
+/** Source/reference image handling for media edit + image-to-video.
+ *
+ *  Normalizes a DataSource (base64 / buffer / url / file-id) into a neutral
+ *  shape, then each provider adapter maps it to its own wire field:
+ *    - OpenAI: `{ image_url }` (data-URL) or `{ file_id }`
+ *    - xAI:    `{ url }` (data-URL) or `{ file_id }`
+ *    - Google: `inline_data {mime_type,data}` or `file_data {file_uri}` */
+import type { DataSource } from '../../llm/types/messages';
+export interface NormalizedImageRef {
+    /** Raw base64 (no `data:` prefix), when inline. */
+    base64?: string;
+    mimeType?: string;
+    /** A remote URL, when the source is a URL. */
+    url?: string;
+    /** A provider Files-API id, when the source is an uploaded file. */
+    fileId?: string;
+}
+/** Collapse any DataSource into base64 / url / fileId. The declared mime is
+ *  cross-checked against the actual bytes (and corrected on mismatch) so a
+ *  mislabeled source image — e.g. JPEG bytes tagged "image/png" — doesn't get
+ *  rejected by strict validators downstream (Google Veo, OpenAI edits). */
+export declare function normalizeImageSource(src: DataSource): NormalizedImageRef;
+/** Build a `data:<mime>;base64,…` URL (or pass a plain URL through). */
+export declare function toDataUrl(ref: NormalizedImageRef): string;
+/** OpenAI image-ref object (`/v1/images/edits` images[], video input_reference). */
+export declare function openaiImageRef(ref: NormalizedImageRef): Record<string, string>;
+/** xAI image-ref object (`/v1/images/edits` image, video image). */
+export declare function xaiImageRef(ref: NormalizedImageRef): Record<string, string>;
+/** Google generateContent image part (inline base64 or Files-API file_uri). */
+export declare function googleImagePart(ref: NormalizedImageRef): Record<string, unknown>;
+/** Google Veo instance image (`:predictLongRunning` instances[].image).
+ *  The predict API uses the Image proto — `bytesBase64Encoded` + `mimeType` —
+ *  NOT the `inlineData` shape of generateContent (Veo rejects inlineData with a
+ *  400). The Gemini Developer API accepts only inline bytes here (no gcsUri /
+ *  file URI), so the URL fallback exists for Vertex-style callers only. */
+export declare function googleVeoImage(ref: NormalizedImageRef): Record<string, unknown>;