@combycode/llm-sdk 2.2.2 → 3.0.0

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

@@ -10,7 +10,8 @@
  *  An in-memory store backs the sandbox sidebar; `toOtlpTraces()` shapes spans
  *  into OTLP-compatible JSON for a real OTel exporter to forward. */
 import type { HookBus } from '../../bus/hook-bus';
-import type { HookName } from '../../bus/hook-map';
+export type { Span, SpanKind, TelemetryAdapterOptions, TelemetryEvent, TelemetryMetrics, TelemetryResource, TraceEvent, TraceEventType, TraceFilter, TraceHandler, } from './types';
+import type { Span, TelemetryAdapterOptions, TelemetryEvent, TelemetryMetrics, TelemetryResource, TraceFilter, TraceHandler } from './types';
 /** Derive a conformant hex id from one of our readable ids. `bytes` is 16 for a trace
  *  id, 8 for a span id.
  *
@@ -22,81 +23,6 @@ export declare function toOtlpId(input: string, bytes: 8 | 16): string;
  *  `intValue` carrying a STRING, which is how OTLP/JSON encodes 64-bit integers; send
  *  them as plain strings instead and no backend can sum them. */
 export declare function toOtlpValue(value: unknown): Record<string, unknown>;
-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;
-    };
-}
 /** Parse a W3C `traceparent`: `00-<32 hex trace>-<16 hex span>-<flags>`.
  *  Returns null for anything malformed or for the all-zero ids the spec forbids —
  *  a bad header must not silently reroute telemetry into a garbage trace. */
@@ -104,63 +30,6 @@ export declare function parseTraceparent(value: string | undefined): {
     traceId: string;
     spanId: string;
 } | null;
-/** 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;
-}
 export declare class TelemetryAdapter {
     readonly events: TelemetryEvent[];
     readonly spans: Span[];

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/chat-specs.d.ts

@@ -0,0 +1,32 @@
+/** The wire specs the RUNTIME loads: chat only, resolved and memoised.
+ *
+ *  Deliberately not `registry.ts`. That index imports all 71 specs — every media,
+ *  realtime, files and batch spec included — so an adapter importing it would pull
+ *  the whole set into every bundle whether or not anything reads them. Measured on
+ *  the 2.3.0 build: interpreter + inherit + transforms is 18 KB minified, the nine
+ *  chat specs add 15 KB, and all 71 specs add 41 KB. Chat-only is +2.7% on the
+ *  bundle; everything is +4.8% for specs nothing executes yet.
+ *
+ *  `registry.ts` stays as the complete index for the tests and the ports. This is
+ *  the runtime's subset, and it grows a family at a time as each adapter is
+ *  migrated — so what ships is always what runs.
+ *
+ *  Chains are resolved once per id and cached: resolution walks `extends` and
+ *  merges deltas, which is pure setup work and has no business happening per
+ *  request.
+ */
+import type { WireSpec } from './interpreter';
+/** The spec for `id`, with its inheritance chain already applied.
+ *
+ *  Throws on an unknown id rather than falling back to something plausible: a
+ *  silently-substituted spec is a wrong request sent confidently, which is the
+ *  exact failure the specs exist to end. Callers pick the fallback themselves —
+ *  see each adapter's DEFAULT_SPEC. */
+export declare function chatSpec(id: string): WireSpec;
+/** Whether a spec id is one the runtime can build. Lets an adapter fall back to
+ *  its default instead of throwing when a catalog pin names a spec from a family
+ *  that is not migrated yet. */
+export declare const isChatSpec: (id: string | undefined) => id is string;
+/** Ids the runtime carries — asserted by the tests so this list and the shipped
+ *  spec files cannot drift apart unnoticed. */
+export declare const CHAT_SPEC_IDS: readonly string[];

package/dist/wire/inherit.d.ts

@@ -0,0 +1,43 @@
+/** 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;
+};
+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,279 @@
+/** 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. */
+        /** `json` (default), `multipart`, `none` for a bodyless GET/DELETE, or
+         *  `raw` when the body is caller-supplied BYTES the spec cannot describe —
+         *  a file being streamed to an upload session. The spec still owns the URL,
+         *  method and headers; only the payload comes from outside. */
+        bodyKind?: 'json' | 'multipart' | 'none' | 'raw' | 'form';
+        /** Headers in declaration order. An entry with `spread` merges an evaluated
+         *  OBJECT of headers instead of setting one, which is what a caller-supplied
+         *  header map or a resolved auth bundle is. Order is the whole point: it is
+         *  what decides whether a configured `accept` overrides the default one or the
+         *  other way round, and that was previously a property of which spread came
+         *  later in a hand-written object literal. */
+        headers?: {
+            name?: string;
+            value?: Json;
+            when?: Cond;
+            spread?: Json;
+        }[];
+        /** Query parameters, appended to `url` (or `path`) in declaration order.
+         *
+         *  Splicing them into the URL with `$join` works only while every parameter is
+         *  present: `$join` propagates an omitted part, so one absent `pageToken` takes
+         *  the whole URL with it. Declaring them separately lets a parameter drop out
+         *  on its own, and puts the encoding in ONE place — the hand-written adapters
+         *  disagreed about whether to call `encodeURIComponent`, which is how a page
+         *  token with a `+` in it silently paged from the wrong place. */
+        query?: {
+            name: string;
+            value: Json;
+            when?: Cond;
+        }[];
+        /** How query values are escaped. `component` (default) percent-escapes
+         *  everything, including a space as `%20`. `form` uses the
+         *  application/x-www-form-urlencoded rules, where a space is `+` — which is
+         *  what RFC 6749 prescribes for an OAuth authorization request, and what its
+         *  servers are used to receiving. Both decode to the same string; they are not
+         *  the same bytes, and a signature over the request would notice. */
+        queryEncoding?: 'component' | 'form';
+    };
+    /** 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;
+        /** Emit ONE field per array element instead of a single array-valued
+         *  field. Real forms use repeated keys for lists — OpenAI's transcription
+         *  takes `languages[]` once per language — and a single field holding an
+         *  array is a different request the server will not accept. */
+        repeat?: boolean;
+    }[];
+    /** 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;
+    /** The body is caller-supplied bytes (bodyKind 'raw'). */
+    rawBody?: boolean;
+    /** Present instead of a JSON body when bodyKind is 'multipart'. */
+    multipart?: MultipartField[];
+    /** The body is form-urlencoded: `body` holds the FIELDS, and the caller encodes
+     *  them. Same split as multipart — the spec says what the form carries, the
+     *  runtime does the encoding, and the frozen fixture stays readable as fields
+     *  rather than as one percent-escaped string. */
+    formBody?: boolean;
+    /** 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[];