@linxiraos/pi-ai 1.0.0

package/dist/types/providers/aws-eventstream.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `application/vnd.amazon.eventstream` decoder.
+ *
+ * Wire format (all integers big-endian):
+ *
+ *   [total length     u32]
+ *   [headers length   u32]
+ *   [prelude CRC32    u32]   <- CRC over the first 8 bytes
+ *   [headers          headers_length]
+ *   [payload          total_length - headers_length - 16]
+ *   [message CRC32    u32]   <- CRC over the entire message minus the trailing 4 bytes
+ *
+ * Headers: a sequence of `[name_len u8][name utf8][value_type u8][value …]`.
+ * We only need the typed values Bedrock emits (boolean true/false, byte, short,
+ * integer, long, byte-array, string, timestamp, uuid). All are surfaced as
+ * strings for ease of consumption — Bedrock only sets string-valued headers in
+ * practice (`:event-type`, `:message-type`, `:content-type`, `:exception-type`).
+ */
+export interface EventStreamMessage {
+    /** Lower-cased copy is *not* applied — Bedrock uses casing like `:event-type` verbatim. */
+    headers: Record<string, string>;
+    payload: Uint8Array;
+}
+/** CRC32 (IEEE / zlib polynomial 0xEDB88320), matches `@aws-crypto/crc32`. */
+export declare function crc32(bytes: Uint8Array): number;
+/**
+ * Decode a single, fully buffered eventstream message. Throws if the framing is
+ * malformed or either CRC mismatches. Used by both `decodeEventStream` (the
+ * streaming entry point) and the unit tests, which exercise it with hand-built
+ * frames.
+ */
+export declare function decodeMessage(frame: Uint8Array): EventStreamMessage;
+/**
+ * Async generator that consumes a `ReadableStream<Uint8Array>` (e.g. a fetch
+ * response body) and yields fully-framed messages. Handles arbitrary chunk
+ * boundaries: messages may span multiple chunks, and a single chunk may carry
+ * many messages.
+ */
+export declare function decodeEventStream(source: ReadableStream<Uint8Array>): AsyncGenerator<EventStreamMessage>;

package/dist/types/providers/aws-sigv4.d.ts

@@ -0,0 +1,55 @@
+/**
+ * AWS Signature V4 signing for HTTP requests. WebCrypto-only — no node:crypto.
+ *
+ * Matches `@smithy/signature-v4` for our usage: header-based signing with a
+ * full SHA-256 payload hash (Bedrock requires `applyChecksum: true`).
+ *
+ * Returns the set of headers to attach to the request:
+ *  - `host`
+ *  - `x-amz-date`
+ *  - `x-amz-content-sha256`
+ *  - `x-amz-security-token` (only when credentials carry a sessionToken)
+ *  - `authorization`
+ */
+export interface AwsCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+export interface SignParams {
+    method: string;
+    /** Hostname only — used to build the `host` header and the canonical request. */
+    host: string;
+    /** URI path component, e.g. `/model/anthropic.claude/converse-stream`. */
+    path: string;
+    /** Optional pre-built query string (without leading `?`). */
+    query?: string;
+    /** Extra headers to sign in addition to `host`/`x-amz-*`. Names are case-insensitive. */
+    headers?: Record<string, string>;
+    body: Uint8Array;
+    region: string;
+    service: string;
+    credentials: AwsCredentials;
+    /** Override clock for deterministic tests. */
+    date?: Date;
+}
+export declare function toHex(bytes: Uint8Array): string;
+export declare function sha256(data: Uint8Array | string): Promise<Uint8Array>;
+export declare function sha256Hex(data: Uint8Array | string): Promise<string>;
+/**
+ * Derive a signing key: HMAC chain `kSecret → kDate → kRegion → kService → kSigning`.
+ */
+export declare function getSigningKey(secretAccessKey: string, shortDate: string, region: string, service: string): Promise<Uint8Array>;
+/** `YYYYMMDDTHHMMSSZ` + 8-char `YYYYMMDD`. */
+export declare function formatAmzDate(d: Date): {
+    longDate: string;
+    shortDate: string;
+};
+export interface SignedHeaders {
+    host: string;
+    "x-amz-date": string;
+    "x-amz-content-sha256": string;
+    authorization: string;
+    "x-amz-security-token"?: string;
+}
+export declare function signRequest(params: SignParams): Promise<SignedHeaders>;

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

