@cjhyy/code-shell-core 0.5.0-rc.0

package/dist/engine/model-facade.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Model call facade — wraps LLM client with transcript integration.
+ */
+import type { LLMClientBase } from "../llm/client-base.js";
+import type { Message, ToolDefinition, LLMResponse, StreamCallback } from "../types.js";
+import { Transcript } from "../session/transcript.js";
+export declare class ModelFacade {
+    private readonly client;
+    private readonly transcript;
+    constructor(client: LLMClientBase, transcript: Transcript);
+    call(systemPrompt: string, messages: Message[], tools: ToolDefinition[], onStream?: StreamCallback, signal?: AbortSignal): Promise<LLMResponse>;
+    /**
+     * Call without streaming — used as fallback when streaming fails.
+     */
+    callWithoutStreaming(systemPrompt: string, messages: Message[], tools: ToolDefinition[], signal?: AbortSignal): Promise<LLMResponse>;
+    /** Record API timing and token usage to bootstrap state. */
+    private recordUsage;
+    /** Optional summarize function for tool use summaries. */
+    summarize?: (systemPrompt: string, userMessage: string) => Promise<string>;
+    /** Get cumulative output tokens (for token budget). */
+    getOutputTokens?(): number;
+    private recordResponse;
+    getUsage(): import("../llm/types.js").LLMUsageTracker;
+}

package/dist/engine/model-facade.js

