@combycode/llm-sdk 2.2.1 → 2.3.0

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

@@ -0,0 +1,139 @@
+/** Telemetry types.
+ *
+ *  Split out of `telemetry.ts` so the adapter file is implementation and this one
+ *  is contract — matching how the rest of the codebase is laid out, and making
+ *  the public surface of the plugin readable without paging through 1,200 lines.
+ */
+import type { HookName } from '../../bus/hook-map';
+export type SpanKind = 'llm' | 'http' | 'media' | 'agent' | 'tool' | 'mcp' | 'other';
+export interface Span {
+    traceId: string;
+    spanId: string;
+    /** The span this one runs under. Without it every span is a sibling and a backend
+     *  draws a flat list instead of a tree — so a run reads as "9 things happened", not
+     *  "a turn, which called a tool, which asked a second model".
+     *
+     *  Resolved in this order: the innermost container span still open on this trace
+     *  (`agent.run` / `tool.call`), else the app's span from a supplied `traceparent`,
+     *  else none — this span is the root. */
+    parentSpanId?: string;
+    name: string;
+    kind: SpanKind;
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    status: 'unset' | 'ok' | 'error';
+    attributes: Record<string, unknown>;
+}
+/** What kind of work an event describes. `message` is conversation content, which is not
+ *  a span — it is the thing you want in a debug store and NOT in your metrics backend,
+ *  which is exactly why it filters separately. */
+export type TraceEventType = 'agent' | 'tool' | 'llm' | 'http' | 'mcp' | 'media' | 'message' | 'other';
+/** One piece of work, carrying enough of the tree that a consumer can push it straight
+ *  into their own tracer without reconstructing anything. */
+export interface TraceEvent {
+    type: TraceEventType;
+    /** The app's trace when it supplied a `traceparent`, else ours. */
+    traceId: string;
+    spanId: string;
+    /** Already resolved past anything this subscriber filtered out — see `survivingParent`. */
+    parentSpanId?: string;
+    /** The conventional name (`chat gpt-5.4-nano`, `execute_tool search`). */
+    name: string;
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    status: 'unset' | 'ok' | 'error';
+    attributes: Record<string, unknown>;
+}
+/** Declarative on purpose, rather than a predicate: knowing the types up front lets a
+ *  filtered-out event cost nothing, where a predicate would force us to build the payload
+ *  just to let the caller throw it away. */
+export interface TraceFilter {
+    types?: readonly TraceEventType[];
+}
+export type TraceHandler = (event: TraceEvent) => void;
+export interface TelemetryEvent {
+    seq: number;
+    time: number;
+    name: HookName;
+    category: string;
+    traceId?: string;
+    ctx: unknown;
+}
+export interface TelemetryMetrics {
+    requests: number;
+    errors: number;
+    retries: number;
+    rateLimitHits: number;
+    completions: number;
+    mediaGenerated: number;
+    costUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    inFlight: number;
+    queueDepth: number;
+    latency: {
+        count: number;
+        min: number;
+        max: number;
+        avg: number;
+    };
+}
+/** OpenTelemetry Resource — identifies the SERVICE producing this telemetry, so
+ *  a shared backend can separate streams from different apps and attribute cost
+ *  per service (`sum by service.name`). Stamped on every span/metric/log. */
+export interface TelemetryResource {
+    /** Primary grouping key, e.g. "billing-api". OTel default: "unknown_service". */
+    serviceName: string;
+    /** Optional namespace/group, e.g. "prod" or a team. */
+    serviceNamespace?: string;
+    /** Unique instance (pod/host/process); a good default is the engine sessionId. */
+    serviceInstanceId?: string;
+    serviceVersion?: string;
+    /** Arbitrary resource attributes (deployment.environment, cloud.region, …). */
+    attributes?: Record<string, string>;
+}
+export interface TelemetryAdapterOptions {
+    /** Cap on retained events (ring buffer). Default 2000. */
+    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;
+    /** Which event types to hand to `onTrace`. Omitted → everything.
+     *
+     *  Filtering SPLICES the tree rather than punching holes in it: drop `http` and the
+     *  spans under it re-parent to the nearest surviving ancestor. Dropping without that
+     *  leaves orphans, and a backend draws an orphan as a second root — worse than not
+     *  filtering at all. */
+    types?: readonly TraceEventType[];
+    /** Whether conversation content rides along on `message` events. Default `'none'`:
+     *  prompts and completions are the debugging gold AND the PII, so sending them is a
+     *  decision to make on purpose rather than inherit. `'full'` adds the Opt-In
+     *  `gen_ai.input.messages` / `gen_ai.output.messages` attributes; `'none'` still
+     *  reports the shape (counts and sizes), which is enough to spot a runaway prompt. */
+    content?: 'none' | 'full';
+    /** Fraction of TRACES to emit, 0..1. Default 1.
+     *
+     *  Per trace, never per span: sampling spans independently shreds every tree it touches
+     *  — a tool call with no run, a model call with no tool. The decision is a hash of the
+     *  trace id, so it is stable across processes and two services sharing a trace agree
+     *  without coordinating.
+     *
+     *  This is HEAD sampling: the choice is made when the trace first appears, before we
+     *  know whether it ends in an error. Keeping all errors needs tail sampling, which
+     *  needs buffering; do that in your collector, which is built for it. */
+    sample?: number;
+    /** Convenience for the common case of a single sink — same as calling `onTrace`. */
+    onTrace?: TraceHandler;
+}

