@combycode/llm-sdk 1.6.1 → 2.0.0

package/README.md

@@ -10,7 +10,7 @@ A unified, pluggable AI SDK for accessing the LLMs of every major provider —
   `model:tier` selectors, capability-based `select()`, tiered pricing, and cost
   tracking.
 - **Cross-environment.** The same code runs on Node, Bun, and the browser. Zero
-  runtime dependencies, ESM.
+  **required** runtime dependencies, ESM.
 
 ## Install
 
@@ -18,7 +18,22 @@ A unified, pluggable AI SDK for accessing the LLMs of every major provider —
 npm install @combycode/llm-sdk      # or: bun add @combycode/llm-sdk
 ```
 
-Requires Node ≥ 18 or Bun ≥ 1.1.
+Upgrading from 1.x? See [MIGRATION.md](./MIGRATION.md) — three things can
+require action, and none of them is a provider change.
+
+Requires **Node ≥ 22** or Bun ≥ 1.1. (Node 18 and 20 are end-of-life; 22 is also the floor
+`openai-node` 7 adopted.)
+
+`dependencies` is empty. The one optional extra is `tiktoken`, an **optional peer** for exact local
+OpenAI token counting — install it only if you want that:
+
+```sh
+npm install tiktoken
+```
+
+Without it everything still works: token counting falls back to the provider count-API
+(Anthropic/Google) or a calibrated heuristic. It is a peer rather than an `optionalDependency` so
+its ~5.6 MB wasm is not installed — or bundled — for people who never use it.
 
 ## Quickstart
 

package/dist/agent/loop-config.d.ts

@@ -4,6 +4,7 @@ import type { LLMClient } from '../llm/client';
 import type { CacheConfig, ThinkingConfig } from '../llm/types/request';
 import type { ConversationHistory } from './history';
 import type { HistorySnapshot } from './history-types';
+import type { ReflectAndRetryConfig } from './reflect-retry';
 import type { AgentTool } from './types';
 import type { Guardrail, ToolInputGuardrail } from './guardrail-types';
 import type { PermissionPolicy } from '../plugins/permissions/policy';
@@ -23,6 +24,27 @@ export interface AgentLoopConfig {
     context?: string;
     /** Executable tools. Indexed by function name (FunctionTool) or type (BuiltinTool). */
     tools?: AgentTool[];
+    /** What to do when two tools claim the same registry key.
+     *
+     *  Registration is a map keyed by function name / builtin type, so a collision means one tool
+     *  SILENTLY replaces another and the model never sees it. The failure then surfaces much later
+     *  as "the model called the wrong tool", with nothing in the logs pointing at the cause.
+     *
+     *  - `'warn'` (default) — keep last-write-wins, but emit an `onWarning`
+     *    (`code: 'tool_name_collision'`) naming the key and which tool lost.
+     *  - `'error'` — throw at construction / `addTool()`, before the model is ever called.
+     *
+     *  Defaults to `'warn'` so an app that unknowingly has a collision keeps working
+     *  (CONSTITUTION.md R4) — the collision just stops being invisible. */
+    toolNameCollisionPolicy?: 'warn' | 'error';
+    /** Self-healing recovery from a recoverable MODEL failure (a malformed tool call, a hallucinated
+     *  tool name, a truncated call). The model is given structured guidance naming the attempt and
+     *  told not to repeat the same call, then the step is retried within a bounded budget.
+     *
+     *  Off unless configured: a retry costs a real request, so it is the caller's decision. This is
+     *  NOT a network retry — the engine already handles transport failures. This one is for a request
+     *  that succeeded and came back unusable, which resending unchanged would never fix. */
+    reflectAndRetry?: ReflectAndRetryConfig;
     /** Reuse an existing history (or rehydrate from a snapshot). New history
      *  is created when omitted. */
     history?: ConversationHistory | HistorySnapshot;

package/dist/agent/loop-step-state.d.ts

@@ -12,6 +12,8 @@ export interface ToolCallAccumEntry {
 /** All mutable state for one streaming step inside AgentLoop.stream(). */
 export interface StepState {
     stepText: string;
+    /** Commentary deltas, kept apart from stepText so the step's answer excludes narration. */
+    stepCommentary: string;
     stepThinking: string;
     stepToolCalls: ToolCallPart[];
     toolCallAccum: Map<string, ToolCallAccumEntry>;

package/dist/agent/loop.d.ts

@@ -36,6 +36,8 @@ export declare class AgentLoop {
     private _temperature?;
     private _thinking?;
     private _cache?;
+    private _collisionPolicy;
+    private readonly _reflectRetry;
     private _parallelToolCalls;
     private _toolTimeout;
     private _maxSteps;
@@ -71,6 +73,11 @@ export declare class AgentLoop {
     get lastReport(): AgentRunReport | null;
     get metadata(): Record<string, unknown>;
     addTool(tool: AgentTool): void;
+    /** Register a tool, surfacing a name collision instead of letting the last write win silently.
+     *
+     *  The `warn` path still overwrites — that is the pre-existing behaviour and changing it would
+     *  break apps that depend on a deliberate override — but it now says which tool lost. */
+    private registerTool;
     removeTool(name: string): void;
     toolNames(): string[];
     stop(): void;

package/dist/agent/reflect-retry.d.ts

@@ -0,0 +1,56 @@
+/** Reflect-and-retry — self-healing recovery from a recoverable MODEL failure.
+ *
+ *  Some turns fail in a way the model itself can fix: it produced malformed tool arguments, named a
+ *  tool that does not exist, or was cut off mid-call. Surfacing that straight to the caller wastes a
+ *  turn that a single corrective nudge would have salvaged. This injects structured guidance —
+ *  naming the attempt number and telling the model not to repeat the same call — and lets the loop
+ *  try again within a bounded budget.
+ *
+ *  Ported from google-adk `ReflectAndRetryModelPlugin` (adk 2.6), including its default trigger
+ *  (`MALFORMED_FUNCTION_CALL`) and its raise-vs-give-up switch.
+ *
+ *  Deliberately NOT a network retry: `NetworkEngine` already retries transport failures. This is for
+ *  a request that SUCCEEDED and came back unusable, which no amount of resending would fix. */
+import type { FinishReason } from '../llm/types/response';
+export interface ReflectAndRetryConfig {
+    /** Consecutive recoverable failures to tolerate before giving up. Default 3. */
+    maxRetries?: number;
+    /** Which finish reasons count as recoverable. Default `['malformed_tool_call']`.
+     *
+     *  Adding `'content_filter'` is possible but rarely wise: a refusal is usually a decision, not a
+     *  mistake, and retrying it burns budget to be refused again. */
+    onFinishReasons?: FinishReason[];
+    /** When the budget is exhausted: `true` (default) throws, `false` returns the last response as-is
+     *  so the caller can decide. Upstream calls this `throw_exception_if_retry_exceeded`. */
+    throwIfExceeded?: boolean;
+}
+export declare const DEFAULT_REFLECT_RETRY_REASONS: FinishReason[];
+export declare class ReflectAndRetryPolicy {
+    readonly maxRetries: number;
+    readonly throwIfExceeded: boolean;
+    private readonly reasons;
+    /** Consecutive failures for the CURRENT run. Reset by any successful turn, so an agent that
+     *  recovers and then fails again much later gets a fresh budget rather than inheriting one. */
+    private consecutive;
+    constructor(config?: ReflectAndRetryConfig);
+    /** Is this finish reason one we try to recover from? */
+    handles(finishReason: FinishReason): boolean;
+    /** Record a successful turn — the failure streak is broken. */
+    recordSuccess(): void;
+    /** Record a recoverable failure and report what to do next.
+     *
+     *  `attempt` counts from 1 so the guidance can say "attempt 1 of 3" the way a human would. */
+    recordFailure(): {
+        retry: boolean;
+        attempt: number;
+        exhausted: boolean;
+    };
+    get consecutiveFailures(): number;
+    /** Reset between runs so one run's failures never spend another run's budget. */
+    reset(): void;
+}
+/** The corrective message fed back to the model.
+ *
+ *  Names the attempt number and explicitly forbids repeating the identical call — without that, a
+ *  model tends to re-emit the same malformed arguments and burn the whole budget on one mistake. */
+export declare function reflectionGuidance(finishReason: FinishReason, attempt: number, maxRetries: number, detail?: string): string;

package/dist/agent/tool-key.d.ts

@@ -1,3 +1,6 @@
 /** Registry key for an AgentTool: the function name, else the builtin type. */
 import type { AgentTool } from './types';
 export declare function toolKey(tool: AgentTool): string;
+/** A short label for a tool, for collision diagnostics. Names the KIND as well as the key, because
+ *  a function tool shadowing a builtin (or the reverse) is the case that reads as impossible. */
+export declare function describeTool(tool: AgentTool): string;

package/dist/bus/hook-map.d.ts

@@ -467,6 +467,16 @@ export interface MediaErrorContext {
     /** For async ops (video). */
     operationId?: string;
 }
+/** Progress ping for a long-running async media op (video generation/extend/
+ *  edit) — emitted once per poll while the job runs, so a UI can show a bar. */
+export interface MediaProgressContext {
+    type: 'video';
+    provider: string;
+    operationId: string;
+    /** 0–100 when the provider reports it; omitted otherwise. */
+    progress?: number;
+    model?: string;
+}
 export interface ServerRequestContext {
     serverId: string;
     requestId: string;
@@ -581,6 +591,7 @@ export interface HookMap {
     onContextMeasure: ContextMeasureContext;
     onMediaGenerated: MediaGeneratedContext;
     onMediaError: MediaErrorContext;
+    onMediaProgress: MediaProgressContext;
     onInternalToolCallStart: InternalToolCallStartContext;
     onInternalToolCallComplete: InternalToolCallCompleteContext;
     onInternalToolCallError: InternalToolCallErrorContext;

package/dist/helpers/mcp.d.ts

@@ -40,8 +40,22 @@ export interface ConnectMcpOptions {
     roots?: McpRoot[] | (() => McpRoot[] | Promise<McpRoot[]>);
     /** Validate tool `structuredContent` against the tool's `outputSchema`. */
     validateOutput?: boolean;
-    /** Send a `ping` every N ms to keep the connection alive (0 = off). */
+    /** Send a `ping` every N ms to keep the connection alive (0 = off).
+     *  Ignored on a 2026-07-28 session, where `ping` no longer exists. */
     keepAliveMs?: number;
+    /** How to negotiate the MCP protocol revision.
+     *
+     *  - `'auto'` (default) — probe `server/discover` first; fall back to the `initialize` handshake
+     *    on anything that is not positive evidence of a 2026-07-28 server.
+     *  - `'legacy'` — skip the probe entirely. Use for a server that mishandles unknown methods
+     *    (the spec says answer with an error; not every implementation does).
+     *  - a version string such as `'2026-07-28'` — adopt it directly, no probe. */
+    protocolMode?: 'auto' | 'legacy' | (string & {});
+    /** Honour the server's `ttlMs` / `cacheScope` hints on list and read results (2026-07-28).
+     *  Off by default; a server that sends no hints caches nothing either way. */
+    cacheResults?: boolean;
+    /** Cap on `input_required` (MRTR) retry rounds before giving up. Default 10. */
+    inputRequiredMaxRounds?: number;
     /** OAuth provider for servers that require authorization (HTTP only). On a
      *  required interactive grant, `connectMcp` throws `McpUnauthorizedError`
      *  after the provider redirects; finish with `finishMcpAuth`, then reconnect. */
@@ -69,11 +83,19 @@ export declare function connectMcp(config: McpServerConfig, opts?: ConnectMcpOpt
 /** Finish an interactive OAuth grant: exchange the callback `code` for tokens
  *  (saved via the provider). The `state` from the authorization callback MUST
  *  be provided and is validated against the persisted value (CSRF guard).
- *  Call after catching `McpUnauthorizedError`, then `connectMcp` again. */
+ *  Call after catching `McpUnauthorizedError`, then `connectMcp` again.
+ *
+ *  **Pass `opts.iss` if the callback URL carried one** (RFC 9207). It is validated against the
+ *  authorization server's issuer before the code is redeemed, which is what stops a malicious
+ *  server handing you a code minted elsewhere and having you replay the user's credentials against
+ *  it. Optional so existing callers keep working, but a server that advertises
+ *  `authorization_response_iss_parameter_supported` will make a missing `iss` an error — as it
+ *  should, since an attacker could otherwise strip the parameter to skip the check. */
 export declare function finishMcpAuth(serverUrl: string, code: string, state: string, opts: {
     auth: McpAuthProvider;
     engine?: EngineHandle;
     security?: SsrfGuardOptions;
+    iss?: string;
 }): Promise<void>;
 export declare function mcpToolset(configs: McpServerConfig[], opts?: ConnectMcpOptions): Promise<{
     tools: AgentTool[];

package/dist/helpers/provenance-types.d.ts

@@ -0,0 +1,63 @@
+/** Types for `checkProvenance()` — detecting provider provenance signals in a file. */
+import type { EngineHandle } from './engine';
+/** Which provenance scheme a signal came from.
+ *
+ *  - `c2pa` — a signed Content Credentials manifest (who made it, with what, when).
+ *  - `synthid` — Google's imperceptible watermark; survives some edits a manifest does not.
+ *
+ *  Open union (CONSTITUTION.md R1): more schemes will appear, and a new one must not break a
+ *  consumer's `switch`. */
+export type ProvenanceSignalKind = 'c2pa' | 'synthid' | (string & {});
+/** How much a detected C2PA manifest can be believed. `trusted` is the only state that means the
+ *  signature verified against a known issuer. Open by R1. */
+export type ProvenanceValidationState = 'trusted' | 'valid' | 'invalid' | 'not_present' | (string & {});
+export interface ProvenanceSignal {
+    kind: ProvenanceSignalKind;
+    detected: boolean;
+    validationState?: ProvenanceValidationState;
+    /** Who signed the manifest (C2PA only). */
+    issuer?: string;
+    /** The model named in the manifest, when it records one. */
+    model?: string;
+    /** When the content was generated, per the manifest. */
+    generatedAt?: string;
+}
+export interface ProvenanceCheckResult {
+    /** Any signal detected at all.
+     *
+     *  **`false` is not proof a human made the file.** Provenance signals are strippable — a
+     *  re-encode, a crop, or a screenshot usually removes them — so absence is absence of evidence,
+     *  not evidence of absence. */
+    detected: boolean;
+    /** A signal was detected AND its manifest validated against a trusted issuer. This is the only
+     *  positive statement the check supports. */
+    trusted: boolean;
+    /** Every signal reported, including the ones that came back `detected: false` — an image is
+     *  checked for both C2PA and SynthID, audio for SynthID only. */
+    signals: ProvenanceSignal[];
+    createdAt?: number;
+}
+export interface CheckProvenanceOptions {
+    /** File bytes to check. */
+    file: Uint8Array;
+    /** Filename with an extension — the API uses it to pick a decoder. */
+    filename: string;
+    /** MIME type of the file (e.g. `image/png`, `audio/wav`). */
+    mimeType: string;
+    provider?: string;
+    apiKey?: string;
+    engine?: EngineHandle;
+}
+/** The raw wire shape, normalised by `parseProvenanceResponse`. */
+export interface ProvenanceRawResponse {
+    object?: string;
+    created_at?: number;
+    results?: Array<{
+        type?: string;
+        outcome?: string;
+        validation_state?: string;
+        issuer?: string;
+        model?: string;
+        generated_at?: string;
+    }>;
+}

package/dist/helpers/provenance.d.ts

@@ -0,0 +1,12 @@
+/** checkProvenance() — does this file carry provider provenance signals?
+ *
+ *    const v = await checkProvenance({ file: bytes, filename: 'photo.png', mimeType: 'image/png' });
+ *    if (v.trusted) { … }   // a manifest that actually validated
+ *
+ *  Same shape as `moderate()`: bytes in, structured verdict out, HTTP through engine.fetch.
+ *
+ *  **Read `detected: false` carefully.** Provenance signals are strippable — a re-encode, a crop or
+ *  a screenshot usually removes them — so a negative result is absence of evidence, not evidence
+ *  that a human made the file. Only `trusted` is a positive statement. */
+import type { CheckProvenanceOptions, ProvenanceCheckResult } from './provenance-types';
+export declare function checkProvenance(opts: CheckProvenanceOptions): Promise<ProvenanceCheckResult>;

package/dist/helpers/transcribe.d.ts

@@ -5,7 +5,7 @@
  *      (gpt-4o-transcribe / whisper). Routed to OpenAITranscriptionAdapter.
  *    - generateContent providers (google, …): transcription is just a normal
  *      completion with the audio attached, so reuse complete(). */
-import type { AudioInput } from '../llm/types/audio';
+import type { AudioInput, TranscriptLanguage, TranscriptSegment, TranscriptWord } from '../llm/types/audio';
 import type { ProviderName } from '../llm/types/provider';
 import type { EngineHandle } from './engine';
 export interface TranscribeOptions {
@@ -15,19 +15,48 @@ export interface TranscribeOptions {
     /** Audio source: a file path, raw bytes, or an AudioInput (with explicit
      *  mimeType for raw/stream audio). */
     audio: string | Uint8Array | AudioInput;
-    /** Optional language hint (BCP-47, e.g. "en"). */
+    /** Optional language hint (BCP-47, e.g. "en") — the language the audio IS in.
+     *  Supported by `whisper-1` and `gpt-4o-transcribe`. Use `languages` instead for
+     *  `gpt-transcribe`, which rejects this field. */
     language?: string;
+    /** Candidate languages for the audio (ISO-639-1), when the language is not known
+     *  up front. Narrowing the candidates changes what the model reports detecting.
+     *  OpenAI: `gpt-transcribe` only — other models reject it with a 400. */
+    languages?: string[];
+    /** Words or phrases that steer spelling — product names, people, jargon. Verified
+     *  to work: an invented name transcribed as "Zalbrequist" without keywords comes
+     *  back as "Zylberquist" with it.
+     *  OpenAI: `gpt-transcribe` only — other models reject it with a 400. */
+    keywords?: string[];
+    /** Ask for word-level timings (and segments).
+     *  OpenAI: `whisper-1` only — other models reject it with a 400. */
+    wordTimestamps?: boolean;
+    /** Ask for speaker-labelled segments.
+     *  OpenAI: `gpt-4o-transcribe-diarize` only — other models reject it with a 400.
+     *  Cannot be combined with `wordTimestamps`: no model returns both. */
+    diarization?: boolean;
     /** Prompt used for generateContent-style providers (ignored by openai). */
     prompt?: string;
-    /** Caller-supplied audio duration in seconds.  Used to price OpenAI
-     *  transcription calls (the API does not return duration).  When omitted,
-     *  the helper tries to parse duration from a WAV header; other formats
-     *  emit an honest zero with a note. */
+    /** Caller-supplied audio duration in seconds, used to price the call.
+     *  Takes precedence when set. Otherwise the provider's own reported duration is
+     *  used when it returns one, then a WAV-header estimate; if none of the three is
+     *  available the cost hook emits an honest zero with a note. */
     audioDurationSeconds?: number;
     engine?: EngineHandle;
 }
+/** `text` is the only guaranteed field. Everything else appears when the chosen
+ *  model returns it, so a consumer written against `text` keeps working forever
+ *  (CONSTITUTION.md R3). */
 export interface TranscribeResult {
     text: string;
+    /** Languages the provider reports detecting. */
+    languages?: TranscriptLanguage[];
+    /** Timed segments. `speaker` is set only when diarization ran. */
+    segments?: TranscriptSegment[];
+    /** Word-level timings. */
+    words?: TranscriptWord[];
+    /** Audio duration in seconds as the provider measured it. */
+    durationSeconds?: number;
 }
 export declare function transcribe(opts: TranscribeOptions): Promise<TranscribeResult>;
 /** WAV PCM duration from raw bytes — pure arithmetic, cross-env.