@@ -0,0 +1,194 @@
+/**
+ * Model call facade — wraps LLM client with transcript integration.
+ */
+import { logger, getCurrentSid } from "../logging/logger.js";
+import { recordLLMError, recordLLMRequest, recordLLMResponse, } from "../logging/session-recorder.js";
+import { sanitizeMessages } from "../logging/sanitize-messages.js";
+import { addAPIDuration, addToModelUsage, addInputTokens, addOutputTokens } from "../state.js";
+let _reqSeq = 0;
+function nextReqId() {
+    _reqSeq += 1;
+    return `r${_reqSeq.toString(36)}`;
+}
+export class ModelFacade {
+    client;
+    transcript;
+    constructor(client, transcript) {
+        this.client = client;
+        this.transcript = transcript;
+    }
+    async call(systemPrompt, messages, tools, onStream, signal) {
+        const startMs = Date.now();
+        const msgCount = messages.length;
+        const sid = getCurrentSid();
+        const reqId = nextReqId();
+        recordLLMRequest(sid, {
+            provider: this.client.provider ?? "?",
+            model: this.client.model ?? "?",
+            stream: true,
+            // Image base64 payloads stay out of recorded prompts — see
+            // logging/sanitize-messages.ts. Transcripts keep the full bytes
+            // (needed for replay); logs do not.
+            messages: sanitizeMessages(messages),
+            tools,
+            systemPrompt,
+        }, reqId);
+        let response;
+        try {
+            response = await this.client.createMessage({
+                systemPrompt,
+                messages,
+                tools,
+                stream: true,
+                onChunk: (chunk) => {
+                    if (!onStream)
+                        return;
+                    if (chunk.type === "text" && chunk.text) {
+                        onStream({ type: "text_delta", text: chunk.text, tokens: chunk.tokens });
+                    }
+                    else if (chunk.type === "tool_use_start" && chunk.toolCall) {
+                        // Forward tool_use_start immediately so the UI can show progress
+                        // while JSON args are still streaming
+                        onStream({
+                            type: "tool_use_start",
+                            toolCall: {
+                                id: chunk.toolCall.id ?? "",
+                                toolName: chunk.toolCall.toolName ?? "",
+                                args: chunk.toolCall.args ?? {},
+                            },
+                        });
+                    }
+                    else if (chunk.type === "tool_use_delta" && chunk.toolCall?.id) {
+                        onStream({
+                            type: "tool_use_args_delta",
+                            toolCallId: chunk.toolCall.id,
+                            args: chunk.toolCall.args ?? {},
+                        });
+                    }
+                },
+                signal,
+            });
+        }
+        catch (err) {
+            recordLLMError(sid, reqId, err, Date.now() - startMs);
+            throw err;
+        }
+        const latencyMs = Date.now() - startMs;
+        logger.info("llm.request", {
+            stream: true,
+            latencyMs,
+            msgCount,
+            stopReason: response.stopReason,
+            toolCalls: response.toolCalls.length,
+            textLen: response.text?.length ?? 0,
+            usage: response.usage,
+        });
+        recordLLMResponse(sid, {
+            text: response.text,
+            toolCalls: response.toolCalls,
+            stopReason: response.stopReason,
+            usage: response.usage,
+            durationMs: latencyMs,
+        }, reqId);
+        this.recordUsage(response, latencyMs);
+        this.recordResponse(response);
+        return response;
+    }
+    /**
+     * Call without streaming — used as fallback when streaming fails.
+     */
+    async callWithoutStreaming(systemPrompt, messages, tools, signal) {
+        const startMs = Date.now();
+        const msgCount = messages.length;
+        const sid = getCurrentSid();
+        const reqId = nextReqId();
+        recordLLMRequest(sid, {
+            provider: this.client.provider ?? "?",
+            model: this.client.model ?? "?",
+            stream: false,
+            // Image base64 payloads stay out of recorded prompts — same rule
+            // as the streaming path above.
+            messages: sanitizeMessages(messages),
+            tools,
+            systemPrompt,
+        }, reqId);
+        let response;
+        try {
+            response = await this.client.createMessage({
+                systemPrompt,
+                messages,
+                tools,
+                stream: false,
+                signal,
+            });
+        }
+        catch (err) {
+            recordLLMError(sid, reqId, err, Date.now() - startMs);
+            throw err;
+        }
+        const latencyMs = Date.now() - startMs;
+        logger.info("llm.request", {
+            stream: false,
+            latencyMs,
+            msgCount,
+            stopReason: response.stopReason,
+            toolCalls: response.toolCalls.length,
+            textLen: response.text?.length ?? 0,
+            usage: response.usage,
+        });
+        recordLLMResponse(sid, {
+            text: response.text,
+            toolCalls: response.toolCalls,
+            stopReason: response.stopReason,
+            usage: response.usage,
+            durationMs: latencyMs,
+        }, reqId);
+        this.recordUsage(response, latencyMs);
+        this.recordResponse(response);
+        return response;
+    }
+    /** Record API timing and token usage to bootstrap state. */
+    recordUsage(response, latencyMs) {
+        addAPIDuration(latencyMs);
+        const u = response.usage;
+        if (u) {
+            addInputTokens(u.promptTokens ?? 0);
+            addOutputTokens(u.completionTokens ?? 0);
+            addToModelUsage(this.client.model ?? "unknown", u.promptTokens ?? 0, u.completionTokens ?? 0, u.cacheReadTokens ?? 0, u.cacheCreationTokens ?? 0);
+        }
+    }
+    /** Optional summarize function for tool use summaries. */
+    summarize;
+    recordResponse(response) {
+        if (response.text || response.toolCalls.length > 0 || response.reasoningContent) {
+            const contentBlocks = [];
+            // DeepSeek V4 thinking mode emits reasoning_content alongside the
+            // reply; we echo it back on the next turn so the model can resume
+            // its chain of thought. Persist as a dedicated block so transcript
+            // -> message round-tripping preserves it without mixing into
+            // displayable text. Goes first so it sits adjacent to the
+            // assistant turn it belongs to even after compaction.
+            if (response.reasoningContent) {
+                contentBlocks.push({
+                    type: "reasoning",
+                    reasoningContent: response.reasoningContent,
+                });
+            }
+            if (response.text) {
+                contentBlocks.push({ type: "text", text: response.text });
+            }
+            for (const tc of response.toolCalls) {
+                contentBlocks.push({
+                    type: "tool_use",
+                    id: tc.id,
+                    name: tc.toolName,
+                    input: tc.args,
+                });
+            }
+            this.transcript.appendMessage("assistant", contentBlocks);
+        }
+    }
+    getUsage() {
+        return this.client.getUsage();
+    }
+}

