@vib-rato/ai 0.16.0

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

@@ -0,0 +1,280 @@
+import Anthropic, { type ClientOptions as AnthropicSdkClientOptions } from "@anthropic-ai/sdk";
+import type { MessageCreateParamsStreaming, MessageParam } from "@anthropic-ai/sdk/resources/messages";
+import type { FetchImpl, Message, Model, ProviderSessionState, ServiceTier, SimpleStreamOptions, StreamFunction, StreamOptions, Usage } from "../types";
+import { type RawHttpRequestDump } from "../utils/http-inspector";
+export type AnthropicHeaderOptions = {
+    apiKey: string;
+    baseUrl?: string;
+    isOAuth?: boolean;
+    extraBetas?: string[];
+    stream?: boolean;
+    modelHeaders?: Record<string, string>;
+    isCloudflareAiGateway?: boolean;
+    /**
+     * Attach ZCode client "source" headers (User-Agent: ZCode/<ver>, X-Title,
+     * X-ZCode-Agent: glm, X-Platform, etc.) so api.z.ai recognizes the caller as
+     * the ZCode client, exactly like ZCode's `buildZCodeSourceHeaders` does for
+     * GLM providers. glm-zcode only.
+     */
+    zcodeSourceHeaders?: boolean;
+};
+export declare function normalizeAnthropicBaseUrl(baseUrl?: string): string | undefined;
+export declare function buildBetaHeader(baseBetas: string[], extraBetas: string[]): string;
+/**
+ * Replicates ZCode's `buildZCodeSourceHeaders()` + GLM `X-ZCode-Agent` tag
+ * (host bundle `Bl` / `buildConnectivitySourceHeaders` for GLM providers), so
+ * api.z.ai sees vib's glm-zcode requests as the ZCode client. Dynamic values
+ * (platform/arch, locale, timezone, OS version) are resolved at runtime exactly
+ * as ZCode does; printable-ASCII-only and conditionally omitted when empty.
+ */
+export declare function buildZCodeSourceHeaders(): Record<string, string>;
+export declare function buildAnthropicHeaders(options: AnthropicHeaderOptions): Record<string, string>;
+type AnthropicCacheControl = {
+    type: "ephemeral";
+    ttl?: "1h" | "5m";
+};
+/**
+ * Clears the in-session "server rejected fast mode" sticky flag. Call when the
+ * caller is explicitly re-arming `serviceTier: "priority"` (e.g. user toggled
+ * `/fast on` after a previous turn auto-disabled it) so the next request
+ * actually carries `speed: "fast"` again. No-op when the map or state entry
+ * hasn't been materialized yet.
+ */
+export declare function clearAnthropicFastModeFallback(providerSessionState: Map<string, ProviderSessionState> | undefined): void;
+export declare function isAnthropicFastModeUnsupportedError(error: unknown): boolean;
+export declare function isAnthropicThinkingBlockMutationError(error: unknown): boolean;
+/**
+ * 400 shape where a replayed `thinking`/`redacted_thinking` block fails signature
+ * validation, e.g. `messages.5.content.24: Invalid \`signature\` in \`thinking\` block`.
+ * Unlike the latest-assistant mutation error above, the cited block can sit anywhere
+ * in the replayed history, so recovery must repair every assistant message rather
+ * than only the latest one.
+ */
+export declare function isAnthropicThinkingSignatureInvalidError(error: unknown): boolean;
+/**
+ * CLIProxyAPI replaces Anthropic's rejection body wholesale instead of forwarding
+ * it: the client only ever sees
+ * `{"type":"error","error":{"type":"api_error","message":"An error occurred while
+ * processing the request."}}`, delivered as an in-stream SSE `error` event on an
+ * HTTP 200 response, so neither the status nor the message survives. Captured CPA
+ * traces for that masked shape carry the thinking-integrity 400 upstream (issue
+ * #3900), and the generic body matches no transient phrase either, so the turn
+ * dies unrecoverably. Nothing in the payload names the cause; callers must pair
+ * this with a request that actually replays signed thinking blocks before
+ * treating it as a thinking-replay rejection.
+ */
+export declare function isAnthropicMaskedProxyRejection(error: unknown): boolean;
+/**
+ * Anthropic rejects a request carrying more than four `cache_control`
+ * breakpoints. An Anthropic-compatible gateway may attach its own block-level
+ * markers before forwarding, and those never appear in the params we serialize,
+ * so no amount of local counting can predict the total. The rejection is the
+ * only evidence that our generated marker is one too many, and it is worth
+ * exactly one retry with generated caching suppressed.
+ *
+ * Our own pre-flight `validateCacheControls` failure is deliberately not
+ * matched: it carries no `invalid_request_error` wording, so a local bug stays
+ * loud instead of being silently retried.
+ */
+export declare function isAnthropicCacheBreakpointOverflowError(error: unknown): boolean;
+export type AnthropicContextManagementInjectionDiagnostic = {
+    strategy: string;
+    message: string;
+    captureNote: string;
+};
+/**
+ * Diagnose a context-management strategy named by an Anthropic 400 but absent
+ * from the body Vibrato sent. This mismatch is evidence of intermediary mutation,
+ * not permission to silently enable thinking or retry the request.
+ */
+export declare function diagnoseAnthropicContextManagementInjection(error: unknown, dump: RawHttpRequestDump | undefined): AnthropicContextManagementInjectionDiagnostic | undefined;
+export interface CpaToolAliasRestoreFailure {
+    /** The rejected tool-call name exactly as CPA quoted it. */
+    alias: string;
+    /**
+     * Base tool name parsed out of the alias (`mcp__<server>__<token>_<base>`
+     * → `<base>`), when the alias shape is well-formed. `undefined` for a
+     * malformed alias — callers must then fall back to direct discovery and
+     * never invent a name.
+     */
+    baseName?: string;
+}
+/**
+ * Classifies the CPA alias-restore signature and extracts the rejected alias
+ * plus its base tool name. Claims only statusless in-stream SSE error events
+ * and HTTP 5xx failures: a non-5xx status carrying this text is not the
+ * observed CPA delivery shape and is left to the other classifiers.
+ */
+export declare function parseCpaToolAliasRestoreFailure(error: unknown): CpaToolAliasRestoreFailure | undefined;
+export declare function isCpaToolAliasRestoreFailure(error: unknown): boolean;
+export declare const claudeCodeVersion = "2.1.219";
+export declare const claudeCodeEntrypoint = "sdk-cli";
+export declare const claudeToolPrefix: string;
+export declare const claudeCodeSystemInstruction = "You are a Claude agent, built on Anthropic's Claude Agent SDK.";
+export declare function mapStainlessOs(platform: string): "MacOS" | "Windows" | "Linux" | "FreeBSD" | `Other::${string}`;
+export declare function mapStainlessArch(arch: string): "x64" | "arm64" | "x86" | `other::${string}`;
+export declare const claudeCodeHeaders: {
+    readonly "X-Stainless-Retry-Count": "0";
+    readonly "X-Stainless-Runtime-Version": "v24.3.0";
+    readonly "X-Stainless-Package-Version": "0.74.0";
+    readonly "X-Stainless-Runtime": "node";
+    readonly "X-Stainless-Lang": "js";
+    readonly "X-Stainless-Arch": "arm64" | "x64" | "x86" | `other::${string}`;
+    readonly "X-Stainless-Os": "FreeBSD" | "Linux" | "MacOS" | "Windows" | `Other::${string}`;
+    readonly "X-Stainless-Timeout": "600";
+};
+export declare function isClaudeCloakingUserId(userId: string): boolean;
+export declare function generateClaudeCloakingUserId(): string;
+export declare const applyClaudeToolPrefix: (name: string, prefixOverride?: string) => string;
+export declare const stripClaudeToolPrefix: (name: string, prefixOverride?: string) => string;
+export type AnthropicEffort = "low" | "medium" | "high" | "xhigh" | "max";
+export type AnthropicThinkingDisplay = "summarized" | "omitted";
+export interface AnthropicOptions extends StreamOptions {
+    /**
+     * Enable extended thinking.
+     * For Opus 4.6+: uses adaptive thinking (Anthropic model decides when/how much to think).
+     * For older models: uses budget-based thinking with thinkingBudgetTokens.
+     */
+    thinkingEnabled?: boolean;
+    /**
+     * Token budget for extended thinking (older models only).
+     * Ignored for Opus 4.6+ which uses adaptive thinking.
+     */
+    thinkingBudgetTokens?: number;
+    /**
+     * Effort level for adaptive thinking (Opus 4.6+ only).
+     * Controls how much thinking Anthropic model allocates:
+     * - "max": Always thinks with no constraints
+     * - "high": Always thinks, deep reasoning (default)
+     * - "medium": Moderate thinking, may skip for simple queries
+     * - "low": Minimal thinking, skips for simple tasks
+     * Ignored for older models.
+     */
+    effort?: AnthropicEffort;
+    /**
+     * Optional reasoning level fallback for direct Anthropic provider usage.
+     * Converted to adaptive effort when effort is not explicitly provided.
+     */
+    reasoning?: SimpleStreamOptions["reasoning"];
+    /**
+     * Controls how Anthropic returns thinking content when the selected thinking
+     * transport supports a display option. Defaults to "summarized" where the
+     * API accepts it.
+     */
+    thinkingDisplay?: AnthropicThinkingDisplay;
+    interleavedThinking?: boolean;
+    toolChoice?: "auto" | "any" | "none" | {
+        type: "tool";
+        name: string;
+    };
+    betas?: string[] | string;
+    /**
+     * Realization of `serviceTier: "priority"` on Anthropic models. When
+     * `"priority"`, sets `speed: "fast"` on the request and appends the
+     * `fast-mode-2026-02-01` beta header. Anthropic rejects unsupported models
+     * with `invalid_request_error`, which triggers an in-provider one-shot
+     * fallback (see `fastModeDisabled` provider state).
+     *
+     * Other `ServiceTier` values are currently ignored on this provider.
+     */
+    serviceTier?: ServiceTier;
+    /** Force OAuth bearer auth mode for proxy tokens that don't match Anthropic token prefixes. */
+    isOAuth?: boolean;
+    /**
+     * Pre-built Anthropic client instance. When provided, skips internal client
+     * construction entirely. Use this to inject alternative SDK clients such as
+     * `AnthropicVertex` that shares the same messaging API.
+     */
+    client?: Anthropic;
+}
+export type AnthropicClientOptionsArgs = {
+    model: Model<"anthropic-messages">;
+    apiKey: string;
+    extraBetas?: string[];
+    stream?: boolean;
+    interleavedThinking?: boolean;
+    headers?: Record<string, string>;
+    dynamicHeaders?: Record<string, string>;
+    isOAuth?: boolean;
+    hasTools?: boolean;
+    onSseEvent?: AnthropicOptions["onSseEvent"];
+    fetch?: FetchImpl;
+    requestMaxRetries?: number;
+    maxRetryDelayMs?: number;
+    streamFirstEventTimeoutMs?: number;
+    streamIdleTimeoutMs?: number;
+};
+export type AnthropicClientOptionsResult = {
+    isOAuthToken: boolean;
+    apiKey: string | null;
+    authToken?: string | null;
+    baseURL?: string;
+    maxRetries: number;
+    timeout?: number;
+    dangerouslyAllowBrowser: boolean;
+    defaultHeaders: Record<string, string>;
+    logLevel: AnthropicSdkClientOptions["logLevel"];
+    fetch?: AnthropicSdkClientOptions["fetch"];
+    fetchOptions?: AnthropicSdkClientOptions["fetchOptions"];
+};
+export declare function resolveGlmZcodeAnthropicBaseUrl(): string;
+export declare function isProviderRetryableError(error: unknown, provider?: string): boolean;
+export type AnthropicUsageLike = {
+    cache_creation?: {
+        ephemeral_5m_input_tokens?: number | null;
+        ephemeral_1h_input_tokens?: number | null;
+    } | null;
+    server_tool_use?: {
+        web_search_requests?: number | null;
+        web_fetch_requests?: number | null;
+    } | null;
+};
+/**
+ * Capture Anthropic's optional cache-creation TTL breakdown and server-tool-use
+ * counters into the harness Usage shape. Only sets fields that were reported, so
+ * a `message_delta` that omits `cache_creation` does not clobber the breakdown
+ * established at `message_start`.
+ */
+export declare function applyAnthropicUsageExtras(usage: Usage, source: AnthropicUsageLike): void;
+export declare const streamAnthropic: StreamFunction<"anthropic-messages">;
+export type AnthropicSystemBlock = {
+    type: "text";
+    text: string;
+    cache_control?: AnthropicCacheControl;
+};
+type SystemBlockOptions = {
+    includeClaudeCodeInstruction?: boolean;
+    extraInstructions?: string[];
+    billingPayload?: unknown;
+    cacheControl?: AnthropicCacheControl;
+};
+export declare function buildAnthropicSystemBlocks(systemPrompt: readonly string[] | undefined, options?: SystemBlockOptions): AnthropicSystemBlock[] | undefined;
+export declare function normalizeExtraBetas(betas?: string[] | string): string[];
+export declare function buildAnthropicClientOptions(args: AnthropicClientOptionsArgs): AnthropicClientOptionsResult;
+export declare function normalizeCacheControlTtlOrdering(params: MessageCreateParamsStreaming): void;
+export declare function convertAnthropicMessages(messages: Message[], model: Model<"anthropic-messages">, isOAuthToken: boolean, options?: {
+    repairLatestAssistantThinking?: boolean;
+    repairAllAssistantThinking?: boolean;
+}): MessageParam[];
+/**
+ * Normalize a JSON Schema node for Anthropic tool `input_schema`.
+ *
+ * Applies the full whitelist semantics from the Anthropic Python SDK's
+ * `lib/_parse/_transform.py::transform_schema`:
+ *
+ * 1. Universal keys (`$ref`, `$defs`, `type`, `anyOf`/`oneOf`/`allOf`, `enum`, `const`,
+ *    `description`, `title`, `default`, `nullable`) are preserved on every node.
+ * 2. Per-type keys are kept additively (object → `properties`/`required`/`additionalProperties`,
+ *    array → `items`/`prefixItems` plus `minItems` only when 0 or 1, string → `format`
+ *    only when in the supported value set).
+ * 3. Everything else is demoted into the node's `description` as `\n\n{key: value, ...}`
+ *    so the model still sees the constraint as a natural-language hint.
+ *
+ * Object nodes default to `additionalProperties: false`, but explicit open-map
+ * declarations (`additionalProperties: true` or a schema literal — Zod's
+ * `z.record(z.string(), z.unknown())` produces `{}`) are preserved. The strict-mode
+ * pass downstream demotes those shapes to non-strict instead of fabricating a closed
+ * object, so callers like the resolve tool keep working open-map semantics.
+ */
+export declare function normalizeAnthropicToolSchema(schema: unknown): unknown;
+export {};

