@margay/ccl-core 1.4.5-rc.9 → 1.5.0-alpha.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, SessionLifecycleEvent, 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, normalizeUserInput, 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 }));
@@ -249,10 +253,13 @@ export async function* queryWithTransport(prompt, options, transport) {
     const hooks = options.hooks ?? {};
     const ownRequestIds = new Set();
     const toolNamesById = new Map();
+    const toolOrigins = new Map();
     let lastSessionId = options.sessionId ?? options.resume;
     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 +274,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,28 +316,50 @@ 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
                 ? options.promptContentBlocks
                 : [{ type: 'text', text: prompt }];
-            await transport.write({
+            await transport.write(normalizeUserInput({
                 type: 'user',
                 message: { role: 'user', content: userContent },
                 parent_tool_use_id: null,
-            });
+            }));
             // slice sdk-observability-hooks-usage (G5): the host's prompt was submitted to the agent.
             await runHook(hooks.onUserPromptSubmit &&
                 (() => hooks.onUserPromptSubmit({ prompt, sessionId: lastSessionId })));
         }
         // 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) {
+            let attribution = rawMessage.input_uuid === null
+                ? { origin: 'background' } : typeof rawMessage.input_uuid === 'string'
+                ? { origin: 'user', turnId: rawMessage.input_uuid }
+                : streamingInput && inputState.turnId ? { turnId: inputState.turnId } : {};
             // 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) {
@@ -338,13 +369,18 @@ export async function* queryWithTransport(prompt, options, transport) {
                 }
             }
             if (options.includeRaw)