package/dist/engine/parse-task.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Parse a single-string `task` for inline image attachments.
+ *
+ * Desktop's composer encodes images as `<codeshell-image>` blocks before
+ * sending — see `packages/desktop/src/renderer/chat/attachments.ts` —
+ * because the agent-server-stdio RPC schema only carries a `task: string`.
+ * The engine recovers the structured form here before handing the message
+ * to the LLM client.
+ *
+ * Wire format (one block per image):
+ *
+ *   <codeshell-image mime="image/png" name="screenshot.png">
+ *   data:image/png;base64,iVBORw0KGgo…
+ *   </codeshell-image>
+ *
+ * Multiple blocks may appear interleaved with regular text — preserved
+ * order matters because some prompts reference "the second image".
+ *
+ * Pure / no I/O. Pure-text tasks (no `<codeshell-image>` substring) hit
+ * a single non-matching indexOf check and return immediately, so CLI / TUI
+ * callers pay essentially nothing.
+ */
+export interface ParsedImage {
+    /** MIME type as declared in the block opening tag. */
+    mime: string;
+    /** Original file name (may be empty). HTML-attr-escaped on the wire; unescaped here. */
+    name: string;
+    /** Full `data:<mime>;base64,<…>` URL — handy for OpenAI-compat clients. */
+    dataUrl: string;
+    /** Just the base64 payload, with the data-URL prefix stripped. */
+    base64: string;
+}
+export interface ParsedTask {
+    /** Remaining plain-text portion (image blocks removed, surrounding whitespace trimmed). */
+    text: string;
+    /** Images in the order they appeared in the source. */
+    images: ParsedImage[];
+    /** Convenience flag — true iff `images.length > 0`. */
+    hasImages: boolean;
+}
+export declare class ImageParseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse `<codeshell-image>` blocks out of `task`.
+ *
+ * Behavior:
+ *   - No marker substring → fast return, no allocations beyond the
+ *     `ParsedTask` shell.
+ *   - One or more well-formed blocks → blocks removed from `text`,
+ *     surrounding whitespace collapsed, blocks accumulated in `images`
+ *     in source order.
+ *   - Malformed block (e.g. unclosed tag, missing data URL) → throws
+ *     {@link ImageParseError}. Callers decide whether to drop or fail
+ *     the run, but **silent fallback is intentionally not provided** —
+ *     dropping image bytes on the floor was the failure mode this whole
+ *     pipeline exists to prevent.
+ */
+export declare function parseTaskWithImages(task: string): ParsedTask;

package/dist/engine/parse-task.js