package/dist/types/providers/aws-credential-config.d.ts

@@ -0,0 +1,19 @@
+import type { AwsCredentials } from "./aws-sigv4";
+export type AwsIniFile = Record<string, Record<string, string>>;
+export interface AwsCredentialSourceOptions {
+    profile?: string;
+}
+export interface AwsCredentialSource {
+    profile: string;
+    credentialsPath: string;
+    configPath: string;
+}
+export type AwsProfileCapability = "static" | "process" | "sso" | undefined;
+export declare function parseAwsIni(text: string): AwsIniFile;
+export declare function resolveAwsCredentialSource(options?: AwsCredentialSourceOptions): AwsCredentialSource;
+export declare function readAwsStaticEnvironmentCredentials(): AwsCredentials | undefined;
+export declare function classifyAwsProfileCapability(profile: string, credentialsIni: AwsIniFile | undefined, configIni: AwsIniFile | undefined): AwsProfileCapability;
+export declare function hasResolvableAwsProfileSource(options?: AwsCredentialSourceOptions & {
+    onScan?: () => void;
+}, now?: number): boolean;
+export declare function isValidBedrockBearerToken(token: string | undefined): token is string;

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

@@ -0,0 +1,43 @@
+/**
+ * AWS credential resolution for the Bedrock provider.
+ *
+ * Chain (first hit wins):
+ *  1. Static credentials from the environment
+ *     (`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` [+ `AWS_SESSION_TOKEN`]).
+ *  2. Profile in `~/.aws/credentials` (and `~/.aws/config` for SSO):
+ *      - static `aws_access_key_id` / `aws_secret_access_key` / `aws_session_token`
+ *      - SSO profile referencing a cached token in `~/.aws/sso/cache/*.json`,
+ *        which we exchange for short-lived role credentials via
+ *        `https://portal.sso.{region}.amazonaws.com/federation/credentials`.
+ *      - `credential_process` — an external command emitting the AWS SDK
+ *        `Version: 1` JSON envelope on stdout. Used by `aws-vault`, `granted`,
+ *        in-house brokers, etc.
+ *  3. EC2 IMDSv2 (only when `AWS_EC2_METADATA_DISABLED` is unset / falsey and
+ *     `169.254.169.254` is reachable within a 1 s timeout).
+ *
+ * Resolved credentials are cached process-wide per profile and refreshed
+ * 60 s before `Expiration` to absorb clock skew.
+ */
+import type { AwsCredentials } from "./aws-sigv4";
+export interface ResolvedCredentials extends AwsCredentials {
+    /** Absolute expiration timestamp in ms. `undefined` for non-expiring static creds. */
+    expiresAt?: number;
+}
+export interface CredentialResolveOptions {
+    /** Named profile from `~/.aws/credentials` / `~/.aws/config`. */
+    profile?: string;
+    /** Falls back to env (`AWS_REGION` / `AWS_DEFAULT_REGION`) and finally `us-east-1`. */
+    region?: string;
+    signal?: AbortSignal;
+}
+export declare function resolveAwsCredentials(opts?: CredentialResolveOptions): Promise<ResolvedCredentials>;
+/** POSIX-shell-style tokenizer used by the AWS CLI for `credential_process`.
+ *
+ * Outside quotes a backslash escapes the next character. Inside single quotes
+ * everything is literal (no escapes, cannot contain `'`). Inside double quotes
+ * a backslash only escapes `$`, `` ` ``, `"`, and `\` — every other backslash
+ * is preserved verbatim, which is what makes Windows paths like
+ * `"C:\Program Files\tool\auth.exe"` survive tokenization. */
+export declare function tokenizeCredentialProcessCommand(cmd: string): string[];
+/** Test/diagnostic helper — drops cached credentials. */
+export declare function clearAwsCredentialCache(): void;

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