@@ -0,0 +1,16 @@
+import type { ServiceTier, StreamFunction, StreamOptions, ToolChoice } from "../types.js";
+export { parseAzureDeploymentNameMap } from "./openai-shared.js";
+export interface AzureOpenAIResponsesOptions extends StreamOptions {
+    reasoning?: "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+    reasoningSummary?: "auto" | "detailed" | "concise" | null;
+    azureApiVersion?: string;
+    azureResourceName?: string;
+    azureBaseUrl?: string;
+    azureDeploymentName?: string;
+    toolChoice?: ToolChoice;
+    serviceTier?: ServiceTier;
+}
+/**
+ * Generate function for Azure OpenAI Responses API
+ */
+export declare const streamAzureOpenAIResponses: StreamFunction<"azure-openai-responses">;

package/dist/types/providers/bedrock-mantle.d.ts

@@ -0,0 +1,13 @@
+import { type AwsBedrockProviderOptions } from "../registry/aws.js";
+import type { FetchImpl, Model } from "../types.js";
+import type { OpenAIResponsesOptions } from "./openai-responses.js";
+export type BedrockMantleProviderOptions = AwsBedrockProviderOptions;
+export interface BedrockMantleOptions extends OpenAIResponsesOptions {
+    providerOptions?: BedrockMantleProviderOptions;
+}
+export declare function createBedrockMantleAuthenticatedFetch(options?: BedrockMantleOptions): FetchImpl;
+export interface PreparedBedrockMantleRequest {
+    model: Model<"openai-responses">;
+    options: OpenAIResponsesOptions;
+}
+export declare function prepareBedrockMantleRequest(model: Model<"openai-responses">, options: BedrockMantleOptions): PreparedBedrockMantleRequest;

package/dist/types/providers/claude-code-fingerprint.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Cowork inference-fingerprint constants, kept in a leaf module so consumers
+ * outside the provider (`registry/oauth/anthropic`, `usage/claude`) don't
+ * import the heavy `providers/anthropic` module.
+ *
+ * That import edge was a live init cycle: `providers/anthropic` → `stream` →
+ * `registry` → `registry/oauth/anthropic` → back into the still-initializing
+ * provider module.
+ */
+/** Claude runtime version bundled by the current Cowork desktop release. */
+export declare const claudeCodeVersion = "2.1.220";
+/** User-Agent emitted by Cowork's `claude-desktop` inference entrypoint. */
+export declare const coworkUserAgent = "claude-cli/2.1.220 (external, claude-desktop)";
+/** Prefix used to isolate custom Anthropic OAuth tools from built-in tools. */
+export declare const claudeToolPrefix: string;
+/** Identity block prepended by Cowork's Claude runtime. */
+export declare const claudeCodeSystemInstruction = "You are a Claude agent, built on Anthropic's Claude Agent SDK.";
+/** Cowork's per-request output-token ceiling. */
+export declare const CLAUDE_CODE_MAX_OUTPUT_TOKENS = 64000;

package/dist/types/providers/cowork-fetch.d.ts

@@ -0,0 +1,3 @@
+import type { FetchImpl } from "../types.js";
+/** Sends Cowork-profiled HTTPS requests with stable header order, HTTP/1.1, and streaming decompression. */
+export declare const coworkFetch: FetchImpl;

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

