@margay/ccl-core 1.4.5-rc.8 → 1.4.6-beta.0

package/dist/sdk/index.d.ts

@@ -7,8 +7,10 @@
  */
 export { buildCliArgs, buildCliEnv, decideFailClosed, getSessionUsage, prepareSkillsWrappers, queryWithTransport, resumeWithDecision, } from './query.js';
 export { query, queryHandleWithTransport } from './queryHandle.js';
+export { createSession, Session, type SessionOptions, type SessionControls, type Turn, type TurnResult } from './session.js';
 export { createSdkMcpServer, tool, SdkMcpRegistry, type SdkMcpToolDefinition, type McpSdkServerConfigWithInstance, } from './mcpServer.js';
 export { defaultStoreDir, fileSessionStore } from './store.js';
 export { spawnCliTransport } from './transport.js';
 export type { RecoveryDiagnostic } from './errorDiagnostics.js';
-export type { AccumulatedUsage, CanUseToolContext, CanUseToolFn, CanUseToolResult, InitializationResult, LifecycleHooks, PendingApproval, PendingDecision, ProviderConfig, Query, QueryOptions, SDKEvent, SessionStore, Transport, Usage, WireMessage, } from './types.js';
+export type { GatewayRequestPhase, GatewayRequestProgress } from './requestProgress.js';
+export type { AccumulatedUsage, CanUseToolContext, CanUseToolFn, CanUseToolResult, InitializationResult, LifecycleHooks, PendingApproval, PendingDecision, ProviderConfig, Query, QueryOptions, SDKEvent, SDKUserMessage, SessionStore, Transport, Usage, WireMessage, } from './types.js';

package/dist/sdk/index.js

@@ -7,6 +7,7 @@
  */
 export { buildCliArgs, buildCliEnv, decideFailClosed, getSessionUsage, prepareSkillsWrappers, queryWithTransport, resumeWithDecision, } from './query.js';
 export { query, queryHandleWithTransport } from './queryHandle.js';
+export { createSession, Session } from './session.js';
 export { createSdkMcpServer, tool, SdkMcpRegistry, } from './mcpServer.js';
 export { defaultStoreDir, fileSessionStore } from './store.js';
 export { spawnCliTransport } from './transport.js';

package/dist/sdk/query.d.ts

@@ -1,32 +1,5 @@
-/**
- * ccl-sdk query() — the programmatic headless entry (issue P0-1) with the
- * canUseTool permission callback (P0-2 including pending suspend/resume),
- * session store integration (P0-3), provider mapping (P0-4), skills dirs
- * (P1-5), lifecycle hooks (P1-6), and usage accumulation (P1-7).
- *
- * Architecture: the SDK is the HOST side of the stream-json control protocol
- * that cli/print.ts already implements. We run the CLI as a managed
- * subprocess (explicitly allowed by the issue's "进程内(或受管子进程)"),
- * which keeps every user-visible CLI behavior — tools, skills, hooks, session
- * persistence, gateway routing — byte-identical between CLI and SDK use.
- *
- * Pending suspend/resume mechanism (P0-2, zero CLI changes):
- * - Suspend: on a `pending` callback result we persist the approval record,
- *   terminate the subprocess WITHOUT answering the can_use_tool request, and
- *   end the stream with a `suspended` event. The transcript on disk ends at
- *   the assistant tool_use whose tool never ran.
- * - Resume: resumeWithDecision() relaunches with --resume <sessionId> and
- *   CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1. The CLI's resume path drops the
- *   unresolved tool_use (filterUnresolvedToolUses) and auto-continues the
- *   interrupted turn (cli/print.ts:1195), so the model re-issues the tool
- *   call; the SDK intercepts the matching can_use_tool request and applies
- *   the recorded decision — on allow, with EXACTLY the approved input (the
- *   recorded pending input, or the host's updatedInput), regardless of what
- *   the model re-generated. Deny works symmetrically. One-shot: the record
- *   is deleted after it is applied.
- */
 import { type InteractionResponse } from './interactionResponseSchema.js';