@@ -0,0 +1,135 @@
+/**
+ * Parse a single-string `task` for inline image attachments.
+ *
+ * Desktop's composer encodes images as `<codeshell-image>` blocks before
+ * sending — see `packages/desktop/src/renderer/chat/attachments.ts` —
+ * because the agent-server-stdio RPC schema only carries a `task: string`.
+ * The engine recovers the structured form here before handing the message
+ * to the LLM client.
+ *
+ * Wire format (one block per image):
+ *
+ *   <codeshell-image mime="image/png" name="screenshot.png">
+ *   data:image/png;base64,iVBORw0KGgo…
+ *   </codeshell-image>
+ *
+ * Multiple blocks may appear interleaved with regular text — preserved
+ * order matters because some prompts reference "the second image".
+ *
+ * Pure / no I/O. Pure-text tasks (no `<codeshell-image>` substring) hit
+ * a single non-matching indexOf check and return immediately, so CLI / TUI
+ * callers pay essentially nothing.
+ */
+export class ImageParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ImageParseError";
+    }
+}
+const IMAGE_BLOCK_MARKER = "<codeshell-image";
+/**
+ * Pulled out so the regex compiles once. Captures:
+ *   1 = raw attribute string (everything between `<codeshell-image` and the
+ *       closing `>` of the opening tag)
+ *   2 = body (everything between the opening tag and `</codeshell-image>`)
+ *
+ * Anchored loosely — we tolerate whitespace inside the opening tag and
+ * around the body, which is what the desktop encoder produces.
+ */
+const IMAGE_BLOCK_RE = /<codeshell-image\b([^>]*)>([\s\S]*?)<\/codeshell-image>/g;
+const ATTR_RE = /(\w+)\s*=\s*"([^"]*)"/g;
+/**
+ * Reverse of the desktop encoder's `escapeAttr` so file names with `&`
+ * or quotes round-trip cleanly.
+ */
+function unescapeAttr(s) {
+    return s
+        .replace(/&quot;/g, '"')
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&amp;/g, "&");
+}
+function parseAttrs(raw) {
+    const out = {};
+    ATTR_RE.lastIndex = 0;
+    let m;
+    while ((m = ATTR_RE.exec(raw)) !== null) {
+        out[m[1].toLowerCase()] = unescapeAttr(m[2]);
+    }
+    return out;
+}
+const DATA_URL_RE = /^data:([^;,]+);base64,([A-Za-z0-9+/=\s]+)$/;
+function parseDataUrl(body) {
+    const trimmed = body.trim();
+    const m = DATA_URL_RE.exec(trimmed);
+    if (!m) {
+        throw new ImageParseError("image block body is not a data URL of the form `data:<mime>;base64,<…>`");
+    }
+    const mime = m[1].trim();
+    // Strip ALL whitespace from the base64 portion — wire format may contain
+    // newlines inserted for readability. The base64 grammar tolerates none.
+    const base64 = m[2].replace(/\s+/g, "");
+    if (base64.length === 0) {
+        throw new ImageParseError("image block body has an empty base64 payload");
+    }
+    return { mime, base64 };
+}
+/**
+ * Parse `<codeshell-image>` blocks out of `task`.
+ *
+ * Behavior:
+ *   - No marker substring → fast return, no allocations beyond the
+ *     `ParsedTask` shell.
+ *   - One or more well-formed blocks → blocks removed from `text`,
+ *     surrounding whitespace collapsed, blocks accumulated in `images`
+ *     in source order.
+ *   - Malformed block (e.g. unclosed tag, missing data URL) → throws
+ *     {@link ImageParseError}. Callers decide whether to drop or fail
+ *     the run, but **silent fallback is intentionally not provided** —
+ *     dropping image bytes on the floor was the failure mode this whole
+ *     pipeline exists to prevent.
+ */
+export function parseTaskWithImages(task) {
+    if (typeof task !== "string" || task.indexOf(IMAGE_BLOCK_MARKER) === -1) {
+        return { text: task ?? "", images: [], hasImages: false };
+    }
+    // Defensively reject the orphaned-opening-tag case before delegating to
+    // the matcher: a `<codeshell-image …>` with no matching `</codeshell-image>`
+    // is exactly the "browser hung up mid-paste" failure mode this parser
+    // exists to surface, not swallow.
+    const openingMatches = task.match(/<codeshell-image\b/g) ?? [];
+    const closingMatches = task.match(/<\/codeshell-image>/g) ?? [];
+    if (openingMatches.length !== closingMatches.length) {
+        throw new ImageParseError(`unbalanced <codeshell-image> tags: ${openingMatches.length} opening vs ${closingMatches.length} closing`);
+    }
+    const images = [];
+    IMAGE_BLOCK_RE.lastIndex = 0;
+    const textWithoutImages = task.replace(IMAGE_BLOCK_RE, (_match, attrsRaw, body) => {
+        const attrs = parseAttrs(attrsRaw);
+        const { mime, base64 } = parseDataUrl(body);
+        const declaredMime = attrs.mime?.trim();
+        // Prefer the opening-tag attribute when it disagrees with the data URL's
+        // self-declared type — the attribute is what the desktop validator gated
+        // on, so it's the "source of truth" the rest of the pipeline expects.
+        const finalMime = declaredMime && declaredMime.length > 0 ? declaredMime : mime;
+        images.push({
+            mime: finalMime,
+            name: attrs.name ?? "",
+            dataUrl: `data:${finalMime};base64,${base64}`,
+            base64,
+        });
+        return "";
+    });
+    // Collapse the whitespace the removed blocks leave behind. Two passes:
+    //   1. Multiple blank lines (3+ newlines) → exactly two newlines, so the
+    //      remaining prose retains paragraph breaks but doesn't look like a
+    //      page of empty whitespace.
+    //   2. Trim leading/trailing whitespace introduced by a block at either
+    //      end of the message.
+    const cleanedText = textWithoutImages.replace(/\n{3,}/g, "\n\n").trim();
+    return {
+        text: cleanedText,
+        images,
+        hasImages: images.length > 0,
+    };
+}

package/dist/engine/patch-orphaned-tools.d.ts