@@ -0,0 +1,98 @@
+/**
+ * Proto builders for the modern Cursor CLI exec frames (`ExecServerMessage`
+ * 27-31, 36-38, 40-55).
+ *
+ * Split out of `cursor.ts` because these are pure `create(...)` shapes with no
+ * transport, stream, or block-state coupling: the dispatcher decides *which*
+ * answer a frame gets, this module knows *what* that answer looks like on the
+ * wire. Every builder returns a result whose oneof case is set — an
+ * `ExecClientMessage` carrying a result with an unset oneof is a fake success
+ * the server reads as "the tool ran and produced nothing".
+ */
+import { type ExecuteHookRequest, type ExecuteHookResult, type McpStateExecResult, type McpToolDefinition, type PiBashExecResult, type PiEditExecResult, type PiFindExecResult, type PiGrepExecResult, type PiLsExecResult, type PiReadExecResult, type PiTruncation, type PiWriteExecResult } from "@linxiraos/pi-catalog/discovery/cursor-gen/agent_pb";
+import type { ToolResultMessage } from "../../types.js";
+/**
+ * The pure arg translation lives in `../cursor-pi-args` so the legacy pi shim
+ * can share it without pulling this module's protobuf graph into the bundled
+ * virtual registry. Re-exported here because this is where the frame builders
+ * and their translation are consumed together.
+ */
+export { piEscapeRegexLiteral, piGrepSkip, piJoinPath, piLimit, piLsPath, piReadDisplayPath, piReadPath, piReadPathHasRange, piTimeout, } 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;
+/**
+ * Translate a local tool's truncation summary into `PiTruncation`.
+ *
+ * Two shapes reach here. `read`/`grep` set `details.truncation`
+ * (`TruncationResult`), which carries an explicit `truncated` boolean. `bash`
+ * sets `details.meta.truncation` (`TruncationMeta`), which has **no** such
+ * flag — its presence *is* the signal, and requiring the boolean silently
+ * dropped every Bash truncation, handing Cursor clipped output with no notice
+ * that it was clipped.
+ *
+ * Returns `undefined` when nothing was truncated: the field is `optional` on
+ * every Pi success message, and emitting a zeroed `PiTruncation` would tell the
+ * server the output was trimmed to nothing.
+ */
+export declare function piTruncation(toolResult: ToolResultMessage): PiTruncation | undefined;
+export declare function buildPiReadResult(toolResult: ToolResultMessage): PiReadExecResult;
+export declare function buildPiReadError(error: string): PiReadExecResult;
+export declare function buildPiBashResult(toolResult: ToolResultMessage): PiBashExecResult;
+export declare function buildPiBashError(error: string): PiBashExecResult;
+/**
+ * `PiEditExecSuccess` requires `diff` and `patch` alongside `output`. The local
+ * `edit` tool reports them under `details`; when it does not, the strings stay
+ * empty rather than being faked from the output text.
+ */
+export declare function buildPiEditResult(toolResult: ToolResultMessage): PiEditExecResult;
+export declare function buildPiEditError(error: string): PiEditExecResult;
+/**
+ * A refusal is not an execution failure: `PiEditExecResult` models them as
+ * separate variants, and answering a denied call with `error` reads as "the
+ * edit ran and broke", which invites a retry of an operation that was never
+ * permitted.
+ */
+export declare function buildPiEditRejected(reason: string): PiEditExecResult;
+export declare function buildPiWriteResult(toolResult: ToolResultMessage): PiWriteExecResult;
+export declare function buildPiWriteError(error: string): PiWriteExecResult;
+/** Same variant split as {@link buildPiEditRejected}. */
+export declare function buildPiWriteRejected(reason: string): PiWriteExecResult;
+export declare function buildPiGrepResult(toolResult: ToolResultMessage): PiGrepExecResult;
+export declare function buildPiGrepError(error: string): PiGrepExecResult;
+export declare function buildPiFindResult(toolResult: ToolResultMessage): PiFindExecResult;
+export declare function buildPiFindError(error: string): PiFindExecResult;
+export declare function buildPiLsResult(toolResult: ToolResultMessage): PiLsExecResult;
+export declare function buildPiLsError(error: string): PiLsExecResult;
+/**
+ * Answer `mcpStateExecArgs` (frame 36) from the catalog already advertised in
+ * `RequestContext.tools`.
+ *
+ * This client hosts no MCP servers of its own: every forwarded tool is a local
+ * pi-agent tool published under a synthetic `providerIdentifier`. Regrouping
+ * the same list keeps the server's view of "which servers exist and what do
+ * they expose" consistent with what it was told at context time, instead of
+ * claiming zero servers while tool calls for them keep arriving.
+ *
+ * `serverIdentifiers` filters the answer when the server asks about specific
+ * servers. `kickOnly` is a restart request — there is nothing to restart, so it
+ * is answered with the same state rather than an error.
+ */
+export declare function buildMcpStateResult(tools: McpToolDefinition[], serverIdentifiers: readonly string[]): McpStateExecResult;
+/**
+ * Build the neutral response for a hook query: the matching response case with
+ * every field unset.
+ *
+ * This client runs no Cursor hooks, and every field of every response variant
+ * is `optional` — so an empty response of the right case means "no hook had
+ * anything to say", which is exactly true. It is NOT the unset-oneof fake
+ * success: the case itself is set, only the payload is empty.
+ *
+ * `ExecuteHookRequest` and `ExecuteHookResponse` are parallel oneofs whose case
+ * names line up, but the two unions are unrelated to the compiler: a `switch`
+ * is what makes each pairing individually type-checked, and it forces a
+ * deliberate branch when a future regen adds a request case.
+ *
+ * Returns `null` for a request case this build does not model, which the
+ * dispatcher answers with `ExecClientThrow` rather than guessing a case.
+ */
+export declare function buildNeutralHookResult(request: ExecuteHookRequest | undefined): ExecuteHookResult | null;

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

