@combycode/llm-sdk 1.6.1 → 2.0.0

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

@@ -1,6 +1,16 @@
 /** 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). */
+ *  the engine's WebSocket factory + hooks. Cross-env (browser + Node/Bun).
+ *
+ *  **NON-STANDARD, and deliberately kept.** The MCP SDK removed its own WebSocket transport in
+ *  `mcp` 2.0.0, reasoning that it "was never part of the MCP specification". Ours stays: it is
+ *  public API we shipped, and deleting an exported transport on an upstream style call would break
+ *  consumers for no protocol reason (CONSTITUTION.md R7 — an upstream deletion is not our
+ *  deletion). Treat it as a supported extra rather than a spec transport: the server has to opt
+ *  into JSON-RPC over a socket, and the standard transports remain stdio and Streamable HTTP.
+ *
+ *  Practical upside of keeping it: being duplex, it supports `subscriptions/listen` today —
+ *  which Streamable HTTP does not yet. */
 import type { EngineConnect } from '../../network/types';
 import type { McpTransport } from './transport';
 import { BaseJsonRpcTransport } from './base-transport';

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

@@ -21,6 +21,17 @@ export interface McpTransport {
     setHandlers(handlers: IncomingMcpHandlers): void;
     /** Record the negotiated protocol version (HTTP sets a header; stdio ignores). */
     setProtocolVersion?(version: string): void;
+    /** Record the negotiated ERA. At `'modern'` (2026-07-28+) the wire is stateless: no
+     *  `Mcp-Session-Id`, and every request carries `Mcp-Method` / `Mcp-Name` routing headers so an
+     *  intermediary can route without parsing the body. Optional — stdio has no headers to set. */
+    setEra?(era: 'handshake' | 'modern'): void;
+    /** Send a long-lived request (`subscriptions/listen`) and return its id, without arming the
+     *  normal response timeout.
+     *
+     *  `onEnd` fires when the stream finishes — cleanly (the server tore the subscription down) or
+     *  with the error that killed it. A subscription that stops delivering is otherwise invisible to
+     *  the caller. */
+    sendLongLivedRequest?(method: string, params?: unknown, onEnd?: (error?: unknown) => void): Promise<string | number>;
     /** 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;

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

@@ -52,7 +52,40 @@ export type McpContentBlock = {
     type: string;
     [k: string]: unknown;
 };
-export interface McpCallResult {
+/** One server→client request embedded in an `input_required` result: a `sampling/createMessage`,
+ *  `elicitation/create` or `roots/list`, in JSON-RPC request shape. Identical in content to what a
+ *  handshake-era server pushes over the back-channel — only the delivery differs. */
+export interface McpInputRequest {
+    method: string;
+    params?: unknown;
+}
+/** Client-side caching directives carried by 2026-07-28 list/read results (`CacheableResult`).
+ *
+ *  Optional here because every pre-2026 server omits them, and a server that sends no hints must
+ *  behave exactly as before (CONSTITUTION.md R3). */
+export interface McpCacheHints {
+    /** How long (ms) the client MAY reuse this result. **`0` means immediately stale** — re-fetch
+     *  every time — so it is NOT the same as "absent" and must not be coerced to a default. */
+    ttlMs?: number;
+    /** `'public'`: no user-specific data, any cache may serve it across authorization contexts.
+     *  `'private'`: reusable only within the same authorization context. */
+    cacheScope?: 'private' | 'public';
+}
+/** The 2026-07-28 multi-round-trip fields (SEP-2322).
+ *
+ *  Upstream models this as a separate `InputRequiredResult` type, making every result a union. We
+ *  attach it as OPTIONAL fields on the existing results instead (CONSTITUTION.md R2): code reading
+ *  `result.content` keeps compiling, and callers who never meet a modern server never see them. */
+export interface McpInputRequiredFields {
+    /** `'complete'` | `'input_required'`. **Absent MUST be read as `'complete'`** — earlier revisions
+     *  never send it. Open by R1: a future revision may add a third kind. */
+    resultType?: 'complete' | 'input_required' | (string & {});
+    /** Server-assigned key → the request to answer. Present when the server has questions. */
+    inputRequests?: Record<string, McpInputRequest>;
+    /** Opaque continuation token. Echoed back byte-exact and never inspected. */
+    requestState?: string;
+}
+export interface McpCallResult extends McpInputRequiredFields {
     content: McpContentBlock[];
     isError?: boolean;
     structuredContent?: Record<string, unknown>;
@@ -92,7 +125,7 @@ export interface McpPromptMessage {
     role: 'user' | 'assistant';
     content: McpContentBlock;
 }
-export interface McpGetPromptResult {
+export interface McpGetPromptResult extends McpInputRequiredFields {
     description?: string;
     messages: McpPromptMessage[];
 }
@@ -180,6 +213,25 @@ export interface McpInitializeResult {
     serverInfo: McpServerInfo;
     instructions?: string;
 }
+/** Result of the 2026-07-28 `server/discover` probe — the modern replacement for the `initialize`
+ *  handshake. Shape verified against mcp-py 2.0.0 (`_v2026_07_28.DiscoverResult`).
+ *
+ *  `McpClient.info` synthesises an `McpInitializeResult` from this, so a caller never has to branch
+ *  on the era (CONSTITUTION.md R2). This type exposes the fields that have no handshake equivalent. */
+export interface McpDiscoverResult {
+    capabilities: Record<string, unknown>;
+    /** Revisions the server speaks; the client picks one from this list. */
+    supportedVersions: string[];
+    /** How long (ms) the client MAY cache this result. `0` = treat as immediately stale. */
+    ttlMs?: number;
+    /** `public` = cacheable across authorization contexts; `private` = same context only. */
+    cacheScope?: 'private' | 'public';
+    instructions?: string;
+    /** Absent on servers implementing an earlier revision, which MUST be read as `'complete'`. */
+    resultType?: string;
+    /** Carries the display-only `io.modelcontextprotocol/serverInfo` stamp. */
+    _meta?: Record<string, unknown>;
+}
 export interface McpHttpConfig {
     /** Streamable-HTTP MCP endpoint URL. Cross-env (browser needs server CORS). */
     url: string;

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

@@ -26,6 +26,15 @@ export declare function toDataUrl(ref: NormalizedImageRef): string;
 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>;
+/** xAI video-ref object (`/v1/videos/extensions` + `/v1/videos/edits` `video`
+ *  field) — `{ url }` (public URL or base64 data-URL) or `{ file_id }`. Kept
+ *  separate from the image path so it doesn't run image mime-sniffing over
+ *  video bytes; the video mime is taken from the DataSource as declared. */
+export declare function xaiVideoRef(src: DataSource): {
+    url: string;
+} | {
+    file_id: 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).

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

@@ -18,6 +18,9 @@ export interface MediaMeta {
     durationMs?: number;
     sampleRate?: number;
     params?: Record<string, unknown>;
+    /** Provider-hosted URL (async video). Present when the bytes live remotely —
+     *  the browser renders from this since a cross-origin byte-fetch is CORS-blocked. */
+    sourceUrl?: string;
 }
 export interface MediaStore {
     save(id: string, data: Uint8Array, meta: MediaMeta): Promise<void>;
@@ -76,13 +79,22 @@ export interface VideoGenRequest {
     provider: string;
     model?: string;
     prompt: string;
+    /** First-frame image → image-to-video. */
     sourceImage?: DataSource;
+    /** Input video → extend or edit an existing clip (see `params.videoMode`).
+     *  The adapter routes to the provider's extension/edit endpoint instead of
+     *  plain generation. */
+    sourceVideo?: DataSource;
     params?: {
         duration?: number;
         aspectRatio?: string;
         resolution?: string;
         /** OpenAI Sora literal pixel `size` (e.g. "720x1280"). */
         size?: string;
+        /** When `sourceVideo` is set, which operation to run. `extend` (default)
+         *  continues the clip from its last frame; `edit` modifies it in place per
+         *  the prompt. Ignored without `sourceVideo`. */
+        videoMode?: 'extend' | 'edit';
     };
 }
 export interface MediaResult {
@@ -94,6 +106,12 @@ export interface MediaResult {
 export interface RawMediaResult {
     data: Uint8Array;
     mimeType: string;
+    /** Provider-hosted URL for the asset, when it exists (async video). In the
+     *  browser, cross-origin buckets (e.g. xAI vidgen) block a programmatic
+     *  byte-fetch via CORS, so `data` may be empty and this URL is the only way
+     *  to render (`<video src>` plays cross-origin without CORS) or to re-submit
+     *  as a `sourceVideo`. */
+    sourceUrl?: string;
     width?: number;
     height?: number;
     durationMs?: number;
@@ -116,6 +134,9 @@ export interface MediaCapabilities {
     audioGeneration: boolean;
     videoGeneration: boolean;
     audioStreaming: boolean;
+    /** Provider can extend/edit an existing video (`sourceVideo` on the request).
+     *  Undefined/false → passing `sourceVideo` throws. */
+    videoExtension?: boolean;
 }
 /** All MediaProviderAdapter HTTP calls now go through the NetworkEngine
  *  queue (rate limits, retries, hooks, observability) instead of holding a

package/dist/plugins/model-catalog/catalog.d.ts

@@ -39,6 +39,9 @@ export interface ModelCapabilities {
     imageGeneration: boolean;
     audioGeneration: boolean;
     videoGeneration: boolean;
+    /** Model accepts an existing video as input to extend/edit it (xAI
+     *  grok-imagine-video). Undefined/false → generation only. */
+    videoExtension?: boolean;
 }
 /** One generation parameter a media model accepts, with its allowed values.
  *  Either an enum (`values` + `default`) or a numeric range (`min`/`max`).

package/dist/plugins/telemetry/telemetry.d.ts

@@ -69,6 +69,17 @@ export interface TelemetryAdapterOptions {
     maxEvents?: number;
     /** Service identity stamped on all exported telemetry. */
     resource?: TelemetryResource;
+    /** Whether provider error TEXT may be stored in telemetry. Default `true`
+     *  (unchanged behaviour, and the same default as the OpenAI Agents SDK's
+     *  `trace_include_sensitive_data`).
+     *
+     *  A provider's `error.message` / `error.raw` can echo request content back —
+     *  a moderation refusal quotes the prompt, a validation error names the offending
+     *  field and value. URLs and headers are always redacted regardless; this switch
+     *  governs the free-text payload. Set `false` when telemetry leaves your trust
+     *  boundary (a shared collector, a vendor APM) and the message is replaced by a
+     *  fixed `[redacted]` string while name/code/status are kept for triage. */
+    includeSensitiveData?: boolean;
 }
 export declare class TelemetryAdapter {
     readonly events: TelemetryEvent[];
@@ -80,6 +91,7 @@ export declare class TelemetryAdapter {
     private latSum;
     private readonly open;
     private readonly maxEvents;
+    private readonly includeSensitiveData;
     private readonly unsub;
     constructor(hooks: HookBus, opts?: TelemetryAdapterOptions);
     /** Stop tapping the bus. */

package/dist/util/http.d.ts

@@ -1,6 +1,14 @@
 /** 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>;
+/** Case-insensitive header lookup. HTTP header names are case-insensitive
+ *  (RFC 9110 §5.1) but a plain record is not, and the casing a server or fetch
+ *  implementation actually sends varies — so read response headers through here
+ *  instead of guessing casings at the call site. */
+export declare function header(headers: Record<string, string>, name: string): string | undefined;
+/** True when a request body cannot be replayed for a retry (the first attempt
+ *  consumes it). FormData, strings and byte views are replayable; a stream is not. */
+export declare function isStreamBody(body: unknown): boolean;
 /** 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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combycode/llm-sdk",
-  "version": "1.6.1",
+  "version": "2.0.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",
@@ -23,7 +23,8 @@
     "dist",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "MIGRATION.md"
   ],
   "scripts": {
     "build": "bun run clean && bun run build:js && bun run build:types",
@@ -43,25 +44,27 @@
     "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",
+    "tiktoken": "^1.0.22",
     "typescript": "^5.6.0"
   },
   "peerDependencies": {
+    "tiktoken": "^1.0.22",
     "typescript": ">=5.0"
   },
   "peerDependenciesMeta": {
     "typescript": {
       "optional": true
+    },
+    "tiktoken": {
+      "optional": true
     }
   },
   "engines": {
-    "node": ">=18",
+    "node": ">=22",
     "bun": ">=1.1.0"
   },
   "repository": {