@combycode/llm-sdk 2.0.1 → 2.2.0

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

@@ -6,3 +6,22 @@ import type { JsonSchema } from './tools';
  * reject schemas without this explicit flag. Safe across all providers.
  */
 export declare function ensureAdditionalProperties(schema: JsonSchema): JsonSchema;
+/** Whose strict-mode rules to judge a schema against. */
+export type StrictDialect = 'openai' | 'anthropic';
+/** Can this schema satisfy the provider's strict mode AS WRITTEN?
+ *
+ *  Strict mode is worth defaulting to — it is what makes a provider constrain the
+ *  tool name and arguments DURING generation rather than checking after. But the
+ *  two providers constrain different things, and a schema that violates either is
+ *  rejected with a 400, not quietly degraded:
+ *
+ *    openai     every property must appear in `required`, at every nesting level
+ *    anthropic  a set of validation keywords is simply unsupported
+ *
+ *  So strict is requested only where it can be honoured. The alternative — rewriting
+ *  the schema to fit, promoting optional properties to required-and-nullable — changes
+ *  what the tool actually receives, and the receiving end is the caller's code. */
+export declare function strictSupport(schema: JsonSchema | undefined, dialect: StrictDialect): {
+    ok: boolean;
+    reason?: string;
+};

package/dist/network/engine.d.ts

