@combycode/llm-sdk 2.0.0 → 2.1.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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combycode/llm-sdk",
-  "version": "2.0.0",
+  "version": "2.1.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",