@@ -0,0 +1,52 @@
+/**
+ * patchOrphanedToolUses — repair message sequences where an assistant
+ * `tool_use` block has no corresponding `tool_result`.
+ *
+ * Why this matters: OpenAI strictly enforces that every `tool_calls`
+ * entry on an assistant message is followed by a matching `role:"tool"`
+ * message (one per `tool_call_id`). An incomplete sequence triggers
+ * `400 An assistant message with 'tool_calls' must be followed by tool
+ * messages responding to each 'tool_call_id'`.
+ *
+ * The sequence can become incomplete in two ways:
+ *   1. The model called tools, the API call between turns failed before
+ *      the executor wrote the results. TurnLoop already patches this
+ *      mid-run (see turn-loop.ts), so the broken state only lives in
+ *      memory.
+ *   2. The process crashed / was Ctrl+C'd after the assistant message
+ *      was persisted to transcript.jsonl but before tool_result events
+ *      were appended. On `/resume`, the loaded message array carries
+ *      this gap into the next API call.
+ *
+ * This module is the resume-side counterpart: scan the entire loaded
+ * history (not just the tail), find every assistant→missing-result gap,
+ * inject a synthetic tool_result for each orphan in the correct
+ * position so the resulting sequence is valid for both Anthropic and
+ * OpenAI message shapes.
+ *
+ * Insertion strategy: we append the synthetic results as a NEW `user`
+ * message with `tool_result` blocks placed immediately after the
+ * assistant message that produced the orphan. This matches what the
+ * runtime would have written if execution had completed normally, and
+ * the OpenAI converter (providers/openai.ts) lifts each `tool_result`
+ * out to a separate `role:"tool"` message keyed by `tool_use_id` —
+ * exactly the shape the API requires.
+ */
+import type { Message } from "../types.js";
+export interface PatchOrphanedSummary {
+    /** How many gaps were found across the whole history. */
+    gapsPatched: number;
+    /** Total synthetic tool_result blocks injected. */
+    toolResultsInjected: number;
+}
+/**
+ * Walk `messages` and, for every assistant message whose `tool_use`
+ * blocks lack corresponding `tool_result`s anywhere later in the array,
+ * splice a synthetic user→tool_result message right after it. Mutates
+ * `messages` in place and returns a summary so callers can log how
+ * much repair was needed.
+ *
+ * Idempotent: a second call on the same array is a no-op because the
+ * first pass already filled every gap.
+ */
+export declare function patchOrphanedToolUses(messages: Message[]): PatchOrphanedSummary;

package/dist/engine/patch-orphaned-tools.js

