@combycode/llm-sdk 1.7.0 → 2.0.0

package/dist/llm/providers/anthropic/constants.d.ts

@@ -11,3 +11,5 @@ export declare const ANTHROPIC_THINKING_BUDGETS: Record<string, number>;
  * unrecognised.
  */
 export declare const DEFAULT_ANTHROPIC_THINKING_BUDGET = 2048;
+/** True when this Anthropic model still accepts `top_k` (see ANTHROPIC_TOP_K_MODELS). */
+export declare function anthropicAcceptsTopK(model: string): boolean;

package/dist/llm/providers/openai/completions.d.ts

@@ -23,6 +23,15 @@ export declare class OpenAIAdapter implements ProviderAdapter {
     baseURL(): string;
     completionPath(): string;
     buildRequest(req: NormalizedRequest): ProviderHttpRequest;
+    /** One universal message can become SEVERAL chat-completions messages.
+     *
+     *  Parallel tool calls are the case that matters: the loop answers a round of calls
+     *  with ONE tool message carrying a `tool_result` part per call, but this API wants a
+     *  separate `{role:'tool'}` message per `tool_call_id`. Emitting only the first left
+     *  the rest unanswered and the provider rejected the whole request with
+     *  "No tool output found for function call <id>" — so parallel tools were broken on
+     *  every chat-completions backend. */
+    private buildMessages;
     private buildMessage;
     enableStreaming(providerReq: ProviderHttpRequest, _req: NormalizedRequest): void;
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;

package/dist/llm/providers/openai/provenance.d.ts

@@ -0,0 +1,26 @@
+/** OpenAI content-provenance adapter — POST /v1/content_provenance_checks (openai-ts 7.x).
+ *
+ *  Answers "does this file carry provider provenance signals?" — a C2PA manifest and/or a SynthID
+ *  watermark. It is the only "was this AI-generated" primitive any tracked SDK ships.
+ *
+ *  Note what it does NOT do: a `not_detected` result is not proof a human made the file. Provenance
+ *  signals are strippable (a re-encode or a screenshot usually loses them), so absence is absence of
+ *  evidence. Only `detected` with a `trusted` validation state is a positive statement.
+ *
+ *  All HTTP flows through the injected EngineFetch. */
+import type { EngineFetch } from '../../../network/types';
+import type { ProvenanceCheckResult, ProvenanceRawResponse } from '../../../helpers/provenance-types';
+export interface OpenAIProvenanceAdapterConfig {
+    apiKey: string;
+    baseURL?: string;
+}
+export declare const OPENAI_PROVENANCE_BASE_URL = "https://api.openai.com";
+export declare const OPENAI_PROVENANCE_PATH = "/v1/content_provenance_checks";
+export declare class OpenAIProvenanceAdapter {
+    private readonly apiKey;
+    private readonly baseURL;
+    constructor(config: OpenAIProvenanceAdapterConfig);
+    check(bytes: Uint8Array, filename: string, mimeType: string, fetch: EngineFetch): Promise<ProvenanceCheckResult>;
+}
+/** Normalise the wire response into the unified verdict. */
+export declare function parseProvenanceResponse(raw: ProvenanceRawResponse | undefined): ProvenanceCheckResult;

package/dist/llm/providers/openai/responses.d.ts

@@ -3,6 +3,7 @@
  *  Modern API: input (not messages), instructions (not system role),
  *  output items (not choices), function_call/function_call_output for tools. */
 import type { SSEEvent } from '../../../network/types';
+import type { AssistantPhase } from '../../types/messages';
 import type { ProviderAdapter, ProviderHttpRequest } from '../../types/provider';
 import type { NormalizedRequest } from '../../types/request';
 import { type CompletionResponse, type FileOutput, type Usage } from '../../types/response';
@@ -20,11 +21,12 @@ export declare class OpenAIResponsesAdapter implements ProviderAdapter {
     baseURL(): string;
     completionPath(): string;
     buildRequest(req: NormalizedRequest): ProviderHttpRequest;
-    /** Convert a universal Message to Responses API input items */
+    /** Convert a universal Message to Responses API input items.
+     *  `toolNames` is threaded across messages so a tool result can name its originating call. */
     private buildInputItems;
     enableStreaming(providerReq: ProviderHttpRequest): void;
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
-    parseStreamEvent(event: SSEEvent): StreamEvent[];
+    parseStreamEvent(event: SSEEvent, phaseByItem?: Map<string, AssistantPhase>): StreamEvent[];
     /** Stateless — each output item finalizes with all its file annotations in a
      *  single response.output_item.done event. */
     createStreamParser(): (event: SSEEvent) => StreamEvent[];

package/dist/llm/providers/openai/transcription.d.ts

@@ -1,6 +1,20 @@
 /** OpenAI transcription adapter — POST /v1/audio/transcriptions (multipart).
  *  All HTTP flows through the injected EngineFetch (rawBody multipart, like the
- *  batch file upload). gpt-4o-transcribe / whisper return `{ text }`. */
+ *  batch file upload).
+ *
+ *  Three response shapes come back from one endpoint, selected by `response_format`
+ *  and constrained by the model (all verified on the wire, 2026-08-09):
+ *
+ *  | model                     | `json`                        | `verbose_json`      | `diarized_json`     |
+ *  |---------------------------|-------------------------------|---------------------|---------------------|
+ *  | `gpt-transcribe`          | text + detected `languages`   | 400                 | 400                 |
+ *  | `gpt-4o-transcribe`       | text                          | 400                 | 400                 |
+ *  | `whisper-1`               | text                          | segments + words    | 400                 |
+ *  | `gpt-4o-transcribe-diarize` | text                        | -                   | segments + speakers |
+ *
+ *  No model returns everything: speaker labels and word timings live on different
+ *  models. `keywords` / `languages` are `gpt-transcribe`-only and 400 elsewhere. */
+import type { TranscriptLanguage, TranscriptSegment, TranscriptWord } from '../../types/audio';
 import type { EngineFetch } from '../../../network/types';
 export interface OpenAITranscriptionAdapterConfig {
     apiKey: string;
@@ -10,11 +24,34 @@ export interface TranscriptionRequest {
     bytes: Uint8Array;
     mimeType: string;
     model: string;
+    /** The language of the input audio (ISO-639-1). Improves accuracy and latency.
+     *  Supported by `whisper-1` / `gpt-4o-transcribe`; NOT by `gpt-transcribe`,
+     *  which uses `languages` instead. */
     language?: string;
+    /** Candidate languages for the input audio (ISO-639-1). `gpt-transcribe` only. */
+    languages?: string[];
+    /** Words or phrases that steer spelling of names and jargon. `gpt-transcribe` only. */
+    keywords?: string[];
+    /** Ask for segment + word timings (`response_format: verbose_json`). `whisper-1` only. */
+    wordTimestamps?: boolean;
+    /** Ask for speaker-labelled segments (`response_format: diarized_json`).
+     *  `gpt-4o-transcribe-diarize` only. */
+    diarization?: boolean;
+}
+export interface OpenAITranscriptionResult {
+    text: string;
+    /** Languages the model reports detecting. Returned unconditionally by `gpt-transcribe`. */
+    languages?: TranscriptLanguage[];
+    segments?: TranscriptSegment[];
+    words?: TranscriptWord[];
+    /** Audio duration in seconds as the provider measured it — this is the quantity
+     *  duration-billed models charge on, so it beats any local estimate. */
+    durationSeconds?: number;
 }
 export declare class OpenAITranscriptionAdapter {
     private readonly apiKey;
     private readonly baseURL;
     constructor(config: OpenAITranscriptionAdapterConfig);
-    transcribe(req: TranscriptionRequest, fetch: EngineFetch): Promise<string>;
+    transcribe(req: TranscriptionRequest, fetch: EngineFetch): Promise<OpenAITranscriptionResult>;
 }
+export declare function parseTranscription(body: unknown): OpenAITranscriptionResult;

package/dist/llm/types/audio.d.ts

@@ -16,3 +16,34 @@ export interface AudioInput {
     mimeType?: string;
     sampleRate?: number;
 }
+/** A language a provider reports detecting in transcribed audio.
+ *
+ *  An object rather than a bare `string` on purpose: providers already annotate
+ *  detections and will annotate them further (confidence, spans). A `string[]`
+ *  could only grow by becoming a different type, which is exactly the breaking
+ *  change CONSTITUTION.md R3 forbids. */
+export interface TranscriptLanguage {
+    /** Language code as the provider reported it (typically ISO-639-1, e.g. `en`). */
+    code: string;
+}
+/** One word with its timing, in seconds from the start of the audio. */
+export interface TranscriptWord {
+    word: string;
+    start: number;
+    end: number;
+}
+/** A timed run of transcript text.
+ *
+ *  `speaker` is present only when diarization ran; no provider surface currently
+ *  returns speakers and word timings together (see `transcribe()`), so a segment
+ *  carries whichever the chosen model produces. */
+export interface TranscriptSegment {
+    /** Provider segment id, normalised to a string (whisper numbers them, the
+     *  diarizing models use `seg_N`). */
+    id?: string;
+    start: number;
+    end: number;
+    text: string;
+    /** Speaker label, e.g. `A` / `B`, or a name from the provider's known-speaker list. */
+    speaker?: string;
+}

package/dist/llm/types/messages.d.ts

@@ -18,11 +18,23 @@ export interface MessageOrigin {
     /** Opaque provider signatures to echo back (thought-signature, encrypted reasoning). */
     signatures?: unknown;
 }
-export type ContentPart = TextPart | ImagePart | DocumentPart | AudioPart | VideoPart | ToolCallPart | ToolResultPart | ImageOutputPart | AudioOutputPart | VideoOutputPart;
+export type ContentPart = TextPart | ImagePart | DocumentPart | AudioPart | VideoPart | ToolCallPart | ToolResultPart | ProgramCallPart | ProgramResultPart | ImageOutputPart | AudioOutputPart | VideoOutputPart;
+/** Whether a piece of assistant text is the ANSWER or narration on the way to it.
+ *
+ *  `commentary` is the model thinking out loud for the user's benefit — distinct from reasoning,
+ *  which is its own part. `final_answer` is the response proper. Codex-family models emit both, and
+ *  without the distinction an agent loop treats narration as the result.
+ *
+ *  Open union (CONSTITUTION.md R1): a provider adding a third phase must not break consumers, so
+ *  write a `default` branch. */
+export type AssistantPhase = 'commentary' | 'final_answer' | (string & {});
 export interface TextPart {
     type: 'text';
     text: string;
     cache?: boolean;
+    /** Set only by providers that report it (OpenAI Responses, `gpt-5.3-codex` and later). Absent
+     *  everywhere else, which reads exactly as it did before: treat the text as the answer. */
+    phase?: AssistantPhase;
 }
 export interface ImagePart {
     type: 'image';
@@ -42,11 +54,30 @@ export interface VideoPart {
     type: 'video';
     source: DataSource;
 }
+/** Who invoked a tool: the model itself, or code the model wrote.
+ *
+ *  Open union (CONSTITUTION.md R1) — the provider enumerates the values it knows
+ *  (`direct` and `program` today) and may add more, so write a `default` branch. */
+export type ToolCallerType = 'direct' | 'program' | (string & {});
+/** The execution context that invoked a tool.
+ *
+ *  A single shape with an optional payload rather than
+ *  `{type:'direct'} | {type:'program', callerId}` (R2): a new caller kind with its own
+ *  fields then extends this instead of widening a union every consumer switches on. */
+export interface ToolCaller {
+    type: ToolCallerType;
+    /** The id of the {@link ProgramCallPart} that made this call. Present when
+     *  `type === 'program'`. */
+    callerId?: string;
+}
 export interface ToolCallPart {
     type: 'tool_call';
     id: string;
     name: string;
     arguments: Record<string, unknown>;
+    /** Who invoked this tool. Absent means the ordinary case — the model called it
+     *  directly — so existing consumers read exactly as before. */
+    caller?: ToolCaller;
     /** Provider-specific metadata (e.g. Google thought signatures). */
     _meta?: Record<string, unknown>;
 }
@@ -55,6 +86,53 @@ export interface ToolResultPart {
     id: string;
     content: string | ContentPart[];
     isError?: boolean;
+    /** The namespace of the tool that produced this result, when the provider tracks one (OpenAI
+     *  Responses). Round-tripped so a namespaced tool's output is attributable on the next turn; the
+     *  tool NAME is derived from the matching call rather than stored twice. */
+    namespace?: string;
+    /** Who invoked the call this result answers. Mirrors {@link ToolCallPart.caller}. */
+    caller?: ToolCaller;
+}
+/** Code the model wrote to orchestrate tool calls itself, instead of emitting them
+ *  one at a time and waiting for each result (OpenAI Responses "programmatic tool
+ *  calling", `gpt-5.6` family).
+ *
+ *  The program runs on the provider's side and suspends at every `await`, so its
+ *  tool calls still arrive as ordinary {@link ToolCallPart}s — each tagged with a
+ *  `caller` pointing back at this part's `id`. When the program finishes, a
+ *  {@link ProgramResultPart} carries what it returned.
+ *
+ *  **This part must be preserved in history and sent back.** Dropping it does not
+ *  merely lose an audit trail: the model re-emits the program and runs it again
+ *  from the start (verified 2026-08-09). */
+export interface ProgramCallPart {
+    type: 'program_call';
+    /** Call id shared with the matching {@link ProgramResultPart} and referenced by
+     *  `ToolCaller.callerId` on every tool call the program made. */
+    id: string;
+    /** The source the model wrote — JavaScript for OpenAI. Readable, and worth showing
+     *  to a user: it is the plan the model is executing. */
+    code: string;
+    /** Opaque provider token that must be round-tripped verbatim. */
+    fingerprint: string;
+    /** Provider-specific metadata: the raw item id, and the provider items this one is
+     *  bound to (OpenAI rejects the program without its reasoning item). Echoed back
+     *  by the adapter that produced it and ignored by every other provider. */
+    _meta?: Record<string, unknown>;
+}
+/** What a {@link ProgramCallPart} returned once it ran to completion. */
+export interface ProgramResultPart {
+    type: 'program_result';
+    /** Matches the {@link ProgramCallPart} `id`. */
+    id: string;
+    /** The program's return value, as the provider serialised it. */
+    result: string;
+    /** Terminal state. Open union (R1): `incomplete` means the program stopped early —
+     *  hitting a step limit or throwing — so the result is partial. */
+    status?: 'completed' | 'incomplete' | (string & {});
+    /** Provider-specific metadata: the raw item id, which OpenAI requires when this item
+     *  is sent back as history ("Missing required parameter: 'input[n].id'"). */
+    _meta?: Record<string, unknown>;
 }
 export interface ImageOutputPart {
     type: 'image_output';
@@ -123,3 +201,13 @@ export interface Message {
 export declare function contentParts(content: Content): ContentPart[];
 /** Extract plain text from content. */
 export declare function contentText(content: Content): string;
+/** The assistant's ANSWER, with commentary removed.
+ *
+ *  Codex-family models narrate before answering and mark the narration `phase: 'commentary'`.
+ *  Concatenating everything makes an agent's final output include its own thinking-out-loud.
+ *
+ *  Excludes only what is explicitly `'commentary'` rather than keeping only `'final_answer'`: the
+ *  phase vocabulary is open (R1), and a phase we do not recognise yet must never cause us to drop
+ *  the answer. Text with no phase at all — every other model — is returned unchanged, so this is
+ *  identical to `contentText` outside the codex family. */
+export declare function finalAnswerText(content: Content): string;

package/dist/llm/types/options.d.ts

@@ -20,6 +20,21 @@ export interface ExecuteOptions {
     maxTokens?: number;
     temperature?: number;
     topP?: number;
+    /** Restrict sampling to the k most likely tokens. Sent to Anthropic, Google
+     *  (generateContent + Interactions), xAI chat and OpenRouter chat; dropped for OpenAI,
+     *  which defines no top-k.
+     *
+     *  ACCEPTED IS NOT HONOURED. A behavioural test on 2026-07-29 (top_k=1 must force greedy
+     *  decoding) found only **Anthropic** actually applies it: six samples collapsed to a
+     *  single output. Google (gemini-2.5-flash, 3.6-flash) and xAI (grok-4.20) returned 200
+     *  but showed no greedy effect — accepted and inert on those models. It is still sent
+     *  (harmless, and may apply elsewhere) but do not rely on it outside Anthropic. */
+    topK?: number;
+    /** Best-effort deterministic sampling: the same seed + params should return the same
+     *  result. Honoured by OpenAI **chat-completions** (the Responses API rejects it), Google
+     *  (generateContent + Interactions), xAI (chat + responses) and OpenRouter chat.
+     *  Anthropic has no seed, so it is dropped there. Determinism is never guaranteed. */
+    seed?: number;
     /** Penalise tokens by prior presence ([-2, 2]). Honoured by OpenAI/xAI chat-completions,
      *  OpenRouter, and Google (generateContent + Interactions); ignored by OpenAI/xAI Responses
      *  and Anthropic, which don't accept it. */

package/dist/llm/types/request.d.ts

@@ -18,6 +18,17 @@ export interface NormalizedRequest {
     maxTokens?: number;
     temperature?: number;
     topP?: number;
+    /** Restrict sampling to the k most likely tokens. Emitted only where the wire accepts it
+     *  (live-verified 2026-07-28): Anthropic, Google generateContent AND Interactions, xAI chat,
+     *  OpenRouter chat. OpenAI has no top-k on either surface, so it is dropped there rather
+     *  than sent and rejected. */
+    topK?: number;
+    /** Best-effort deterministic sampling. Emitted only where the wire accepts it
+     *  (live-verified 2026-07-28): OpenAI **chat-completions** — the Responses API rejects it
+     *  (400 "Unknown parameter: 'seed'") — Google generateContent + Interactions, xAI chat AND
+     *  responses, OpenRouter chat. Anthropic has no seed (400 "Extra inputs are not permitted"),
+     *  so it is dropped there. */
+    seed?: number;
     /** Penalise tokens by prior presence (OpenAI/xAI chat-completions, OpenRouter, Google). */
     presencePenalty?: number;
     /** Penalise tokens by prior frequency (OpenAI/xAI chat-completions, OpenRouter, Google). */
@@ -47,7 +58,8 @@ export interface NormalizedRequest {
  *  rendered back to it on later turns of a stateful conversation (chained via
  *  `previousResponseId` / server-state). `all_turns` keeps continuity at higher
  *  token cost; `current_turn` drops earlier reasoning; `auto` lets OpenAI decide.
- *  Ignored by every other provider. */
+ *  Omitted, the model picks: the gpt-5.6 family defaults to `all_turns`, earlier
+ *  models to `current_turn`. Ignored by every other provider. */
 export type ReasoningContext = 'auto' | 'current_turn' | 'all_turns';
 /** How much of the model's reasoning is returned. `full` (default) returns it as
  *  fully as the provider allows; `summary` a condensed form where the provider

package/dist/llm/types/response.d.ts

@@ -24,6 +24,16 @@ export interface CompletionResponse {
      *  Report-only: present for observability; it never blocks the call. Absent when
      *  moderation was not requested. */
     moderation?: ModerationReport;
+    /** Why the turn failed, when `finishReason` is `'error'`. Some providers report a
+     *  failure *inside* a 200 response instead of a transport error (OpenAI Responses
+     *  `status: 'failed'` + `response.error`, Google Interactions `status: 'failed'`), so
+     *  there is no exception to catch — without this the caller only sees an empty result.
+     *  Absent unless the provider reported a failure. */
+    error?: {
+        /** Provider error code, e.g. OpenAI `data_residency_mismatch` (added 2026-07). */
+        code?: string;
+        message?: string;
+    };
     latencyMs: number;
     raw: unknown;
 }
@@ -66,7 +76,27 @@ export interface BuiltinToolCall {
      *  actions, which carry a URL instead of a query). Absent for plain searches. */
     url?: string;
 }
-export type FinishReason = 'stop' | 'tool_use' | 'length' | 'content_filter' | 'error';
+/** The finish reasons this SDK documents and maps deliberately. */
+export type KnownFinishReason = 'stop' | 'tool_use' | 'length' | 'content_filter' | 'error' | 'pending'
+/** The model tried to call a tool and produced something unusable — malformed arguments, a
+ *  hallucinated tool name, a truncated call. Distinct from `error` (the request itself failed)
+ *  and from `tool_use` (a call we can execute): this turn is *recoverable* by telling the model
+ *  what went wrong and letting it try again — see `reflectAndRetry` on `AgentLoop`. */
+ | 'malformed_tool_call';
+/** Why a turn ended.
+ *
+ *  **This union is OPEN by design** (CONSTITUTION.md R1). Providers keep inventing terminal states —
+ *  four of them did so in a single upstream cycle — and against a closed union every one of those is
+ *  a breaking change for every consumer, including consumers of providers that changed nothing.
+ *  Always write a `default` branch; use `KnownFinishReason` where you want the documented set alone.
+ *
+ *  `pending` is NOT terminal: the provider accepted the request but has not produced a completion
+ *  yet, so the response carries no content. It exists because several providers can return a
+ *  non-terminal status on an otherwise successful call — Google Interactions `queued` (google 2.13)
+ *  and OpenAI Responses `queued` / `in_progress` (background mode). Those used to fall through to
+ *  `stop`, which claimed a clean finish for an empty response. Treat `pending` as "poll/retry",
+ *  never as a result. */
+export type FinishReason = KnownFinishReason | (string & {});
 export interface Usage {
     inputTokens: number;
     outputTokens: number;

package/dist/llm/types/stream.d.ts

@@ -1,13 +1,26 @@
 /** Universal streaming event types. */
 import type { ModerationEntry } from '../moderation/types';
+import type { AssistantPhase } from './messages';
 import type { FileOutput, Usage } from './response';
 export type MediaStreamType = 'image' | 'audio' | 'video';
-export type StreamEvent = {
+export type StreamEvent = 
+/** `itemId` identifies WHICH output item a delta belongs to, when the provider reports
+ *  one (OpenAI Responses forwards `item_id`; chat-completions has no per-item concept,
+ *  so it is absent there). A single turn can interleave deltas from several output
+ *  items, so a consumer that reassembles them per item — rather than just concatenating
+ *  into one string — needs this to keep them apart. Optional and additive: ignoring it
+ *  gives exactly the previous behaviour. */
+/** `phase` mirrors the buffered `TextPart.phase`: whether this delta is commentary or the answer
+ *  proper. Reported only by models that distinguish them (codex family); absent elsewhere. */
+{
     type: 'text';
     text: string;
+    itemId?: string;
+    phase?: AssistantPhase;
 } | {
     type: 'thinking';
     text: string;
+    itemId?: string;
 } | {
     type: 'tool_call_start';
     id: string;

package/dist/llm/types/tiers.d.ts

@@ -1,11 +1,11 @@
-/** Unified service tier for a request. The four named values are the
- *  cross-provider core; the open `(string & {})` lets callers pass any tier
- *  (e.g. `'scale'`, or a future internal-optimization label) — each adapter
- *  decides whether it can honor it (pass through if the provider allows it,
- *  else fall back to that provider's `auto`).
+/** Unified service tier for a request. The named values are the cross-provider core; the open
+ *  `(string & {})` lets callers pass any tier (e.g. `'scale'`, or a future internal-optimization
+ *  label) — each adapter decides whether it can honor it (pass through if the provider allows it,
+ *  else fall back to that provider's `auto`). Open by design, per CONSTITUTION.md R1: a provider
+ *  adding a tier must never break a consumer, so listing a value here only adds autocomplete.
  *
  *  `batch` is intentionally NOT a value here — it's a separate API (the Batch
  *  endpoint), not a per-request flag on a synchronous call.
  *
  *  Tier mapping is provider-specific and lives ENTIRELY in the adapters. */
-export type ServiceTier = 'auto' | 'standard' | 'priority' | 'flex' | (string & {});
+export type ServiceTier = 'auto' | 'standard' | 'priority' | 'flex' | 'fast' | (string & {});

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

@@ -9,6 +9,11 @@ export interface RetryConfig {
     totalTimeoutMs: number;
     attemptTimeoutMs: number;
     backoff: BackoffConfig;
+    /** Longest `Retry-After` we are willing to honour. A server asking us to wait longer than this
+     *  does not get waited for: the request fails fast instead of parking in the queue, and the rate
+     *  limiter is not paused for that long either. Without a cap, a single `Retry-After: 86400`
+     *  silently holds a request — and the whole limiter — for a day. */
+    maxRetryAfterMs: number;
     perKind?: Partial<Record<ErrorKind, ErrorRetryConfig>>;
 }
 export interface BackoffConfig {

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

@@ -37,6 +37,13 @@ export declare class QueueState {
     private settleOnWorkerCrash;
     private executeWithRetry;
     private handleRetry;
+    /** The `Retry-After` we will actually honour: the server's value clamped to `maxRetryAfterMs`.
+     *  Anything above the cap never reaches here as a retry (see `retryAfterTooLong`), so the clamp
+     *  is a floor-level guard for the limiter-pause path and any future consumer. */
+    /** The effective retry policy for one request: the queue's, with any per-request override
+     *  applied on top. `perKind` is never overridden — see `RequestRetryOverride`. */
+    private retryFor;
+    private honoredRetryAfterMs;
     private calculateBackoff;
     private executeOnce;
     private waitForCapacity;

package/dist/network/types.d.ts

@@ -26,6 +26,29 @@ export interface HttpRequest {
     /** Trace correlation — set by the caller (LLM client / media op) from the
      *  RequestContext so every network event can echo `sessionId:requestId`. */
     trace?: TraceContext;
+    /** Per-request retry overrides, applied over the queue's policy for THIS request only.
+     *
+     *  The queue's policy is shared by every call on it, so a one-off needing to be more (or less)
+     *  patient — a long batch submit, a health check that should fail fast — previously had to accept
+     *  the shared policy or get its own queue. Mirrors Google moving `retryOptions` from client-level
+     *  to per-request `HttpOptions` (google-ts 2.15). */
+    retry?: RequestRetryOverride;
+}
+/** The retry knobs a single request may override.
+ *
+ *  Deliberately a subset: `perKind` stays queue-level, because one request cannot sensibly redefine
+ *  which error classes are retryable for the queue it shares with everyone else. */
+export interface RequestRetryOverride {
+    maxRetries?: number;
+    totalTimeoutMs?: number;
+    attemptTimeoutMs?: number;
+    maxRetryAfterMs?: number;
+    backoff?: Partial<{
+        initialMs: number;
+        maxMs: number;
+        multiplier: number;
+        jitter: number;
+    }>;
 }
 /** Raw HTTP response (post-fetch, pre-provider-parse). */
 export interface HttpResponse {

package/dist/plugins/context-guard/strategies/anchored.d.ts

@@ -0,0 +1,47 @@
+/** AnchoredStrategy — one growing scratchpad instead of a chain of summaries.
+ *
+ *  `LayeredStrategy` emits a NEW summary each time it compacts, so a long conversation accumulates
+ *  summaries-of-summaries: the oldest facts get re-summarised repeatedly and drift further from
+ *  what was actually said. This strategy keeps a SINGLE anchor entry at the head of history and
+ *  merges each compaction into it — the anchor grows, but every fact is summarised from the raw
+ *  text exactly once.
+ *
+ *  The trade is real and worth stating: one anchor means one blast radius. A bad merge corrupts the
+ *  whole record, where a chain of summaries only corrupts one link. Anchored suits long-running
+ *  task/state tracking ("what have we established so far"); layered suits conversations where
+ *  recency matters more than a durable state.
+ *
+ *  Ported from google-adk-ts `AnchoredContextCompactor` (adk 1.5), including its refusal to split a
+ *  tool call from its result. */
+import type { HistoryEntry } from '../../../agent/history-types';
+import type { ContextStrategy, ReactContext, StrategyDecision, TriggerLevel } from '../types';
+export interface AnchoredStrategyConfig {
+    /** Raw entries to keep verbatim at the tail. */
+    keepRecent?: number;
+    /** Cap on the anchor's own length, so the thing that replaces history cannot become history. */
+    anchorMaxChars?: number;
+    triggers?: TriggerLevel[];
+    /** Above this usage ratio, report `decline` — compaction alone will not save the request. */
+    declineCeiling?: number;
+}
+/** Marks the anchor entry so it can be found again on the next compaction. Kept in the text rather
+ *  than in metadata because the anchor has to survive an export/import round trip of history. */
+export declare const ANCHOR_MARKER = "[context-anchor]";
+/** Where the retained tail starts, refusing to split a tool call from its result.
+ *
+ *  Cutting between them leaves a `tool_result` whose call is gone, which several providers reject
+ *  outright and the rest silently misread. Walking the boundary backwards keeps the pair together.
+ *  Direct port of adk's `calculateRetainStartIndex`. */
+export declare function calculateRetainStartIndex(entries: readonly HistoryEntry[], keepRecent: number): number;
+export declare class AnchoredStrategy implements ContextStrategy {
+    readonly name: "anchored";
+    readonly triggers: TriggerLevel[];
+    private readonly keepRecent;
+    private readonly anchorMaxChars;
+    private readonly declineCeiling;
+    constructor(config?: AnchoredStrategyConfig);
+    react(ctx: ReactContext): Promise<StrategyDecision>;
+}
+/** Fold a new summary into the anchor, bounded so the anchor cannot itself become the problem.
+ *  When trimming is needed the NEWER text is kept — it already subsumes the older state. */
+export declare function mergeAnchor(previous: string, addition: string, maxChars: number): string;

package/dist/plugins/context-measurer/counter/hybrid.d.ts

@@ -19,7 +19,10 @@ export interface HybridCounterConfig {
  */
 export declare class HybridTokenCounter implements TokenCounter {
     private heuristic;
-    private tiktoken;
+    /** Built on first use, not in the constructor — most consumers never route to the tiktoken
+     *  strategy, and the optional peer dependency should not be reached for merely constructing a
+     *  counter. See CONSTITUTION.md standing decisions (2026-08-08). */
+    private _tiktoken?;
     private countApi;
     private readonly _config;
     constructor(config: HybridCounterConfig);

package/dist/plugins/context-measurer/counter/tiktoken.d.ts

@@ -1,6 +1,13 @@
-/** Tiktoken adapter — exact tokenization for OpenAI models. */
+/** Tiktoken adapter — exact tokenization for OpenAI models.
+ *
+ *  `tiktoken` is an OPTIONAL PEER dependency: it is not installed unless the consumer asks for it,
+ *  and nothing here runs until local token counting is actually used. See the standing decisions in
+ *  CONSTITUTION.md (2026-08-08).
+ */
 import type { Message } from '../../../llm/types/messages';
 import type { TokenCountContext, TokenCounter, LearnInput } from '../../../agent/types';
+/** Build the error thrown when the optional peer is missing. Exported for tests; not public API. */
+export declare function tiktokenUnavailableError(cause: unknown): Error;
 export declare class TiktokenCounter implements TokenCounter {
     private encodings;
     estimate(text: string, ctx?: TokenCountContext): number;

package/dist/plugins/mcp/base-transport.d.ts

@@ -39,11 +39,27 @@ export declare abstract class BaseJsonRpcTransport {
     protected nextId: number;
     protected handlers: IncomingMcpHandlers;
     protected readonly pending: Map<number, Pending>;
+    /** Long-lived requests (`subscriptions/listen`) awaiting their end-of-stream response. Kept apart
+     *  from `pending` because these must NOT time out. */
+    protected readonly longLived: Map<number, ((error?: unknown) => void) | undefined>;
     setHandlers(handlers: IncomingMcpHandlers): void;
     /** Write a serialised JSON-RPC object back to the peer. */
     protected abstract sendMessage(obj: unknown): void | Promise<void>;
     /** Allocate the next monotonic request id. */
     protected allocateId(): number;
+    /** Send a request that is NOT expected to answer promptly, and return its id.
+     *
+     *  `subscriptions/listen` (2026-07-28) is long-lived by design: the response arrives only when
+     *  the server tears the subscription down, while notifications flow in the meantime. Routing it
+     *  through `request()` would arm the normal timeout and kill a perfectly healthy subscription, so
+     *  no pending entry is registered — the eventual response is dropped, its only meaning being
+     *  "the stream ended".
+     *
+     *  The caller correlates frames itself via the returned id. Duplex transports (stdio, WebSocket)
+     *  support this; a request/response transport must override and reject. */
+    sendLongLivedRequest(method: string, params?: unknown, onEnd?: (error?: unknown) => void): Promise<number>;
+    /** Settle a long-lived request from its (late) response. Returns whether one was waiting. */
+    protected resolveLongLived(id: number | string, error?: unknown): boolean;
     /** Register a pending request and arm its timeout. */
     protected registerPending(id: number, resolve: (v: unknown) => void, reject: (e: unknown) => void, timeoutMs: number, method: string): void;
     /** Dispatch a parsed inbound message to the correct handler. */