package/dist/util/hash.d.ts

@@ -0,0 +1,8 @@
+/** FNV-1a, 32-bit. Deterministic, synchronous and dependency-free — used where a
+ *  stable short id has to be derived from content rather than from a clock.
+ *
+ *  Not cryptographic. Collisions are acceptable for naming and bucketing; do not
+ *  use it for integrity or security. */
+export declare function fnv1a32(input: string): number;
+/** Same value as 8 lowercase hex characters. */
+export declare function fnv1a32Hex(input: string): string;

package/dist/{plugins/media → util}/source-image.d.ts

@@ -5,7 +5,7 @@
  *    - 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';
+import type { DataSource } from '../llm/types/messages';
 export interface NormalizedImageRef {
     /** Raw base64 (no `data:` prefix), when inline. */
     base64?: string;

package/dist/wire/inherit.d.ts

@@ -0,0 +1,47 @@
+/** Spec inheritance: a spec version extends the previous one and overrides only
+ *  what changed.
+ *
+ *  This replaces the `variants` section. Instead of asking "which shape does this
+ *  model id take?" at request time — which needed version arithmetic, and which
+ *  is currently WRONG for `claude-opus-4-20250514` (the date suffix parses as the
+ *  minor version, so a 4.0 model resolves to the 4.6+ shape) — the catalog pins a
+ *  model to a spec id, and the spec chain carries the differences as deltas.
+ *
+ *  Merge rules, in one sentence each:
+ *    - `fields`  are keyed by `to`   — child replaces, `remove:true` deletes, new ones append
+ *    - `blocks`  are keyed by `name` — same, with `before`/`after` for explicit placement
+ *    - `tables`  merge per table, per key
+ *    - `overlays`/`envelope.headers` are keyed and replaced
+ *    - everything scalar: child wins
+ *
+ *  Block ORDER is load-bearing (proved by the mutation suite), so appended blocks
+ *  land at the end unless the delta says otherwise.
+ */
+import type { WireSpec } from './interpreter';
+export interface Deltas {
+    extends?: string;
+    /** Rules to delete from the inherited spec. */
+    removeFields?: string[];
+    removeBlocks?: string[];
+    /** Explicit placement for an appended block. */
+    placeBlocks?: Record<string, {
+        before?: string;
+        after?: string;
+    }>;
+}
+export type SpecDelta = Partial<WireSpec> & Deltas & {
+    id: string;
+};
+/** Apply one delta to a resolved spec. This is the whole of composition, and it
+ *  is deliberately shared: a CHAIN picks the delta sequence by walking parents, a
+ *  MATRIX picks it by selecting features. Behind the resolver they are the same
+ *  operation — see `compose.ts`. */
+export declare function applyDelta(base: WireSpec, delta: SpecDelta): WireSpec;
+/** Resolve a spec id to its fully flattened form by walking `extends`. */
+export declare function resolveSpec(id: string, byId: Map<string, SpecDelta>, seen?: Set<string>): WireSpec;
+/** Catalog pin: model id -> spec id. `default` is what an unknown model gets. */
+export interface PinTable {
+    default: string;
+    models: Record<string, string>;
+}
+export declare function specForModel(model: string, pins: PinTable): string;

package/dist/wire/interpreter.d.ts

@@ -0,0 +1,236 @@
+/** Wire-spec interpreter — prototype for report 037 / 3.0.0.
+ *
+ *  Turns a declarative wire spec + a NormalizedRequest into the same
+ *  ProviderHttpRequest the hand-written `buildRequest` produces today.
+ *
+ *  The point is NOT to eliminate code. It is to move the per-provider and
+ *  per-MODEL knowledge — field names, shapes, enum values, which variant a
+ *  model takes — out of imperative code and into reviewable data that the
+ *  update pipeline can diff and that all three language ports can share.
+ *
+ *  Structural work (turning unified messages into provider content parts) stays
+ *  as named code in the registry. See `transforms.ts`.
+ */
+export type Json = unknown;
+/** A condition evaluated against the request + resolved model variants. */
+export type Cond = {
+    defined: string;
+} | {
+    truthy: string;
+} | {
+    eq: [string, Json];
+} | {
+    ne: [string, Json];
+} | {
+    variant: string;
+} | {
+    flavor: string | string[];
+} | {
+    pred: string;
+}
+/** Truthiness of a field on the current $map item. */
+ | {
+    itemTruthy: string;
+}
+/** The current $map item equals this value (items are scalars here). */
+ | {
+    itemEq: Json;
+} | {
+    isLast: true;
+} | {
+    isFunctionTool: true;
+} | {
+    builtin: string;
+}
+/** `req.tools` contains a builtin of this type. */
+ | {
+    hasTool: string;
+}
+/** `req.tools` contains at least one function tool. */
+ | {
+    hasFunctionTool: true;
+}
+/** Array at `path` contains `value`. */
+ | {
+    includes: [string, Json];
+} | {
+    not: Cond;
+} | {
+    all: Cond[];
+} | {
+    any: Cond[];
+};
+export interface FieldRule {
+    /** Dotted path into NormalizedRequest. */
+    from: string;
+    /** Dotted path into the body. */
+    to: string;
+    /** Default when the source is absent. Emits the field even if unset. */
+    default?: Json;
+    /** Extra gate on top of the presence check. */
+    when?: Cond;
+    /** Presence test: `defined` (!== undefined) or `truthy`. Default `defined`. */
+    presence?: 'defined' | 'truthy';
+    /** Named value table to map the source value through. */
+    table?: string;
+    /** Value used when the table has no entry (rather than dropping the field). */
+    tableDefault?: Json;
+    /** Named transform applied to the source value. */
+    call?: string;
+}
+export interface BlockRule {
+    /** Documentation handle; also used in diff output. */
+    name: string;
+    when?: Cond;
+    /** Dotted target path. Omit to merge the result into the body root. */
+    to?: string;
+    /** Deep-merge into whatever is already at `to` (output_config case). */
+    merge?: boolean;
+    /** Value template. */
+    template?: Json;
+    /** Named builder invoked with (req, ctx) instead of a template. */
+    call?: string;
+    /** Named cross-field effects run after the block is written. */
+    effects?: string[];
+}
+export interface WireSpec {
+    id: string;
+    provider: string;
+    api: string;
+    /** Adapter flavor, for specs shared by several providers (openai|xai|openrouter). */
+    flavors?: string[];
+    envelope?: {
+        path?: Json;
+        /** Full URL template. Non-chat adapters (media, files, batch) address an
+         *  absolute URL rather than a path under a shared base. */
+        url?: Json;
+        method?: string;
+        /** `json` (default), `multipart`, or `none` for GET/DELETE with no body.
+         *  Multipart matters: a FormData body JSON-stringifies to `{}`, so comparing
+         *  it as JSON would pass vacuously no matter what the fields are. */
+        bodyKind?: 'json' | 'multipart' | 'none';
+        headers?: {
+            name: string;
+            value: Json;
+            when?: Cond;
+        }[];
+    };
+    /** Model-id → variant flags. The migration target is a catalog pin; the
+     *  `idMatch` form is what today's regex helpers do, expressed as data.
+     *  `fn` is the escape hatch for rules a pattern cannot express (version
+     *  arithmetic) — every use of it is a finding, not a feature. */
+    variants?: {
+        flag: string;
+        idMatch?: string;
+        fn?: string;
+        unless?: string;
+        note?: string;
+    }[];
+    /** Value tables referenced by `table:` and `$table`. */
+    tables?: Record<string, Record<string, Json>>;
+    /** Fields we deliberately never send, with the reason. */
+    unsupported?: {
+        from: string;
+        reason: string;
+    }[];
+    fields?: FieldRule[];
+    blocks?: BlockRule[];
+    /** Multipart form fields, in order, when `envelope.bodyKind` is 'multipart'. */
+    multipart?: {
+        name: string;
+        value?: Json;
+        file?: boolean;
+        when?: Cond;
+    }[];
+    /** Non-HTTP surfaces. A realtime session is not one request: it is a
+     *  connection descriptor plus a sequence of outbound frames, so those are
+     *  named operations rather than a single envelope+body. */
+    operations?: Record<string, OperationRule>;
+    /** Per-flavor patches applied after the blocks. This mirrors what the xai and
+     *  openrouter adapters already do today: call the base builder, then patch the
+     *  result. Expressing it as ops keeps the shared spec authoritative. */
+    overlays?: Record<string, {
+        ops: OverlayOp[];
+    }>;
+}
+export interface OverlayOp {
+    op: 'rename' | 'delete' | 'set' | 'mergeFrom' | 'call';
+    /** rename/delete: body path. mergeFrom: request path. */
+    from?: string;
+    /** rename/set: body path. */
+    to?: string;
+    value?: Json;
+    call?: string;
+    when?: Cond;
+}
+export interface Ctx {
+    req: any;
+    spec: WireSpec;
+    flavor: string;
+    /** Adapter-level configuration (baseURL, apiKey, ...) referenced by `$config`.
+     *  Keeps the URL declarative rather than pushing it into a named transform. */
+    config: Record<string, unknown>;
+    variants: Set<string>;
+    body: Record<string, unknown>;
+    /** Per-item scope while inside a $map. */
+    item?: {
+        value: any;
+        index: number;
+        isLast: boolean;
+    };
+    /** Collected multipart fields, when the spec declares a multipart body. */
+    multipart?: MultipartField[];
+}
+export interface MultipartField {
+    name: string;
+    kind: 'file' | 'value';
+    value?: Json;
+}
+export type Transform = (value: any, ctx: Ctx) => Json;
+export type Builder = (ctx: Ctx) => Json;
+export type Predicate = (ctx: Ctx) => boolean;
+export type Effect = (ctx: Ctx) => void;
+export interface Registry {
+    transforms: Record<string, Transform>;
+    builders: Record<string, Builder>;
+    predicates: Record<string, Predicate>;
+    effects: Record<string, Effect>;
+}
+export declare function getPath(root: any, path: string): any;
+export declare function evalCond(cond: Cond | undefined, ctx: Ctx, reg: Registry): boolean;
+export declare function resolveVariants(spec: WireSpec, model: string, reg: Registry): Set<string>;
+export interface BuiltRequest {
+    body: Record<string, unknown>;
+    headers?: Record<string, string>;
+    path?: string;
+    url?: string;
+    method?: string;
+    /** Present instead of a JSON body when bodyKind is 'multipart'. */
+    multipart?: MultipartField[];
+    /** True when the spec declares the request carries no body at all. */
+    noBody?: boolean;
+}
+export declare function buildFromSpec(spec: WireSpec, req: any, reg: Registry, flavor?: string, 
+/** Coverage hook: called with every rule that actually fired. */
+onUse?: (kind: 'field' | 'block' | 'header' | 'variant' | 'overlay', name: string) => void, 
+/** Adapter config exposed to `$config`. */
+config?: Record<string, unknown>): BuiltRequest;
+export interface OperationRule {
+    /** Connection descriptor (realtime `connect`). */
+    url?: Json;
+    protocols?: Json;
+    /** Outbound frames, in order. A frame whose template evaluates away is skipped. */
+    frames?: {
+        name?: string;
+        when?: Cond;
+        template: Json;
+    }[];
+}
+export interface BuiltConnection {
+    url: string;
+    protocols?: string[];
+}
+/** Build the connection descriptor for an operation (realtime `connect`). */
+export declare function buildConnection(spec: WireSpec, operation: string, input: any, reg: Registry, config?: Record<string, unknown>): BuiltConnection;
+/** Build the outbound frames for an operation (realtime `open` / `send`). */
+export declare function buildFrames(spec: WireSpec, operation: string, input: any, reg: Registry, config?: Record<string, unknown>): Json[];

package/dist/wire/registry.d.ts

@@ -0,0 +1,18 @@
+/** Every wire spec the SDK ships, indexed by id.
+ *
+ *  A spec says HOW to talk to a provider API: field names, enum values, defaults,
+ *  which shape a model version takes. It is deliberately DATA, so the same file
+ *  is consumed by this SDK and by the Python and Rust ports, and a provider
+ *  change is one reviewable diff rather than three code changes.
+ *
+ *  Generated index — regenerate rather than hand-edit when adding a spec.
+ *
+ *  Specs are not yet wired into the adapters: they currently serve as the
+ *  differential oracle that proves the hand-written adapters and this data agree
+ *  (see tests/unit/wire). Making them authoritative is the 3.0.0 step.
+ */
+import type { SpecDelta } from './inherit';
+/** All shipped specs, keyed by `provider/api@version` id. */
+export declare const WIRE_SPECS: ReadonlyMap<string, SpecDelta>;
+/** Resolve a spec id to its flattened form, walking `extends`. */
+export declare function getWireSpec(id: string): SpecDelta;

package/dist/wire/transforms.d.ts

@@ -0,0 +1,22 @@
+/** The named-code registry the wire specs delegate to.
+ *
+ *  Everything here is bound to the REAL library internals, never reimplemented —
+ *  if the interpreter's output matches the adapter's, it is because the spec
+ *  drove the same code, not because I wrote a second copy that happens to agree.
+ *
+ *  What lands in this file is the honest answer to "what cannot be data":
+ *  structural message/content transformation, schema-shape rules, and one
+ *  variant rule that is arithmetic rather than a pattern.
+ */
+import type { Registry } from './interpreter';
+/** Adapters whose private message builders we reuse. Instantiated once; the
+ *  builders are pure with respect to the request. */
+export interface AdapterHandles {
+    anthropic: any;
+    google: any;
+    openaiResponses: any;
+    openaiCompletions: any;
+    googleInteractions?: any;
+    openrouterMedia?: any;
+}
+export declare function makeRegistry(a: AdapterHandles): Registry;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combycode/llm-sdk",
-  "version": "2.2.1",
+  "version": "2.3.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",
@@ -43,9 +43,9 @@
     "format": "biome format --write src tests",
     "check": "biome check src tests",
     "check:fix": "biome check --write src tests",
-    "gate": "node ../../quality-gate/gate.mjs",
+    "gate": "bun run scripts/gate.ts",
     "gate:selftest": "node ../../quality-gate/selftest.mjs",
-    "gate:snapshot": "node ../../quality-gate/gate.mjs --only api-snapshot --update"
+    "gate:snapshot": "bun run scripts/gate.ts --only api-snapshot --update"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",