@linxiraos/pi-ai 1.0.0

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

@@ -0,0 +1,15 @@
+import type { DialectDefinition, InbandScanEvent, InbandScanner, InbandScannerOptions } from "./types.js";
+export declare const ANTHROPIC_THINKING_TAG_PREFIXES: readonly ["<thinking", "</thinking", "<think", "</think", "<scratchpad", "</scratchpad", "<antml:thinking", "</antml:thinking", "<antml:think", "</antml:think", "<antml:scratchpad", "</antml:scratchpad"];
+export interface AnthropicInbandScannerConfig {
+    readonly wrapperTags?: Readonly<Record<string, true>>;
+    readonly baseTagPrefixes?: readonly string[];
+    readonly allTagPrefixes?: readonly string[];
+}
+export declare class AnthropicInbandScanner implements InbandScanner {
+    #private;
+    constructor(options?: InbandScannerOptions, config?: AnthropicInbandScannerConfig);
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const definition: DialectDefinition;
+export default definition;

package/dist/types/dialect/catalog.d.ts

@@ -0,0 +1,3 @@
+import type { Dialect, InbandTool } from "./types.js";
+export declare function renderToolCatalog(tools: readonly InbandTool[]): string;
+export declare function renderInbandToolPrompt(tools: readonly InbandTool[], dialect: Dialect): string;

package/dist/types/dialect/coercion.d.ts

@@ -0,0 +1,23 @@
+import type { InbandTool } from "./types.js";
+export interface ToolArgShape {
+    stringArgs: Set<string>;
+    properties: Record<string, unknown>;
+    parameterOrder: string[];
+}
+export declare function buildArgShapes(tools?: readonly InbandTool[]): Map<string, ToolArgShape>;
+export declare function buildStringArgsResolver(tools?: readonly InbandTool[]): (toolName: string) => ReadonlySet<string>;
+export declare function resolveToolSchema(tool: InbandTool): Record<string, unknown>;
+export declare function isStringOnlySchema(schema: unknown): boolean;
+export declare function collectSchemaTypes(schema: unknown, out?: Set<string>, depth?: number): Set<string>;
+export declare function jsonTypeOf(value: unknown): string;
+export declare function decodeValue(raw: string): unknown;
+export declare function coerceValue(raw: string, schema: unknown): unknown;
+export declare function isArraySchema(schema: unknown): boolean;
+export declare function isObjectSchema(schema: unknown): boolean;
+export declare function getObjectProperties(schema: unknown): Record<string, unknown>;
+export declare function getArrayItemSchema(schema: unknown): unknown;
+export declare function mintToolCallId(): string;
+export declare function partialSuffixOverlap(text: string, tag: string): number;
+export declare function partialSuffixOverlapAny(text: string, tags: readonly string[]): number;
+export declare function normalizeKimiFunctionName(rawId: string): string;
+export declare function asRecord(value: unknown): Record<string, unknown>;

package/dist/types/dialect/deepseek.d.ts

@@ -0,0 +1,14 @@
+import type { DialectDefinition, InbandScanEvent, InbandScanner, InbandScannerOptions } from "./types.js";
+export declare const DEEPSEEK_TOOL_CALLS_BEGIN = "<\uFF5Ctool\u2581calls\u2581begin\uFF5C>";
+export declare const DEEPSEEK_TOOL_CALLS_END = "<\uFF5Ctool\u2581calls\u2581end\uFF5C>";
+export declare const DEEPSEEK_TOOL_CALL_BEGIN = "<\uFF5Ctool\u2581call\u2581begin\uFF5C>";
+export declare const DEEPSEEK_TOOL_CALL_END = "<\uFF5Ctool\u2581call\u2581end\uFF5C>";
+export declare const DEEPSEEK_TOOL_SEPARATOR = "<\uFF5Ctool\u2581sep\uFF5C>";
+export declare class DeepSeekInbandScanner implements InbandScanner {
+    #private;
+    constructor(options?: InbandScannerOptions);
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const definition: DialectDefinition;
+export default definition;

package/dist/types/dialect/demotion.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Wrap a prior-turn reasoning string for demotion into native conversation
+ * history — the cross-provider / cross-model case where the target cannot
+ * replay it as a structured thinking block (verified end-to-end against Gemini
+ * 3: a replayed unsigned `thought` part is schema-accepted but silently
+ * discarded — neither recalled nor influencing generation).
+ *
+ * The Anthropic/Claude dialect is the primary exception: Anthropic's
+ * `reasoning_extraction` classifier blocks requests that replay prior
+ * reasoning inside `<thinking>` / `antml:thinking` tags — it reads the
+ * wrapped chain-of-thought as an attempt to duplicate model outputs and
+ * refuses (Fable) or leaks it as visible reasoning (Opus / Sonnet / Haiku /
+ * Mythos). Every Anthropic-dialect Claude model therefore receives prior
+ * reasoning as bare assistant prose: no tag, no wrapper, no trailing newline.
+ * Heat is cumulative (block count and early-conversation position also raise
+ * it), so this lowers per-block signal but does not license unbounded replay.
+ *
+ * Harmony and Gemma are the other exceptions: their `renderThinking` emits
+ * chat-template control tokens (`<|channel|>analysis`, `<|channel>thought`)
+ * that must not appear inside a structured native message, so they fall back
+ * to a plain `<think>` block. Every other dialect's thinking form is
+ * inline-safe XML tags or a markdown fence.
+ *
+ * The result does not append a delimiter; callers that flatten adjacent blocks
+ * into a single string must insert their own separator.
+ *
+ * Distinct from {@link DialectDefinition.renderThinking}, which targets the
+ * owned-dialect *text transport* where those control tokens are legal.
+ */
+export declare function renderDemotedThinking(modelId: string, text: string): string;

package/dist/types/dialect/examples.d.ts

@@ -0,0 +1,18 @@
+import type { InbandTool } from "./types.js";
+/**
+ * Render a tool's examples as an `<examples>` block. Calls render in Python
+ * keyword-argument syntax (`name(key="value", n=1)`) regardless of the model's
+ * tool-call dialect, so example bytes stay identical across models. Multiline
+ * string args render as verbatim `"""…"""` blocks, and a call whose only
+ * argument is a string renders as the bare value — the block already names the
+ * tool, and payload args (commands, code, patches) read best verbatim.
+ */
+export declare function renderToolExamples(tool: InbandTool, intentField?: string): string;
+/**
+ * Render a tool's examples as JSDoc-style `@example` lines for comment-gutter
+ * contexts (the Harmony `namespace functions` inventory): `@example "caption"`
+ * followed by the call in the same Python kwargs syntax as the wire block. The
+ * tag line delimits each example, so no XML envelope is needed — which is why
+ * the inventory uses this instead of `//`-prefixing the `<examples>` block.
+ */
+export declare function renderToolExamplesJsdoc(tool: InbandTool): string;

package/dist/types/dialect/factory.d.ts

@@ -0,0 +1,3 @@
+import type { Dialect, DialectDefinition, InbandScanner, InbandScannerOptions } from "./types.js";
+export declare function getDialectDefinition(dialect: Dialect): DialectDefinition;
+export declare function createInbandScanner(dialect: Dialect, options?: InbandScannerOptions): InbandScanner;

package/dist/types/dialect/fenced-thinking.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Close-matcher for a ` ```thinking ` block that respects nested Markdown code
+ * fences. A naive `indexOf("```")` closes the thinking section at the FIRST
+ * backtick fence inside the reasoning, so an inner ` ```rs … ``` ` code block
+ * leaks its body (and everything after) into the visible channel. This scanner
+ * tracks inner-fence nesting so only the real thinking closer ends the block.
+ *
+ * Distinguishing an inner opener from the closer: a fenced code block opener is
+ * ` ``` ` immediately followed by a language token (`rs`, `tool_code`, `c++` …)
+ * and a newline. The thinking closer is a bare ` ``` `, or ` ``` ` glued to the
+ * visible reply — its remainder is prose (contains whitespace/punctuation), not
+ * a language token. So a top-level fence whose info is a single language-token
+ * word opens a nested block; anything else closes the thinking, and the text
+ * after the fence run is the visible reply. This preserves the long-standing
+ * inline-close behavior (` ```Visible reply ` ends the block) while skipping
+ * language-tagged inner fences.
+ *
+ * Used by both the owned Gemini scanner (live ` ```thinking ` stream) and the
+ * generic `ThinkingInbandScanner` (leaked-idiom healing).
+ *
+ * Limitation: an *info-less* nested fence (a bare ` ``` ` opening a code block
+ * inside the reasoning) is indistinguishable from the thinking closer and ends
+ * the block. Models tag their fences with a language in practice, so this is
+ * strictly better than the previous first-` ``` ` behavior.
+ */
+/** Result of feeding bytes to {@link FencedThinkingScanner}. */
+export interface FencedThinkingResult {
+    /** Thinking text to emit for this feed (may be empty). */
+    readonly thinking: string;
+    /** True once the thinking closer has been consumed. */
+    readonly closed: boolean;
+    /** Bytes after the closing fence (visible reply); only meaningful when {@link closed}. */
+    readonly rest: string;
+}
+/**
+ * Stateful, line-oriented close-matcher for one ` ```thinking ` block. Owns the
+ * partial-line buffer so an ambiguous trailing fence is held until it resolves.
+ *
+ * Streaming stays character-level for ordinary content: a line is emitted as its
+ * bytes arrive, yet retained in the buffer until its newline so the complete
+ * line can be classified ({@link #emitted} tracks how many leading bytes are
+ * already emitted). A top-level fence candidate is held until its info
+ * disambiguates opener (language token) from closer (prose / bare).
+ */
+export declare class FencedThinkingScanner {
+    #private;
+    /**
+     * Feed bytes and return thinking deltas plus close state. When `final`, the
+     * held tail resolves: a bare ` ``` ` or a ` ```<reply> ` fence closes the
+     * block (remainder becomes `rest`), otherwise it is unterminated thinking.
+     */
+    feed(text: string, final: boolean): FencedThinkingResult;
+}

package/dist/types/dialect/gemini.d.ts

@@ -0,0 +1,17 @@
+import type { DialectDefinition, InbandScanEvent, InbandScanner, InbandScannerOptions } from "./types.js";
+/**
+ * Scanner for the hosted-Gemini / Gemma 3 Pythonic tool-calling convention
+ * (see `docs/toolconv/gemini.md`). Tool calls arrive as a ```` ```tool_code ````
+ * fenced block whose body is one or more Python call expressions, e.g.
+ * `print(default_api.search(pattern="x", skip=40))`. Like the qwen3 scanner we
+ * buffer the whole block until its closing fence, then parse all calls at once
+ * (no incremental argument deltas — Python literals are not worth streaming).
+ */
+export declare class GeminiInbandScanner implements InbandScanner {
+    #private;
+    constructor(options?: InbandScannerOptions);
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const definition: DialectDefinition;
+export default definition;

package/dist/types/dialect/gemma.d.ts

@@ -0,0 +1,15 @@
+import type { DialectDefinition, InbandScanEvent, InbandScanner, InbandScannerOptions } from "./types.js";
+/**
+ * Scanner for the Gemma 4 token-delimited tool-calling convention (see
+ * `docs/toolconv/gemma.md`). Each call is one `<|tool_call>call:NAME{…}<tool_call|>`
+ * block whose argument list is `key:value` pairs; string values are wrapped in
+ * the `<|"|>` token rather than ASCII quotes, so splitting must skip those spans.
+ */
+export declare class GemmaInbandScanner implements InbandScanner {
+    #private;
+    constructor(options?: InbandScannerOptions);
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const definition: DialectDefinition;
+export default definition;

package/dist/types/dialect/glm.d.ts

@@ -0,0 +1,9 @@
+import type { DialectDefinition, InbandScanEvent, InbandScanner, InbandScannerOptions } from "./types.js";
+export declare class GLMInbandScanner implements InbandScanner {
+    #private;
+    constructor(options?: InbandScannerOptions);
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const definition: DialectDefinition;
+export default definition;

package/dist/types/dialect/harmony.d.ts

@@ -0,0 +1,8 @@
+import type { DialectDefinition, InbandScanEvent, InbandScanner } from "./types.js";
+export declare class HarmonyInbandScanner implements InbandScanner {
+    #private;
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const definition: DialectDefinition;
+export default definition;

package/dist/types/dialect/hermes.d.ts

@@ -0,0 +1,9 @@
+import type { DialectDefinition, InbandScanEvent, InbandScanner, InbandScannerOptions } from "./types.js";
+export declare class HermesInbandScanner implements InbandScanner {
+    #private;
+    constructor(options?: InbandScannerOptions);
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const definition: DialectDefinition;
+export default definition;

package/dist/types/dialect/history.d.ts

@@ -0,0 +1,3 @@
+import type { Context } from "../types.js";
+import type { Dialect, InbandTool } from "./types.js";
+export declare function encodeInbandToolHistory(messages: Context["messages"], dialect: Dialect, tools?: readonly InbandTool[]): Context["messages"];

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

@@ -0,0 +1,11 @@
+export * from "./catalog.js";
+export * from "./coercion.js";
+export * from "./demotion.js";
+export * from "./examples.js";
+export * from "./factory.js";
+export * from "./history.js";
+export * from "./inventory.js";
+export * from "./owned-stream.js";
+export { renderDelimitedThinking } from "./rendering.js";
+export * from "./thinking.js";
+export * from "./types.js";

package/dist/types/dialect/inventory.d.ts

@@ -0,0 +1,9 @@
+import type { InbandTool } from "./types.js";
+/**
+ * Tool catalog in the OpenAI-Harmony `namespace functions { … }` shape: each
+ * tool renders as its full description (and Python-syntax examples) as `//`
+ * comment lines above a flat `type <name> = (_: {…});` declaration. Shared by
+ * the verbose system-prompt inventory and `/dump` so both render the catalog
+ * the same way.
+ */
+export declare function renderToolInventory(tools: readonly InbandTool[]): string;

package/dist/types/dialect/kimi.d.ts

@@ -0,0 +1,14 @@
+import type { DialectDefinition, InbandScanEvent, InbandScanner, InbandScannerOptions } from "./types.js";
+export declare const KIMI_SECTION_BEGIN = "<|tool_calls_section_begin|>";
+export declare const KIMI_SECTION_END = "<|tool_calls_section_end|>";
+export declare const KIMI_CALL_BEGIN = "<|tool_call_begin|>";
+export declare const KIMI_CALL_END = "<|tool_call_end|>";
+export declare const KIMI_ARG_BEGIN = "<|tool_call_argument_begin|>";
+export declare class KimiInbandScanner implements InbandScanner {
+    #private;
+    constructor(options?: InbandScannerOptions);
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const definition: DialectDefinition;
+export default definition;

package/dist/types/dialect/minimax.d.ts

@@ -0,0 +1,3 @@
+import type { DialectDefinition } from "./types.js";
+declare const definition: DialectDefinition;
+export default definition;

package/dist/types/dialect/owned-stream.d.ts

@@ -0,0 +1,4 @@
+import type { AssistantMessage, AssistantMessageEventStream as AssistantMessageEventStreamType } from "../types.js";
+import type { Dialect, InbandTool } from "./types.js";
+export declare function parseInbandToolMessage(message: AssistantMessage, dialect: Dialect, tools: readonly InbandTool[]): AssistantMessage;
+export declare function wrapInbandToolStream(inner: AssistantMessageEventStreamType, tools: readonly InbandTool[], dialect: Dialect, onAbort?: () => void, abortOnFabrication?: boolean): AssistantMessageEventStreamType;

package/dist/types/dialect/qwen3.d.ts

@@ -0,0 +1,9 @@
+import type { DialectDefinition, InbandScanEvent, InbandScanner, InbandScannerOptions } from "./types.js";
+export declare class Qwen3InbandScanner implements InbandScanner {
+    #private;
+    constructor(options?: InbandScannerOptions);
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const definition: DialectDefinition;
+export default definition;

package/dist/types/dialect/rendering.d.ts

@@ -0,0 +1,54 @@
+import type { AssistantMessage, Message, ToolCall } from "../types.js";
+import type { DialectRenderOptions, DialectToolResult } from "./types.js";
+export declare function renderToolResponseResults(results: readonly DialectToolResult[]): string;
+export declare function kimiCallId(name: string, id: string, index: number): string;
+export declare function harmonyRecipient(name: string): string;
+export declare function stringifyJson(value: unknown): string;
+/**
+ * Render `name(key=value, …)` with Python-literal argument values. Top-level
+ * multiline strings render as verbatim `"""…"""` blocks so payload-carrying
+ * args (file content, scripts, patches) keep real newlines instead of `\n`
+ * escape soup; nested values always use escaped single-line literals.
+ */
+export declare function pyCall(name: string, args: Record<string, unknown>): string;
+/** Render a JSON-ish value as a Python literal (`True`/`False`/`None`, escaped strings, lists, dicts). */
+export declare function pyValue(value: unknown): string;
+export declare function escapeXmlAttr(value: string): string;
+export declare function escapeXmlText(value: string): string;
+export type AssistantTranscriptParts = {
+    readonly text: string;
+    readonly thinking: string;
+    readonly toolCalls: readonly ToolCall[];
+};
+export type ToolCallRenderer = (calls: readonly ToolCall[], options?: DialectRenderOptions) => string;
+export type ToolResultRenderer = (results: readonly DialectToolResult[], options?: DialectRenderOptions) => string;
+export type ChatMlTranscriptConfig = {
+    readonly bos?: string;
+    readonly toolResultRole: "tool" | "user";
+    readonly renderThinking: (text: string) => string;
+    readonly renderCalls: ToolCallRenderer;
+    readonly renderResultsBody: ToolResultRenderer;
+};
+export type LegacyTextTranscriptConfig = {
+    readonly renderThinking: (text: string) => string;
+    readonly renderCalls: ToolCallRenderer;
+    readonly renderResults: ToolResultRenderer;
+};
+export declare function renderChatMlTranscript(messages: readonly Message[], options: DialectRenderOptions, config: ChatMlTranscriptConfig): string;
+export declare function renderLegacyTextTranscript(messages: readonly Message[], options: DialectRenderOptions, config: LegacyTextTranscriptConfig): string;
+export declare function assistantTranscriptParts(message: AssistantMessage): AssistantTranscriptParts;
+export declare function collectToolResultRun(messages: readonly Message[], start: number): {
+    readonly results: readonly DialectToolResult[];
+    readonly next: number;
+};
+export declare function messageContentText(content: string | readonly {
+    readonly type: string;
+    readonly text?: string;
+    readonly mimeType?: string;
+}[]): string;
+export declare function renderDelimitedThinking(open: string, close: string, text: string): string;
+export declare function chatMlTurn(role: "assistant" | "system" | "tool" | "user", body: string): string;
+export declare function kimiTurn(role: "assistant" | "system" | "user", name: string, body: string): string;
+export declare function gemmaTurn(role: "model" | "system" | "user", body: string): string;
+export declare function geminiTurn(role: "model" | "user", body: string): string;
+export declare function joinUserBodies(left: string, right: string): string;

package/dist/types/dialect/thinking.d.ts

@@ -0,0 +1,6 @@
+import type { InbandScanEvent, InbandScanner } from "./types.js";
+export declare class ThinkingInbandScanner implements InbandScanner {
+    #private;
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}

package/dist/types/dialect/types.d.ts

@@ -0,0 +1,68 @@
+import type { Dialect as CatalogDialect } from "@linxiraos/pi-catalog/identity";
+import type { Context, Message, ToolCall } from "../types.js";
+export type { Dialect } from "@linxiraos/pi-catalog/identity";
+export type InbandScanEvent = {
+    type: "text";
+    text: string;
+} | {
+    type: "thinkingStart";
+} | {
+    type: "thinkingDelta";
+    delta: string;
+} | {
+    type: "thinkingEnd";
+    thinking: string;
+} | {
+    type: "toolStart";
+    id: string;
+    name: string;
+} | {
+    type: "toolArgDelta";
+    id: string;
+    name: string;
+    key: string;
+    delta: string;
+} | {
+    type: "toolEnd";
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    rawBlock?: string;
+};
+export interface InbandScanner {
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+export interface DialectToolResult {
+    readonly id: string;
+    readonly name: string;
+    readonly index: number;
+    readonly text: string;
+    readonly isError: boolean;
+}
+export interface DialectRenderOptions {
+    readonly tools?: readonly InbandTool[];
+}
+export interface DialectDefinition {
+    readonly dialect: CatalogDialect;
+    readonly prompt: string;
+    createScanner(options?: InbandScannerOptions): InbandScanner;
+    /** Render a single tool-call invocation — the inner element only, WITHOUT any parallel-call block envelope (e.g. anthropic's `<function_calls>` / kimi's section wrapper). */
+    renderToolCall(call: ToolCall, options?: DialectRenderOptions): string;
+    /** Render a batch of (parallel) tool calls as one complete block, including whatever envelope the dialect wraps multiple calls in. */
+    renderAssistantToolCalls(calls: readonly ToolCall[], options?: DialectRenderOptions): string;
+    renderToolResults(results: readonly DialectToolResult[], options?: DialectRenderOptions): string;
+    renderThinking(text: string): string;
+    renderTranscript(messages: readonly Message[], options?: DialectRenderOptions): string;
+}
+export interface InbandScannerOptions {
+    /** string-typed arg names for a tool → read verbatim. Ignored by JSON-carrying dialects. */
+    stringArgs?: (toolName: string) => ReadonlySet<string>;
+    /** Full tool schemas for schema-driven dialects such as GLM XML and pi-native. */
+    tools?: readonly InbandTool[];
+    /** XML only: parse pipe-wrapped DeepSeek DSML tags vs plain Anthropic invoke/parameter tags. */
+    xmlTagset?: "anthropic" | "dsml";
+    /** Emit thinking markers as thinking events instead of visible text when the dialect defines them. */
+    parseThinking?: boolean;
+}
+export type InbandTool = NonNullable<Context["tools"]>[number];

package/dist/types/dialect/xml.d.ts

@@ -0,0 +1,9 @@
+import type { DialectDefinition, InbandScanEvent, InbandScanner, InbandScannerOptions } from "./types.js";
+export declare class XmlInbandScanner implements InbandScanner {
+    #private;
+    constructor(options?: InbandScannerOptions);
+    feed(text: string): InbandScanEvent[];
+    flush(): InbandScanEvent[];
+}
+declare const definition: DialectDefinition;
+export default definition;

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

@@ -0,0 +1,14 @@
+/**
+ * A request was cancelled — by the caller's `AbortSignal` or a provider-local
+ * watchdog. Carries the {@link Flag.Abort} classification structurally so retry
+ * logic does not have to regex the message text.
+ *
+ * The default message is kept byte-identical to the historical
+ * `"Request was aborted"` string so any remaining text-based matchers keep
+ * working through the migration.
+ */
+export declare class AbortError extends Error {
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}

package/dist/types/error/auth-classify.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Whether an OAuth refresh failure is definitive (the credential must be
+ * disabled) versus transient. Thin alias over the {@link Flag.OAuthExpiry}
+ * text classifier {@link isOAuthExpiry}; retained as the public
+ * `@linxiraos/pi-ai` entrypoint name used by the coding agent and auth-broker.
+ */
+export declare function isDefinitiveOAuthFailure(errorMsg: string): boolean;
+/** Whether an upstream response explicitly says the supplied OAuth bearer was invalidated. */
+export declare function isInvalidatedOAuthTokenError(error: unknown): boolean;
+/**
+ * Whether an upstream failure should rotate to a sibling credential: a hard
+ * `401`, a `403` (token valid but access denied — plan, model policy, or org
+ * restriction a sibling account may not share), a body-classified usage limit
+ * (Codex `usage_limit_reached`, Anthropic account rate-limit, Google
+ * `resource_exhausted`, OpenAI `insufficient_quota`, …), or a bare `429`
+ * whose payload did not preserve a richer quota code.
+ * Transient 429s (`Too many requests`, per-minute caps) stay in the
+ * upstream-backoff lane.
+ */
+export declare function isAuthRetryableError(error: unknown): boolean;

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

@@ -0,0 +1,27 @@
+/**
+ * No API key / credential was available to dispatch a request.
+ *
+ * The default message preserves the historical `"No API key for provider: X"`
+ * wording, which {@link Flag.AuthFailed}'s regex (`no api key`) keys off — but
+ * the flag is also attached structurally so classification never depends on the
+ * exact phrasing.
+ */
+export declare class MissingApiKeyError extends Error {
+    readonly provider: string | undefined;
+    constructor(provider?: string, message?: string);
+}
+/** A user-facing login flow required an `onPrompt` callback that was not supplied. */
+export declare class OnPromptRequiredError extends Error {
+    constructor(providerLabel: string);
+}
+/** An interactive login asked for an API key but the user supplied an empty value. */
+export declare class ApiKeyRequiredError extends Error {
+    constructor(message?: string);
+}
+/**
+ * A user cancelled an interactive login / device flow. Classified as an abort
+ * so it is never surfaced as a retryable transient failure.
+ */
+export declare class LoginCancelledError extends Error {
+    constructor(message?: string);
+}

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

@@ -0,0 +1,27 @@
+/** Which AWS credential-resolution path failed. */
+export type AwsCredentialsErrorKind = 
+/** No usable credential source resolved (chain exhausted). */
+"resolution"
+/** SSO cache token missing (`aws sso login` not run). */
+ | "sso-token-missing"
+/** SSO cache token present but expired. */
+ | "sso-token-expired"
+/** SSO `GetRoleCredentials` call failed or returned no role. */
+ | "sso-role"
+/** External `credential_process` failed, timed out, or emitted bad output. */
+ | "credential-process"
+/** STS web-identity exchange failed or returned malformed credentials. */
+ | "web-identity"
+/** ECS/container credential endpoint failed or returned malformed credentials. */
+ | "container";
+/** A failure resolving AWS credentials for the Bedrock provider. */
+export declare class AwsCredentialsError extends Error {
+    readonly kind: AwsCredentialsErrorKind;
+    constructor(message: string, kind: AwsCredentialsErrorKind, options?: {
+        cause?: unknown;
+    });
+}
+/** A malformed AWS event-stream frame (bad length, CRC mismatch, unknown header type). */
+export declare class EventStreamFrameError extends Error {
+    constructor(detail: string);
+}

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

@@ -0,0 +1,106 @@
+import type { CapturedHttpErrorResponse } from "../utils/http-inspector.js";
+/** Prefix on errors raised when an Anthropic SSE stream envelope is malformed. */
+export declare const STREAM_ENVELOPE_ERROR_PREFIX = "Anthropic stream envelope error:";
+/** Structured HTTP errors thrown by provider clients. */
+export interface ProviderHttpErrorOptions {
+    /** Response headers; enables `retry-after`/rate-limit extraction downstream. */
+    headers?: Headers;
+    /** Machine-readable error code from the response body (`error.code` / `error.type`). */
+    code?: string;
+    cause?: unknown;
+}
+/** Non-2xx HTTP response from a provider. */
+export declare class ProviderHttpError extends Error {
+    readonly status: number;
+    readonly headers: Headers | undefined;
+    readonly code: string | undefined;
+    constructor(message: string, status: number, options?: ProviderHttpErrorOptions);
+}
+/** Non-2xx response from an OpenAI-wire endpoint, with the decoded body attached. */
+export declare class OpenAIHttpError extends ProviderHttpError {
+    readonly captured: CapturedHttpErrorResponse;
+    constructor(message: string, captured: CapturedHttpErrorResponse, code?: string, cause?: unknown);
+    /**
+     * Pull a human-readable message and machine code out of an OpenAI-style error
+     * envelope (`{ error: { message, code, type } }`), tolerating the flat shapes
+     * compat hosts return (`{ error: "..." }`, `{ message: "..." }`) and falling
+     * back to the raw body text.
+     */
+    static parseEnvelope(bodyJson: unknown, bodyText: string | undefined): {
+        detail: string | undefined;
+        code: string | undefined;
+    };
+}
+/** Test-only control for the otherwise bounded Anthropic error-body drain. */
+export declare const __anthropicApiErrorForTesting: {
+    setBodyReadTimeoutMs(timeoutMs: number | undefined): void;
+};
+/** Non-2xx response from the Anthropic API. */
+export declare class AnthropicApiError extends ProviderHttpError {
+    readonly headers: Headers;
+    readonly requestId: string | null;
+    constructor(status: number, message: string, headers: Headers);
+    static fromResponse(response: Response, signal?: AbortSignal): Promise<AnthropicApiError>;
+}
+/** Network-level failure (DNS, TLS, socket reset) after retries were exhausted. */
+export declare class AnthropicConnectionError extends Error {
+    constructor(cause: unknown);
+}
+/** No response headers arrived within the configured request timeout. */
+export declare class AnthropicConnectionTimeoutError extends Error {
+    constructor();
+}
+/**
+ * A malformed Anthropic SSE stream envelope — events arriving out of order
+ * (before `message_start`) or otherwise violating the message-event grammar.
+ * The message is prefixed with {@link STREAM_ENVELOPE_ERROR_PREFIX} so the
+ * shared envelope predicates classify it.
+ */
+export declare class AnthropicStreamEnvelopeError extends Error {
+    constructor(detail: string);
+}
+/** Non-2xx response (or in-stream exception event) from the Bedrock runtime API. */
+export declare class BedrockApiError extends ProviderHttpError {
+    readonly name = "BedrockApiError";
+}
+/** Non-2xx response (or in-stream error chunk) from the Cloud Code Assist API. */
+export declare class GeminiCliApiError extends ProviderHttpError {
+    readonly name = "GeminiCliApiError";
+}
+/** Non-2xx response (or in-stream error chunk) from the Google Generative Language / Vertex API. */
+export declare class GoogleApiError extends ProviderHttpError {
+    readonly name = "GoogleApiError";
+}
+/** Non-2xx response from the Ollama `/api/chat` endpoint. */
+export declare class OllamaApiError extends ProviderHttpError {
+    readonly name = "OllamaApiError";
+}
+/** Auth gateway HTTP failure. */
+export declare class AuthGatewayError extends ProviderHttpError {
+    constructor(message: string, status: number, headers?: Headers, code?: string);
+}
+export declare class CodexWebSocketTransportError extends Error {
+    constructor(detail: string);
+}
+export declare class CodexWhitespaceToolCallLoopError extends Error {
+    constructor(message: string);
+}
+export declare class CodexProviderStreamError extends Error {
+    readonly retryable: boolean;
+    constructor(message: string, options?: {
+        retryable?: boolean;
+        cause?: unknown;
+    });
+}
+export declare class AuthBrokerError extends Error {
+    readonly status: number | undefined;
+    readonly body: string | undefined;
+    constructor(message: string, opts?: {
+        status?: number;
+        body?: string;
+        cause?: unknown;
+    });
+}
+export declare class AuthBrokerStreamUnsupportedError extends AuthBrokerError {
+    constructor(message?: string);
+}