@@ -21,11 +21,11 @@ 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 { RetryPolicyOverride } from './queue-state-config';
 import type { ConnectFn, FetchFn, HttpRequest, HttpResponse, RealtimeConnection, SSEEvent, WsRequest } from './types';
 export interface QueueSettings {
     limits?: Partial<RateLimiterConfig>;
-    retry?: Partial<RetryConfig>;
+    retry?: RetryPolicyOverride;
     queue?: Partial<QueueConfig>;
 }
 export interface NetworkEngineConfig {
@@ -39,6 +39,12 @@ export interface NetworkEngineConfig {
     connect?: ConnectFn;
     /** Pre-configured per-queue settings. Looked up by queueName at queue creation. */
     queues?: Record<string, QueueSettings>;
+    /** Retry policy inherited by EVERY queue this engine creates.
+     *
+     *  Retry is a cross-cutting setting, not something a caller should thread through each call, so
+     *  it is configured once (`createEngine({ retry })`) and applies everywhere. Three layers,
+     *  narrowest wins: `HttpRequest.retry` > `queues[name].retry` > this. */
+    retry?: RetryPolicyOverride;
 }
 /** Optional context for fetch/fetchStream. RequestContext + per-call overrides. */
 export interface FetchOptions {
@@ -52,6 +58,8 @@ export declare class NetworkEngine {
     readonly hooks: HookBus;
     private readonly fetchFn;
     private readonly connectFn;
+    /** Engine-wide retry policy, inherited by every queue created from here. */
+    private readonly defaultRetry;
     private readonly settings;
     private readonly queues;
     constructor(config?: NetworkEngineConfig);

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

@@ -22,6 +22,14 @@ export interface BackoffConfig {
     multiplier: number;
     jitter: number;
 }
+/** A retry policy stated as a partial override of another one.
+ *
+ *  `Partial<RetryConfig>` only makes the TOP-level keys optional, so it still demands a complete
+ *  `backoff` object — which makes "override one knob, keep the rest" inexpressible even though the
+ *  merge has always supported it. Engine-level and queue-level overrides take this instead. */
+export type RetryPolicyOverride = Omit<Partial<RetryConfig>, 'backoff'> & {
+    backoff?: Partial<BackoffConfig>;
+};
 export interface ErrorRetryConfig {
     retryable?: boolean;
     maxRetries?: number;
@@ -34,7 +42,7 @@ export interface QueueStateConfig {
     fetch: FetchFn;
     hooks: HookBus;
     limits: RateLimiterConfig;
-    retry?: Partial<RetryConfig>;
+    retry?: RetryPolicyOverride;
     queue?: Partial<QueueConfig>;
 }
 export declare const Priority: {
@@ -43,4 +51,4 @@ export declare const Priority: {
     readonly BACKGROUND: 2;
     readonly LOW: 3;
 };
-export declare function mergeRetry(overrides?: Partial<RetryConfig>): RetryConfig;
+export declare function mergeRetry(overrides?: RetryPolicyOverride): RetryConfig;

package/dist/network/types.d.ts

@@ -69,6 +69,12 @@ export interface TraceContext {
     sessionId?: string;
     requestId?: string;
     callId?: string;
+    /** W3C `traceparent` of the span this work runs UNDER, when the caller runs the SDK
+     *  inside its own trace. It rides with the ids because every span we emit needs it,
+     *  not only the ones built straight from a caller's RequestContext — an agent run
+     *  reaches its tool calls and its nested agents through this object, and those were
+     *  left rooting traces of their own while the LLM spans joined the caller's. */
+    traceparent?: string;
 }
 /** Point-in-time numeric state of one queue (for metrics / observability). */
 export interface QueueSnapshot {

package/dist/plugins/cost-collector/collector.d.ts

@@ -13,6 +13,8 @@ export declare class CostCollector {
     private budgets;
     private triggeredThresholds;
     private _runningTotal;
+    /** Models already reported as unpriced, so the warning fires once rather than per call. */
+    private warnedUnpriced;
     private watchedAgents;
     private unsub;
     private unsubMedia;
@@ -36,6 +38,16 @@ export declare class CostCollector {
     import(entries: CostEntry[]): void;
     private handleMediaGenerated;
     private handleCompletion;
+    /** A total of exactly 0 because the model is not in the catalog reads identically to a
+     *  total of 0 because the call was free — and it silently under-counts every budget
+     *  and report built on it. `source: 'unknown'` already records the difference per
+     *  entry, but nothing aggregated it, so a whole benchmark run once reported $0.00000
+     *  for a live provider and looked like a free arm.
+     *
+     *  Fires once per provider/model: an unpriced model is a configuration fact, not a
+     *  per-request event, and repeating it on every call would train the reader to ignore
+     *  it. Free calls are priced 'calculated' with an explicit note, so they stay silent. */
+    private noteIfUnpriced;
     private checkBudgets;
     private filterEntries;
     private groupBy;

package/dist/plugins/cost-collector/cost-collector-types.d.ts

@@ -39,4 +39,12 @@ export interface CostSummary {
         reasoning: number;
     };
     entries: number;
+    /** How many of `entries` could not be priced — no catalog entry for the model, or no
+     *  applicable rate. They count as 0 in every field above, so a summary without this
+     *  number cannot tell "this run was cheap" from "this run was never priced". Free
+     *  calls are NOT counted here: they are priced, at zero. */
+    unpriced: number;
+    /** The distinct `provider/model` values behind `unpriced`, so the gap is actionable
+     *  rather than merely visible. Empty when everything was priced. */
+    unpricedModels: string[];
 }

package/dist/plugins/mcp/result-cache.d.ts

@@ -21,7 +21,14 @@ export declare class McpResultCache {
      *  different entries. */
     static key(method: string, params?: unknown): string;
     get(key: string, now?: number): unknown | undefined;
-    /** Store only when the server actually asked for it. Returns whether anything was stored. */
+    /** Store only when the server actually asked for it. Returns whether anything was stored.
+     *
+     *  A non-positive `ttlMs` is an instruction, not a missing value: the server is saying *do not
+     *  reuse this*. Any entry already held under that key is dropped, so the next `get` re-fetches.
+     *  Without the eviction the hint is inert — a server that first said "cache for 60s" and then
+     *  says "stale now" would keep being answered from the stale entry for the rest of the original
+     *  TTL. Absent hints are different and must stay different: they carry no instruction, so an
+     *  existing entry is left alone and pre-2026 servers behave exactly as before. */
     set(key: string, value: unknown, hints: McpCacheHints | undefined, now?: number): boolean;
     /** Drop everything — e.g. after a `*_changed` notification says the server moved on. */
     clear(): void;

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

@@ -8,6 +8,8 @@ export interface McpToolAdapterOptions {
     /** Validate `structuredContent` against the tool's `outputSchema`; on mismatch
      *  the tool returns an error string instead of the content. Default false. */
     validateOutput?: boolean;
+    /** Register the tool without declaring it — see `AgentTool.lazy`. */
+    lazy?: boolean;
 }
 /** Map a `tools/call` result to our tool-result shape: a plain string when the
  *  content is text-only, else a ContentPart[] (images/audio kept as base64).

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

@@ -14,6 +14,40 @@ export interface JsonRpcResponse {
     result?: unknown;
     error?: JsonRpcError;
 }
+/** Behavioural hints a server publishes about a tool. Advisory and UNVERIFIED — a
+ *  server asserts them about itself — so they inform a host's UX (confirm before a
+ *  destructive call) and must never be treated as a security boundary.
+ *
+ *  Open (CONSTITUTION R1): the spec gains hints over time and an unknown one must
+ *  survive rather than be dropped. */
+export interface McpToolAnnotations {
+    title?: string;
+    /** The tool does not modify its environment. Default false. */
+    readOnlyHint?: boolean;
+    /** The tool may perform destructive updates rather than only additive ones. */
+    destructiveHint?: boolean;
+    /** Repeated calls with the same arguments have no additional effect. */
+    idempotentHint?: boolean;
+    /** The tool touches an open world (the internet) rather than a closed one. */
+    openWorldHint?: boolean;
+    [hint: string]: unknown;
+}
+/** An icon a host may render beside the tool. Display only. */
+export interface McpToolIcon {
+    src: string;
+    mimeType?: string;
+    sizes?: string[];
+    theme?: 'light' | 'dark' | (string & {});
+}
+/** How the tool must be invoked.
+ *
+ *  `taskSupport: 'required'` means the client MUST call it as a task rather than a
+ *  plain `tools/call`. Task invocation is not implemented here, so such a tool
+ *  cannot be called through this client — carrying the field lets a caller SEE
+ *  that instead of discovering it as a server error. Absent means `'forbidden'`. */
+export interface McpToolExecution {
+    taskSupport?: 'required' | 'optional' | 'forbidden' | (string & {});
+}
 export interface McpToolDef {
     name: string;
     description?: string;
@@ -22,6 +56,15 @@ export interface McpToolDef {
     inputSchema: Record<string, unknown>;
     /** JSON Schema for the tool's `structuredContent` output (optional). */
     outputSchema?: Record<string, unknown>;
+    /** Advisory behavioural hints. HOST-facing, never sent to the model: no
+     *  provider's function-tool schema has a field that could carry them. */
+    annotations?: McpToolAnnotations;
+    /** Display icons for a host UI. */
+    icons?: McpToolIcon[];
+    /** Invocation requirements; see {@link McpToolExecution}. */
+    execution?: McpToolExecution;
+    /** Spec-defined passthrough metadata. */
+    _meta?: Record<string, unknown>;
 }
 /** A content block in a `tools/call` result. Open union — unknown types ignored. */
 export type McpContentBlock = {

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

@@ -11,10 +11,29 @@
  *  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';
+/** Derive a conformant hex id from one of our readable ids. `bytes` is 16 for a trace
+ *  id, 8 for a span id.
+ *
+ *  Deterministic on purpose: the same logical trace maps to the same OTLP id on every
+ *  export and in every process, so a trace stitched together from two exports — or
+ *  from two services sharing a sessionId — still joins up in the backend. */
+export declare function toOtlpId(input: string, bytes: 8 | 16): string;
+/** One attribute in OTLP's AnyValue shape, keeping numbers numeric. Integers go out as
+ *  `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;
@@ -23,6 +42,34 @@ export interface Span {
     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;
@@ -50,6 +97,13 @@ export interface TelemetryMetrics {
         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. */
+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. */
@@ -80,6 +134,32 @@ export interface TelemetryAdapterOptions {
      *  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[];
@@ -88,15 +168,79 @@ export declare class TelemetryAdapter {
     /** Service identity stamped on exported telemetry. */
     readonly resource: TelemetryResource;
     private seq;
+    /** Discriminator for POINT spans (media, mcp connect/tool), whose natural keys are
+     *  not unique — the same server reconnects, a run emits two images, two tool calls
+     *  land in one millisecond. A duplicate span id inside a trace is invalid OTLP and
+     *  the backend silently keeps only one. */
+    private spanSeq;
+    /** Per trace: the app's span from a `traceparent`, and the CONTAINER spans currently
+     *  open on it. Together they decide what a new span hangs under — see `parentFor`.
+     *  Both are cleared once a trace has nothing open, so a long-lived process does not
+     *  accumulate an entry per conversation forever.
+     *
+     *  A list, not a single slot: an agent nested in a tool call (C2 inside C1's tool) is a
+     *  second run on the SAME trace, and with one slot it overwrote its own parent and then
+     *  deleted it on close — leaving the rest of the outer run parentless. */
+    private appParent;
+    private containers;
     private latSum;
     private readonly open;
     private readonly maxEvents;
     private readonly includeSensitiveData;
     private readonly unsub;
+    /** Subscribers, each with its own filter. Re-parenting is computed PER SINK: two
+     *  consumers asking for different types each get a tree that is correct for them. */
+    private readonly sinks;
+    private readonly content;
+    private readonly sampleRate;
+    /** spanId → its parent and type, for EVERY span including filtered ones — walking up
+     *  past a dropped ancestor is the whole point, so the dropped ones must still be here.
+     *  Bounded, because a long-lived process would otherwise remember every span it ever
+     *  saw. */
+    private readonly lineage;
+    private readonly maxLineage;
+    private msgSeq;
     constructor(hooks: HookBus, opts?: TelemetryAdapterOptions);
+    /** Subscribe to the event stream. Returns an unsubscribe function.
+     *
+     *  ```ts
+     *  const stop = telemetry.onTrace({ types: ['agent', 'tool'] }, (e) => pipeline.push(e));
+     *  ```
+     */
+    onTrace(handler: TraceHandler): () => void;
+    onTrace(filter: TraceFilter, handler: TraceHandler): () => void;
+    /** Record a finished span and hand it to the subscribers. Every span reaches the store
+     *  through here, so there is one place where an event can be missed rather than five. */
+    private recordSpan;
+    private remember;
+    private dispatch;
+    /** The nearest ancestor this subscriber actually receives. Without this, filtering out
+     *  `http` would leave its children pointing at a span that never arrives, and a backend
+     *  renders a dangling parent as a separate root. */
+    private survivingParent;
+    /** Hashed rather than random, so the same trace samples the same way in every process
+     *  and a trace shared by two services is kept or dropped by both. */
+    private isSampled;
+    /** Conversation content, as its own event so it can be routed somewhere different from
+     *  the spans — a debug store, not the metrics backend. */
+    private emitMessage;
     /** Stop tapping the bus. */
     destroy(): void;
     private handle;
+    /** What a new span on this trace hangs under: the innermost container still open on
+     *  it, else the app's span, else nothing (we are the root).
+     *
+     *  A container wins over the app's span because an LLM call made during a run belongs
+     *  to that run — attaching it straight to the app would flatten the very nesting the
+     *  tree exists to show. A span joins the stack only after it is built, so nothing can
+     *  become its own parent, and a run nested in a tool call lands under that tool call —
+     *  exactly where it happened.
+     *
+     *  Limit worth naming: with tools running in parallel two `tool.call` spans are open at
+     *  once and "innermost" is merely the more recent one. Attributing a nested run to the
+     *  right sibling needs real async context propagation, which this adapter does not
+     *  have; sequential tools, the common case, are exact. */
+    private parentFor;
     private openSpan;
     private closeSpan;
     private recordLatency;

package/dist/types/request-context.d.ts

@@ -25,6 +25,17 @@ export interface RequestContext {
      *  server/agent set it, else the LLM client mints in buildContext). Follows
      *  the whole chain; the request half of the trace id. */
     requestId?: string;
+    /** W3C trace context of the span this work runs UNDER — `00-<32 hex trace>-<16 hex
+     *  span>-<flags>`, exactly the `traceparent` header shape.
+     *
+     *  Pass it and the SDK stops rooting its own trace: its spans join that trace and hang
+     *  under that span. Without it the library cannot know it is inside an application's
+     *  request, so the business chain and the model calls reach the backend as two
+     *  unrelated traces.
+     *
+     *  Sources: the inbound `traceparent` header, or an active span from an OTel SDK if
+     *  the app already runs one. */
+    traceparent?: string;
     /** = `history.id`. Stable for the lifetime of the conversation. */
     conversationId?: string;
     /** Unique per `.complete()` / `.stream()` call. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combycode/llm-sdk",
-  "version": "2.0.1",
+  "version": "2.2.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",
@@ -42,7 +42,10 @@
     "lint:fix": "biome lint --write src tests",
     "format": "biome format --write src tests",
     "check": "biome check src tests",
-    "check:fix": "biome check --write src tests"
+    "check:fix": "biome check --write src tests",
+    "gate": "node ../../quality-gate/gate.mjs",
+    "gate:selftest": "node ../../quality-gate/selftest.mjs",
+    "gate:snapshot": "node ../../quality-gate/gate.mjs --only api-snapshot --update"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",