@linxiraos/pi-ai 1.0.0

package/dist/types/types.d.ts

@@ -0,0 +1,1064 @@
+export * from "@linxiraos/pi-catalog/effort";
+export * from "@linxiraos/pi-catalog/types";
+import type { DeleteArgs, DeleteResult, DiagnosticsArgs, DiagnosticsResult, GrepArgs, GrepResult, LsArgs, LsResult, McpResult, PiBashExecArgs, PiBashExecResult, PiEditExecArgs, PiEditExecResult, PiFindExecArgs, PiFindExecResult, PiGrepExecArgs, PiGrepExecResult, PiLsExecArgs, PiLsExecResult, PiReadExecArgs, PiReadExecResult, PiWriteExecArgs, PiWriteExecResult, ReadArgs, ReadResult, ShellArgs, ShellResult, WriteArgs, WriteResult } from "@linxiraos/pi-catalog/discovery/cursor-gen/agent_pb";
+import type { Effort } from "@linxiraos/pi-catalog/effort";
+import type { Api, FetchImpl, Model, Provider, ThinkingBudgets, Usage } from "@linxiraos/pi-catalog/types";
+import type { Type } from "@linxiraos/pi-omptype";
+import type { ApiKey } from "./auth-retry.js";
+import type { BedrockOptions } from "./providers/amazon-bedrock.js";
+import type { AnthropicOptions } from "./providers/anthropic.js";
+import type { FallbackParam, StopDetails } from "./providers/anthropic-wire.js";
+import type { AzureOpenAIResponsesOptions } from "./providers/azure-openai-responses.js";
+import type { CursorOptions } from "./providers/cursor.js";
+import type { DevinOptions } from "./providers/devin.js";
+import type { GitLabDuoWorkflowOptions } from "./providers/gitlab-duo-workflow.js";
+import type { GoogleOptions } from "./providers/google.js";
+import type { GoogleGeminiCliOptions } from "./providers/google-gemini-cli.js";
+import type { GoogleVertexOptions } from "./providers/google-vertex.js";
+import type { OllamaChatOptions } from "./providers/ollama.js";
+import type { OpenAICodexResponsesOptions } from "./providers/openai-codex-responses.js";
+import type { OpenAICompletionsOptions } from "./providers/openai-completions.js";
+import type { OpenAIResponsesOptions } from "./providers/openai-responses.js";
+import type { kStreamingPartialJson } from "./utils/block-symbols.js";
+import type { AssistantMessageEventStream } from "./utils/event-stream.js";
+export type { StopDetails } from "./providers/anthropic-wire.js";
+export type { AssistantMessageEventStream } from "./utils/event-stream.js";
+/**
+ * Ceiling on the output-token count omp requests from any OpenAI-family endpoint
+ * (openai-responses, azure/xai responses, and openai-completions). Mirrors
+ * Anthropic's {@link CLAUDE_CODE_MAX_OUTPUT_TOKENS}.
+ *
+ * Catalog `maxTokens` frequently reflects a model's context window rather than a
+ * given upstream's real per-request output cap. OpenRouter, for instance,
+ * advertises 131072 output tokens for `z-ai/glm-4.7`, but the Cerebras upstream
+ * only allows ~131072 tokens total — so requesting the full ceiling overflows
+ * with a 400. Requested output is clamped to this value (and to `model.maxTokens`).
+ */
+export declare const OPENAI_MAX_OUTPUT_TOKENS = 64000;
+export interface ApiOptionsMap {
+    "anthropic-messages": AnthropicOptions;
+    "bedrock-converse-stream": BedrockOptions;
+    "openai-completions": OpenAICompletionsOptions;
+    "openai-responses": OpenAIResponsesOptions;
+    openrouter: OpenAIResponsesOptions | OpenAICompletionsOptions;
+    "openai-codex-responses": OpenAICodexResponsesOptions;
+    "azure-openai-responses": AzureOpenAIResponsesOptions;
+    "google-generative-ai": GoogleOptions;
+    "google-gemini-cli": GoogleGeminiCliOptions;
+    "google-vertex": GoogleVertexOptions;
+    "ollama-chat": OllamaChatOptions;
+    "cursor-agent": CursorOptions;
+    "gitlab-duo-agent": GitLabDuoWorkflowOptions;
+    "devin-agent": DevinOptions;
+}
+export type OptionsForApi<TApi extends Api> = StreamOptions | (TApi extends keyof ApiOptionsMap ? ApiOptionsMap[TApi] : never);
+export interface TokenTaskBudget {
+    type: "tokens";
+    total: number;
+    remaining?: number;
+}
+export type MessageAttribution = "user" | "agent";
+export type NativeToolMarker = {
+    type: "computer";
+};
+export type ToolChoice = "auto" | "none" | "any" | "required" | {
+    type: "function";
+    name: string;
+} | {
+    type: "function";
+    function: {
+        name: string;
+    };
+} | {
+    type: "tool";
+    name: string;
+} | {
+    type: "computer";
+};
+export type CacheRetention = "none" | "short" | "long";
+/**
+ * Service tier hint for processing priority / cost control. These are the
+ * values providers consume on the wire:
+ *
+ * - OpenAI / OpenAI-Codex: sent verbatim as the `service_tier` field
+ *   (`flex`/`scale`/`priority`).
+ * - Google (Gemini API + Vertex AI): sent as the top-level `serviceTier`
+ *   field (`flex`/`priority`).
+ * - OpenRouter: passed through as `service_tier`; OpenRouter realizes it for
+ *   the OpenAI- and Google-family upstreams it supports and ignores it
+ *   otherwise.
+ * - Direct Anthropic: `"priority"` is translated into `speed: "fast"` plus the
+ *   fast-mode beta on supported Opus models. Other tiers are ignored.
+ *
+ * Per-family scoping is expressed by {@link ServiceTierByFamily}, not by
+ * scoped sentinel values — see {@link serviceTierFamily}.
+ */
+export type ServiceTier = "auto" | "default" | "flex" | "scale" | "priority";
+/** Provider families that expose an independent service-tier knob. */
+export type ServiceTierFamily = "openai" | "anthropic" | "google";
+/**
+ * Per-family service-tier selection. A request consults only the entry for the
+ * family its model belongs to (see {@link resolveModelServiceTier}), so a user
+ * can opt one family into priority without affecting the others when switching
+ * models mid-session.
+ */
+export type ServiceTierByFamily = Partial<Record<ServiceTierFamily, ServiceTier>>;
+type ServiceTierModel = Pick<Model, "provider" | "api" | "id">;
+/**
+ * Classify a model into the service-tier family whose knob governs it, or
+ * `undefined` when the model exposes no serving-priority control.
+ *
+ * OpenRouter models are classified by id namespace (`anthropic/`, `google/`,
+ * `openai/`); Claude on Bedrock/Vertex (api `anthropic-messages`) is the
+ * anthropic family even though its provider is `amazon-bedrock`/`google-vertex`.
+ * Custom OpenAI-compatible relays that serve OpenAI model ids are OpenAI family
+ * too unless the provider owns a separate tier control (Fireworks) or rejects
+ * OpenAI's service-tier field (GitHub Copilot).
+ */
+export declare function serviceTierFamily(model: ServiceTierModel): ServiceTierFamily | undefined;
+/**
+ * Reduce a per-family tier map to the single wire tier for `model` — the entry
+ * for the model's family, or `undefined` when the model has no family.
+ */
+export declare function resolveModelServiceTier(tiers: ServiceTierByFamily | null | undefined, model: Pick<Model, "provider" | "api" | "id">): ServiceTier | undefined;
+/**
+ * True when the tier should be sent on the wire as the provider's service-tier
+ * request field. `auto` is never forwarded — it is OpenAI's implicit default, so
+ * omitting `service_tier` is identical to requesting `auto`, and the Codex
+ * (ChatGPT OAuth) endpoint rejects an explicit `auto` outright. OpenAI /
+ * OpenAI-Codex accept every other {@link ServiceTier}; Google (Gemini API +
+ * Vertex) and OpenRouter accept `flex`/`priority`; Fireworks Serverless
+ * realizes only its Priority serving path. Anthropic is absent because it
+ * realizes `priority` via `speed: "fast"`.
+ */
+export declare function shouldSendServiceTier(serviceTier: ServiceTier | null | undefined, target: Provider | ServiceTierModel | undefined): boolean;
+/**
+ * True when `priority` will actually be realized on the wire for `model`.
+ * Direct Anthropic realizes fast mode; OpenAI/Google/Fireworks emit the
+ * service-tier field; OpenRouter realizes it only for its OpenAI- and
+ * Google-family upstreams. Bedrock/Vertex Claude and OpenRouter Anthropic
+ * models do not realize priority and return `false`.
+ */
+export declare function realizesPriorityServiceTier(serviceTier: ServiceTier | null | undefined, model: Pick<Model, "provider" | "api" | "id">): boolean;
+/**
+ * Premium-request weight contributed by a priority request to a provider that
+ * realizes it and bills extra. Mirrors GitHub Copilot's `premiumRequests`
+ * accounting so the "premium requests" stat aggregates priority traffic across
+ * the OpenAI family, direct Anthropic fast mode, and Google priority.
+ *
+ * Returns 1 only when priority is actually realized on the wire for `model`
+ * (see {@link realizesPriorityServiceTier}) and the provider bills it as a
+ * premium request. OpenRouter is excluded — it bills per its own pricing, not
+ * Copilot-premium semantics — as are Bedrock/Vertex Claude, where priority is
+ * silently dropped.
+ */
+export declare function getPriorityPremiumRequests(serviceTier: ServiceTier | null | undefined, model: Pick<Model, "provider" | "api" | "id">): number;
+/**
+ * Coerce a persisted service-tier value to a {@link ServiceTierByFamily}. Newer
+ * sessions store the family map directly; legacy sessions stored a single
+ * scalar — `"priority"` applied everywhere, `"openai-only"`/`"claude-only"`
+ * scoped to one family, and the remaining values were OpenAI-only semantics.
+ */
+export declare function coerceServiceTierByFamily(value: unknown): ServiceTierByFamily | undefined;
+export interface ProviderSessionState {
+    close(): void;
+}
+export interface ProviderResponseMetadata {
+    status: number;
+    headers: Record<string, string>;
+    requestId?: string | null;
+    metadata?: Record<string, unknown>;
+}
+export interface RawSseEvent {
+    event: string | null;
+    data: string;
+    raw: string[];
+}
+/** Lifecycle fields shared by every Codex compaction implementation. */
+export interface CodexCompactionContext {
+    /** Stable only for one logical compaction, including parallel summary calls. */
+    operationId: string;
+    trigger: "manual" | "auto";
+    reason: "user_requested" | "context_limit" | "model_downshift" | "comp_hash_changed";
+    phase: "standalone_turn" | "pre_turn" | "mid_turn";
+    strategy: "memento" | "prefix_compaction";
+}
+/** Canonical nested metadata serialized into the Codex turn envelope. */
+export interface CodexCompactionMetadata {
+    trigger: "manual" | "auto";
+    reason: "user_requested" | "context_limit" | "model_downshift" | "comp_hash_changed";
+    implementation: "responses" | "responses_compaction_v2" | "responses_compact";
+    phase: "standalone_turn" | "pre_turn" | "mid_turn";
+    strategy: "memento" | "prefix_compaction";
+}
+/** Dispatch context combining canonical metadata with its local operation identity. */
+export interface CodexCompactionRequestContext extends CodexCompactionMetadata {
+    operationId: string;
+}
+/** OpenAI's GPT-5.6+ explicit prompt-cache controls. */
+export interface OpenAIPromptCacheOptions {
+    /** `explicit` disables OpenAI's automatic latest-message breakpoint. */
+    mode: "implicit" | "explicit";
+    /** The only currently supported minimum breakpoint lifetime. */
+    ttl?: "30m";
+    /** By default, mark one existing block from stable history; `none` suppresses that marker. */
+    breakpoint?: "latest-stable-message" | "none";
+}
+export type OpenAIResponseInclude = "file_search_call.results" | "web_search_call.results" | "web_search_call.action.sources" | "message.input_image.image_url" | "computer_call_output.output.image_url" | "code_interpreter_call.outputs" | "reasoning.encrypted_content" | "message.output_text.logprobs";
+export interface StreamOptions {
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    minP?: number;
+    presencePenalty?: number;
+    repetitionPenalty?: number;
+    /**
+     * Stop sequences. Anthropic encodes as `stop_sequences` (array, max 4);
+     * OpenAI chat-completions encodes as `stop` (string or array of up to 4);
+     * OpenAI Responses API has no `stop` field today (silently dropped by the
+     * provider when present).
+     */
+    stopSequences?: string[];
+    /**
+     * Frequency penalty (OpenAI). Penalizes new tokens based on existing frequency
+     * in the text so far. Range -2.0 to 2.0. Parallel to {@link presencePenalty}.
+     */
+    frequencyPenalty?: number;
+    maxTokens?: number;
+    signal?: AbortSignal;
+    apiKey?: string;
+    cacheRetention?: CacheRetention;
+    /**
+     * Additional headers to include in provider requests.
+     * These are merged on top of model-defined headers.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Optional explicit request attribution override for providers that support it.
+     */
+    initiatorOverride?: MessageAttribution;
+    /**
+     * Maximum delay in milliseconds to wait for a retry when the server requests a long wait.
+     * If the server's requested delay exceeds this value, the request fails immediately
+     * with an error containing the requested delay, allowing higher-level retry logic
+     * to handle it with user visibility.
+     * Default: 60000 (60 seconds). Set to 0 to disable the cap.
+     */
+    maxRetryDelayMs?: number;
+    /**
+     * Optional metadata to include in API requests.
+     * Providers extract the fields they understand and ignore the rest.
+     * For example, Anthropic uses `user_id` for abuse tracking and rate limiting.
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Provider-owned request configuration. Provider hooks interpret this bag;
+     * generic API transports do not forward its fields onto the wire.
+     */
+    providerOptions?: Readonly<Record<string, unknown>>;
+    /** OpenAI Responses/Codex response fields to include verbatim. */
+    include?: OpenAIResponseInclude[];
+    /**
+     * Config options for the thinking/response loop guard.
+     */
+    loopGuard?: {
+        enabled?: boolean;
+        checkAssistantContent?: boolean;
+    };
+    /**
+     * Advisory token budget for a full agentic loop. Anthropic encodes this as
+     * `output_config.task_budget` with the `task-budgets-2026-03-13` beta header.
+     */
+    taskBudget?: TokenTaskBudget;
+    /**
+     * Optional session identifier for providers that support session-based
+     * routing, request affinity, or transport reuse. Providers may also use this
+     * as the prompt-cache key when `promptCacheKey` is not set.
+     */
+    sessionId?: string;
+    /**
+     * Optional prompt-cache identity. OpenAI-family providers use this for
+     * `prompt_cache_key` payloads and cache-affinity headers such as
+     * `x-grok-conv-id`; when omitted, they fall back to `sessionId`.
+     */
+    promptCacheKey?: string;
+    /**
+     * OpenAI GPT-5.6+ prompt-cache policy. Ignored by providers that do not
+     * support explicit OpenAI cache breakpoints; explicit mode fails locally on
+     * incompatible OpenAI-compatible endpoints.
+     */
+    promptCache?: OpenAIPromptCacheOptions;
+    /**
+     * Disable OpenAI Responses server-side turn chaining for this request.
+     * Diagnostic callers that compare independent requests can set this to
+     * `false` so `previous_response_id` cannot explain a result.
+     */
+    statefulResponses?: boolean;
+    /**
+     * Provider-scoped mutable state store for this agent session.
+     * Providers can use this to persist transport/session state between turns.
+     */
+    providerSessionState?: Map<string, ProviderSessionState>;
+    /** Canonical Codex compaction classification; ignored by other providers. */
+    codexCompaction?: CodexCompactionRequestContext;
+    /**
+     * Optional per-provider concurrent request cap for LLM stream calls. Keys are
+     * provider ids (`model.provider`); positive numeric values cap in-flight
+     * requests across local OMP processes that share the same config root. Omitted
+     * providers are unlimited. Non-chat provider APIs that bypass stream helpers
+     * are not covered.
+     */
+    maxInFlightRequests?: Record<string, number>;
+    /**
+     * Optional callback for inspecting or replacing provider payloads before sending.
+     * Return undefined to keep the payload unchanged.
+     */
+    onPayload?: (payload: unknown, model?: Model<Api>) => unknown | undefined | Promise<unknown | undefined>;
+    /**
+     * Optional callback for provider response metadata after headers are received.
+     */
+    onResponse?: (response: ProviderResponseMetadata, model?: Model<Api>) => void | Promise<void>;
+    /**
+     * Optional callback for raw Server-Sent Events as they arrive from HTTP streaming providers,
+     * plus synthesized SSE-shaped frames for the Codex WebSocket transport (one synthetic frame
+     * per JSON request/response message). WebSocket frames are tagged with a leading
+     * `: ws → <type>` (outbound) or `: ws ← <type>` (inbound) comment line in `RawSseEvent.raw`.
+     *
+     * Diagnostic only: provider implementations must ignore callback failures and must not
+     * let observers alter stream contents.
+     */
+    onSseEvent?: (event: RawSseEvent, model?: Model<Api>) => void;
+    /**
+     * Optional override for the first-event watchdog in milliseconds. Built-in
+     * providers apply this budget twice when they can: once to the underlying
+     * SDK/request while waiting for the HTTP stream object to exist, then again
+     * in the iterator while waiting for the first semantic stream event. Set to
+     * `0` to disable both layers for this request. After the first semantic
+     * event arrives, `streamIdleTimeoutMs` governs inter-event stalls. Falls
+     * back to `PI_STREAM_FIRST_EVENT_TIMEOUT_MS` and then to a 100s default.
+     * OpenAI-family transports additionally honor
+     * `PI_OPENAI_STREAM_FIRST_EVENT_TIMEOUT_MS` as the most-specific override and
+     * floor the first-event budget at the resolved idle (per-call
+     * `streamIdleTimeoutMs` or `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS`) so slow local
+     * OpenAI-compatible servers are not undercut during prompt processing.
+     *
+     * Iterator-level honored by: every built-in provider (via the lazy-stream
+     * forwarder in `register-builtins`). SDK-request honored by:
+     * `openai-completions`, `openai-responses`, `azure-openai-responses`,
+     * `anthropic-messages`.
+     */
+    streamFirstEventTimeoutMs?: number;
+    /**
+     * Optional override for the maximum idle gap between streamed events in
+     * milliseconds. Once the first event arrives, this guards against silent
+     * mid-stream stalls (broker dies, half-open socket, model produces no real
+     * progress for too long). Set to `0` to disable. Falls back to
+     * `PI_STREAM_IDLE_TIMEOUT_MS` (alias: `PI_OPENAI_STREAM_IDLE_TIMEOUT_MS`)
+     * and then to a 120s default.
+     */
+    streamIdleTimeoutMs?: number;
+    /**
+     * Optional cap on Codex SSE pre-response attempts, including the initial
+     * request. WebSocket retries and outer agent retries have separate budgets.
+     * Finite values below `1` and non-finite values are clamped to one request;
+     * omission preserves the provider default.
+     */
+    codexSseMaxAttempts?: number;
+    /**
+     * Optional retry delay hook for tests and transports that need custom scheduling.
+     */
+    providerRetryWait?: (delayMs: number, signal?: AbortSignal) => Promise<void>;
+    /**
+     * Optional `fetch` implementation override. Providers route every HTTP
+     * request — direct calls, SDK clients, and retry helpers — through this
+     * implementation when set. Defaults to `globalThis.fetch`. Providers that
+     * do not use `fetch` (Bedrock's AWS SDK transport, Cursor's HTTP/2
+     * channel) silently ignore the override.
+     */
+    fetch?: FetchImpl;
+    /** Current session working directory for providers that need workspace-scoped discovery. */
+    cwd?: string;
+    /** Cursor exec/MCP tool handlers (cursor-agent only). */
+    execHandlers?: CursorExecHandlers;
+}
+export interface SimpleStreamOptions extends Omit<StreamOptions, "apiKey"> {
+    /**
+     * API key for the request: either a static bearer string, or an
+     * {@link ApiKeyResolver} that mints/rotates the key across the central
+     * a/b/c auth-retry policy. `streamSimple`/`completeSimple` resolve a
+     * resolver to a string before per-provider dispatch, so providers only
+     * ever see the resolved {@link StreamOptions.apiKey} string.
+     */
+    apiKey?: ApiKey;
+    reasoning?: Effort;
+    /**
+     * Force-disable reasoning for the request even when the model supports it.
+     * Takes precedence over `reasoning`. Useful for fast utility calls
+     * (e.g. title generation) where the model would otherwise burn the entire
+     * output budget on internal thinking. Provider support is format-specific:
+     * some transports can disable reasoning directly, while generic
+     * effort-based OpenAI-compatible endpoints use the lowest supported effort.
+     */
+    disableReasoning?: boolean;
+    /**
+     * If true, request that the provider omit thinking/reasoning summaries
+     * from the response (e.g. Anthropic `thinking.display = "omitted"`,
+     * OpenAI Responses `reasoning.summary` left unset). The model still
+     * reasons internally; only the human-readable summary stream is dropped.
+     * Useful when the UI hides thinking blocks anyway and the summary is wasted bandwidth.
+     */
+    hideThinkingSummary?: boolean;
+    /** OpenAI Responses/Codex `text.verbosity` response detail level. */
+    textVerbosity?: "low" | "medium" | "high";
+    /** Custom token budgets for thinking levels (token-based providers only) */
+    thinkingBudgets?: ThinkingBudgets;
+    /** Cursor exec handlers for local tool execution */
+    cursorExecHandlers?: CursorExecHandlers;
+    /**
+     * Optional rewrite of Cursor exec-channel tool results. May return a Promise.
+     *
+     * The Agent reserves the original result in its buffer before awaiting this
+     * hook, and the `message_end` drain waits for a still-pending rewrite, so an
+     * async transformer is honored even when the turn closes in the same chunk.
+     * A rejecting transformer is swallowed and the reserved payload stands in.
+     */
+    cursorOnToolResult?: CursorToolResultHandler;
+    /** Optional tool choice override for compatible providers */
+    toolChoice?: ToolChoice;
+    /** OpenAI service tier for processing priority/cost control. Ignored by non-OpenAI providers. */
+    serviceTier?: ServiceTier;
+    /** Explicit Kimi Code API format override; omitted uses live per-model protocol metadata. */
+    kimiApiFormat?: "openai" | "anthropic";
+    /** API format for Synthetic provider: "openai" or "anthropic" (default: "openai") */
+    syntheticApiFormat?: "openai" | "anthropic";
+    /** Hint that websocket transport should be preferred when supported by the provider implementation. */
+    preferWebsockets?: boolean;
+    /**
+     * OpenRouter routing-variant suffix automatically appended to model IDs when
+     * the request targets OpenRouter (`model.provider === "openrouter"`). Common
+     * values: `"nitro"` (throughput), `"floor"` (cheapest), `"online"` (web
+     * search plugin), `"exacto"` (cherry-picked high-quality providers, only
+     * defined for some models). Ignored when the resolved model id already
+     * contains a `:<variant>` suffix (e.g. the user typed `:nitro` explicitly
+     * or the catalog entry already names the variant).
+     */
+    openrouterVariant?: string;
+    /**
+     * Caller-owned Google context-cache resource name. Forwarded only to the
+     * direct Gemini GenerateContent and Vertex GenerateContent APIs; all other
+     * providers ignore it. Callers own the cache lifecycle and compatibility.
+     */
+    cachedContent?: string;
+    /** Antigravity endpoint routing mode: "auto" (default with failover), "production", "sandbox". */
+    antigravityEndpointMode?: "auto" | "production" | "sandbox";
+    /**
+     * Anthropic `server-side-fallback-2026-06-01` fallback chain (top-level
+     * `fallbacks` request field). Opt-in ONLY — leaving this undefined is
+     * the default and preserves the pre-fallback behavior on every
+     * provider. Non-Anthropic providers ignore the field.
+     */
+    fallbacks?: FallbackParam[];
+}
+export type StreamFunction<TApi extends Api> = (model: Model<TApi>, context: Context, options: OptionsForApi<TApi>) => AssistantMessageEventStream;
+export interface TextSignatureV1 {
+    v: 1;
+    id: string;
+    phase?: "commentary" | "final_answer";
+}
+export interface TextContent {
+    type: "text";
+    text: string;
+    textSignature?: string;
+}
+export interface ThinkingContent {
+    type: "thinking";
+    thinking: string;
+    thinkingSignature?: string;
+    itemId?: string;
+}
+export interface RedactedThinkingContent {
+    type: "redactedThinking";
+    data: string;
+}
+/**
+ * Anthropic server-side-fallback boundary marker persisted on assistant
+ * turns whose provider request opted into
+ * `AnthropicOptions.fallbacks`. Consumers other than the Anthropic
+ * provider MUST ignore it — `transformMessages` strips the block on any
+ * cross-provider hop and on non-official Anthropic replays, so downstream
+ * converters never see it.
+ */
+export interface AnthropicFallbackContent {
+    type: "fallback";
+    from: {
+        model: string;
+    };
+    to: {
+        model: string;
+    };
+}
+/**
+ * Verbatim Anthropic web-search call/result retained for same-provider
+ * history replay. Other providers discard it in `transformMessages`.
+ */
+export interface AnthropicServerToolContent {
+    type: "anthropicServerTool";
+    block: {
+        type: "server_tool_use";
+        id: string;
+        name: "web_search";
+        input?: Record<string, unknown> | null;
+        [key: string]: unknown;
+    } | {
+        type: "web_search_tool_result";
+        tool_use_id: string;
+        content: unknown;
+        [key: string]: unknown;
+    };
+}
+export interface ImageContent {
+    type: "image";
+    data: string;
+    mimeType: string;
+    /**
+     * OpenAI-only resolution hint. `"original"` preserves native resolution
+     * (required for snapcompact frames, whose glyphs do not survive the
+     * default `auto` downscale). Providers without a detail knob ignore it.
+     */
+    detail?: "auto" | "low" | "high" | "original";
+}
+export type ComputerAction = {
+    type: "click";
+    button: "left" | "right" | "wheel" | "back" | "forward";
+    x: number;
+    y: number;
+    keys?: string[] | null;
+} | {
+    type: "double_click";
+    x: number;
+    y: number;
+    keys: string[] | null;
+} | {
+    type: "drag";
+    path: Array<{
+        x: number;
+        y: number;
+    }>;
+    keys?: string[] | null;
+} | {
+    type: "keypress";
+    keys: string[];
+} | {
+    type: "move";
+    x: number;
+    y: number;
+    keys?: string[] | null;
+} | {
+    type: "screenshot";
+} | {
+    type: "scroll";
+    x: number;
+    y: number;
+    scroll_x: number;
+    scroll_y: number;
+    keys?: string[] | null;
+} | {
+    type: "type";
+    text: string;
+} | {
+    type: "wait";
+};
+export interface ComputerSafetyCheck {
+    id: string;
+    code?: string | null;
+    message?: string | null;
+}
+export interface ComputerToolCallMetadata {
+    type: "computer";
+    providerItemId: string;
+    actions: ComputerAction[];
+    pendingSafetyChecks: ComputerSafetyCheck[];
+}
+export type ToolCallProviderMetadata = ComputerToolCallMetadata;
+export type ComputerScreenshotRef = {
+    type: "computer_screenshot";
+    image_url: string;
+    file_id?: never;
+} | {
+    type: "computer_screenshot";
+    file_id: string;
+    image_url?: never;
+};
+export interface ComputerToolResultMetadata {
+    type: "computer";
+    screenshot: ComputerScreenshotRef;
+    acknowledgedSafetyChecks: ComputerSafetyCheck[];
+}
+export type ToolResultProviderMetadata = ComputerToolResultMetadata;
+export interface ToolCall {
+    type: "toolCall";
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    [kStreamingPartialJson]?: string;
+    thoughtSignature?: string;
+    intent?: string;
+    /**
+     * Verbatim in-band syntax block that produced this synthetic `ptc_*` call.
+     * Present only for owned prompt/tool-call formats; provider-native calls omit it.
+     */
+    rawBlock?: string;
+    /**
+     * Original wire-level name when the tool was invoked via OpenAI's custom-tool
+     * mechanism (e.g., `apply_patch`). Set by `openai-responses` on receive so
+     * the history-replay path can re-emit the call as `custom_tool_call` with
+     * its paired tool-result as `custom_tool_call_output`. Absent for regular
+     * JSON function tools.
+     */
+    customWireName?: string;
+    /** Provider-native metadata required to execute and faithfully replay this call. */
+    providerMetadata?: ToolCallProviderMetadata;
+}
+export type StopReason = "stop" | "length" | "toolUse" | "error" | "aborted";
+export interface OpenAIResponsesHistoryPayload {
+    type: "openaiResponsesHistory";
+    provider?: string;
+    dt?: boolean;
+    items: Array<Record<string, unknown>>;
+}
+export type ProviderPayload = OpenAIResponsesHistoryPayload;
+export interface UserMessage {
+    role: "user";
+    content: string | (TextContent | ImageContent)[];
+    /** True if the message was injected by the system (e.g., auto-continue). */
+    synthetic?: boolean;
+    /** True when injected mid-turn as a steer; consumed by the agent's pre-LLM transform to wrap it for emphasis. Never rendered. */
+    steering?: boolean;
+    /** Who initiated this message for billing/attribution semantics. */
+    attribution?: MessageAttribution;
+    /** Provider-specific opaque payload used to reconstruct transport-native history. */
+    providerPayload?: ProviderPayload;
+    timestamp: number;
+}
+export interface DeveloperMessage {
+    role: "developer";
+    content: string | (TextContent | ImageContent)[];
+    /** Who initiated this message for billing/attribution semantics. */
+    attribution?: MessageAttribution;
+    /** Provider-specific opaque payload used to reconstruct transport-native history. */
+    providerPayload?: ProviderPayload;
+    timestamp: number;
+}
+/** How an automatic retry recovered or ultimately settled a failed attempt. */
+export type AssistantRetryRecoveryKind = "credential" | "model" | "wait" | "plain";
+/** Persisted presentation state for an assistant error superseded by an automatic retry saga. */
+export type AssistantRetryRecovery = {
+    kind: "auto-retry";
+    status: "recovered";
+    attempt: number;
+    recoveredAt: string;
+    recovery: AssistantRetryRecoveryKind;
+    note: string;
+    supersededBy?: {
+        timestamp: number;
+        responseId?: string;
+        provider: string;
+        model: string;
+    };
+} | {
+    kind: "auto-retry";
+    status: "superseded";
+    attempt: number;
+    recovery: AssistantRetryRecoveryKind;
+    note: string;
+};
+export interface ContextSnapshot {
+    promptTokens: number;
+    nonMessageTokens: number;
+    /** Estimated prompt tokens removed by local history rewrites after this provider snapshot was recorded. */
+    historyRewriteTokensRemoved?: number;
+    lastMessageTimestamp?: number;
+}
+export interface AssistantMessage {
+    role: "assistant";
+    content: (TextContent | ThinkingContent | RedactedThinkingContent | AnthropicFallbackContent | AnthropicServerToolContent | ImageContent | ToolCall)[];
+    api: Api;
+    provider: Provider;
+    model: string;
+    contextSnapshot?: ContextSnapshot;
+    retryRecovery?: AssistantRetryRecovery;
+    responseId?: string;
+    /**
+     * Name of the upstream provider an aggregator routed this request to, as
+     * reported in the response (e.g. OpenRouter's top-level `provider` field:
+     * `"OpenAI"`, `"Anthropic"`, `"Together"`). Distinct from `provider`, which
+     * is the configured gateway we called (`"openrouter"`). Undefined for direct
+     * providers that expose no such field.
+     */
+    upstreamProvider?: string;
+    usage: Usage;
+    stopReason: StopReason;
+    stopDetails?: StopDetails | null;
+    errorMessage?: string;
+    /** Per-tool abort messages used when an aborted assistant turn needs different placeholder results per tool call. */
+    toolCallAbortMessages?: Record<string, string>;
+    /** HTTP status surfaced by the provider when the request failed. Populated by every provider's catch block alongside `errorMessage` so consumers (auth retry, telemetry, UI) can branch without regex-scraping the message. */
+    errorStatus?: number;
+    /** Structured machine-readable error classifier; see `utils/error-id.ts` for bit layout and helpers. */
+    errorId?: number;
+    /**
+     * Stable identifiers for request features the provider silently dropped
+     * during this turn (e.g. `"priority"`). Set when a server-side rejection
+     * triggered an in-provider fallback retry that succeeded without the
+     * feature. Callers can use this to sync user-facing toggles back to the
+     * server's actual state.
+     */
+    disabledFeatures?: string[];
+    /** Provider-specific opaque payload used to reconstruct transport-native history. */
+    providerPayload?: ProviderPayload;
+    timestamp: number;
+    duration?: number;
+    ttft?: number;
+}
+export interface ToolResultMessage<TDetails = unknown> {
+    role: "toolResult";
+    toolCallId: string;
+    toolName: string;
+    content: (TextContent | ImageContent)[];
+    details?: TDetails;
+    isError: boolean;
+    /** Who initiated this message for billing/attribution semantics. */
+    attribution?: MessageAttribution;
+    /** Timestamp when output was pruned (ms since epoch). Undefined if unpruned. */
+    prunedAt?: number;
+    /** Provider-native metadata required to faithfully replay this result. */
+    providerMetadata?: ToolResultProviderMetadata;
+    /**
+     * Tool-declared: this result carried no information worth retaining once
+     * consumed (zero matches, elapsed wait). Compaction passes may elide it.
+     * Never set together with isError.
+     */
+    useless?: boolean;
+    timestamp: number;
+}
+export type Message = UserMessage | DeveloperMessage | AssistantMessage | ToolResultMessage;
+export type CursorExecHandlerResult<T> = {
+    result: T;
+    toolResult?: ToolResultMessage;
+} | T | ToolResultMessage;
+/**
+ * Optional rewrite of a Cursor exec-channel tool result.
+ * May return a Promise. Returning `undefined` keeps the original result.
+ *
+ * The Agent reserves the original result in its buffer before awaiting this
+ * hook, and the `message_end` drain waits for a still-pending rewrite, so an
+ * async transformer is honored even when the turn closes in the same chunk.
+ * A rejecting transformer is swallowed and the reserved payload stands in.
+ */
+export type CursorToolResultHandler = (result: ToolResultMessage) => ToolResultMessage | undefined | Promise<ToolResultMessage | undefined>;
+/**
+ * Identifies the synthesized assistant block a Cursor exec call was filed
+ * under, so paths that produce no handler `toolResult` can still pair one.
+ */
+export interface CursorExecPairing {
+    toolCallId: string;
+    toolName: string;
+}
+export interface CursorMcpCall {
+    name: string;
+    providerIdentifier: string;
+    toolName: string;
+    toolCallId: string;
+    args: Record<string, unknown>;
+    rawArgs: Record<string, Uint8Array>;
+    /**
+     * The frame asks only whether this call would be permitted — it must not
+     * run. The server sends it to resolve a smart-mode approval decision ahead
+     * of the real invocation, and answers with the dedicated `approved`
+     * variant, so executing here would fire a side-effecting tool the user has
+     * not yet been asked about (and fire it twice once the real call arrives).
+     */
+    approvalOnly?: boolean;
+}
+export interface CursorTodoSnapshotItem {
+    content: string;
+    status: "pending" | "in_progress" | "completed" | "abandoned";
+}
+/**
+ * Authoritative todo list state settled by Cursor's server-side
+ * `update_todos` / `read_todos` tools.
+ */
+export interface CursorTodoSnapshot {
+    todos: CursorTodoSnapshotItem[];
+    /** True when the server reported the update as a merge. Presentation only. */
+    merged: boolean;
+}
+/**
+ * Settles a native todo call in the host.
+ *
+ * Called for every completed native todo call, not just successful ones: the
+ * interactive todo card only resolves on a matching `tool_execution_end`, so a
+ * refused or failed call that stayed silent would animate forever.
+ *
+ * `snapshot` is the server-confirmed list, or `null` when there is nothing to
+ * mirror — a server error (`error` set), or a benign refusal with `error` null:
+ * a filtered, truncated, or empty read, or a snapshot the local model cannot
+ * represent (two rows sharing content). Local state MUST be left untouched
+ * unless a snapshot is supplied.
+ *
+ * `toolCallId` is the id of the streamed native call, which is also the key the
+ * interactive transcript filed the visible block under. The host MUST reuse it
+ * when emitting the synthetic completion, or that block never resolves.
+ *
+ * Returns the result to persist for that block — always, since every settle
+ * needs a paired result or `buildSessionContext` strips the block as dangling.
+ * Only the host knows the phase grouping the todo renderer replays from, so the
+ * provider persists this value verbatim. When no handler is registered at all,
+ * the provider falls back to its own summary-only result.
+ */
+export type CursorTodoSyncHandler = (snapshot: CursorTodoSnapshot | null, toolCallId: string, error: string | null) => ToolResultMessage;
+export interface CursorShellStreamCallbacks {
+    onStdout(data: string): void;
+    onStderr(data: string): void;
+}
+/**
+ * A modern Pi exec frame plus the call id the dispatcher minted for it.
+ *
+ * Unlike the legacy exec args (`ReadArgs`, `ShellArgs`, ...), the Pi frames
+ * carry no `tool_call_id` field: on modern builds the id rides the streamed
+ * `ToolCall` envelope (`ToolCall.tool_call_id = 57`) instead of each variant's
+ * args. The exec channel has no access to that envelope, so the dispatcher
+ * mints an id and hands it to the handler, keeping the synthesized transcript
+ * block and its paired `toolResult` on the same key.
+ */
+export interface CursorPiCall<TArgs> {
+    args: TArgs;
+    toolCallId: string;
+}
+/** One resource a host's MCP servers advertise. */
+export interface CursorMcpResource {
+    uri: string;
+    name?: string;
+    description?: string;
+    mimeType?: string;
+    /** The server advertising it; Cursor addresses reads by this name. */
+    server: string;
+}
+/**
+ * The content of one resource read.
+ *
+ * `text` and `blob` are the wire's content oneof: exactly one is sent, with
+ * `text` winning when a host supplies both. A download instead sets
+ * `downloadPath` and no content at all — the model is told where the file
+ * landed rather than being handed its bytes.
+ */
+export interface CursorMcpResourceContent {
+    uri: string;
+    name?: string;
+    description?: string;
+    mimeType?: string;
+    text?: string;
+    blob?: Uint8Array;
+    /**
+     * Where the host wrote the resource, workspace-relative, when the frame
+     * asked for a download. Set this INSTEAD of `text`/`blob`: the wire
+     * contract is that a download returns no content to the model.
+     */
+    downloadPath?: string;
+}
+export interface CursorExecHandlers {
+    read?: (args: ReadArgs) => Promise<CursorExecHandlerResult<ReadResult>>;
+    ls?: (args: LsArgs) => Promise<CursorExecHandlerResult<LsResult>>;
+    grep?: (args: GrepArgs) => Promise<CursorExecHandlerResult<GrepResult>>;
+    write?: (args: WriteArgs) => Promise<CursorExecHandlerResult<WriteResult>>;
+    delete?: (args: DeleteArgs) => Promise<CursorExecHandlerResult<DeleteResult>>;
+    shell?: (args: ShellArgs) => Promise<CursorExecHandlerResult<ShellResult>>;
+    shellStream?: (args: ShellArgs, callbacks: CursorShellStreamCallbacks) => Promise<CursorExecHandlerResult<ShellResult>>;
+    diagnostics?: (args: DiagnosticsArgs) => Promise<CursorExecHandlerResult<DiagnosticsResult>>;
+    mcp?: (call: CursorMcpCall) => Promise<CursorExecHandlerResult<McpResult>>;
+    /**
+     * Answers "would this MCP call be permitted", without running it.
+     *
+     * A modern `mcpArgs` frame carrying `smart_mode_approval_only` asks for the
+     * permission decision alone, ahead of the real invocation. Executing the
+     * tool to answer it would fire a side effect the user never approved — and
+     * fire it twice once the real call arrives.
+     *
+     * `true` only when the host's policy resolves to a definite allow. A pending
+     * prompt is `false`: it can only be answered interactively at execution
+     * time, and there is no "ask me later" reply in this frame's result. When no
+     * handler is registered the provider refuses, since it cannot decide.
+     */
+    mcpApprovalPreflight?: (call: CursorMcpCall) => Promise<boolean>;
+    /**
+     * Modern Cursor CLI Pi tool frames (`ExecServerMessage` 45-51). They are a
+     * distinct frame family from the legacy `readArgs`/`shellArgs`/... set, not
+     * an alias: different args, different result oneofs, and no `tool_call_id`.
+     */
+    piRead?: (call: CursorPiCall<PiReadExecArgs>) => Promise<CursorExecHandlerResult<PiReadExecResult>>;
+    piBash?: (call: CursorPiCall<PiBashExecArgs>) => Promise<CursorExecHandlerResult<PiBashExecResult>>;
+    piEdit?: (call: CursorPiCall<PiEditExecArgs>) => Promise<CursorExecHandlerResult<PiEditExecResult>>;
+    piWrite?: (call: CursorPiCall<PiWriteExecArgs>) => Promise<CursorExecHandlerResult<PiWriteExecResult>>;
+    piGrep?: (call: CursorPiCall<PiGrepExecArgs>) => Promise<CursorExecHandlerResult<PiGrepExecResult>>;
+    piFind?: (call: CursorPiCall<PiFindExecArgs>) => Promise<CursorExecHandlerResult<PiFindExecResult>>;
+    piLs?: (call: CursorPiCall<PiLsExecArgs>) => Promise<CursorExecHandlerResult<PiLsExecResult>>;
+    /**
+     * The resources the host's MCP servers advertise, optionally filtered to one
+     * server. Without a handler the provider answers an empty catalog, which
+     * hides resources a host is in fact holding live connections to.
+     */
+    listMcpResources?: (args: {
+        server?: string;
+    }) => Promise<CursorMcpResource[]>;
+    /**
+     * Read one resource. `null` means the server or uri is genuinely unknown,
+     * which the provider answers as `not_found`; throwing surfaces as `error`.
+     */
+    readMcpResource?: (args: {
+        server: string;
+        uri: string;
+        /**
+         * When set, write the resource here (workspace-relative) and return
+         * `downloadPath` instead of content.
+         */
+        downloadPath?: string;
+    }) => Promise<CursorMcpResourceContent | null>;
+    /** Mirror Cursor's server-owned todo list into local session state. */
+    todoSync?: CursorTodoSyncHandler;
+    onToolResult?: CursorToolResultHandler;
+}
+/**
+ * Plain JSON Schema document used by extension-authored tools (legacy TypeBox
+ * emits this shape). Distinguished from arktype at runtime.
+ */
+export type TJsonSchema = Record<string, unknown>;
+/**
+ * Schema type accepted by the {@link Tool} interface.
+ *
+ * Canonical authoring uses ArkType. Extension compat may supply a JSON Schema
+ * object (including TypeBox static schema objects).
+ */
+export type TSchema = Type | TJsonSchema;
+/** Resolve parameter types for tool execution / handlers. */
+export type Static<S> = S extends Type ? S["infer"] : S extends {
+    static: infer T;
+} ? T : unknown;
+export interface ToolCallExample<TArgs = Record<string, unknown>> {
+    caption?: string;
+    call: TArgs;
+}
+export interface ToolCompareExample<TArgs = Record<string, unknown>> {
+    caption?: string;
+    bad: TArgs;
+    good: TArgs;
+}
+export interface ToolNoteExample {
+    caption: string;
+    note?: string;
+}
+export type ToolExample<TArgs = Record<string, unknown>> = ToolCallExample<TArgs> | ToolCompareExample<TArgs> | ToolNoteExample;
+export interface Tool<TParameters extends TSchema = TSchema> {
+    name: string;
+    description: string;
+    parameters: TParameters;
+    /** If true, tool is strictly typed and validated against the parameters schema before execution */
+    strict?: boolean;
+    /**
+     * Optional grammar constraint for OpenAI custom-tool emission.
+     * When set, providers that support grammar-constrained tools (currently only
+     * `openai-responses` against models with the right capability flag) may emit
+     * this tool as `{type: "custom", format: {type: "grammar", …}}` instead of a
+     * JSON function tool. Other providers ignore the field.
+     */
+    customFormat?: {
+        syntax: "lark" | "regex";
+        definition: string;
+    };
+    /**
+     * Optional wire-level name used when this tool is emitted as a custom tool
+     * (e.g. OpenAI's `{type: "custom"}` shape). Models trained on specific tool
+     * names — like GPT-5 on `apply_patch` — need to see that exact name on the
+     * wire, but it may differ from the harness-internal `name`. The agent-loop
+     * dispatcher matches both `name` and `customWireName` so returned tool
+     * calls route correctly. Absent for regular JSON function tools.
+     */
+    customWireName?: string;
+    /** Selects a provider-native hosted tool instead of a JSON-schema function tool. */
+    native?: NativeToolMarker;
+    /**
+     * Illustrative calls/notes; the AI layer renders them into an `<examples>`
+     * block in the model's native tool-call syntax and appends to the wire
+     * description. Author `call`/`bad`/`good` as plain argument objects WITHOUT
+     * `i` — when intent tracing injects `i` into the schema, the renderer adds
+     * a placeholder `i` automatically. Type each tool's `examples` against its
+     * own schema (e.g. `readonly ToolExample<typeof schema["type"]>[]`).
+     */
+    examples?: readonly ToolExample[];
+}
+export interface Context {
+    systemPrompt?: string[];
+    messages: Message[];
+    tools?: Tool[];
+}
+export type AssistantMessageEvent = {
+    type: "start";
+    contentIndex?: undefined;
+    partial: AssistantMessage;
+} | {
+    type: "text_start";
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: "text_delta";
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: "text_end";
+    contentIndex: number;
+    content: string;
+    partial: AssistantMessage;
+} | {
+    type: "thinking_start";
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: "thinking_delta";
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: "thinking_end";
+    contentIndex: number;
+    content: string;
+    partial: AssistantMessage;
+} | {
+    type: "image_end";
+    contentIndex: number;
+    content: ImageContent;
+    partial: AssistantMessage;
+} | {
+    type: "toolcall_start";
+    contentIndex: number;
+    partial: AssistantMessage;
+} | {
+    type: "toolcall_delta";
+    contentIndex: number;
+    delta: string;
+    partial: AssistantMessage;
+} | {
+    type: "toolcall_end";
+    contentIndex: number;
+    toolCall: ToolCall;
+    partial: AssistantMessage;
+} | {
+    type: "done";
+    contentIndex?: undefined;
+    reason: Extract<StopReason, "stop" | "length" | "toolUse">;
+    message: AssistantMessage;
+} | {
+    type: "error";
+    contentIndex?: undefined;
+    reason: Extract<StopReason, "aborted" | "error">;
+    error: AssistantMessage;
+};