@yanlinglabs/winter-agent-sdk 0.0.1

package/dist/protocol/frames.d.ts

@@ -0,0 +1,598 @@
+import type { InitPluginInfo } from "./config.js";
+export type ProtocolVersion = `${number}.${number}`;
+export declare const PROTOCOL_VERSION: "1.0";
+export interface WireMcpServerStatus {
+    name: string;
+    status: string;
+}
+export interface InitFrame {
+    type: "init";
+    protocolVersion: ProtocolVersion;
+    sessionId: string;
+    cwd: string;
+    model: string;
+    permissionMode: string;
+    tools: string[];
+    mcp_servers?: WireMcpServerStatus[];
+    [k: string]: unknown;
+}
+export interface UserFrame {
+    type: "user";
+    text: string;
+    [k: string]: unknown;
+}
+export interface DataFrame {
+    type: "data";
+    message: SdkMessage;
+    [k: string]: unknown;
+}
+export interface ControlRequestFrame {
+    type: "control_request";
+    requestId: string;
+    subtype: string;
+    payload: unknown;
+}
+export interface ControlResponseFrame {
+    type: "control_response";
+    requestId: string;
+    ok: boolean;
+    payload?: unknown;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export interface UnknownFrame {
+    type: string;
+    [k: string]: unknown;
+}
+export type WinterFrame = InitFrame | UserFrame | DataFrame | ControlRequestFrame | ControlResponseFrame | UnknownFrame;
+export interface SDKHookStartedMessage {
+    type: "system";
+    subtype: "hook_started";
+    hook_id: string;
+    hook_name: string;
+    hook_event: string;
+    session_id: string;
+    uuid: string;
+}
+export interface SDKHookProgressMessage {
+    type: "system";
+    subtype: "hook_progress";
+    hook_id: string;
+    hook_name: string;
+    hook_event: string;
+    stdout: string;
+    stderr: string;
+    output: string;
+    session_id: string;
+    uuid: string;
+}
+export interface SDKHookResponseMessage {
+    type: "system";
+    subtype: "hook_response";
+    hook_id: string;
+    hook_name: string;
+    hook_event: string;
+    output: string;
+    stdout: string;
+    stderr: string;
+    exit_code?: number;
+    outcome: "success" | "error" | "cancelled";
+    session_id: string;
+    uuid: string;
+}
+export interface SDKPermissionDeniedMessage {
+    type: "system";
+    subtype: "permission_denied";
+    tool_name: string;
+    tool_use_id: string;
+    agent_id?: string;
+    decision_reason_type?: string;
+    decision_reason?: string;
+    message: string;
+    uuid: string;
+    session_id: string;
+}
+export interface SDKPermissionDenial {
+    tool_name: string;
+    tool_use_id: string;
+    tool_input: Record<string, unknown>;
+}
+export interface SDKTaskStartedMessage {
+    type: "system";
+    subtype: "task_started";
+    task_id: string;
+    tool_use_id?: string;
+    description: string;
+    subagent_type?: string;
+    is_backgrounded?: boolean;
+    spawn_depth?: number;
+    task_type?: string;
+    workflow_name?: string;
+    prompt?: string;
+    skip_transcript?: boolean;
+    ambient?: boolean;
+    uuid: string;
+    session_id: string;
+}
+export interface SDKTaskNotificationMessage {
+    type: "system";
+    subtype: "task_notification";
+    task_id: string;
+    tool_use_id?: string;
+    status: "completed" | "failed" | "stopped";
+    output_file: string;
+    summary: string;
+    usage?: {
+        total_tokens: number;
+        tool_uses: number;
+        duration_ms: number;
+    };
+    skip_transcript?: boolean;
+    ambient?: boolean;
+    uuid: string;
+    session_id: string;
+}
+export interface SDKTaskUpdatedMessage {
+    type: "system";
+    subtype: "task_updated";
+    task_id: string;
+    patch: {
+        status?: "pending" | "running" | "completed" | "failed" | "killed" | "paused";
+        description?: string;
+        end_time?: number;
+        total_paused_ms?: number;
+        error?: string;
+        is_backgrounded?: boolean;
+    };
+    uuid: string;
+    session_id: string;
+}
+export interface SDKTaskProgressMessage {
+    type: "system";
+    subtype: "task_progress";
+    task_id: string;
+    tool_use_id?: string;
+    description: string;
+    subagent_type?: string;
+    usage: {
+        total_tokens: number;
+        tool_uses: number;
+        duration_ms: number;
+    };
+    last_tool_name?: string;
+    summary?: string;
+    uuid: string;
+    session_id: string;
+}
+export interface SDKBackgroundTasksChangedMessage {
+    type: "system";
+    subtype: "background_tasks_changed";
+    tasks: Array<{
+        task_id: string;
+        task_type: string;
+        description: string;
+        ambient?: boolean;
+    }>;
+    uuid: string;
+    session_id: string;
+}
+export interface SDKLocalCommandOutputMessage {
+    type: "system";
+    subtype: "local_command_output";
+    content: string;
+    uuid: string;
+    session_id: string;
+}
+export type BackgroundTaskMessage = SDKTaskStartedMessage | SDKTaskNotificationMessage | SDKTaskUpdatedMessage | SDKTaskProgressMessage | SDKBackgroundTasksChangedMessage | SDKLocalCommandOutputMessage;
+export type SDKStatus = "compacting" | "requesting" | null;
+export interface SDKStatusMessage {
+    type: "system";
+    subtype: "status";
+    status: SDKStatus;
+    permissionMode?: string;
+    compact_result?: "success" | "failed";
+    compact_error?: string;
+    uuid: string;
+    session_id: string;
+}
+export interface SDKCompactBoundaryMessage {
+    type: "system";
+    subtype: "compact_boundary";
+    compact_metadata: {
+        trigger: "manual" | "auto";
+        pre_tokens: number;
+        post_tokens?: number;
+        duration_ms?: number;
+        preserved_segment?: {
+            head_uuid: string;
+            anchor_uuid: string;
+            tail_uuid: string;
+        };
+        preserved_messages?: {
+            anchor_uuid: string;
+            uuids: string[];
+        };
+    };
+    uuid: string;
+    session_id: string;
+}
+export type WireContentBlock = {
+    type: "text";
+    text: string;
+    [k: string]: unknown;
+}
+/** `signature` is a plain string that MAY be `""`: capture (F) shows the pinned runtime normalising a signatureless thinking block to exactly that and REPLAYING it. Optional would let a producer omit it and break the signature chain silently. */
+ | {
+    type: "thinking";
+    thinking: string;
+    signature: string;
+    [k: string]: unknown;
+}
+/** `data` is OPAQUE provider state. It rides in-dialect (the dialect defines it) and NOWHERE else -- never a log, never an error message, never the advisor transcript (Global Constraints). */
+ | {
+    type: "redacted_thinking";
+    data: string;
+    [k: string]: unknown;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: unknown;
+    [k: string]: unknown;
+} | {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string | WireContentBlock[];
+    [k: string]: unknown;
+} | {
+    type: "image";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    };
+    [k: string]: unknown;
+};
+export type WireStreamEventDelta = {
+    type: "text_delta";
+    text: string;
+    [k: string]: unknown;
+}
+/** `estimated_tokens` is the one delta payload field the pin names at all -- second-hand, in `SDKThinkingTokensMessage`'s own JSDoc (`sdk.d.ts:5015`) -- so it is optional here beside the text Winter's emitter sets. */
+ | {
+    type: "thinking_delta";
+    thinking: string;
+    estimated_tokens?: number;
+    [k: string]: unknown;
+} | {
+    type: "signature_delta";
+    signature: string;
+    [k: string]: unknown;
+} | {
+    type: "input_json_delta";
+    partial_json: string;
+    [k: string]: unknown;
+};
+export type WireStreamEvent = {
+    type: "message_start";
+    message?: {
+        id?: string;
+        model?: string;
+        role?: "assistant";
+        content?: WireContentBlock[];
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+} | {
+    type: "content_block_start";
+    index: number;
+    content_block: WireContentBlock;
+    [k: string]: unknown;
+} | {
+    type: "content_block_delta";
+    index: number;
+    delta: WireStreamEventDelta;
+    [k: string]: unknown;
+} | {
+    type: "content_block_stop";
+    index: number;
+    [k: string]: unknown;
+} | {
+    type: "message_delta";
+    delta: {
+        stop_reason?: string | null;
+        stop_sequence?: string | null;
+        [k: string]: unknown;
+    };
+    usage?: {
+        output_tokens?: number;
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+} | {
+    type: "message_stop";
+    [k: string]: unknown;
+};
+/**
+ * Phase 6 Task 3 (derived-shapes-p6.md item (a), `sdk.d.ts:4544-4558`): the live-token-streaming frame.
+ *
+ * SIX FIELDS PLUS THE DISCRIMINANT, and two of them are easy to miss: `ttft_ms?` (`4553`) and
+ * `user_message_uuid?` (`4557`). `parent_tool_use_id` is `string | null` and NOT optional -- a
+ * main-thread frame emits the key explicitly with `null`, matching `SDKAssistantMessage`'s own
+ * convention.
+ *
+ * GATED on `includePartialMessages` (`1712-1716`), and ADDITIVE: the pin's own JSDoc (`4542`) says
+ * the complete `assistant` message still follows as its own message, which is what lets a host ignore
+ * `stream_event` entirely and still see every completed block. R6-G: auxiliary provider calls
+ * (compaction summariser, classifier, advisor, countTokens) emit NONE of these -- capture (F) observed
+ * the pinned runtime suppressing exactly that call's stream events -- and `ttft_ms` rides the FIRST
+ * `stream_event` of each forwarded generation.
+ */
+export interface SDKPartialAssistantMessage {
+    type: "stream_event";
+    event: WireStreamEvent;
+    parent_tool_use_id: string | null;
+    uuid: string;
+    session_id: string;
+    ttft_ms?: number;
+    user_message_uuid?: string;
+}
+/**
+ * The pinned provider-error taxonomy, `sdk.d.ts:3159` -- the closed 11-member union carried on
+ * `api_retry.error`, `SDKAssistantMessage.error?` and `StopFailureHookInput.error`.
+ *
+ * These eleven buckets are all a Winter adapter has to map into for parity; anything finer is a
+ * Winter extension to disclose (provider-runtime's `ProviderError.providerCode` is exactly that).
+ * DECLARED HERE as well as in provider-runtime's `types.ts` on purpose: this package is
+ * dependency-free and fence-resident and cannot import the Bun-only one, and the frame that carries
+ * the union must declare what it carries.
+ */
+export type SDKAssistantMessageError = "authentication_failed" | "oauth_org_not_allowed" | "account_on_hold" | "billing_error" | "rate_limit" | "overloaded" | "invalid_request" | "model_not_found" | "server_error" | "unknown" | "max_output_tokens";
+/**
+ * `sdk.d.ts:3085-3095` (JSDoc `3083`). Nine keys, ALL REQUIRED -- none optional.
+ *
+ * `error_status: number | null`: the null case is a connection error (e.g. a timeout) that had no
+ * HTTP response, which is why provider-runtime's `ProviderError.status` is ABSENT rather than `null`
+ * for that case and this frame's producer maps absence to `null` at the boundary.
+ *
+ * R6-6/R6-C: one frame per retry attempt, announced BEFORE the delay is taken; `max_retries` is 10
+ * (capture (G) pinned it on every frame of all three runs).
+ */
+export interface SDKAPIRetryMessage {
+    type: "system";
+    subtype: "api_retry";
+    attempt: number;
+    max_retries: number;
+    retry_delay_ms: number;
+    error_status: number | null;
+    error: SDKAssistantMessageError;
+    uuid: string;
+    session_id: string;
+}
+/**
+ * `sdk.d.ts:4651-4669`. Every field except `status` is optional, and the vocabulary is
+ * consumer-SUBSCRIPTION-shaped throughout -- which is the whole point of R6-B.
+ */
+export interface SDKRateLimitInfo {
+    status: "allowed" | "allowed_warning" | "rejected";
+    rateLimitType?: "five_hour" | "seven_day" | "seven_day_opus" | "seven_day_sonnet" | "seven_day_overage_included" | "overage";
+    resetsAt?: number;
+    utilization?: number;
+    [k: string]: unknown;
+}
+/**
+ * `sdk.d.ts:4638-4646`. A TOP-LEVEL `type`, not a `system` subtype -- unlike `api_retry`/`status`/
+ * `thinking_tokens`/the refusal pair. `auth_status` and `tool_progress` share this convention.
+ *
+ * **R6-B: an HTTP 429 is NOT this frame.** Capture (G) proved the pinned runtime emits ZERO
+ * `rate_limit_event` frames for a 429 carrying a full `anthropic-ratelimit-*` header set with a
+ * `rejected` unified status; the pinned 429 path is `api_retry` with `error_status: 429` and
+ * `error: "rate_limit"`. Winter emits this ONLY for subscription-shaped quota states (the codex-oauth
+ * quota manager's limited/`resumeAt`), and header-derived limits never become frames at all.
+ */
+export interface SDKRateLimitEvent {
+    type: "rate_limit_event";
+    rate_limit_info: SDKRateLimitInfo;
+    uuid: string;
+    session_id: string;
+}
+/**
+ * `sdk.d.ts:3161-3168`. Top-level `type`, four payload fields, and NO JSDoc at all on the pin.
+ *
+ * R6-F: this is a LOGIN-FLOW PROGRESS channel (codex-oauth login/refresh), never the
+ * credential-failure frame -- a bad key is a provider error that lands on the result shape.
+ * `isAuthenticating: boolean` + `output: string[]` is a running transcript of an interactive auth
+ * attempt, which is what that shape reads as.
+ */
+export interface SDKAuthStatusMessage {
+    type: "auth_status";
+    isAuthenticating: boolean;
+    output: string[];
+    error?: string;
+    uuid: string;
+    session_id: string;
+}
+/**
+ * `sdk.d.ts:5017-5024` (JSDoc `5015`). NOT gated on `includePartialMessages`: a host that never opts
+ * into `stream_event` still gets thinking progress. `estimated_tokens` is the running total for the
+ * CURRENT thinking block and `estimated_tokens_delta` this frame's increment; both are approximate
+ * progress for a spinner, explicitly not the billed `output_tokens`.
+ */
+export interface SDKThinkingTokensMessage {
+    type: "system";
+    subtype: "thinking_tokens";
+    estimated_tokens: number;
+    estimated_tokens_delta: number;
+    uuid: string;
+    session_id: string;
+}
+/**
+ * `sdk.d.ts:4476-4508` (JSDoc `4474`). `trigger` is the literal `'refusal'` and NOTHING ELSE, and
+ * the JSDoc scopes emission to "the primary model ends the stream with `stop_reason` 'refusal' and
+ * the turn is retried once on a fallback model".
+ *
+ * **A MODEL-REFUSAL FALLBACK IS NOT AN OVERLOAD FALLBACK** (R6-C). Capture (G) confirmed the overload
+ * swap is FRAME-INVISIBLE on the pin; Winter emits its own `system/model_switch` for that and this
+ * pinned pair only on `stopReason: "refusal"`.
+ *
+ * `direction`'s `'revert'`/`'sticky'` are doc-marked as retained for consumer compat and no longer
+ * emitted. `api_refusal_explanation` is doc-marked unstable human prose, display-only, NEVER to be
+ * parsed -- a rule Winter carries verbatim.
+ */
+export interface SDKModelRefusalFallbackMessage {
+    type: "system";
+    subtype: "model_refusal_fallback";
+    trigger: "refusal";
+    direction: "retry" | "revert" | "sticky";
+    scope?: "session" | "local";
+    original_model: string;
+    fallback_model: string;
+    request_id: string | null;
+    api_refusal_category?: string | null;
+    api_refusal_explanation?: string | null;
+    retracted_message_uuids?: string[];
+    refused_user_message_uuid?: string | null;
+    content: string;
+    uuid: string;
+    session_id: string;
+}
+/** `sdk.d.ts:4513-4523` (JSDoc `4511`): the refusal produced NO retry. Nine fields -- no `direction`/`scope`/`fallback_model`, because there is no fallback to name. */
+export interface SDKModelRefusalNoFallbackMessage {
+    type: "system";
+    subtype: "model_refusal_no_fallback";
+    trigger: "refusal";
+    original_model: string;
+    request_id: string | null;
+    api_refusal_category?: string | null;
+    api_refusal_explanation?: string | null;
+    retracted_message_uuids?: string[];
+    refused_user_message_uuid?: string | null;
+    content: string;
+    uuid: string;
+    session_id: string;
+}
+/**
+ * R6-8: a foreign model's reasoning SUMMARY, surfaced live WITHOUT entering the transcript.
+ *
+ * Capture (F) settled why this frame has to exist: the pinned runtime never emits or replays a
+ * thinking block without a `signature` key -- when the stream carries none it materialises `""` -- so
+ * a foreign summary written into `assistant.message.content` as a `thinking` block would go on the
+ * wire carrying an empty or fabricated signature. That is precisely the impersonation R6-8 forbids,
+ * and the pin offers no mechanism to omit the field instead. The summary therefore lives in the
+ * provider-state sidecar and rides this frame; Anthropic-family thinking/redacted blocks ride
+ * in-dialect with their REAL signatures, exactly as before.
+ */
+export interface SDKReasoningSummaryMessage {
+    type: "system";
+    subtype: "reasoning_summary";
+    text: string;
+    provider: string;
+    model: string;
+    uuid: string;
+    session_id: string;
+}
+/**
+ * R6-C: the model this session is generating with CHANGED, and the pin has no frame that says so.
+ *
+ * `reason` distinguishes the three producers: `"fallback"` (the primary was abandoned per
+ * `fallbackModel`), `"set_model"` (a host asked, applied at the quiescent boundary), and
+ * `"interrupt"` (a pending switch applied immediately because the turn was interrupted). The swap is
+ * additionally recorded in the dialect record's `providerHistory`, so a transcript reader can
+ * reconstruct which model produced which entry after the fact.
+ */
+export interface SDKModelSwitchMessage {
+    type: "system";
+    subtype: "model_switch";
+    reason: "fallback" | "set_model" | "interrupt";
+    from_model: string;
+    to_model: string;
+    provider: string;
+    uuid: string;
+    session_id: string;
+}
+/**
+ * R6-7: a resume found the provider-state chain incomplete, so some message was degraded.
+ *
+ * THE SIMPLEST OF THE TWO CHANNELS THE PLAN OFFERED, and the choice is recorded here rather than left
+ * implicit: the alternative was a warning list threaded onto the history renderer's input, but the
+ * renderer is Lane C's and the ledger pins `ContinuationChain` as the bare `Map` `buildContinuationChain`
+ * returns -- a warning list would have had to ride a second, parallel return value through a frozen
+ * signature. A frame reaches the host directly, needs no seam, and is where a user-visible degradation
+ * belongs.
+ *
+ * `detail` is Winter-authored prose about COUNTS and IDENTITY only. It never names or contains opaque
+ * provider state (Global Constraints).
+ */
+export interface SDKContinuityWarningMessage {
+    type: "system";
+    subtype: "continuity_warning";
+    /**
+     * Five values (P6 fix wave). `provider_state_missing` / `provider_state_deleted` /
+     * `sidecar_unreadable` are emitted on a RESUME (`store/continuation-attach.ts`);
+     * `cross_domain_replay_dropped` at a MODEL SWITCH whose loss class is `warned-lossy` (Ruling E-2,
+     * `applyPendingModelSwitch`); `child_provider_refused` when an R6-17 child named a model on
+     * ANOTHER provider for which no credential is configured (Ruling E-1 / R-E3) -- the child then
+     * runs on a deferred-refusal provider whose first generation is R6-F's result with no request,
+     * never the parent's provider with a foreign model id on the parent's wire.
+     */
+    warning: "provider_state_missing" | "provider_state_deleted" | "cross_domain_replay_dropped" | "sidecar_unreadable" | "child_provider_refused";
+    detail: string;
+    anchor_uuid?: string;
+    uuid: string;
+    session_id: string;
+}
+export type SdkMessage = {
+    type: "system";
+    subtype: "init";
+    session_id: string;
+    cwd: string;
+    model: string;
+    permissionMode: string;
+    tools: string[];
+    slash_commands: string[];
+    terminal_slash_commands?: string[];
+    output_style: string;
+    skills: string[];
+    plugins: InitPluginInfo[];
+    mcp_servers?: WireMcpServerStatus[];
+    [k: string]: unknown;
+} | SDKHookStartedMessage | SDKHookProgressMessage | SDKHookResponseMessage | SDKPermissionDeniedMessage | SDKStatusMessage | SDKCompactBoundaryMessage | BackgroundTaskMessage | SDKPartialAssistantMessage | SDKAPIRetryMessage | SDKRateLimitEvent | SDKAuthStatusMessage | SDKThinkingTokensMessage | SDKModelRefusalFallbackMessage | SDKModelRefusalNoFallbackMessage | SDKReasoningSummaryMessage | SDKModelSwitchMessage | SDKContinuityWarningMessage | {
+    type: "assistant";
+    message: {
+        content: Array<{
+            type: "text";
+            text: string;
+        } | {
+            type: string;
+            [k: string]: unknown;
+        }>;
+    };
+    parent_tool_use_id?: string | null;
+    [k: string]: unknown;
+} | {
+    type: "user";
+    message: {
+        role: "user";
+        content: Array<{
+            type: string;
+            [k: string]: unknown;
+        }>;
+    };
+    parent_tool_use_id?: string | null;
+    [k: string]: unknown;
+} | {
+    type: "result";
+    subtype: "success" | "error_max_turns" | "error_during_execution" | "error_max_budget_usd" | "error_max_structured_output_retries" | string;
+    is_error?: boolean;
+    result?: string;
+    structured_output?: unknown;
+    terminal_reason?: "structured_output_retry_exhausted" | "api_error" | string;
+    api_error_status?: number | null;
+    permission_denials: SDKPermissionDenial[];
+    [k: string]: unknown;
+} | {
+    type: string;
+    [k: string]: unknown;
+};

package/dist/query.d.ts

@@ -0,0 +1,81 @@
+import type { SdkMessage as RuntimeSdkMessage } from "./protocol/frames.js";
+import type { AccountInfo, ModelInfo, ModelFamilyListing, RewindFilesResult } from "./protocol/config.js";
+import { type Options } from "./options.js";
+import type { PermissionMode, PermissionResult } from "./permissions/types.js";
+export type SdkMessage = Extract<RuntimeSdkMessage, {
+    type: "system";
+} | {
+    type: "assistant";
+} | {
+    type: "result";
+}>;
+export type ControlRequestHandlerResult = {
+    ok: true;
+    payload?: unknown;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+export type ControlRequestHandler = (payload: unknown) => Promise<ControlRequestHandlerResult>;
+export interface QueryInternal {
+    registerControlRequestHandler(subtype: string, handler: ControlRequestHandler): void;
+    respondPermission(requestId: string, result: PermissionResult): void;
+}
+export interface Query extends AsyncGenerator<SdkMessage> {
+    interrupt(): Promise<void>;
+    setModel(model?: string): Promise<void>;
+    /**
+     * Phase 6 Task 10 (derived-shapes-p6 item (d), `sdk.d.ts:2566`): the models this session may select.
+     *
+     * A BARE ARRAY — no envelope, no default marker, no "current model" field; the current model is read
+     * from `system/init.model` instead, and no pinned `Query` method returns it. Served from the
+     * worker's own registry (capture (J): the pinned runtime issues no `/v1/models` request for this),
+     * so the answer is a table lookup rather than a network round trip.
+     */
+    supportedModels(): Promise<ModelInfo[]>;
+    /**
+     * WS-13c §7 (P6.6 Lane C) — WINTER-ONLY, no pinned counterpart: the active slot set this session is
+     * currently offering, plus every model family behind "more options". A model switcher shows
+     * `active.slots` first and renders `families[].models` any way it likes (§7's own last sentence).
+     *
+     * Rides its own `list_model_families` control subtype, same shape as `supportedModels`/`accountInfo`
+     * above. A malformed or absent runtime payload degrades to `{ active: undefined, families: [] }`
+     * rather than a throw — this method answers with data, so a rejected promise could not tell "no
+     * families configured" from a transport fault.
+     */
+    listModelFamilies(): Promise<ModelFamilyListing>;
+    /**
+     * `AccountInfo` for this session (`sdk.d.ts:2632`). Every field is optional and an empty object is a
+     * valid answer — capture (J) observed exactly three keys present under API-key auth.
+     *
+     * DISCLOSED DIVERGENCE IN THE TRANSPORT, not in the shape: the pin carries `AccountInfo` on the
+     * `initialize`/`reinitialize` response, a surface Winter's protocol does not have, so this rides its
+     * own Winter-only `account_info` control subtype. The public method and its return shape are the
+     * pin's.
+     */
+    accountInfo(): Promise<AccountInfo>;
+    /**
+     * Phase 5 Task 3 (R5-11, derived-shapes-p5 item (e)): restore every tracked file to its state at
+     * `userMessageId`. Requires `enableFileCheckpointing`; without it the result is
+     * `{canRewind: false, error}`, never a throw.
+     *
+     * The parameter is `userMessageId` on the pin -- its own `@param` line describes the VALUE as a
+     * uuid, so the name and the value disagree; WS-11 §9 and the phase plan both wrote
+     * `userMessageUuid` and are corrected here to the shape authority.
+     *
+     * `dryRun` previews without touching the filesystem -- and, per item (e), without populating
+     * `skippedLinks`, so a preview's counts do not reflect link-safety refusals.
+     */
+    rewindFiles(userMessageId: string, options?: {
+        dryRun?: boolean;
+    }): Promise<RewindFilesResult>;
+    setPermissionMode(mode: PermissionMode): Promise<void>;
+    __internal?: QueryInternal;
+}
+export declare function query(args: {
+    prompt: string | AsyncIterable<string>;
+    options: Options;
+}): Query;