-import type { CanUseToolFn, PendingDecision, QueryOptions, SDKEvent, SessionStore, Transport } from './types.js';
+import type { CanUseToolFn, PendingDecision, QueryOptions, SDKEvent, SDKUserMessage, SessionStore, Transport } from './types.js';
 /** Builds the CLI argv for a query. Exported for unit tests. */
 export declare function buildCliArgs(options: QueryOptions): string[];
 /** Builds subprocess env additions. Exported for unit tests. */
@@ -68,7 +41,7 @@ export declare function decideFailClosed(callback: CanUseToolFn, toolName: strin
  * Core loop, transport-injectable for tests. Production callers use query()
  * or resumeWithDecision().
  */
-export declare function queryWithTransport(prompt: string | null, options: QueryOptions, transport: Transport): AsyncGenerator<SDKEvent>;
+export declare function queryWithTransport(prompt: string | null | AsyncIterable<SDKUserMessage>, options: QueryOptions, transport: Transport): AsyncGenerator<SDKEvent>;
 /** Spawns the managed CLI subprocess for a set of options. Shared with the P1 Query handle. */
 export declare function spawnForOptions(options: QueryOptions): Transport;
 /**

package/dist/sdk/query.js

@@ -1,3 +1,4 @@
+import { sanitizeRequestProgress } from './requestProgress.js';
 /**
  * ccl-sdk query() — the programmatic headless entry (issue P0-1) with the
  * canUseTool permission callback (P0-2 including pending suspend/resume),
@@ -34,6 +35,7 @@ import { fileURLToPath } from 'url';
 import { SdkMcpRegistry } from './mcpServer.js';
 import { fileSessionStore } from './store.js';
 import { spawnCliTransport } from './transport.js';
+import { isAsyncInput, readWithInput } from './queryInput.js';
 const DEFAULT_CAN_USE_TOOL_TIMEOUT_MS = 300_000;
 /** Builds the CLI argv for a query. Exported for unit tests. */
 export function buildCliArgs(options) {
@@ -89,6 +91,8 @@ export function buildCliArgs(options) {
         args.push('--include-partial-messages');
     if (options.includeErrorDiagnostics)
         args.push('--include-error-diagnostics');
+    if (options.includeRequestProgress)
+        args.push('--include-request-progress');
     // slice sdk-input-external-mcp (G2): external MCP servers via --mcp-config (JSON string).
     if (options.mcpServers && Object.keys(options.mcpServers).length > 0) {
         args.push('--mcp-config', JSON.stringify({ mcpServers: options.mcpServers }));
@@ -253,6 +257,8 @@ export async function* queryWithTransport(prompt, options, transport) {
     let turn = 0;
     let sawResult = false;
     let sessionEnded = false;
+    const streamingInput = isAsyncInput(prompt);
+    const inputState = { finished: false };
     // resumeWithDecision path: the recorded approval this run must settle.
     let pendingApproval = null;
     let pendingDecision = options.pendingDecision;
@@ -267,6 +273,8 @@ export async function* queryWithTransport(prompt, options, transport) {
     }
     const onAbort = () => void transport.close();
     options.signal?.addEventListener('abort', onAbort, { once: true });
+    if (options.signal?.aborted)
+        onAbort();
     // slice sdk-in-process-mcp-server: host-defined in-process MCP servers, bridged to the subprocess
     // agent over the control protocol. The registry replies to each `mcp_message` control_request with
     // its server's JSONRPC response ({ mcp_response }). null when the host passed no sdkMcpServers.
@@ -307,7 +315,7 @@ export async function* queryWithTransport(prompt, options, transport) {
         });
         // On pending-decision resume the CLI auto-continues the interrupted turn
         // (CLAUDE_CODE_RESUME_INTERRUPTED_TURN); a prompt would double-drive it.
-        if (prompt !== null && !pendingDecision) {
+        if (typeof prompt === 'string' && !pendingDecision) {
             // slice sdk-input-external-mcp (G6): multimodal input — host-provided content blocks replace
             // the plain-text content when set; otherwise the string prompt is a single text block.
             const userContent = options.promptContentBlocks && options.promptContentBlocks.length > 0
@@ -324,11 +332,29 @@ export async function* queryWithTransport(prompt, options, transport) {
         }
         // slice sdk-observability-hooks-usage (G5): fire onSessionStart once, on the first session_id.
         let sessionStarted = false;
-        for await (const rawMessage of transport.read()) {
+        const messages = streamingInput
+            ? readWithInput(prompt, transport, inputState, async (message) => {
+                sawResult = false;
+                const text = typeof message.message.content === 'string' ? message.message.content
+                    : message.message.content.filter(b => b.type === 'text').map(b => b.text).join('\n');
+                await runHook(hooks.onUserPromptSubmit && (() => hooks.onUserPromptSubmit({ prompt: text, sessionId: lastSessionId })));
+            })
+            : transport.read();
+        for await (const rawMessage of messages) {
             // Keep ordinary raw passthrough unchanged. Diagnostic payloads are an
             // untrusted error boundary even when a host asks for raw wire events.
-            const message = rawMessage.type === 'system' && rawMessage.subtype === 'error_diagnostic'
-                ? sanitizeErrorEnvelope(rawMessage) : rawMessage;
+            if (rawMessage.type === 'system' && rawMessage.subtype === 'request_progress' && !options.includeRequestProgress)
+                continue;
+            const progress = rawMessage.type === 'system' && rawMessage.subtype === 'request_progress'
+                ? sanitizeRequestProgress(rawMessage.progress) : undefined;
+            if (rawMessage.type === 'system' && rawMessage.subtype === 'request_progress' && !progress)
+                continue;
+            const message = progress
+                ? { type: 'system', subtype: 'request_progress', progress,
+                    ...(typeof rawMessage.session_id === 'string' ? { session_id: rawMessage.session_id } : {}),
+                    ...(typeof rawMessage.uuid === 'string' ? { uuid: rawMessage.uuid } : {}) }
+                : rawMessage.type === 'system' && rawMessage.subtype === 'error_diagnostic'
+                    ? sanitizeErrorEnvelope(rawMessage) : rawMessage;
             if (typeof message.session_id === 'string') {
                 lastSessionId = message.session_id;
                 if (!sessionStarted) {
@@ -341,6 +367,11 @@ export async function* queryWithTransport(prompt, options, transport) {
                 yield { type: 'raw', message };
             switch (message.type) {
                 case 'system': {
+                    if (message.subtype === 'request_progress' && progress)
+                        yield {
+                            type: 'request_progress', progress,
+                            sessionId: typeof message.session_id === 'string' ? message.session_id : undefined,
+                        };
                     if (message.subtype === 'error_diagnostic') {
                         const diagnostic = sanitizeRecoveryDiagnostic(message.diagnostic);
                         if (diagnostic)
@@ -615,6 +646,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                     }
                     yield {
                         type: 'result',
+                        ...(streamingInput ? { turnId: inputState.turnId } : {}),
                         subtype: String(message.subtype ?? 'unknown'),
                         usage,
                         totalCostUsd,
@@ -634,14 +666,15 @@ export async function* queryWithTransport(prompt, options, transport) {
                         structuredOutput: message
                             .structured_output,
                     };
-                    sessionEnded = true;
-                    await runHook(hooks.onSessionEnd &&
-                        (() => hooks.onSessionEnd({
-                            sessionId,
-                            subtype: String(message.subtype ?? 'unknown'),
-                            isError: message.is_error === true,
-                            usage,
-                        })));
+                    sessionEnded = !streamingInput;
+                    if (!streamingInput)
+                        await runHook(hooks.onSessionEnd &&
+                            (() => hooks.onSessionEnd({
+                                sessionId,
+                                subtype: String(message.subtype ?? 'unknown'),
+                                isError: message.is_error === true,
+                                usage,
+                            })));
                     break;
                 }
                 case 'stream_event': {
@@ -660,10 +693,15 @@ export async function* queryWithTransport(prompt, options, transport) {
                 default:
                     break;
             }
-            if (sawResult)
+            if (sawResult && !streamingInput)
                 break;
         }
-        if (!sawResult) {
+        if (streamingInput && inputState.finished) {
+            await runHook(hooks.onSessionEnd && (() => hooks.onSessionEnd({
+                sessionId: lastSessionId, subtype: 'input_complete', isError: false,
+            })));
+        }
+        else if (!sawResult || streamingInput) {
             const code = await transport.exited;
             const aborted = options.signal?.aborted === true;
             yield {

package/dist/sdk/queryHandle.d.ts

@@ -23,19 +23,19 @@
  *   supportedAgents()/accountInfo() serve it, and reinitialize() sends a new
  *   initialize (fresh request_id) and refreshes the cache.
  */
-import type { Query, QueryOptions, Transport } from './types.js';
+import type { Query, QueryOptions, SDKUserMessage, Transport } from './types.js';
 /**
  * Test-injection seam for the P1 Query handle, mirroring queryWithTransport.
  * Production callers use query().
  */
-export declare function queryHandleWithTransport(prompt: string | null, options: QueryOptions, transport: Transport): Query;
+export declare function queryHandleWithTransport(prompt: string | null | AsyncIterable<SDKUserMessage>, options: QueryOptions, transport: Transport): Query;
 /** @deprecated Use the object form query({ prompt, options }) instead. */
-export declare function query(prompt: string | AsyncIterable<unknown>, options?: QueryOptions): Query;
+export declare function query(prompt: string | AsyncIterable<SDKUserMessage>, options?: QueryOptions): Query;
 /**
  * Run one prompt against a CCL agent session and return a Query handle: the
  * async stream of SDKEvents plus the control methods of the wire protocol.
  */
 export declare function query(params: {
-    prompt: string;
+    prompt: string | AsyncIterable<SDKUserMessage>;
     options?: QueryOptions;
 }): Query;

package/dist/sdk/queryHandle.js

@@ -24,6 +24,7 @@
  *   initialize (fresh request_id) and refreshes the cache.
  */
 import { queryWithTransport, spawnForOptions } from './query.js';
+import { isAsyncInput } from './queryInput.js';
 let requestCounter = 0;
 const nextRequestId = () => `ccl-sdk-req-${++requestCounter}-${Math.random().toString(36).slice(2, 10)}`;
 class QueryHandle {
@@ -66,7 +67,10 @@ class QueryHandle {
     initPromise;
     initResolve;
     initReject;
+    streamingInput;
+    cancelPermission;
     constructor(prompt, options, transport) {
+        this.streamingInput = isAsyncInput(prompt);
         this.transport = transport;
         this.options = options;
         this.innerRead = transport.read()[Symbol.asyncIterator]();
@@ -77,16 +81,41 @@ class QueryHandle {
         // The init promise is settled internally; hosts that never ask for the
         // initialization result must not see an unhandled rejection.
         this.initPromise.catch(() => { });
-        void this.pump(prompt, options);
+        void transport.exited.then(() => this.cancelPermission?.(), () => this.cancelPermission?.());
+        const callback = options.canUseTool;
+        void this.pump(prompt, callback ? {
+            ...options,
+            canUseTool: async (...args) => {
+                let cancel;
+                const cancelled = new Promise(resolve => {
+                    cancel = () => resolve({ behavior: 'deny', message: 'Permission wait cancelled by host', interrupt: true });
+                });
+                this.cancelPermission = cancel;
+                try {
+                    return await Promise.race([Promise.resolve().then(() => callback(...args)), cancelled]);
+                }
+                finally {
+                    if (this.cancelPermission === cancel)
+                        this.cancelPermission = undefined;
+                }
+            },
+        } : options);
     }
     // ------------------------------------------------------------- event pump
     async pump(prompt, options) {
         try {
             for await (const event of queryWithTransport(prompt, options, this.tap())) {
+                // Long-lived streams must not retain unlimited output when the host
+                // stops reading. Fail explicitly rather than dropping agent events.
+                if (this.streamingInput && this.eventQueue.length >= 1024) {
+                    await this.transport.close();
+                    throw new Error('ccl-sdk: streamed query event buffer exceeded 1024 events; consume events as they arrive');
+                }
                 this.eventQueue.push(event);
                 if (event.type === 'result') {
                     this.resultDelivered = true;
-                    this.markEnded('ccl-sdk: query has ended (result delivered)');
+                    if (!this.streamingInput)
+                        this.markEnded('ccl-sdk: query has ended (result delivered)');
                 }
                 this.notifyEventWaiters();
             }
@@ -99,7 +128,7 @@ class QueryHandle {
             // Normal completion (result) is a SOFT end — the child stays alive for
             // post-run control requests until close(). Every other exit (stream
             // ended, suspended, error) really closed the transport: hard end.
-            if (!this.resultDelivered) {
+            if (!this.resultDelivered || this.streamingInput) {
                 this.markDead('ccl-sdk: query has ended (transport closed)');
             }
             this.notifyEventWaiters();
@@ -130,7 +159,7 @@ class QueryHandle {
                 // requests after the result, which is what makes the post-run
                 // rewind_files round-trip possible. Abort/error paths (no result)
                 // close for real, exactly as before.
-                if (this.resultDelivered && !this.transportDead)
+                if (this.resultDelivered && !this.transportDead && !this.streamingInput)
                     return;
                 await inner.close();
             },
@@ -153,7 +182,8 @@ class QueryHandle {
             // The inner event loop stopped consuming (result delivered / early
             // return). Keep observing control_responses on the SAME iterator so
             // post-run control requests (rewind_files) still settle.
-            this.startResidualReader();
+            if (!this.streamingInput)
+                this.startResidualReader();
         }
     }
     /** Post-loop observer: drains the shared read iterator after the inner
@@ -259,6 +289,7 @@ class QueryHandle {
         });
     }
     interrupt() {
+        this.cancelPermission?.();
         return this.controlRequest({ subtype: 'interrupt' });
     }
     setPermissionMode(mode) {
@@ -341,6 +372,7 @@ class QueryHandle {
         return (await this.initializationResult()).account;
     }
     async close() {
+        this.cancelPermission?.();
         this.markDead('ccl-sdk: query closed');
         await this.transport.close();
     }
@@ -400,15 +432,18 @@ export function queryHandleWithTransport(prompt, options, transport) {
     return new QueryHandle(prompt, options, transport);
 }
 export function query(promptOrParams, positionalOptions) {
-    const positional = typeof promptOrParams === 'string' ||
-        (typeof promptOrParams === 'object' &&
-            promptOrParams !== null &&
-            Symbol.asyncIterator in promptOrParams);
+    const positional = typeof promptOrParams === 'string' || isAsyncInput(promptOrParams);
     const prompt = positional
         ? promptOrParams
         : promptOrParams.prompt;
     const options = (positional
         ? positionalOptions
         : promptOrParams.options) ?? {};
+    if (typeof prompt !== 'string' && !isAsyncInput(prompt)) {
+        throw new TypeError('ccl-sdk: prompt must be a string or an AsyncIterable of user messages');
+    }
+    if (isAsyncInput(prompt) && options.pendingDecision) {
+        throw new TypeError('ccl-sdk: use resumeWithDecision to resolve a suspended approval before streaming new input');
+    }
     return queryHandleWithTransport(prompt, options, spawnForOptions(options));
 }

package/dist/sdk/queryInput.d.ts

@@ -0,0 +1,13 @@
+import type { SDKUserMessage, Transport, WireMessage } from './types.js';
+export declare function isAsyncInput(value: unknown): value is AsyncIterable<SDKUserMessage>;
+/** Validate at the public input boundary, before sending anything to the CLI. */
+export declare function normalizeUserInput(value: unknown): SDKUserMessage;
+export type InputState = {
+    finished: boolean;
+    turnId?: string;
+};
+/**
+ * One input is in flight at a time. Keep reading controls while the producer
+ * waits, without reading ahead into an unbounded queue of future prompts.
+ */
+export declare function readWithInput(input: AsyncIterable<SDKUserMessage>, transport: Transport, state: InputState, submitted: (message: SDKUserMessage) => Promise<void>): AsyncGenerator<WireMessage>;

package/dist/sdk/queryInput.js

@@ -0,0 +1,70 @@
+import { randomUUID } from 'node:crypto';
+export function isAsyncInput(value) {
+    return value !== null && typeof value === 'object' &&
+        typeof value[Symbol.asyncIterator] === 'function';
+}
+/** Validate at the public input boundary, before sending anything to the CLI. */
+export function normalizeUserInput(value) {
+    const input = value;
+    if (!input || input.type !== 'user' || input.message?.role !== 'user') {
+        throw new TypeError('ccl-sdk: streamed input must be a user message with message.role="user"');
+    }
+    const content = input.message.content;
+    if (typeof content !== 'string' && !(Array.isArray(content) && content.every(block => block !== null && typeof block === 'object' && typeof block.type === 'string' &&
+        (block.type !== 'text' || typeof block.text === 'string')))) {
+        throw new TypeError('ccl-sdk: user message content must be text or content blocks');
+    }
+    if (input.uuid !== undefined && (typeof input.uuid !== 'string' || !input.uuid)) {
+        throw new TypeError('ccl-sdk: user message uuid must be a nonempty string');
+    }
+    return {
+        type: 'user', uuid: input.uuid ?? randomUUID(),
+        message: { role: 'user', content }, parent_tool_use_id: null,
+    };
+}
+/**
+ * One input is in flight at a time. Keep reading controls while the producer
+ * waits, without reading ahead into an unbounded queue of future prompts.
+ */
+export async function* readWithInput(input, transport, state, submitted) {
+    const source = input[Symbol.asyncIterator]();
+    const wire = transport.read()[Symbol.asyncIterator]();
+    const pull = () => Promise.resolve().then(() => source.next()).then(value => ({ kind: 'input', value }), error => ({ kind: 'input-error', error }));
+    let pendingInput = pull();
+    let pendingWire;
+    try {
+        for (;;) {
+            pendingWire ??= wire.next().then(value => ({ kind: 'wire', value }));
+            const next = await Promise.race(pendingInput ? [pendingWire, pendingInput] : [pendingWire]);
+            if (next.kind === 'input-error')
+                throw next.error;
+            if (next.kind === 'input') {
+                pendingInput = undefined;
+                if (next.value.done) {
+                    state.finished = true;
+                    return;
+                }
+                const message = normalizeUserInput(next.value.value);
+                state.turnId = message.uuid;
+                await transport.write(message);
+                await submitted(message);
+            }
+            else {
+                pendingWire = undefined;
+                if (next.value.done)
+                    return;
+                yield next.value.value;
+                if (next.value.value.type === 'result') {
+                    state.turnId = undefined;
+                    pendingInput = pull();
+                }
+            }
+        }
+    }
+    finally {
+        // A producer may be waiting on user code forever. Request cancellation,
+        // but never let an uncooperative iterator prevent subprocess cleanup.
+        void Promise.resolve().then(() => source.return?.()).catch(() => { });
+        void Promise.resolve().then(() => wire.return?.()).catch(() => { });
+    }
+}

package/dist/sdk/requestProgress.d.ts

@@ -0,0 +1,14 @@
+/** Nonterminal gateway status. It is not model output or permission to retry. */
+export type GatewayRequestPhase = 'preparing' | 'connecting' | 'sending' | 'waiting_response' | 'response_headers' | 'retry_wait' | 'streaming' | 'finished';
+export type GatewayRequestProgress = {
+    requestId: string;
+    phase: GatewayRequestPhase;
+    attempt: number;
+    elapsedMs: number;
+    /** Age of the last effective model event, never of a status notification. */
+    idleMs: number;
+    slow: boolean;
+};
+/** Allow-listed projection at the child-process boundary; never forwards arbitrary text. */
+export declare function sanitizeRequestProgress(value: unknown): GatewayRequestProgress | undefined;
+export declare function formatRequestProgress(event: GatewayRequestProgress): string | null;

package/dist/sdk/requestProgress.js

@@ -0,0 +1,26 @@
+const phases = new Set(['preparing', 'connecting', 'sending', 'waiting_response', 'response_headers', 'retry_wait', 'streaming', 'finished']);
+/** Allow-listed projection at the child-process boundary; never forwards arbitrary text. */
+export function sanitizeRequestProgress(value) {
+    if (!value || typeof value !== 'object')
+        return;
+    const v = value;
+    if (typeof v.requestId !== 'string' || !/^[a-zA-Z0-9_.:-]{1,128}$/.test(v.requestId) ||
+        !phases.has(v.phase) || typeof v.slow !== 'boolean')
+        return;
+    for (const name of ['attempt', 'elapsedMs', 'idleMs']) {
+        if (!Number.isSafeInteger(v[name]) || v[name] < 0)
+            return;
+    }
+    return { requestId: v.requestId, phase: v.phase, attempt: v.attempt,
+        elapsedMs: v.elapsedMs, idleMs: v.idleMs, slow: v.slow };
+}
+export function formatRequestProgress(event) {
+    if (event.phase === 'finished' || (event.phase === 'streaming' && !event.slow))
+        return null;
+    const labels = {
+        preparing: 'Preparing request', connecting: 'Connecting to gateway', sending: 'Sending request',
+        waiting_response: 'Waiting for gateway response', response_headers: 'Reading gateway response',
+        retry_wait: 'Waiting to retry gateway request', streaming: 'Waiting for model progress',
+    };
+    return `${labels[event.phase]}${event.slow ? ` (${Math.floor(event.idleMs / 1000)}s without model progress; Esc to cancel)` : ''}`;
+}

package/dist/sdk/session.d.ts

@@ -0,0 +1,48 @@
+import type { Query, QueryOptions, SDKEvent, SDKUserMessage, Transport } from './types.js';
+export type TurnResult = Extract<SDKEvent, {
+    type: 'result';
+}>;
+export type SessionControls = Omit<Query, keyof AsyncGenerator<SDKEvent, void, unknown>>;
+export type SessionOptions = QueryOptions & {
+    /** Maximum accepted but not yet completed turns, including the active turn. */
+    maxPendingTurns?: number;
+    /** Events are delivered as they arrive; Session does not retain an event history. */
+    onEvent?: (event: SDKEvent) => void;
+};
+export interface Turn {
+    readonly id: string;
+    readonly result: Promise<TurnResult>;
+    cancel(): Promise<void>;
+}
+/** One CLI process, sequential turns, and a bounded host-side input queue. */
+export declare class Session {
+    readonly pid: number | undefined;
+    /** Existing SDK controls, including initialization, model and task controls. */
+    readonly controls: SessionControls;
+    private readonly handle;
+    private readonly limit;
+    private readonly options;
+    private queue;
+    private active?;
+    private wake?;
+    private accepting;
+    private closed;
+    private drainWaiters;
+    private readonly pumping;
+    constructor(options?: SessionOptions, transport?: Transport);
+    prompt(content: SDKUserMessage['message']['content']): Turn;
+    followUp(content: SDKUserMessage['message']['content']): Turn;
+    /** Interrupt the active turn; correction runs before queued follow-ups. */
+    steer(content: SDKUserMessage['message']['content']): Turn;
+    private enqueue;
+    private inputs;
+    private consume;
+    private fail;
+    private notifyDrained;
+    interrupt(): Promise<void>;
+    private cancel;
+    /** Stop accepting inputs and drain accepted turns, keeping controls alive. */
+    endInput(): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function createSession(options?: SessionOptions): Session;