@@ -0,0 +1,105 @@
+/**
+ * Translate a Pi frame's args into the local tool kwargs that run it.
+ *
+ * Shared deliberately by three consumers: the provider synthesizes a display
+ * block from these, the coding-agent bridge executes with them, and the legacy
+ * pi shim performs the identical translation for the old wire. Separate
+ * hand-rolled copies drift, and the drift is invisible — the transcript shows
+ * one operation while a different one runs.
+ *
+ * Kept apart from `cursor/exec-modern.ts` on purpose: these are pure
+ * string/path functions with no protobuf coupling, while that module pulls in
+ * `@bufbuild/protobuf` and the generated `agent_pb` graph. The legacy shim is
+ * compiled into the bundled virtual module registry, so importing it from a
+ * nested path would drag the whole exec implementation in with it — and
+ * `./providers/*` is a single-segment wildcard export that cannot serve a
+ * nested specifier under bunfs (issue #3442).
+ *
+ * Every `optional int32` here is presence-sensitive: `0` is a supplied value,
+ * not "unset", so it must never be folded into a default.
+ */
+/**
+ * A `pi_read` range composed onto the path as `read`'s inline `:raw:N+K`
+ * selector.
+ *
+ * `read` exposes no range kwargs, so an uncomposed range reads the whole file.
+ * `offset` is a 1-indexed start clamped like the reference's
+ * `Math.max(0, offset - 1)` over 0-indexed lines; `limit` is a line count.
+ * `null` marks a present `limit: 0` — zero lines, which no selector expresses
+ * and which must not degrade into a whole-file read.
+ *
+ * The range is `raw` because a plain `:N+K` deliberately pads with one leading
+ * and three trailing context lines: helpful for a human reading a snippet,
+ * wrong for a caller that asked for exactly `limit` lines from `offset`. The
+ * wire result is an opaque `output` string, so the hashline and line-number
+ * gutter that `raw` also drops carry nothing the frame's contract needs.
+ * A range-free read keeps the ordinary form — whole-file reads want them.
+ */
+export declare function piReadPath(readPath: string, offset?: number, limit?: number): string | null;
+/**
+ * Whether a read path ends in an OMP line selector, including compound `raw`
+ * forms. Cursor uses this only to describe the operation already executed by
+ * the coding-agent read tool; the selector remains embedded in the path.
+ */
+export declare function piReadPathHasRange(readPath: string): boolean;
+/**
+ * The same range as {@link piReadPath}, rendered for a transcript block rather
+ * than for execution.
+ *
+ * Differs only at `limit: 0`, where `piReadPath` returns `null` because no
+ * selector reads zero lines and the frame is answered with empty output
+ * directly. The block still has to say so: falling back to the bare path there
+ * would record a whole-file read whose result is empty, which is the widest
+ * possible gap between what a rebuilt transcript shows and what happened.
+ * `+0` is never executed — it exists to be read.
+ */
+export declare function piReadDisplayPath(readPath: string, offset?: number, limit?: number): string;
+/**
+ * A legacy `grep` frame's pagination `offset` as the local tool's file `skip`.
+ *
+ * `grep` paginates by file and reports "use skip=N for the next page" in that
+ * same unit, so the offset maps across directly. A present `0` means "start at
+ * the beginning", which is the unskipped search rather than a skip of zero.
+ *
+ * Shared because both the executing bridge and the provider's transcript
+ * synthesis need it: a block showing an unskipped search beside a result from
+ * a later file window misreports what was searched.
+ */
+export declare function piGrepSkip(offset?: number): number | undefined;
+/**
+ * Join a Pi frame's optional `path` with the `glob`/`pattern` it scopes.
+ *
+ * The local `grep`/`glob` tools take one combined path spec. An absolute
+ * pattern ignores the path, and an absent or `.` path leaves the pattern
+ * standing alone rather than building a `./`- or `//`-prefixed spec.
+ *
+ * Uses `node:path` rather than string surgery so Windows absolutes (`C:\…`,
+ * UNC) are recognised and separators stay normalized.
+ */
+export declare function piJoinPath(basePath: string | undefined, pattern: string): string;
+/**
+ * The path a `pi_ls` frame lists.
+ *
+ * The frame's `limit` is deliberately NOT mapped. It caps directory *entries*
+ * (the reference does a flat `readdir` and slices the entry array), while the
+ * local `read` tool renders a depth-2 tree with per-directory caps and elision
+ * summaries and applies a selector as a *rendered line* slice. Nested rows,
+ * headers and "N more" lines all count toward that slice, so `:1+K` would cap
+ * a different unit while looking honored — worse than leaving it unset, which
+ * at least reports the local listing's own truncation faithfully.
+ */
+export declare function piLsPath(basePath: string | undefined): string;
+/** Escape a literal string so the regex-only local `grep` tool matches it verbatim. */
+export declare function piEscapeRegexLiteral(value: string): string;
+/** Clamp a present `optional int32` result cap the way the reference does; `undefined` stays unset. */
+export declare function piLimit(limit: number | undefined): number | undefined;
+/**
+ * A `pi_bash` frame's timeout as the local `bash` tool's kwarg.
+ *
+ * Presence-sensitive like every other `optional int32` here, and unusually
+ * load-bearing: `bash` documents `timeout: 0` as "disables the command
+ * deadline", so folding a supplied `0` into `undefined` applies the 300s
+ * default and kills exactly the long-running command that asked not to be.
+ * Negative values have no local meaning and fall back to the default.
+ */
+export declare function piTimeout(timeout: number | undefined): number | undefined;

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

