@margay/ccl-core 1.3.5-rc.6

package/dist/sdk/query.js

@@ -0,0 +1,697 @@
+/**
+ * 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 { existsSync, mkdtempSync, symlinkSync } from 'fs';
+import { tmpdir } from 'os';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { SdkMcpRegistry } from './mcpServer.js';
+import { fileSessionStore } from './store.js';
+import { spawnCliTransport } from './transport.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) {
+    const args = [
+        '--print',
+        '--verbose',
+        '--output-format',
+        'stream-json',
+        '--input-format',
+        'stream-json',
+    ];
+    if (options.canUseTool || options.pendingDecision)
+        args.push('--permission-prompt-tool', 'stdio');
+    if (options.model)
+        args.push('--model', options.model);
+    if (options.provider?.type === 'anthropic') {
+        if (options.provider.baseUrl)
+            args.push('--base-url', options.provider.baseUrl);
+        if (options.provider.apiKey)
+            args.push('--api-key', options.provider.apiKey);
+    }
+    if (options.allowedTools?.length)
+        args.push('--allowed-tools', options.allowedTools.join(','));
+    if (options.disallowedTools?.length)
+        args.push('--disallowed-tools', options.disallowedTools.join(','));
+    if (options.sessionId)
+        args.push('--session-id', options.sessionId);
+    if (options.resume)
+        args.push('--resume', options.resume);
+    if (options.forkSession)
+        args.push('--fork-session');
+    if (options.maxTurns !== undefined)
+        args.push('--max-turns', String(options.maxTurns));
+    if (options.maxBudgetUsd !== undefined)
+        args.push('--max-budget-usd', String(options.maxBudgetUsd));
+    if (options.permissionMode)
+        args.push('--permission-mode', options.permissionMode);
+    for (const dir of options.pluginDirs ?? [])
+        args.push('--plugin-dir', dir);
+    if (options.addDirs?.length)
+        args.push('--add-dir', ...options.addDirs);
+    if (options.settings)
+        args.push('--settings', options.settings);
+    if (options.agents)
+        args.push('--agents', options.agents);
+    if (options.persistSession === false)
+        args.push('--no-session-persistence');
+    if (options.cwd)
+        args.push('--cwd', options.cwd);
+    // slice sdk-token-streaming (G3): opt-in token-level streaming — the CLI then emits stream_event
+    // (Anthropic raw message stream) deltas. Default off keeps the minimal event set unchanged.
+    if (options.includePartialMessages)
+        args.push('--include-partial-messages');
+    // 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 }));
+    }
+    if (options.extraArgs?.length)
+        args.push(...options.extraArgs);
+    return args;
+}
+/** Builds subprocess env additions. Exported for unit tests. */
+export function buildCliEnv(options) {
+    const env = { ...options.env };
+    if (options.provider?.type === 'openai-compatible') {
+        env.CCL_GATEWAY_URL = options.provider.baseUrl;
+        if (options.provider.apiKey)
+            env.CCL_GATEWAY_KEY = options.provider.apiKey;
+    }
+    if (options.pendingDecision) {
+        // Auto-continue the interrupted turn on resume (cli/print.ts:1195) so
+        // the model re-issues the suspended tool call without a new user prompt.
+        env.CLAUDE_CODE_RESUME_INTERRUPTED_TURN = '1';
+    }
+    return env;
+}
+/**
+ * Wraps each skills dir as an ephemeral plugin (a temp dir whose `skills`
+ * entry symlinks to the user's dir) so the CLI loads it via --plugin-dir,
+ * its cwd-independent skill channel (P1-5). Exported for unit tests.
+ */
+export function prepareSkillsWrappers(skillsDirs) {
+    return skillsDirs.map(dir => {
+        const target = resolve(dir);
+        if (!existsSync(target)) {
+            throw new Error(`ccl-sdk: skills dir does not exist: ${target}`);
+        }
+        const wrapper = mkdtempSync(join(tmpdir(), 'ccl-sdk-skills-'));
+        symlinkSync(target, join(wrapper, 'skills'), 'dir');
+        return wrapper;
+    });
+}
+function resolveCliPath(options) {
+    if (options.cliPath)
+        return options.cliPath;
+    if (process.env.CCL_SDK_CLI_PATH)
+        return process.env.CCL_SDK_CLI_PATH;
+    // Packaged layout: <pkg>/dist/sdk/query.js or <pkg>/sdk/query.ts, both
+    // resolve to the sibling <pkg>/dist/cli.js.
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const candidate of [
+        join(here, '..', 'cli.js'),
+        join(here, '..', 'dist', 'cli.js'),
+    ]) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    throw new Error('ccl-sdk: cannot locate the CCL CLI. Pass options.cliPath or set CCL_SDK_CLI_PATH.');
+}
+/**
+ * Fail-closed wrapper around the host's canUseTool callback (issue P0-2):
+ * throw, timeout, or an unrecognized return value all become deny, and the
+ * tool does not execute. `pending` is surfaced to the caller for suspend.
+ */
+export async function decideFailClosed(callback, toolName, input, context, timeoutMs) {
+    const deny = (message, failClosedReason) => ({
+        kind: 'decision',
+        decision: { behavior: 'deny', message, toolUseID: context.toolUseId },
+        failClosedReason,
+    });
+    let raw;
+    let timer;
+    try {
+        const callbackPromise = Promise.resolve(callback(toolName, input, context));
+        raw =
+            timeoutMs > 0
+                ? await Promise.race([
+                    callbackPromise,
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new Error(`canUseTool timed out after ${timeoutMs}ms`)), timeoutMs);
+                    }),
+                ])
+                : await callbackPromise;
+    }
+    catch (error) {
+        return deny(`Denied (fail-closed): canUseTool callback failed: ${error instanceof Error ? error.message : String(error)}`, 'callback_error');
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+    if (!raw || typeof raw !== 'object' || typeof raw.behavior !== 'string') {
+        return deny('Denied (fail-closed): canUseTool returned an unrecognized value', 'unrecognized_result');
+    }
+    switch (raw.behavior) {
+        case 'allow': {
+            const updated = raw.updatedInput && Object.keys(raw.updatedInput).length > 0
+                ? raw.updatedInput
+                : input;
+            return {
+                kind: 'decision',
+                decision: {
+                    behavior: 'allow',
+                    updatedInput: updated,
+                    toolUseID: context.toolUseId,
+                },
+            };
+        }
+        case 'deny':
+            return {
+                kind: 'decision',
+                decision: {
+                    behavior: 'deny',
+                    message: raw.message ?? 'Denied by host',
+                    ...(raw.interrupt !== undefined && { interrupt: raw.interrupt }),
+                    toolUseID: context.toolUseId,
+                },
+            };
+        case 'pending':
+            return { kind: 'pending' };
+        default:
+            return deny(`Denied (fail-closed): unknown behavior '${raw.behavior}'`, 'unrecognized_result');
+    }
+}
+function contentBlocks(message) {
+    if (typeof message !== 'object' || message === null)
+        return [];
+    const content = message.content;
+    if (typeof content === 'string')
+        return [{ type: 'text', text: content }];
+    if (!Array.isArray(content))
+        return [];
+    return content.filter((b) => typeof b === 'object' && b !== null);
+}
+async function runHook(fn) {
+    if (!fn)
+        return;
+    try {
+        await fn();
+    }
+    catch {
+        // P1-6 contract: hooks are observability, never control flow.
+    }
+}
+/**
+ * Core loop, transport-injectable for tests. Production callers use query()
+ * or resumeWithDecision().
+ */
+export async function* queryWithTransport(prompt, options, transport) {
+    const timeoutMs = options.canUseToolTimeoutMs ?? DEFAULT_CAN_USE_TOOL_TIMEOUT_MS;
+    const store = options.store ?? fileSessionStore();
+    const hooks = options.hooks ?? {};
+    const ownRequestIds = new Set();
+    const toolNamesById = new Map();
+    let lastSessionId = options.sessionId ?? options.resume;
+    let turn = 0;
+    let sawResult = false;
+    let sessionEnded = false;
+    // resumeWithDecision path: the recorded approval this run must settle.
+    let pendingApproval = null;
+    let pendingDecision = options.pendingDecision;
+    if (pendingDecision) {
+        if (!options.resume) {
+            throw new Error('ccl-sdk: pendingDecision requires options.resume');
+        }
+        pendingApproval = await store.loadPendingApproval(options.resume);
+        if (!pendingApproval) {
+            throw new Error(`ccl-sdk: no pending approval recorded for session ${options.resume}`);
+        }
+    }
+    const onAbort = () => void transport.close();
+    options.signal?.addEventListener('abort', onAbort, { once: true });
+    // 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.
+    const sdkMcpRegistry = options.sdkMcpServers && options.sdkMcpServers.length > 0
+        ? await SdkMcpRegistry.create(options.sdkMcpServers, (requestId, mcpResponse) => {
+            void transport.write({
+                type: 'control_response',
+                response: {
+                    subtype: 'success',
+                    request_id: requestId,
+                    response: { mcp_response: mcpResponse },
+                },
+            });
+        })
+        : null;
+    try {
+        const initId = `ccl-sdk-init-${Date.now().toString(36)}`;
+        ownRequestIds.add(initId);
+        await transport.write({
+            type: 'control_request',
+            request_id: initId,
+            request: {
+                subtype: 'initialize',
+                ...(options.systemPrompt !== undefined && {
+                    systemPrompt: options.systemPrompt,
+                }),
+                ...(options.appendSystemPrompt !== undefined && {
+                    appendSystemPrompt: options.appendSystemPrompt,
+                }),
+                ...(sdkMcpRegistry && sdkMcpRegistry.names.length > 0
+                    ? { sdkMcpServers: sdkMcpRegistry.names }
+                    : {}),
+                // slice sdk-json-schema-output (G4): structured-output schema over the control channel
+                // (print.ts reads request.jsonSchema at initialize), not argv, to avoid ARG_MAX.
+                ...(options.jsonSchema ? { jsonSchema: options.jsonSchema } : {}),
+            },
+        });
+        // 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) {
+            // 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({
+                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 message of transport.read()) {
+            if (typeof message.session_id === 'string') {
+                lastSessionId = message.session_id;
+                if (!sessionStarted) {
+                    sessionStarted = true;
+                    await runHook(hooks.onSessionStart &&
+                        (() => hooks.onSessionStart({ sessionId: message.session_id })));
+                }
+            }
+            if (options.includeRaw)
+                yield { type: 'raw', message };
+            switch (message.type) {
+                case 'assistant': {
+                    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 };
+                        }
+                        else if (block.type === 'tool_use') {
+                            const toolUseId = String(block.id ?? '');
+                            const toolName = String(block.name ?? '');
+                            toolNamesById.set(toolUseId, toolName);
+                            yield {
+                                type: 'tool_use',
+                                toolName,
+                                input: (block.input ?? {}),
+                                toolUseId,
+                                sessionId,
+                            };
+                        }
+                    }
+                    turn += 1;
+                    // slice sdk-observability-hooks-usage (G7): surface this turn's token usage from the
+                    // assistant message when present.
+                    const turnUsage = message.message?.usage;
+                    await runHook(hooks.onTurnEnd &&
+                        (() => hooks.onTurnEnd({ turn, sessionId, usage: turnUsage })));
+                    break;
+                }
+                case 'user': {
+                    const sessionId = message.session_id;
+                    for (const block of contentBlocks(message.message)) {
+                        if (block.type === 'tool_result') {
+                            const toolUseId = String(block.tool_use_id ?? '');
+                            const isError = block.is_error === true;
+                            yield {
+                                type: 'tool_result',
+                                toolUseId,
+                                content: block.content,
+                                isError,
+                                sessionId,
+                            };
+                            await runHook(hooks.onToolUse &&
+                                (() => hooks.onToolUse({
+                                    toolUseId,
+                                    toolName: toolNamesById.get(toolUseId),
+                                    content: block.content,
+                                    isError,
+                                    sessionId,
+                                })));
+                        }
+                    }
+                    break;
+                }
+                case 'control_request': {
+                    const requestId = String(message.request_id ?? '');
+                    const request = (message.request ?? {});
+                    // slice sdk-in-process-mcp-server: route MCP tool calls to host in-process servers.
+                    if (request.subtype === 'mcp_message') {
+                        if (sdkMcpRegistry) {
+                            sdkMcpRegistry.handle(String(request.server_name ?? ''), request.message, requestId);
+                        }
+                        else {
+                            await transport.write({
+                                type: 'control_response',
+                                response: {
+                                    subtype: 'error',
+                                    request_id: requestId,
+                                    error: 'ccl-sdk received mcp_message but no sdkMcpServers configured',
+                                },
+                            });
+                        }
+                        break;
+                    }
+                    if (request.subtype !== 'can_use_tool') {
+                        await transport.write({
+                            type: 'control_response',
+                            response: {
+                                subtype: 'error',
+                                request_id: requestId,
+                                error: `ccl-sdk does not support control_request subtype '${String(request.subtype)}'`,
+                            },
+                        });
+                        break;
+                    }
+                    const toolName = String(request.tool_name ?? '');
+                    const input = (request.input ?? {});
+                    const toolUseId = String(request.tool_use_id ?? '');
+                    const agentId = typeof request.agent_id === 'string' ? request.agent_id : undefined;
+                    yield {
+                        type: 'permission_request',
+                        requestId,
+                        toolName,
+                        input,
+                        toolUseId,
+                        agentId,
+                    };
+                    // Resume path: settle the recorded approval on its matching call.
+                    // Match by toolName — on allow the tool runs with the RECORDED
+                    // input (or the host's explicit updatedInput), never the model's
+                    // re-generated one, so what the owner approved is what executes.
+                    if (pendingDecision && pendingApproval?.toolName === toolName) {
+                        const decision = pendingDecision.behavior === 'allow'
+                            ? {
+                                behavior: 'allow',
+                                updatedInput: pendingDecision.updatedInput ?? pendingApproval.input,
+                                toolUseID: toolUseId,
+                            }
+                            : {
+                                behavior: 'deny',
+                                message: pendingDecision.message ?? 'Denied by owner',
+                                toolUseID: toolUseId,
+                            };
+                        await transport.write({
+                            type: 'control_response',
+                            response: {
+                                subtype: 'success',
+                                request_id: requestId,
+                                response: decision,
+                            },
+                        });
+                        await store.deletePendingApproval(pendingApproval.sessionId);
+                        pendingDecision = undefined;
+                        pendingApproval = null;
+                        yield {
+                            type: 'permission_resolved',
+                            requestId,
+                            toolUseId,
+                            behavior: decision.behavior,
+                            source: 'pending_decision',
+                        };
+                        break;
+                    }
+                    const outcome = options.canUseTool
+                        ? await decideFailClosed(options.canUseTool, toolName, input, { toolUseId, agentId }, timeoutMs)
+                        : {
+                            kind: 'decision',
+                            decision: {
+                                behavior: 'deny',
+                                message: 'Denied (fail-closed): no canUseTool callback configured',
+                                toolUseID: toolUseId,
+                            },
+                            failClosedReason: 'no_callback',
+                        };
+                    if (outcome.kind === 'pending') {
+                        const sessionId = lastSessionId;
+                        if (!sessionId) {
+                            // Cannot resume without a session identity — fail closed.
+                            await transport.write({
+                                type: 'control_response',
+                                response: {
+                                    subtype: 'success',
+                                    request_id: requestId,
+                                    response: {
+                                        behavior: 'deny',
+                                        message: 'Denied (fail-closed): pending requires a known session_id',
+                                        toolUseID: toolUseId,
+                                    },
+                                },
+                            });
+                            yield {
+                                type: 'error',
+                                message: 'pending approval requested before any session_id was observed',
+                                fatal: false,
+                                code: 'pending_without_session',
+                            };
+                            yield {
+                                type: 'permission_resolved',
+                                requestId,
+                                toolUseId,
+                                behavior: 'deny',
+                                failClosedReason: 'pending_without_session',
+                            };
+                            break;
+                        }
+                        const record = {
+                            sessionId,
+                            requestId,
+                            toolUseId,
+                            toolName,
+                            input,
+                            createdAt: new Date().toISOString(),
+                        };
+                        await store.savePendingApproval(record);
+                        // Deliberately NO control_response: the tool must not run and
+                        // 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 {
+                            type: 'suspended',
+                            sessionId,
+                            requestId,
+                            toolUseId,
+                            toolName,
+                            input,
+                        };
+                        sessionEnded = true;
+                        await runHook(hooks.onSessionEnd &&
+                            (() => hooks.onSessionEnd({
+                                sessionId,
+                                subtype: 'suspended',
+                                isError: false,
+                            })));
+                        return;
+                    }
+                    await transport.write({
+                        type: 'control_response',
+                        response: {
+                            subtype: 'success',
+                            request_id: requestId,
+                            response: outcome.decision,
+                        },
+                    });
+                    yield {
+                        type: 'permission_resolved',
+                        requestId,
+                        toolUseId,
+                        behavior: outcome.decision.behavior,
+                        source: 'callback',
+                        ...(outcome.failClosedReason && {
+                            failClosedReason: outcome.failClosedReason,
+                        }),
+                    };
+                    break;
+                }
+                case 'control_response': {
+                    const response = (message.response ?? {});
+                    const requestId = String(response.request_id ?? '');
+                    if (ownRequestIds.has(requestId)) {
+                        ownRequestIds.delete(requestId);
+                        if (response.subtype === 'error') {
+                            yield {
+                                type: 'error',
+                                message: `initialize failed: ${String(response.error)}`,
+                                fatal: false,
+                                code: 'initialize_error',
+                            };
+                        }
+                    }
+                    break;
+                }
+                case 'result': {
+                    sawResult = true;
+                    const sessionId = message.session_id;
+                    const usage = message.usage;
+                    const totalCostUsd = typeof message.total_cost_usd === 'number'
+                        ? message.total_cost_usd
+                        : undefined;
+                    if (sessionId && usage) {
+                        // P1-7: per-session accumulation, queryable via getSessionUsage.
+                        try {
+                            await store.addUsage(sessionId, usage, totalCostUsd);
+                        }
+                        catch {
+                            // Metering must not break the conversation stream.
+                        }
+                    }
+                    yield {
+                        type: 'result',
+                        subtype: String(message.subtype ?? 'unknown'),
+                        usage,
+                        totalCostUsd,
+                        numTurns: typeof message.num_turns === 'number' ? message.num_turns : undefined,
+                        durationMs: typeof message.duration_ms === 'number'
+                            ? message.duration_ms
+                            : undefined,
+                        isError: message.is_error === true,
+                        sessionId,
+                        result: typeof message.result === 'string' ? message.result : undefined,
+                        // slice sdk-json-schema-output (G4): surface the CLI's schema-validated structured
+                        // output (present only when the query ran with jsonSchema).
+                        structuredOutput: message
+                            .structured_output,
+                    };
+                    sessionEnded = true;
+                    await runHook(hooks.onSessionEnd &&
+                        (() => hooks.onSessionEnd({
+                            sessionId,
+                            subtype: String(message.subtype ?? 'unknown'),
+                            isError: message.is_error === true,
+                            usage,
+                        })));
+                    break;
+                }
+                case 'stream_event': {
+                    // slice sdk-token-streaming (G3): forward one Anthropic raw message stream event
+                    // (token-level delta). Only arrives when includePartialMessages passed the flag.
+                    const streamEvent = message.event;
+                    if (streamEvent && typeof streamEvent.type === 'string') {
+                        yield {
+                            type: 'stream_event',
+                            event: streamEvent,
+                            sessionId: message.session_id,
+                        };
+                    }
+                    break;
+                }
+                default:
+                    break;
+            }
+            if (sawResult)
+                break;
+        }
+        if (!sawResult) {
+            const code = await transport.exited;
+            const aborted = options.signal?.aborted === true;
+            yield {
+                type: 'error',
+                message: aborted
+                    ? 'query aborted by host signal'
+                    : `CCL subprocess ended without a result event (exit code ${code})`,
+                fatal: true,
+                code: aborted ? 'aborted' : 'subprocess_exit',
+            };
+            if (!sessionEnded) {
+                await runHook(hooks.onSessionEnd &&
+                    (() => hooks.onSessionEnd({
+                        sessionId: lastSessionId,
+                        subtype: aborted ? 'aborted' : 'subprocess_exit',
+                        isError: true,
+                    })));
+            }
+        }
+    }
+    finally {
+        options.signal?.removeEventListener('abort', onAbort);
+        await sdkMcpRegistry?.close();
+        await transport.close();
+    }
+}
+/** Spawns the managed CLI subprocess for a set of options. Shared with the P1 Query handle. */
+export function spawnForOptions(options) {
+    const pluginDirs = [
+        ...(options.pluginDirs ?? []),
+        ...(options.skillsDirs?.length ? prepareSkillsWrappers(options.skillsDirs) : []),
+    ];
+    const effective = { ...options, pluginDirs };
+    return spawnCliTransport({
+        execPath: options.execPath ?? process.execPath,
+        cliPath: resolveCliPath(options),
+        args: buildCliArgs(effective),
+        cwd: options.cwd,
+        env: buildCliEnv(effective),
+    });
+}
+/**
+ * Run one prompt against a CCL agent session and stream JSON-serializable
+ * events. See QueryOptions for session resume, permission callback, model,
+ * provider, and tool configuration.
+ */
+export function query(prompt, options = {}) {
+    return queryWithTransport(prompt, options, spawnForOptions(options));
+}
+/**
+ * Resume a session suspended by a `pending` permission result and apply the
+ * owner's decision (issue P0-2 acceptance path). Cross-process: the pending
+ * record lives in the session store, the conversation in the CLI's
+ * transcript store — nothing is held in memory between suspend and resume.
+ *
+ * On allow, the suspended tool executes with exactly the recorded input (or
+ * decision.updatedInput if the owner amended it); on deny the model receives
+ * the denial and the session continues.
+ */
+export function resumeWithDecision(sessionId, decision, options = {}) {
+    const merged = {
+        ...options,
+        resume: sessionId,
+        pendingDecision: decision,
+    };
+    return queryWithTransport(null, merged, spawnForOptions(merged));
+}
+/** P1-7: accumulated usage for a session, across all queries that ran it. */
+export async function getSessionUsage(sessionId, store = fileSessionStore()) {
+    return store.getUsage(sessionId);
+}