@@ -0,0 +1,38 @@
+/**
+ * `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;
+}
+export declare function crc32(bytes: Uint8Array, seed?: number): 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.Anthropic model/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,22 @@
+import type { Model, ServiceTier, StreamFunction, StreamOptions, ToolChoice } from "../types";
+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">;
+/** Test seam: the Azure endpoint config as resolved from trusted env. */
+export declare function resolveAzureConfigForTest(model: Model<"azure-openai-responses">, options?: AzureOpenAIResponsesOptions): {
+    baseUrl: string;
+    apiVersion: string;
+};
+/** Test seam: the client API key as resolved from a caller value plus trusted env. */
+export declare function resolveAzureClientApiKeyForTest(apiKey: string): string | undefined;

package/dist/types/providers/composer-discipline.d.ts

@@ -0,0 +1,32 @@
+export declare function isComposerHarnessModel(modelId: string): boolean;
+/** Stable text contract for a local shell rejection caused by Composer file-I/O discipline. */
+export declare const COMPOSER_BASH_POLICY_ERROR_PREFIX = "Composer bash policy blocked repository file I/O.";
+export declare const COMPOSER_BASH_POLICY_ERROR_CODE = "composer-bash-policy:repository-file-io";
+export type ComposerBashPolicyToolSurface = "generic" | "cursor";
+/**
+ * Format the model-visible policy rejection with a stable marker and the tool
+ * vocabulary the model actually receives on this provider surface.
+ */
+export declare function formatComposerBashPolicyError(surface?: ComposerBashPolicyToolSurface): string;
+/**
+ * Matches both the structured current error and the original prefix so a
+ * resumed session can recover after an upgrade without string-version skew.
+ */
+export declare function isComposerBashPolicyBlockedError(text: string): boolean;
+/**
+ * Matches only errors emitted directly by the current policy implementation.
+ * Live recovery must use this strict form so failed shell output that merely
+ * quotes a policy error cannot masquerade as the policy gate itself.
+ */
+export declare function isCurrentComposerBashPolicyBlockedError(text: string): boolean;
+/** One bounded, tool-enabled retry instruction for generic Composer agent loops. */
+export declare const COMPOSER_BASH_POLICY_RECOVERY_PROMPT: string;
+/** One bounded, tool-enabled retry instruction for Cursor's native remote tool surface. */
+export declare const CURSOR_COMPOSER_BASH_POLICY_RECOVERY_PROMPT: string;
+export declare const COMPOSER_EDIT_DISCIPLINE_PROMPT = "File-editing discipline for this Composer harness (this OVERRIDES contrary habits from your training):\n\n- Discover file names ONLY with the find tool; search file contents ONLY with the search tool; read file bodies or line ranges ONLY with the read tool. NEVER inspect repository files through shell commands (ls, find, fd, cat, sed, awk, grep, rg, head, tail, less, more) or scripts \u2014 that output carries no hashline anchors and bypasses the agent's safety limits.\n- Modify files ONLY with the edit/write tools. NEVER mutate files through shell redirection, tee, sed -i, perl -pi, inline python/node/bun scripts, or other out-of-band writes \u2014 those writes invalidate every known anchor and break edit recovery.\n- A line anchor (e.g. \"42sr\") is a line number plus a 2-char content hash. You CANNOT compute the hash yourself: copy anchors verbatim from the MOST RECENT read/search/edit output of that exact file. NEVER guess, renumber, or arithmetically shift an anchor.\n- After ANY edit to a file (including your own), anchors you saw earlier are stale. Re-read the edited region, or copy the fresh anchors printed in the edit result, before issuing the next edit.\n- If an edit is rejected with \"anchors do not match\", the rejection message prints the current lines WITH fresh anchors. Retry using exactly those printed anchors.\n- Tool-call arguments must be the exact JSON/schema object requested by the tool. Do not include Markdown, commentary, analysis text, or invented fields inside tool arguments.\n- Use bash only for terminal operations such as tests, builds, package scripts, and git commands. A shell command string must contain only the command itself; NEVER interleave reasoning or commentary into command strings or heredocs.";
+/**
+ * Cursor executes a different native tool vocabulary from the generic agent
+ * loop. Keep this prompt separate so Composer is never told to call `edit`,
+ * `find`, or `search` when those names are unavailable remotely.
+ */
+export declare const CURSOR_COMPOSER_EDIT_DISCIPLINE_PROMPT: string;

package/dist/types/providers/cursor/client-version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The Cursor client version reported to api2.cursor.sh.
+ *
+ * Every call against the Cursor backend must send the same
+ * x-cursor-client-version: the backend gates features and minimum versions on
+ * it, so a drift between the agent Run path and model discovery makes one of
+ * them fail while the other keeps working. Keep this as the single source of
+ * truth for the header value.
+ */
+export declare const CURSOR_CLIENT_VERSION = "cli-2026.02.13-41ac335";

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 { ToolResultMessage } from "../../types";
+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 "./gen/agent_pb";
+/**
+ * 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 { omitUndefinedArgs, piEscapeRegexLiteral, piGrepSkip, piJoinPath, piLimit, piLsPath, piReadDisplayPath, piReadPath, piReadPathHasRange, piTimeout, } from "../cursor-pi-args";
+/** 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;