@combycode/llm-sdk 1.7.0 → 2.0.1

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/agent/types.d.ts

@@ -1,7 +1,7 @@
 /** Agent-layer shared types — TokenCounter contract used by ContextRegistry,
  *  ConversationHistory, and the ContextMeasurer plugin.
  *  Also defines AgentTool (executable tool) and run-report types. */
-import type { ContentPart, Message } from '../llm/types/messages';
+import type { AssistantPhase, ContentPart, Message } from '../llm/types/messages';
 import type { Tool } from '../llm/types/tools';
 import type { Usage } from '../llm/types/response';
 import type { HistorySnapshot } from './history-types';
@@ -103,9 +103,15 @@ export interface AgentRunReport {
 export type AgentStreamEvent = {
     type: 'step_start';
     step: number;
-} | {
+}
+/** `phase` mirrors the raw stream event: `'commentary'` is the model narrating, anything
+ *  else (usually absent) is the answer. Passed through so a consumer can tell them apart
+ *  LIVE — `finalAnswerText()` only cleans a finished message and cannot touch deltas.
+ *  Absent on every provider that reports no phase, exactly as before. */
+ | {
     type: 'text';
     text: string;
+    phase?: AssistantPhase;
 } | {
     type: 'thinking';
     text: string;

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.