@@ -0,0 +1,221 @@
+import http2 from "node:http2";
+import { type JsonValue } from "@bufbuild/protobuf";
+import type { McpToolDefinition } from "@linxiraos/pi-catalog/discovery/cursor-gen/agent_pb";
+import { type AgentServerMessage, type ConversationStateStructure } from "@linxiraos/pi-catalog/discovery/cursor-gen/agent_pb";
+import type { AssistantMessage, CursorExecHandlerResult, CursorExecHandlers, CursorExecPairing, CursorTodoSyncHandler, CursorToolResultHandler, Message, StreamFunction, StreamOptions, TextContent, ThinkingContent, Tool, ToolCall, ToolResultMessage } from "../types.js";
+import { kCursorExecResolved, kStreamingBlockIndex, kStreamingBlockKind, kStreamingEnvelopeId, kStreamingLastParseLen, kStreamingPartialJson } from "../utils/block-symbols.js";
+import { AssistantMessageEventStream } from "../utils/event-stream.js";
+export declare const CURSOR_API_URL = "https://api2.cursor.sh";
+export declare const CURSOR_CLIENT_VERSION = "cli-2026.07.23-e383d2b";
+export interface CursorOptions extends StreamOptions {
+    customSystemPrompt?: string;
+    conversationId?: string;
+    execHandlers?: CursorExecHandlers;
+    onToolResult?: CursorToolResultHandler;
+}
+/**
+ * Maps an opaque HTTP/2 negotiation failure into an actionable error.
+ *
+ * bun only opens an HTTP/2 session when TLS-ALPN negotiates `h2`. Behind a
+ * TLS-intercepting proxy that strips ALPN (e.g. Zscaler), the handshake yields
+ * no `h2` protocol and bun throws `ERR_HTTP2_ERROR: h2 is not supported`. The
+ * Cursor run RPC is HTTP/2-only (the ALB rejects HTTP/1.1 with 464), so there
+ * is no h1 fallback the way model discovery has one — the run simply cannot
+ * proceed. Replace the opaque message with one that names the cause and points
+ * at the `providers.cursor.baseUrl` workaround.
+ *
+ * Non-ALPN errors pass through untouched.
+ */
+export declare function mapH2TransportError(error: unknown, baseUrl: string): unknown;
+export declare const streamCursor: StreamFunction<"cursor-agent">;
+export type ToolCallState = ToolCall & {
+    [kStreamingBlockIndex]: number;
+    [kStreamingPartialJson]?: string;
+    [kStreamingLastParseLen]?: number;
+    [kStreamingBlockKind]: "mcp" | "todo" | "cursor-exec" | "connect-scm";
+    [kStreamingEnvelopeId]?: string;
+    [kCursorExecResolved]?: true;
+};
+export interface BlockState {
+    currentTextBlock: (TextContent & {
+        [kStreamingBlockIndex]: number;
+    }) | null;
+    currentThinkingBlock: (ThinkingContent & {
+        [kStreamingBlockIndex]: number;
+    }) | null;
+    currentToolCall: ToolCallState | null;
+    /**
+     * Open streamed tool-call blocks, keyed by the interaction envelope's
+     * `call_id`.
+     *
+     * Cursor interleaves calls: two `toolCallStarted` frames can arrive before
+     * either completes. A single "current" slot would let the second overwrite
+     * the first, orphaning a block that nothing then settles. Every keyed block
+     * stays reachable until its own completion, and `currentToolCall` remains
+     * only as the fallback for frames that carry no `call_id`.
+     */
+    openToolCalls: Map<string, ToolCallState>;
+    /** MCP call IDs synthesized from exec frames before their redundant streamed block arrives. */
+    resolvedMcpToolCallIds: Set<string>;
+    firstTokenTime: number | undefined;
+    setTextBlock: (b: (TextContent & {
+        [kStreamingBlockIndex]: number;
+    }) | null) => void;
+    setThinkingBlock: (b: (ThinkingContent & {
+        [kStreamingBlockIndex]: number;
+    }) | null) => void;
+    setToolCall: (t: ToolCallState | null) => void;
+    setFirstTokenTime: () => void;
+    /** Mirror a server-confirmed todo snapshot into local session state. */
+    onTodoSnapshot?: CursorTodoSyncHandler;
+    /**
+     * Persist a paired `toolResult` for a server-resolved call. Native todo calls
+     * never travel the exec channel, so without this the resolved block has no
+     * matching result and every transcript rebuild strips it as dangling.
+     */
+    onToolResult?: CursorToolResultHandler;
+}
+export interface UsageState {
+    sawTokenDelta: boolean;
+}
+/** Exported for tests: drives one Cursor server message through the stream (exec waits mark the stream busy). */
+export declare function handleServerMessage(msg: AgentServerMessage, output: AssistantMessage, stream: AssistantMessageEventStream, state: BlockState, blobStore: Map<string, Uint8Array>, h2Request: http2.ClientHttp2Stream, execHandlers: CursorExecHandlers | undefined, onToolResult: CursorToolResultHandler | undefined, usageState: UsageState, requestContextTools: McpToolDefinition[], onConversationCheckpoint?: (checkpoint: ConversationStateStructure) => void): Promise<void>;
+/**
+ * Exported for tests: verifies handler is invoked with correct `this` when passed as bound.
+ *
+ * Every exit pairs a `toolResult`. The synthesized block was already marked
+ * `kCursorExecResolved` before this runs (`synthesizeCursorExecToolCall`), so
+ * `agent-loop.ts` emits no placeholder for it: a path that returns without a
+ * result leaves the call unpaired and `buildSessionContext` strips the whole
+ * interaction on replay. The three result-less paths — no handler installed, a
+ * handler that produced nothing, and a thrown handler — therefore synthesize
+ * one from the same text the server sees in `execResult`.
+ *
+ * `pairing` is required so a new callsite cannot silently recreate the orphan,
+ * and nullable for the one caller whose block is NOT pre-resolved: MCP without
+ * an `mcp` handler, which `agent-loop.ts` runs locally and pairs itself.
+ */
+export declare function resolveExecHandler<TArgs, TResult>(args: TArgs, handler: ((args: TArgs) => Promise<CursorExecHandlerResult<TResult>>) | undefined, onToolResult: CursorToolResultHandler | undefined, buildFromToolResult: (toolResult: ToolResultMessage) => TResult, buildRejected: (reason: string) => TResult, buildError: (error: string) => TResult, pairing: CursorExecPairing | null): Promise<{
+    execResult: TResult;
+    toolResult?: ToolResultMessage;
+}>;
+/**
+ * Reject a Cursor exec-channel `grepArgs` frame whose `pattern` is empty or
+ * whitespace-only. Returns an actionable error message when the pattern is
+ * unusable (with a `glob`-aware hint when the model likely meant to list
+ * files), or `null` when the pattern is valid and grep should run.
+ *
+ * Exported for tests. Cursor's model sometimes sends `pattern=""` together
+ * with a non-empty `glob`, expecting grep to enumerate matching files; the
+ * downstream coding-agent `grep` tool rejects that with a bare "Pattern must
+ * not be empty", which the TUI renders as `?` in the tool preview (issue
+ * #4574). Handling it at the Cursor exec dispatch keeps the synthesized
+ * `toolCall` block off the persisted assistant message and gives the model a
+ * specific recovery hint.
+ */
+export declare function emptyGrepPatternRejection(pattern: string | undefined, glob: string | undefined): string | null;
+/**
+ * Retain a freshly opened streamed tool-call block.
+ *
+ * Keyed by the interaction envelope's `call_id`, which is the only key every
+ * `ToolCall*Update` for that call shares. The block's own `id` is deliberately
+ * not the key: MCP, Pi and connect-SCM blocks are filed under the id carried
+ * inside the call's `args`, because that is what the exec channel pairs its
+ * result under and what the transcript files the visible block under.
+ *
+ * `currentToolCall` is still set, as the fallback for frames that carry no
+ * `call_id` (proto3-optional, and unset on what older builds send).
+ */
+/**
+ * Close every tool-call block still open when the stream ends.
+ *
+ * Not just the last one started: with interleaved calls several can be open at
+ * once, and an unclosed block leaves its live card animating and its call
+ * unpaired.
+ *
+ * Only blocks fed by a streamed argument buffer get reparsed. Todo,
+ * connect-SCM and MCP-settled frames arrive with complete `arguments` and
+ * never set the partial buffer; `parseStreamingJson(undefined)` returns `{}`,
+ * so reparsing unconditionally would erase the arguments of every such block
+ * caught open by a truncated stream.
+ *
+ * Server-owned blocks are also paired here. `connect-scm` and `todo` are
+ * stamped {@link kCursorExecResolved} the moment they open, so `agent-loop.ts`
+ * synthesizes no placeholder for them and only their `toolCallCompleted` frame
+ * pairs a result. A transport that closes before that frame would leave the
+ * call unpaired, and `buildSessionContext` strips a dangling call from every
+ * rebuilt transcript — the interaction disappears. An interrupted result is
+ * emitted instead.
+ *
+ * MCP blocks are excluded even when resolved: the exec dispatch that marked
+ * them owns their result, and `drainInFlightDispatches` awaits it before this
+ * runs, so pairing here would duplicate one against the same `toolCallId`.
+ */
+export declare function flushOpenToolCalls(output: AssistantMessage, stream: AssistantMessageEventStream, state: BlockState): void;
+/**
+ * Merge the decoded completion-frame `McpArgs` map into the args assembled
+ * from streamed `args_text_delta` snapshots.
+ *
+ * The completion frame is authoritative for the scalars it carries — but it
+ * can omit oversized parameters entirely and can downgrade a structured value
+ * to its raw string fallback when `decodeMcpArgValue` cannot parse it as
+ * JSON. Overwriting the streamed args wholesale therefore loses data (e.g.
+ * the task tool's `tasks` array on multi-subagent dispatches, issue #2615).
+ *
+ * Rules per key:
+ * - completion key absent  → keep the streamed value.
+ * - completion is a string while the streamed value is structured (object or
+ *   array) → keep the streamed value (the completion frame downgraded it).
+ * - otherwise               → completion wins.
+ */
+export declare function mergeCursorMcpToolCallArgs(streamed: Record<string, unknown> | undefined, completion: Record<string, unknown> | undefined): Record<string, unknown>;
+/**
+ * Synthesize a completed `toolCall` content block for a Cursor exec-channel
+ * native tool (`shell`, `read`, `write`, `grep`, `ls`, `delete`, `diagnostics`)
+ * or for an MCP exec frame whose corresponding interaction block is absent.
+ *
+ * Args arrive complete on the exec message, so the block opens and closes in
+ * one step — no partial-JSON streaming path. Without this the persisted
+ * assistant message carries only text/thinking blocks, and on replay the
+ * following `toolResult` messages have no matching `toolCall.id` in
+ * `renderSessionContext`, so they render beneath the final answer or disappear.
+ *
+ * The block is stamped with {@link kCursorExecResolved} so the shared
+ * `agent-loop.ts` execution pass skips it — Cursor's server-driven exec
+ * channel already ran the tool via the bridge and buffered the result, so
+ * treating this block as runnable would re-execute the same side-effecting
+ * tool a second time.
+ *
+ * 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>): void;
+/** Exported for tests: drives one Cursor interaction update through the streaming state machine. */
+export declare function processInteractionUpdate(update: any, output: AssistantMessage, stream: AssistantMessageEventStream, state: BlockState, usageState: UsageState): void;
+export declare function buildMcpToolDefinitions(tools: Tool[] | undefined): McpToolDefinition[];
+/**
+ * Build `ConversationStateStructure.rootPromptMessagesJson` blob IDs for the
+ * system prompt plus prior conversation history, as JSON blobs matching
+ * Cursor's internal Vercel-AI-SDK-shaped message format.
+ *
+ * Cursor's server uses `rootPromptMessagesJson` (not `turns[]`) to build the
+ * actual model prompt. `turns[]` is UI/display metadata. Without populating
+ * this field, multi-turn conversations lose prior context — the model sees
+ * only an empty placeholder where historical user turns should be.
+ * The active user message is excluded because it is sent in the action.
+ */
+/**
+ * Build one Cursor system-message JSON blob per ordered system prompt. Emitting separate blobs
+ * (rather than a single `\n\n`-joined string) lets Cursor's blob cache hit independently per
+ * entry: changing only the last prompt does not invalidate earlier blob ids, so the prefix
+ * up to the changed prompt remains cached on the server side.
+ *
+ * When no system prompts are provided, returns a single default greeting so we never emit
+ * an empty `rootPromptMessagesJson` head.
+ */
+export declare function buildCursorSystemPromptJsons(systemPrompt: readonly string[] | undefined): string[];
+/** Exported for tests: decodes Cursor history blobs built from conversation messages. */
+export declare function buildCursorHistoryForTest(messages: Message[], activeUserMessageIndex?: number, targetModelId?: string): {
+    rootPromptMessagesJson: unknown[];
+    turnUserMessagesJson: JsonValue[];
+    turnStepMessagesJson: JsonValue[][];
+};

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