-                yield { type: 'raw', message };
+                yield { ...attribution, type: 'raw', message };
             switch (message.type) {
                 case 'system': {
+                    if (message.subtype === 'request_progress' && progress)
+                        yield { ...attribution,
+                            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)
-                            yield {
+                            yield { ...attribution,
                                 type: 'error_diagnostic', diagnostic,
                                 sessionId: typeof message.session_id === 'string' ? message.session_id : undefined,
                             };
@@ -355,19 +391,19 @@ export async function* queryWithTransport(prompt, options, transport) {
                     const sessionId = message.session_id;
                     for (const block of contentBlocks(message.message)) {
                         if (block.type === 'text' && typeof block.text === 'string') {
-                            yield { type: 'assistant_text', text: block.text, sessionId };
+                            yield { ...attribution, type: 'assistant_text', text: block.text, sessionId };
                         }
                         else if (block.type === 'tool_use') {
                             const toolUseId = String(block.id ?? '');
                             const toolName = String(block.name ?? '');
                             toolNamesById.set(toolUseId, toolName);
-                            yield {
+                            toolOrigins.set(toolUseId, attribution);
+                            yield { ...attribution,
                                 type: 'tool_use',
                                 toolName,
                                 input: (block.input ?? {}),
                                 toolUseId,
-                                sessionId,
-                            };
+                                sessionId, };
                         }
                     }
                     turn += 1;
@@ -389,7 +425,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                                     : Array.isArray(block.content) ? block.content.map(part => part?.type === 'text' && typeof part.text === 'string' ? { ...part, text: sanitizeErrorText(part.text) } : part)
                                         : describeError(block.content)
                                 : block.content;
-                            yield {
+                            yield { ...attribution,
                                 type: 'tool_result',
                                 toolUseId,
                                 content: resultContent,
@@ -404,6 +440,8 @@ export async function* queryWithTransport(prompt, options, transport) {
                                     isError,
                                     sessionId,
                                 })));
+                            toolOrigins.delete(toolUseId);
+                            toolNamesById.delete(toolUseId);
                         }
                     }
                     break;
@@ -442,8 +480,9 @@ export async function* queryWithTransport(prompt, options, transport) {
                     const toolName = String(request.tool_name ?? '');
                     const input = (request.input ?? {});
                     const toolUseId = String(request.tool_use_id ?? '');
+                    attribution = toolOrigins.get(toolUseId) ?? attribution;
                     const agentId = typeof request.agent_id === 'string' ? request.agent_id : undefined;
-                    yield {
+                    yield { ...attribution,
                         type: 'permission_request',
                         requestId,
                         toolName,
@@ -478,7 +517,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                         await store.deletePendingApproval(pendingApproval.sessionId);
                         pendingDecision = undefined;
                         pendingApproval = null;
-                        yield {
+                        yield { ...attribution,
                             type: 'permission_resolved',
                             requestId,
                             toolUseId,
@@ -515,13 +554,13 @@ export async function* queryWithTransport(prompt, options, transport) {
                                     },
                                 },
                             });
-                            yield {
+                            yield { ...attribution,
                                 type: 'error',
                                 message: 'pending approval requested before any session_id was observed',
                                 fatal: false,
                                 code: 'pending_without_session',
                             };
-                            yield {
+                            yield { ...attribution,
                                 type: 'permission_resolved',
                                 requestId,
                                 toolUseId,
@@ -543,7 +582,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                         // the model must not see a denial. Terminating here leaves the
                         // transcript ending at the unresolved tool_use, which the
                         // resume path drops and re-drives.
-                        yield {
+                        yield { ...attribution,
                             type: 'suspended',
                             sessionId,
                             requestId,
@@ -568,7 +607,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                             response: outcome.decision,
                         },
                     });
-                    yield {
+                    yield { ...attribution,
                         type: 'permission_resolved',
                         requestId,
                         toolUseId,
@@ -587,7 +626,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                     if (ownRequestIds.has(requestId)) {
                         ownRequestIds.delete(requestId);
                         if (response.subtype === 'error') {
-                            yield {
+                            yield { ...attribution,
                                 type: 'error',
                                 message: `initialize failed: ${String(response.error)}`,
                                 fatal: false,
@@ -613,8 +652,9 @@ export async function* queryWithTransport(prompt, options, transport) {
                             // Metering must not break the conversation stream.
                         }
                     }
-                    yield {
+                    yield { ...attribution,
                         type: 'result',
+                        ...(streamingInput ? { turnId: inputState.resultTurnId } : {}),
                         subtype: String(message.subtype ?? 'unknown'),
                         usage,
                         totalCostUsd,
@@ -634,14 +674,21 @@ 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,
-                        })));
+                    for (const [id, origin] of toolOrigins) {
+                        if (origin.turnId === attribution.turnId && origin.origin === attribution.origin) {
+                            toolOrigins.delete(id);
+                            toolNamesById.delete(id);
+                        }
+                    }
+                    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': {
@@ -649,7 +696,7 @@ export async function* queryWithTransport(prompt, options, transport) {
                     // (token-level delta). Only arrives when includePartialMessages passed the flag.
                     const streamEvent = message.event;
                     if (streamEvent && typeof streamEvent.type === 'string') {
-                        yield {
+                        yield { ...attribution,
                             type: 'stream_event',
                             event: streamEvent,
                             sessionId: message.session_id,
@@ -660,10 +707,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,14 @@
+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;
+    resultTurnId?: 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,82 @@
+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;
+                const message = next.value.value;
+                const resultId = Object.prototype.hasOwnProperty.call(message, 'input_uuid')
+                    ? typeof message.input_uuid === 'string' ? message.input_uuid : undefined
+                    : state.turnId; // Compatibility with CLIs predating explicit attribution.
+                const completesInput = message.type === 'result' && state.turnId !== undefined && resultId === state.turnId;
+                if (message.type === 'result')
+                    state.resultTurnId = resultId;
+                yield next.value.value;
+                if (next.value.value.type === 'result') {
+                    if (completesInput)
+                        state.turnId = undefined;
+                    // Scheduled work can finish while the host is already waiting for
+                    // the next user input. Replacing that pull loses its eventual value
+                    // and strands a Session turn behind another source.next().
+                    if (!state.turnId)
+                        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)` : ''}`;
+}