@linxiraos/pi-ai 1.2.0 → 1.3.0

package/dist/types/error/classes.d.ts

@@ -47,7 +47,7 @@ export declare class AnthropicApiError extends ProviderHttpError {
 }
 /** Network-level failure (DNS, TLS, socket reset) after retries were exhausted. */
 export declare class AnthropicConnectionError extends Error {
-    constructor(cause: unknown);
+    constructor(cause: unknown, requestUrl?: string);
 }
 /** No response headers arrived within the configured request timeout. */
 export declare class AnthropicConnectionTimeoutError extends Error {

package/dist/types/error/flags.d.ts

@@ -68,10 +68,25 @@ export declare function isCodexSteerRejection(message: {
     api?: Api;
     errorMessage?: string;
 }): boolean;
+/**
+ * Transport-failure wording that marks an error transient. Covers
+ * diagnostics forwarded verbatim by gateways/proxies in other runtimes, e.g.
+ * undici's "other side closed" and Go's `net.ErrClosed` ("use of closed
+ * network connection", #15385). Also covers OMP's own network-failure
+ * sentences from `networkFailureMessage` (offline / unreachable / refused /
+ * TLS), which must stay at least as retryable as the bare `Connection error.`
+ * text they replaced.
+ */
 export declare const TRANSIENT_TRANSPORT_PATTERN: RegExp;
 export declare const ANTHROPIC_ACCOUNT_POLICY_PATTERN: RegExp;
 /** Whether an error message represents an Anthropic account-scoped permission/policy denial. */
 export declare function isAnthropicAccountPolicyText(text: string, provider?: string, statusArg?: number): boolean;
+/**
+ * Anthropic's rejection of a replayed latest assistant turn whose `thinking` or
+ * `redacted_thinking` blocks no longer verify. Resending the same turn fails the
+ * same way; only a request that changes that turn's reasoning can succeed.
+ */
+export declare function isImmutableLatestThinkingText(text: string): boolean;
 /**
  * Local llama.cpp / Ollama deterministic tool-call argument JSON parse failure.
  * The model emitted invalid JSON in a tool call and the server returned HTTP 500

package/dist/types/error/index.d.ts

@@ -8,6 +8,7 @@ export * from "./finalize.js";
 export * from "./flags.js";
 export * from "./format.js";
 export * from "./gateway.js";
+export * from "./network-cause.js";
 export * from "./oauth.js";
 export * from "./provider.js";
 export * from "./rate-limit.js";

package/dist/types/error/network-cause.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Local transport diagnosis for a rejected `fetch`.
+ *
+ * Bun and Node describe the same outage with different shapes — Bun throws a
+ * `TypeError` carrying `code: "ETIMEOUT" | "FailedToOpenSocket" |
+ * "ConnectionRefused"`, undici nests an `ENOTFOUND`/`ECONNREFUSED` errno under
+ * `TypeError: fetch failed` (sometimes through an `AggregateError`), and
+ * `fetchWithRetry` may already have flattened the chain into a message-only
+ * `Error`. Both the code and the text are inspected so every one of those
+ * shapes lands in the right bucket.
+ */
+/** Transport-level failure families that get their own user-visible wording. */
+export type NetworkFailureKind = "offline" | "unreachable" | "refused" | "tls";
+/** What {@link classifyNetworkCause} reports about a rejected `fetch`: the failure family plus the bits its sentence needs. */
+export interface NetworkFailure {
+    kind: NetworkFailureKind;
+    /** Runtime error code when the chain exposed one (`ETIMEOUT`, `FailedToOpenSocket`, …). */
+    code: string | undefined;
+    /** Short parenthetical detail for the user-visible message. */
+    detail: string | undefined;
+    /** Host named by the error text, when it named one. */
+    host: string | undefined;
+}
+/**
+ * Walk an error's `cause`/`errors` graph (bounded depth, cycle-safe) and report
+ * the outermost link that describes a local transport failure. Returns
+ * `undefined` for anything else, including HTTP-level provider errors.
+ */
+export declare function classifyNetworkCause(err: unknown): NetworkFailure | undefined;
+/**
+ * User-visible sentence for a network failure, or `undefined` when the error is
+ * not one. `requestUrl` wins over any host parsed out of the error text.
+ */
+export declare function networkFailureMessage(err: unknown, requestUrl?: string): string | undefined;
+/**
+ * Re-describe a rejected `fetch` with {@link networkFailureMessage}, keeping the
+ * original error as `cause`. Anything that is not a local transport failure is
+ * returned untouched, so provider/HTTP errors keep their identity.
+ */
+export declare function networkFailureError(err: unknown, requestUrl?: string): unknown;

package/dist/types/images/shared.d.ts

@@ -1,7 +1,8 @@
 import type { FetchImpl, Model, Usage } from "@linxiraos/pi-catalog/types";
 import type { ApiKey } from "../auth-retry.js";
 import * as AIError from "../error/index.js";
-import type { GeneratedImage } from "./types.js";
+import type { ImageContent } from "../types.js";
+import type { GeneratedImage, ImageInput } from "./types.js";
 export declare class ImageApiError extends AIError.ProviderHttpError {
     readonly name = "ImageApiError";
 }
@@ -38,6 +39,29 @@ export declare function decodeImageResponse(value: unknown, fetch: FetchImpl, si
  * multi-MB payloads are never fully decoded just to be labelled.
  */
 export declare function sniffBase64ImageMimeType(base64: string): string | undefined;
-export declare function toDataUrl(image: GeneratedImage): string;
+/**
+ * Validate provider-bound image input without changing it. Accepts non-empty standard base64
+ * with canonical trailing bits and optional padding, and case-insensitive image MIME syntax
+ * (RFC 6838 restricted names). Does not sniff the MIME type, decode image pixels, or enforce
+ * provider-specific format support; data-URL transports additionally go through `toDataUrl`.
+ *
+ * @throws {AIError.ValidationError} If the base64 data or image MIME type is invalid.
+ */
+export declare function validateImageInput(image: ImageInput): void;
+/**
+ * Encode validated image input as a base64 data URL.
+ *
+ * @throws {AIError.ValidationError} If the input is invalid or its MIME type cannot survive a data URL.
+ */
+export declare function toDataUrl(image: ImageInput): string;
+/**
+ * Whether a MIME type survives a data URL intact: a raw `#` starts a URL fragment and
+ * data-URL consumers leave a `%23` escape undecoded, so no data-URL transport preserves it.
+ */
+export declare function isDataUrlMimeType(mimeType: string): boolean;
+/** Whether a value is an embedded image with valid base64 data, MIME type, and detail. */
+export declare function isEmbeddedImageContent(image: unknown): image is ImageContent;
+/** Convert one validated embedded image to a lowercase-MIME inline data URL. */
+export declare function embeddedImageDataUrl(image: unknown): string;
 export declare function resolveOpenAIImageSize(aspectRatio?: string, imageSize?: string): string | undefined;
 export {};

package/dist/types/index.d.ts

@@ -64,6 +64,7 @@ export * from "./utils/anthropic-auth.js";
 export * from "./utils/event-stream.js";
 export * from "./utils/glyph-codec.js";
 export * from "./utils/openrouter-headers.js";
+export * from "./utils/narration.js";
 export * from "./utils/schema/index.js";
 export * from "./utils/thinking-loop.js";
 export * from "./utils/tool-call-loop-guard.js";

package/dist/types/judgment/native.d.ts

@@ -1,9 +1,32 @@
+/**
+ * Native judgment client: the {@link Judge} backend for catalog models whose
+ * API answers typed questions directly ({@link isJudgmentApi}).
+ *
+ * Each judgment API is one wire dialect: TypeSafe's System One route
+ * (`POST /v1/systemone`), OpenRouter Decisions (`POST /api/alpha/decisions`,
+ * same body), Cloudflare Workers AI (`POST /ai/run/{model}`, same body plus
+ * top-level data URL images; `systemone.ts`), and OpenAI Decisions
+ * (`POST /v1/decisions`, translated both ways; `openai-decisions.ts`).
+ * Credentials flow through {@link withAuth}, so a stored key rotates on
+ * 401/403 exactly like chat providers; transient 429/5xx responses retry with
+ * bounded, `retry-after`-aware backoff. Endpoints that cap the questions per
+ * request (the catalog's `judgment-questions-max`, e.g. OpenJEV at 16) get
+ * oversized requests split into chunks under `maxQuestions`, at most
+ * {@link CHUNK_PARALLEL} in flight at once.
+ *
+ * Environment (mirrors the official TypeSafe SDK, for judges built without an
+ * explicit model): `TYPESAFE_API_KEY` is resolved by the auth registry
+ * (`rules/auth/typesafe.kdl`), `TYPESAFE_BASE_URL` overrides the API root,
+ * `TYPESAFE_DEFAULT_MODEL` the model.
+ */
+import { type JudgmentImageInput } from "@linxiraos/pi-catalog/compat/judgment-images";
 import type { Api, FetchImpl } from "@linxiraos/pi-catalog/types";
 import { type ApiKey } from "../auth-retry.js";
 import * as AIError from "../error/index.js";
-import type { Model, Usage } from "../types.js";
+import type { ImageContent, Model, Usage } from "../types.js";
 import { type Judge, type JudgeOptions, type JudgmentRequest, type JudgmentResult, type Questions } from "./types.js";
-import type { JudgmentWire } from "./wire.js";
+import type { JudgmentImageAssets, JudgmentWire } from "./wire.js";
+export type { JudgmentImageAssets } from "./wire.js";
 export declare const TYPESAFE_PROVIDER = "typesafe";
 export declare const TYPESAFE_DEFAULT_MODEL = "jev-latest";
 declare const JUDGMENT_WIRES: {
@@ -16,6 +39,19 @@ declare const JUDGMENT_WIRES: {
 export type JudgmentApi = keyof typeof JUDGMENT_WIRES;
 /** Whether a catalog API answers judgments natively. */
 export declare function isJudgmentApi(api: Api): api is JudgmentApi;
+/** Whether both the native protocol and catalog model support image input. */
+export declare function nativeJudgmentSupportsImages(model: Model): boolean;
+/**
+ * Whether `model`'s native judgment API takes these exact images: image support plus every documented
+ * transport and catalog bound. A judge chain skips a candidate that would refuse them instead of failing on it.
+ */
+export declare function nativeJudgmentAcceptsImages(model: Model, images: readonly ImageContent[]): boolean;
+/**
+ * Reject images that `model`'s native judgment API cannot take — no image support, an unsupported or
+ * unreferenced asset, or a transport or catalog bound exceeded — before any credential or upstream work.
+ * @throws {AIError.ValidationError} naming the reason.
+ */
+export declare function checkNativeJudgmentImages(model: Model, request: JudgmentRequest, imageAssets?: JudgmentImageAssets): void;
 /** `TYPESAFE_BASE_URL` when set, else the public API root; trailing slashes stripped. */
 export declare function typesafeBaseUrl(): string;
 /** `TYPESAFE_DEFAULT_MODEL` when set, else {@link TYPESAFE_DEFAULT_MODEL}. */
@@ -43,9 +79,18 @@ export interface NativeJudgeOptions extends NativeJudgeConnection {
      * requests are split. Unset: no cap.
      */
     maxQuestions?: number;
+    /**
+     * Whether images are enabled for this judge. `false` disables image input; `true` enables
+     * dialects that require explicit opt-in but cannot enable a wire without image support.
+     */
+    supportsImages?: boolean;
+    /** Catalog-selected image bounds, applied in addition to the wire's transport constraints. */
+    imageInput?: JudgmentImageInput;
 }
 /** Per-call options for {@link NativeJudge.judge}. */
 export interface NativeJudgeCallOptions extends JudgeOptions {
+    /** Assets keyed by their existing references; wires without asset transport reject them. */
+    imageAssets?: JudgmentImageAssets;
     /**
      * Called before a split judgment rejects, with the summed usage of the chunks that had already
      * succeeded: billed upstream, but their answers are discarded with the failure. Not called when
@@ -60,6 +105,8 @@ export declare class JudgmentApiError extends AIError.ProviderHttpError {
 export declare class NativeJudge implements Judge {
     #private;
     readonly label: string;
+    /** True when the selected native wire and model or direct-call option permit image input. */
+    readonly supportsImages?: boolean;
     readonly api: JudgmentApi;
     readonly provider: string;
     /** Wire model id sent with every request. */
@@ -67,6 +114,8 @@ export declare class NativeJudge implements Judge {
     readonly baseUrl: string;
     constructor(options: NativeJudgeOptions);
     judge<Q extends Questions>(request: JudgmentRequest<Q>, options?: NativeJudgeCallOptions): Promise<JudgmentResult<Q>>;
+    /** Effective image detail for cache identity after applying this wire's forwarding behavior. */
+    effectiveImageDetail(detail: ImageContent["detail"]): ImageContent["detail"];
 }
 /**
  * The {@link NativeJudge} for a catalog judge model: its API's dialect, wire id
@@ -77,4 +126,3 @@ export declare class NativeJudge implements Judge {
  * @throws ConfigurationError when the model's API is not a judgment API.
  */
 export declare function createNativeJudge(model: Model, connection: NativeJudgeConnection): NativeJudge;
-export {};

package/dist/types/judgment/systemone.d.ts

@@ -1,7 +1,14 @@
-import { type JudgmentWire } from "./wire.js";
+import { type JudgmentRequest } from "./types.js";
+import { type JudgmentImageAssets, type JudgmentWire } from "./wire.js";
+/**
+ * The subset of `assets` that `request` references. TypeSafe substitutes a reference wherever it
+ * occurs as text in a string of `state`, a question's `instructions`, or its `criteria` (never in
+ * object keys) and rejects a request carrying an unreferenced asset.
+ */
+export declare function referencedImageAssets(request: JudgmentRequest, assets: JudgmentImageAssets): JudgmentImageAssets;
 /** TypeSafe's own route, shared by every System One server. */
 export declare const typesafeWire: JudgmentWire;
-/** OpenRouter Decisions: the System One body under `/api/alpha`. */
+/** OpenRouter Decisions: System One body under `/api/alpha`, with image parts preserved in state. */
 export declare const openrouterDecisionsWire: JudgmentWire;
 /** Cloudflare Workers AI decision models (Clef) through the account-scoped `ai/run` route. */
 export declare const workersAiWire: JudgmentWire;

package/dist/types/judgment/text.d.ts

@@ -1,8 +1,10 @@
-import type { Usage } from "../types.js";
+import type { ImageContent, Usage } from "../types.js";
 import { type Answer, type Judge, type JudgeOptions, type JudgmentRequest, type JudgmentResult, type JudgmentState, type Question, type Questions } from "./types.js";
 export interface TextPrompt {
     system: string;
     user: string;
+    /** Images are kept as distinct content blocks, never rendered into JSON text. */
+    images?: readonly ImageContent[];
     /** Format-correction attempt; chat backends may enforce tool suppression on the wire. */
     retry?: boolean;
 }
@@ -16,6 +18,8 @@ export interface TextBackend {
     readonly api: string;
     readonly provider: string;
     readonly model: string;
+    /** Whether this backend can send image content on the wire. */
+    readonly supportsImages?: boolean;
     /** State guard for agent-tuned chat models; on-device classifier workers may disable it. */
     readonly guardState?: boolean;
     /** Format-correction retries after a completion cannot be parsed. */
@@ -26,10 +30,11 @@ export interface TextBackend {
 export declare function renderJudgmentState(state: JudgmentState): string;
 /**
  * Render a request: the system prompt carries the preamble and question
- * definitions (constant across states, so prompt caches hit); the user message
- * carries XML-field state followed by the answer-format cue. Small models act
- * on a bare request (answer it, emit tool calls) instead of classifying it —
- * explicit tags and the trailing cue keep them on task.
+ * definitions (constant across states, so prompt caches hit); the user text
+ * carries XML-field state followed by the answer-format cue. Images remain
+ * separate content blocks. Small models act on a bare request (answer it,
+ * emit tool calls) instead of classifying it — explicit tags and the trailing
+ * cue keep them on task.
  */
 export declare function renderJudgmentPrompt(request: JudgmentRequest, options?: {
     guardState?: boolean;
@@ -53,6 +58,7 @@ export declare function splitAnswerLines(text: string, ids: readonly string[]):
 export declare function parseAnswer(id: string, question: Question, reply: string): Answer;
 export declare class TextJudge implements Judge {
     #private;
+    readonly supportsImages?: boolean;
     readonly label: string;
     constructor(backend: TextBackend);
     judge<Q extends Questions>(request: JudgmentRequest<Q>, options?: JudgeOptions): Promise<JudgmentResult<Q>>;

package/dist/types/judgment/types.d.ts

@@ -11,7 +11,7 @@
  * bridge ({@link TextJudge}) renders the same questions into keyword prompts
  * for an ordinary chat model.
  */
-import type { Usage } from "../types.js";
+import type { ImageContent, Usage } from "../types.js";
 /** JSON-compatible value; readonly containers are accepted so `as const` state passes through. */
 export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;
@@ -73,6 +73,8 @@ export type AnswerFor<Q extends Question> = Q extends ChoiceQuestion<infer L> ?
 export interface JudgmentRequest<Q extends Questions = Questions> {
     state: JudgmentState;
     questions: Q;
+    /** Images evaluated alongside the state; never part of the JSON state itself. */
+    images?: readonly ImageContent[];
 }
 export interface JudgmentResult<Q extends Questions = Questions> {
     /** Transport that produced the answers (a judgment api such as `typesafe`, or the chat model's api). */
@@ -89,6 +91,8 @@ export interface JudgeOptions {
 }
 /** Answers typed questions about a state. Implementations are stateless and safe to share. */
 export interface Judge {
+    /** Whether this backend can consume separate image content blocks. */
+    readonly supportsImages?: boolean;
     /** Backend description for logs, e.g. `typesafe/jev-latest`. */
     readonly label: string;
     judge<Q extends Questions>(request: JudgmentRequest<Q>, options?: JudgeOptions): Promise<JudgmentResult<Q>>;

package/dist/types/judgment/wire.d.ts

@@ -3,7 +3,8 @@
  * encodes, and decodes one request for each API it serves. Internal to the
  * judgment module; `native.ts` maps every judgment API to its dialect.
  */
-import type { Usage } from "../types.js";
+import type { ImageContent, Usage } from "../types.js";
+import type { JudgmentImageInput } from "@linxiraos/pi-catalog/compat/judgment-images";
 import type { JudgmentRequest } from "./types.js";
 /** Where one attempt posts and which bearer token it sends. */
 export interface JudgmentTarget {
@@ -20,6 +21,8 @@ export interface DecodedJudgment {
     refused: readonly string[];
     usage: Usage;
 }
+/** Image assets kept separately from judgment state for asset-aware native wires. */
+export type JudgmentImageAssets = Readonly<Record<string, ImageContent>>;
 /** How one judgment API addresses, encodes, and decodes a request. */
 export interface JudgmentWire {
     /**
@@ -27,8 +30,18 @@ export interface JudgmentWire {
      * Throws when the credential cannot address the endpoint (e.g. no account id).
      */
     target(baseUrl: string, model: string, key: string): JudgmentTarget;
-    /** Request body for `model`. */
-    encode(request: JudgmentRequest, model: string): unknown;
+    /** Request body for `model`, with optional asset context for dialects that preserve references. */
+    encode(request: JudgmentRequest, model: string, imageAssets?: JudgmentImageAssets): unknown;
+    /** Headers this dialect adds to requests that carry images. */
+    imageHeaders?: Readonly<Record<string, string>>;
+    /** Image input this dialect accepts; absent means text-only. */
+    images?: JudgmentImageInput;
+    /** Whether raw asset maps can be transported without loss by this dialect. */
+    supportsImageAssets?: boolean;
+    /** Whether image support must be enabled explicitly for direct NativeJudge construction. */
+    imagesRequireOptIn?: boolean;
+    /** Whether this wire drops per-image detail metadata. */
+    ignoresImageDetail?: boolean;
     /** The response's answers and usage; `undefined` when the payload is not this API's response shape. */
     decode(payload: unknown): DecodedJudgment | undefined;
 }

package/dist/types/provider-session-state.d.ts

@@ -18,8 +18,8 @@
  *   siblings are endpoint-scoped and stay: `strictToolsDisabled`
  *   (grammar-too-large 400 for the model's tool schema),
  *   `replayUnsignedThinkingDisabled` / `thinkingReplayDisabled` (the endpoint
- *   is a signing proxy), `prefixDroppedThinkingBlocks` (blocks a prefix-binding
- *   400 made the client strip).
+ *   is a signing proxy), `prefixDroppedThinkingBlocks` (blocks a rejected
+ *   replay made the client strip).
  * - **OpenAI Responses** — the `previous_response_id` chain baselines are
  *   account-scoped: a stored response belongs to the account that created it.
  *   Strict-tools / reasoning-effort fallbacks, replay warmup and the chaining

package/dist/types/providers/anthropic-images.d.ts

@@ -0,0 +1,7 @@
+import type { Context, Model } from "../types.js";
+/**
+ * Clamp every image a Claude reader would receive to the host's contract.
+ * Limits the model's policy leaves unset fall back to the canonical Anthropic
+ * API. Returns `context` itself when nothing needed resizing.
+ */
+export declare function prepareAnthropicImageContext(context: Context, model: Model<"anthropic-messages"> | Model<"google-gemini-cli">): Promise<Context>;

package/dist/types/providers/anthropic-signature.d.ts

@@ -1,14 +1,17 @@
 /**
- * Recovers the serving model id Anthropic embeds in thinking-block signatures.
+ * Reads the cleartext header Anthropic embeds in thinking-block signatures.
  *
  * A signature is a base64 protobuf: outer `{1: version, 2: envelope}`, envelope
  * `{1: header, 2..5: nonce/ciphertext/tag}`, header
- * `{1: schema, 5: hash, 6: model, 8: "thinking", 11: org uuid, 15: profile, 21: unix ts}`.
+ * `{1: schema, 5: hash, 6: model, 8: kind, 11: org uuid, 15: profile, 21: unix ts}`.
  * Field 6 names the model that actually produced the block — a concrete
  * snapshot (`claude-haiku-4-5-20251001`) or an internal codename
  * (`numbat-v6-…`) — which lets a caller notice a gateway serving something other
  * than the requested model. The v4 outer format (`CAQS…`) ships a header
  * without field 6; the decoder then yields nothing.
+ * Field 8 names the block kind: `thinking` for reasoning, `narration` for the
+ * user-facing prose the API converts into a thinking block when the model
+ * writes it between tool calls (connector-text summarization).
  */
 /**
  * Model id embedded in an Anthropic thinking signature, or undefined when the
@@ -16,6 +19,13 @@
  * nothing resembling a model id.
  */
 export declare function servedModelFromAnthropicSignature(signature: string): string | undefined;
+/**
+ * Whether an Anthropic thinking signature marks its block as narration: prose
+ * the model addressed to the user between tool calls, which the API returns as
+ * a thinking block. Only an exact `narration` kind matches; any other or
+ * unreadable header stays reasoning.
+ */
+export declare function isAnthropicNarrationSignature(signature: string): boolean;
 /**
  * Model id from an OpenRouter reasoning item — a `reasoning_details` entry on
  * chat completions or a Responses `reasoning` output item — which forwards the

package/dist/types/providers/anthropic-state.d.ts

@@ -7,6 +7,13 @@ export declare const ANTHROPIC_OPAQUE_CLIENT_ANCHOR_KEY = "anthropic-opaque-clie
 export declare function normalizeAnthropicBaseUrl(baseUrl?: string): string | undefined;
 /** Resolve the endpoint for a first-party Anthropic model without loading its provider implementation. */
 export declare function resolveDirectAnthropicBaseUrl(model: Model<Api>): string;
+/**
+ * Whether a request to `model` reaches the official endpoint its compat was built for. `compat.officialEndpoint`
+ * classifies the configured `baseUrl`, but a first-party Anthropic model is rerouted at request time by
+ * `ANTHROPIC_BASE_URL` or Foundry's `FOUNDRY_BASE_URL` without rebuilding compat. Gates official-only host
+ * limits such as the catalog's inline image byte and image count budgets.
+ */
+export declare function reachesOfficialEndpoint(model: Model<Api>): boolean;
 /** Build the endpoint-and-model-scoped Anthropic session-state key. */
 export declare function anthropicProviderSessionStateKey(baseUrl: string, modelId: string): string;
 /** Re-arm fast mode across materialized Anthropic session-state entries. */

package/dist/types/providers/anthropic.d.ts

@@ -1,5 +1,5 @@
 import type { Effort } from "@linxiraos/pi-catalog/effort";
-import type { AnthropicCompactionRequest, AnthropicOutputEffort, FetchImpl, Message, Model, ServiceTier, SimpleStreamOptions, StreamFunction, StreamOptions, Usage } from "../types.js";
+import type { AnthropicCompactionRequest, AnthropicOutputEffort, Api, FetchImpl, Message, Model, ServiceTier, SimpleStreamOptions, StreamFunction, StreamOptions, Usage } from "../types.js";
 import { type AnthropicFetchOptions, type AnthropicMessagesClientLike } from "./anthropic-client.js";
 import { type FallbackParam, type MessageParam, type TextBlockParam } from "./anthropic-wire.js";
 import { resolvesToOfficialAnthropicEndpoint, supportsAnthropicCompaction, supportsAnthropicCompactionOnClient } from "./anthropic-compaction.js";
@@ -118,7 +118,8 @@ export interface AnthropicOptions extends StreamOptions {
      * header is auto-attached; the response parser then honors mid-stream
      * `fallback` content blocks and `usage.iterations` for served-model
      * promotion and per-attempt pricing. Opt-in ONLY — leaving this
-     * undefined preserves the pre-fallback behavior on every code path.
+     * undefined sends neither and keeps both off; a `fallback` block in the
+     * response (a gateway opted in) is still persisted as a replay boundary.
      */
     fallbacks?: FallbackParam[];
 }
@@ -132,6 +133,8 @@ export type AnthropicClientOptionsArgs = {
     dynamicHeaders?: Record<string, string>;
     isOAuth?: boolean;
     hasTools?: boolean;
+    /** Whether a tool in ANTHROPIC_BUFFERED_INPUT_TOOLS is present; suppresses the request-wide fine-grained streaming beta. */
+    hasBufferedInputTools?: boolean;
     thinkingEnabled?: boolean;
     thinkingDisplay?: AnthropicThinkingDisplay;
     disableStrictTools?: boolean;
@@ -240,6 +243,17 @@ type SystemBlockOptions = {
 export declare function buildAnthropicSystemBlocks(systemPrompt: readonly string[] | undefined, options?: SystemBlockOptions): AnthropicSystemBlock[] | undefined;
 export declare function normalizeExtraBetas(betas?: string[] | string): string[];
 export declare function buildAnthropicClientOptions(args: AnthropicClientOptionsArgs): AnthropicClientOptionsResult;
+/**
+ * Warm-up target for a first-party `anthropic` model: the effective official
+ * API URL plus the TLS options real requests use (sockets pool per TLS
+ * configuration, so a warm-up made with other options is never reused).
+ * `undefined` when requests resolve elsewhere — `ANTHROPIC_BASE_URL` or
+ * Foundry gateways never receive unsolicited probes.
+ */
+export declare function resolveAnthropicPrewarmTarget(model: Model<Api>): {
+    url: string;
+    init: RequestInit;
+} | undefined;
 /**
  * True when enabled thinking on `model` is budget thinking
  * (`thinking.type: "enabled"` with `budget_tokens`) rather than adaptive.
@@ -283,10 +297,11 @@ export type AnthropicMessageParam = MessageParam;
  * Serialize zeta {@link Message}s to Anthropic wire messages.
  *
  * `opts.serverSideFallbackEnabled` — when the CURRENT request itself
- * opts into the server-side-fallback beta chain. Only then may a persisted
- * `fallback` content block from a prior turn be replayed on the wire;
- * otherwise the block is dropped to avoid a 400 on non-fallback requests
- * that don't send the beta.
+ * opts into the server-side-fallback beta chain. Only then, and only on the
+ * official endpoint, may a persisted `fallback` content block from a prior
+ * turn be replayed on the wire; otherwise the block is dropped to avoid a 400
+ * on requests that don't send the beta, and its turn keeps one model's
+ * reasoning (see {@link collapseFallbackSegments}).
  *
  * `opts.replayCompaction` — replay a user-role compaction summary that
  * carries an {@link AnthropicCompactionPayload} from this provider as a

package/dist/types/providers/connection-prewarm.d.ts

@@ -0,0 +1,15 @@
+import type { Api, FetchImpl, Model } from "../types.js";
+/**
+ * Opens, or keeps alive, a pooled connection to {@link model}'s API host so
+ * the next turn skips DNS + TCP + TLS. Sends a credential-less `HEAD` (nothing
+ * is billed; hosts answer 401/404/405) through the same transport — proxy,
+ * extra CA, Cowork profile, TLS options — as real requests, because sockets
+ * pool per transport configuration and a warm-up made any other way (e.g.
+ * `fetch.preconnect`, which also throws on Windows) is never reused.
+ * Throttled per origin; best effort, never throws.
+ */
+export declare function prewarmModelConnection(model: Model<Api>, options?: {
+    fetch?: FetchImpl;
+}): Promise<void>;
+/** Test hook: forgets every warm-up so the next call is not throttled. */
+export declare function resetConnectionPrewarmForTesting(): void;

package/dist/types/providers/cursor/exec-modern.d.ts

@@ -17,7 +17,7 @@ import type { ToolResultMessage } from "../../types.js";
  * virtual registry. Re-exported here because this is where the frame builders
  * and their translation are consumed together.
  */
-export { cursorExecReadPath, cursorRawReadPath, omitUndefinedArgs, piEscapeRegexLiteral, piGrepSkip, piJoinPath, piLimit, piLsPath, piReadDisplayPath, piReadPath, piReadPathHasRange, piTimeout, shellTimeoutSeconds, } from "../cursor-pi-args.js";
+export { cursorExecReadPath, cursorRawReadPath, omitUndefinedArgs, piEscapeRegexLiteral, piGrepSkip, piJoinPath, piLimit, piLsPath, piReadDisplayPath, piReadPath, piReadPathHasRange, piTimeout, shellDeadlineSeconds, shellTimeoutSeconds, } from "../cursor-pi-args.js";
 /** Flatten a tool result's content into the single `output` string the Pi frames carry. */
 export declare function piOutputText(toolResult: ToolResultMessage): string;
 /**

package/dist/types/providers/cursor-pi-args.d.ts

@@ -129,6 +129,19 @@ export declare function piTimeout(timeout: number | undefined): number | undefin
  * budgets round up: 0 seconds means "no deadline" to the bash tool.
  */
 export declare function shellTimeoutSeconds(timeoutMs: number | undefined): number | undefined;
+/**
+ * The bash-tool kill deadline, in seconds, for a Cursor `ShellArgs`/`ShellStreamArgs` frame.
+ *
+ * Cursor's `timeout` carries the model's `block_until_ms`, which Cursor's Shell tool documents as
+ * how long to block before moving the command to the background, not as a kill deadline; the kill
+ * deadline is `hard_timeout`. Without one, a short wait (`block_until_ms: 5000` on a build) must not
+ * kill the command: the deadline stays the bash default (`undefined`), raised to the wait only when
+ * the wait is longer.
+ */
+export declare function shellDeadlineSeconds(args: {
+    timeout: number;
+    hardTimeout?: number;
+}): number | undefined;
 /**
  * Drop keys whose value is `undefined` so optional local-tool kwargs stay
  * absent rather than present-as-undefined.

package/dist/types/providers/cursor.d.ts

@@ -218,6 +218,13 @@ export declare function mergeCursorMcpToolCallArgs(streamed: Record<string, unkn
  * call handed to an external executor is only a handoff while the marker is
  * absent, and the consumer that runs it needs a runnable block.
  *
+ * A frame whose `toolCallId` already has a block in `output` is the server
+ * re-dispatching that call (a new `execId`, e.g. a `read` re-sent once a
+ * parallel shell created the file). It adds no block: a second block with the
+ * same id makes every rebuilt history replay the call twice, which Cursor
+ * rejects (issue #15749). The re-run's result supersedes the first one in the
+ * host's result buffer.
+ *
  * Exported for tests to exercise ordering with adjacent text/thinking blocks.
  */
 export declare function synthesizeCursorExecToolCall(output: AssistantMessage, stream: AssistantMessageEventStream, state: BlockState, toolCallId: string, toolName: string, args: Record<string, unknown>, { executed }?: {

package/dist/types/providers/openai-codex-responses.d.ts

@@ -6,6 +6,12 @@ export type { CodexAttestationProvider } from "./openai-codex-attestation.js";
 import type { ResponseInput } from "./openai-responses-wire.js";
 export interface OpenAICodexResponsesOptions extends StreamOptions {
     reasoning?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+    /**
+     * Run with the least reasoning the model allows; takes precedence over
+     * `reasoning`. Sends the `none` tier where the catalog's disable mode is
+     * `none-effort`, else the model's lowest supported effort.
+     */
+    disableReasoning?: boolean;
     reasoningSummary?: "auto" | "concise" | "detailed" | null;
     /** Explicit `reasoning.context` replay scope. Omitted by default so Codex applies its native request policy. */
     reasoningContext?: CodexReasoningContext;

package/dist/types/providers/openai-responses.d.ts

@@ -114,6 +114,15 @@ interface OpenAIResponsesChainState {
     /** Set once chaining is judged unsupported for this session (circuit breaker). */
     disabled: boolean;
 }
+/**
+ * Whether the next request for `model` replays native Responses history items
+ * (encrypted reasoning, item ids), as {@link buildParams} decides it. A session
+ * is cold, rebuilding turns from message content, from the first request on a
+ * connection-bound host (`compat.connectionBoundNativeHistory`, GitHub Copilot)
+ * and after `close()` on any host, until a response succeeds. Without session
+ * state every request replays.
+ */
+export declare function openAIResponsesReplaysNativeHistory(model: Pick<Model, "api" | "provider" | "compat"> | null | undefined, providerSessionState: Map<string, ProviderSessionState> | undefined): boolean;
 /**
  * Set the process-wide storage default per provider id, used when a request
  * leaves `storeResponses` unset. Hosts call this from their settings so every

package/dist/types/providers/openai-shared.d.ts

@@ -399,6 +399,22 @@ interface StrictToolsRetryContext {
     strictToolsApplied: boolean;
     tools: Tool[] | undefined;
 }
+/**
+ * Read OpenRouter's `error.metadata.raw` from a captured non-2xx body.
+ *
+ * OpenRouter routes to a different upstream per request, so its top-level
+ * `error.message` is a generic policy sentence ("Access denied by security
+ * policy") and the only place the routed provider's own words appear is
+ * `error.metadata.raw`. Providers that proxy through OpenRouter also hang the
+ * upstream provider name there.
+ *
+ * The detail lives in the decoded body captured on the thrown
+ * {@link AIError.OpenAIHttpError}, not on the error object itself: no error
+ * class in this package carries an `error` property, so reading
+ * `error.error.metadata.raw` unconditionally yielded `undefined` and the
+ * upstream detail was dropped from every surfaced message.
+ */
+export declare function readOpenRouterRawMetadata(capturedErrorResponse: CapturedHttpErrorResponse | undefined): string | undefined;
 /** Decide whether an OpenAI-family request should retry once with non-strict tools. */
 export declare function shouldRetryWithoutStrictTools(error: unknown, capturedErrorResponse: CapturedHttpErrorResponse | undefined, context: StrictToolsRetryContext): boolean;
 export declare const OPENAI_RESPONSES_PROGRESS_EVENT_TYPES: ReadonlySet<string>;
@@ -525,6 +541,20 @@ export interface BuildResponsesInputOptions<TApi extends Api> {
  * Callers gate on {@link isHarmonyDialectModel}. Items are copied, not mutated.
  */
 export declare function escapeReplayedControlTokens(items: ResponseInput): ResponseInput;
+/**
+ * Whether a same-provider assistant turn may replay its native items while the
+ * provider session is still cold (#489). A cold session rebuilds turns from
+ * message content because some backends bind native items to one connection
+ * (GitHub Copilot: `401 input item does not belong to this connection`, #488).
+ * Binding needs server-issued state that survives replay sanitization: an
+ * `encrypted_content` blob or an item id. A turn with neither, whose every
+ * reasoning item carries plaintext `reasoning_text`, has nothing to bind and is
+ * exactly what the server receives once the session warms; rebuilding it would
+ * drop that reasoning and change the prompt prefix the server cached.
+ * Summary-only reasoning keeps the rebuild: it is no evidence of a server that
+ * returns plaintext reasoning.
+ */
+export declare function isColdReplayableResponsesTurn(items: ResponseInput): boolean;
 export declare function buildResponsesInput<TApi extends Api>(options: BuildResponsesInputOptions<TApi>): ResponseInput;
 /**
  * Non-empty `reasoning_text` shipped for a synthesized reasoning item when no