@@ -0,0 +1,12 @@
+import type { StreamFunction, StreamOptions } from "../types.js";
+/** Base host for Codeium/Windsurf's Cascade chat API (Connect protocol over HTTP/1.1). */
+export declare const DEVIN_API_URL = "https://server.codeium.com";
+export interface DevinOptions extends StreamOptions {
+    /** Cascade conversation id; reused as `cascade_id` so the server threads turns. */
+    conversationId?: string;
+    /** Falls back to `cascade_id` when no `conversationId` is supplied. */
+    sessionId?: string;
+    /** Wire model uid selected after thinking-effort routing. */
+    chatModelUid?: string;
+}
+export declare const streamDevin: StreamFunction<"devin-agent">;

package/dist/types/providers/error-message.d.ts

@@ -0,0 +1,25 @@
+import type { Api, Model } from "../types.js";
+export declare function createProviderErrorMessage(model: Model<Api>, err: unknown): {
+    role: "assistant";
+    content: never[];
+    errorMessage: string;
+    api: Api;
+    provider: string;
+    model: string;
+    usage: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        totalTokens: number;
+        cost: {
+            input: number;
+            output: number;
+            cacheRead: number;
+            cacheWrite: number;
+            total: number;
+        };
+    };
+    stopReason: "error";
+    timestamp: number;
+};