@@ -0,0 +1,95 @@
+/**
+ * patchOrphanedToolUses — repair message sequences where an assistant
+ * `tool_use` block has no corresponding `tool_result`.
+ *
+ * Why this matters: OpenAI strictly enforces that every `tool_calls`
+ * entry on an assistant message is followed by a matching `role:"tool"`
+ * message (one per `tool_call_id`). An incomplete sequence triggers
+ * `400 An assistant message with 'tool_calls' must be followed by tool
+ * messages responding to each 'tool_call_id'`.
+ *
+ * The sequence can become incomplete in two ways:
+ *   1. The model called tools, the API call between turns failed before
+ *      the executor wrote the results. TurnLoop already patches this
+ *      mid-run (see turn-loop.ts), so the broken state only lives in
+ *      memory.
+ *   2. The process crashed / was Ctrl+C'd after the assistant message
+ *      was persisted to transcript.jsonl but before tool_result events
+ *      were appended. On `/resume`, the loaded message array carries
+ *      this gap into the next API call.
+ *
+ * This module is the resume-side counterpart: scan the entire loaded
+ * history (not just the tail), find every assistant→missing-result gap,
+ * inject a synthetic tool_result for each orphan in the correct
+ * position so the resulting sequence is valid for both Anthropic and
+ * OpenAI message shapes.
+ *
+ * Insertion strategy: we append the synthetic results as a NEW `user`
+ * message with `tool_result` blocks placed immediately after the
+ * assistant message that produced the orphan. This matches what the
+ * runtime would have written if execution had completed normally, and
+ * the OpenAI converter (providers/openai.ts) lifts each `tool_result`
+ * out to a separate `role:"tool"` message keyed by `tool_use_id` —
+ * exactly the shape the API requires.
+ */
+const SYNTHETIC_ERROR_TEXT = "Error: Tool execution did not complete (process interrupted or earlier API failure). " +
+    "This result was injected during session resume to keep the message sequence valid.";
+/**
+ * Walk `messages` and, for every assistant message whose `tool_use`
+ * blocks lack corresponding `tool_result`s anywhere later in the array,
+ * splice a synthetic user→tool_result message right after it. Mutates
+ * `messages` in place and returns a summary so callers can log how
+ * much repair was needed.
+ *
+ * Idempotent: a second call on the same array is a no-op because the
+ * first pass already filled every gap.
+ */
+export function patchOrphanedToolUses(messages) {
+    const summary = { gapsPatched: 0, toolResultsInjected: 0 };
+    // Pre-compute the set of tool_result ids already answered anywhere in
+    // the history, then scan forward. Doing this in one pass avoids the
+    // O(n²) "for each assistant, scan tail" pattern in TurnLoop's
+    // single-shot version — resume sessions can be long.
+    const answeredIds = new Set();
+    for (const msg of messages) {
+        if (!Array.isArray(msg.content))
+            continue;
+        for (const block of msg.content) {
+            if (block.type === "tool_result" && block.tool_use_id) {
+                answeredIds.add(block.tool_use_id);
+            }
+        }
+    }
+    // Walk left-to-right, splicing inserts immediately after the offending
+    // assistant message. We iterate by index and bump past the inserted
+    // message so we don't re-process it.
+    for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i];
+        if (msg.role !== "assistant" || !Array.isArray(msg.content))
+            continue;
+        const orphanedIds = [];
+        for (const block of msg.content) {
+            if (block.type === "tool_use" && block.id && !answeredIds.has(block.id)) {
+                orphanedIds.push(block.id);
+            }
+        }
+        if (orphanedIds.length === 0)
+            continue;
+        const errorBlocks = orphanedIds.map((id) => ({
+            type: "tool_result",
+            tool_use_id: id,
+            content: SYNTHETIC_ERROR_TEXT,
+        }));
+        messages.splice(i + 1, 0, { role: "user", content: errorBlocks });
+        // Mark these ids answered so a later assistant message referencing
+        // the same id (shouldn't happen with real id generation, but guards
+        // against bad transcripts) doesn't double-patch.
+        for (const id of orphanedIds)
+            answeredIds.add(id);
+        summary.gapsPatched += 1;
+        summary.toolResultsInjected += orphanedIds.length;
+        // Skip the synthetic message we just spliced in.
+        i += 1;
+    }
+    return summary;
+}

package/dist/engine/query.d.ts

@@ -0,0 +1,50 @@
+/**
+ * High-level query API — async generator wrapping TurnLoop.
+ *
+ * Callers consume events via `for await (const event of query(params))`.
+ * This is the public entry point for running agentic queries; TurnLoop
+ * is the internal state machine.
+ *
+ * Adapted from restored-src/src/query.ts, simplified for Code Shell.
+ */
+import type { Message, StreamEvent, ToolDefinition, TerminalReason } from "../types.js";
+import { type TurnLoopDeps } from "./turn-loop.js";
+export interface QueryParams {
+    /** Initial message history (including the new user message). */
+    messages: Message[];
+    /** System prompt text. */
+    systemPrompt: string;
+    /** Available tool definitions. */
+    tools: ToolDefinition[];
+    /** Max turns before forced stop. */
+    maxTurns?: number;
+    /** Max tool calls per turn (default 20). */
+    maxToolCallsPerTurn?: number;
+    /** Abort signal for cancellation. */
+    signal?: AbortSignal;
+    /** Dependencies injected by the caller (engine). */
+    deps: QueryDeps;
+}
+export interface QueryDeps {
+    model: TurnLoopDeps["model"];
+    toolExecutor: TurnLoopDeps["toolExecutor"];
+    contextManager: TurnLoopDeps["contextManager"];
+    hooks: TurnLoopDeps["hooks"];
+    transcript: TurnLoopDeps["transcript"];
+}
+export interface QueryResult {
+    text: string;
+    reason: TerminalReason;
+    turnCount: number;
+}
+/**
+ * Run an agentic query and yield stream events as they occur.
+ *
+ * Usage:
+ *   const events: StreamEvent[] = [];
+ *   for await (const event of query(params)) {
+ *     events.push(event);
+ *   }
+ *   // last event contains the final result
+ */
+export declare function query(params: QueryParams): AsyncGenerator<StreamEvent, QueryResult, undefined>;