package/dist/types/providers/github-copilot-headers.d.ts

@@ -0,0 +1,40 @@
+import type { Message } from "../types.js";
+/**
+ * Infer whether the current request to Copilot is user-initiated or agent-initiated.
+ * Accepts `unknown[]` because providers may pass pre-converted message shapes.
+ */
+export type CopilotInitiator = "user" | "agent";
+export type CopilotPremiumRequests = number;
+export type CopilotDynamicHeaders = {
+    headers: Record<string, string>;
+    initiator: CopilotInitiator;
+    premiumRequests: CopilotPremiumRequests;
+};
+export declare function resolveGitHubCopilotBaseUrl(baseUrl: string | undefined, apiKey: string | undefined): string | undefined;
+export declare function inferCopilotInitiator(messages: unknown[]): CopilotInitiator;
+/** Check whether any message in the conversation contains image content. */
+export declare function hasCopilotVisionInput(messages: Message[]): boolean;
+/**
+ * Resolve an explicitly configured Copilot initiator header, if present.
+ * Handles case-insensitive X-Initiator keys and returns the last valid value.
+ */
+export declare function getCopilotInitiatorOverride(headers: Record<string, string> | undefined): CopilotInitiator | undefined;
+export type CopilotPlanTier = "free" | "paid";
+export declare function getCopilotPremiumMultiplier(premiumMultiplier: number | undefined, planTier?: string): number;
+export declare function getCopilotPremiumRequests(params: {
+    initiator: CopilotInitiator;
+    premiumMultiplier?: number;
+    planTier?: string;
+}): CopilotPremiumRequests;
+/**
+ * Build dynamic Copilot headers that vary per-request.
+ * Static headers (User-Agent, Editor-Version, etc.) come from model.headers.
+ */
+export declare function buildCopilotDynamicHeaders(params: {
+    messages: unknown[];
+    hasImages: boolean;
+    premiumMultiplier?: number;
+    headers?: Record<string, string>;
+    initiatorOverride?: CopilotInitiator;
+    planTier?: string;
+}): CopilotDynamicHeaders;