@cjhyy/code-shell-core 0.6.0-rc.8 → 0.7.0-beta.1

package/dist/engine/image-policy.d.ts

@@ -149,6 +149,12 @@ export interface DropOversizedResult {
     droppedCount: number;
 }
 export declare function dropOversizedImages(images: readonly ParsedImage[]): DropOversizedResult;
+export interface ImagePolicyByteInput {
+    name: string;
+    mime: string;
+    bytes: number;
+}
+export declare function enforceImageBytePolicy(images: readonly ImagePolicyByteInput[]): ImagePolicyVerdict;
 export declare function enforceImagePolicy(images: readonly ParsedImage[]): ImagePolicyVerdict;
 /**
  * Collect the workspace file paths of any attached images that came from a

package/dist/engine/image-policy.js

@@ -107,15 +107,13 @@ export function dropOversizedImages(images) {
     if (dropped.length === 0) {
         return { kept, placeholder: "", droppedCount: 0 };
     }
-    const list = dropped
-        .map((d) => `「${d.name}」(~${fmtMB(d.bytes)})`)
-        .join("、");
+    const list = dropped.map((d) => `「${d.name}」(~${fmtMB(d.bytes)})`).join("、");
     const placeholder = `[已自动跳过 ${dropped.length} 张超大图片:${list};` +
         `单图上限 ${fmtMB(IMAGE_LIMITS.maxBytesPerImage)}。` +
         `图片未进入对话历史,本轮其余内容继续。]`;
     return { kept, placeholder, droppedCount: dropped.length };
 }
-export function enforceImagePolicy(images) {
+export function enforceImageBytePolicy(images) {
     if (images.length === 0)
         return { ok: true };
     if (images.length > IMAGE_LIMITS.maxImagesPerTurn) {
@@ -126,13 +124,13 @@ export function enforceImagePolicy(images) {
                 `本次有 ${images.length} 张。请删掉一些再发。`,
             totals: {
                 imageCount: images.length,
-                totalBytes: images.reduce((s, i) => s + byteLengthFromBase64(i.base64), 0),
+                totalBytes: images.reduce((s, i) => s + i.bytes, 0),
             },
         };
     }
     let totalBytes = 0;
     for (const img of images) {
-        const bytes = byteLengthFromBase64(img.base64);
+        const bytes = img.bytes;
         if (bytes > IMAGE_LIMITS.maxBytesPerImage) {
             return {
                 ok: false,
@@ -163,6 +161,13 @@ export function enforceImagePolicy(images) {
     }
     return { ok: true };
 }
+export function enforceImagePolicy(images) {
+    return enforceImageBytePolicy(images.map((img) => ({
+        name: img.name,
+        mime: img.mime,
+        bytes: byteLengthFromBase64(img.base64),
+    })));
+}
 /**
  * Collect the workspace file paths of any attached images that came from a
  * real file (the desktop composer's path-attach flow sets ParsedImage.name to
@@ -178,6 +183,12 @@ export function enforceImagePolicy(images) {
 export function collectAttachedImagePaths(images, resolve, exists) {
     const out = [];
     for (const img of images) {
+        const path = img.path?.trim();
+        if (path) {
+            if (exists(resolve(path)))
+                out.push(path);
+            continue;
+        }
         const name = img.name?.trim();
         if (!name)
             continue;

package/dist/engine/input-attachments.d.ts

@@ -0,0 +1,13 @@
+import type { InputAttachmentMeta } from "../protocol/types.js";
+import type { ParsedImage } from "./parse-task.js";
+export interface InputAttachmentContext {
+    text: string;
+    images: ParsedImage[];
+    errors: string[];
+    hasStructuredImageAttachments: boolean;
+}
+export interface BuildInputAttachmentContextOptions {
+    includeImageBytes?: boolean;
+    expectedSessionId?: string;
+}
+export declare function buildInputAttachmentContext(attachments: readonly InputAttachmentMeta[] | undefined, cwd: string, options?: BuildInputAttachmentContextOptions): Promise<InputAttachmentContext>;

package/dist/engine/input-attachments.js

@@ -0,0 +1,255 @@
+import { createHash } from "node:crypto";
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import { extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { classifyPath } from "../tool-system/path-policy.js";
+import { enforceImageBytePolicy } from "./image-policy.js";
+const IMAGE_MIME_BY_EXT = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+};
+const MAX_DIRECTORY_TREE_ENTRIES = 200;
+const MAX_DIRECTORY_TREE_DEPTH = 2;
+export async function buildInputAttachmentContext(attachments, cwd, options = {}) {
+    if (!attachments || attachments.length === 0) {
+        return { text: "", images: [], errors: [], hasStructuredImageAttachments: false };
+    }
+    const cwdReal = await realpath(cwd);
+    const includeImageBytes = options.includeImageBytes ?? true;
+    const expectedSessionId = options.expectedSessionId;
+    const textBlocks = [];
+    const images = [];
+    const errors = [];
+    const pendingImages = [];
+    let hasStructuredImageAttachments = false;
+    if (!expectedSessionId) {
+        return {
+            text: "",
+            images: [],
+            errors: ["input attachments require an expected sessionId"],
+            hasStructuredImageAttachments: false,
+        };
+    }
+    if (!isSafeSessionPathSegment(expectedSessionId)) {
+        return {
+            text: "",
+            images: [],
+            errors: [`expected sessionId "${expectedSessionId}" is not a safe path segment`],
+            hasStructuredImageAttachments: false,
+        };
+    }
+    for (const attachment of attachments) {
+        if (!attachment || typeof attachment !== "object")
+            continue;
+        const displayPath = attachment.path || attachment.relPath || attachment.absPath;
+        if (!displayPath) {
+            errors.push(`attachment ${attachment.id || "(unknown)"} has no path`);
+            continue;
+        }
+        if (attachment.sessionId !== expectedSessionId) {
+            errors.push(`attachment ${attachment.id || displayPath} session mismatch: expected ${expectedSessionId}, got ${attachment.sessionId}`);
+            continue;
+        }
+        const resolved = resolveAttachmentPath(attachment, cwd);
+        let info;
+        try {
+            info = await stat(resolved);
+        }
+        catch (err) {
+            errors.push(`attachment ${attachment.id || displayPath} stat failed: ${err.message}`);
+            continue;
+        }
+        const policy = classifyPath(resolved, { workspaceRoot: cwdReal, operation: "read" });
+        if (policy.decision !== "allow") {
+            errors.push(`attachment ${attachment.id || displayPath} blocked by path policy: ${policy.reason}`);
+            continue;
+        }
+        const realPath = policy.resolvedPath;
+        const stagedPathError = await validateStagedAttachmentPath(attachment, realPath, cwdReal, expectedSessionId, displayPath);
+        if (stagedPathError) {
+            errors.push(stagedPathError);
+            continue;
+        }
+        if (attachment.kind === "directory" || info.isDirectory()) {
+            const tree = await directoryTree(realPath, cwdReal).catch((err) => ({
+                lines: [`(directory tree unavailable: ${err.message})`],
+                truncated: true,
+                entryCount: 0,
+            }));
+            textBlocks.push([
+                `<attached-directory path="${escapeText(displayPath)}" entries="${tree.entryCount}" truncated="${tree.truncated}">`,
+                ...tree.lines,
+                `</attached-directory>`,
+            ].join("\n"));
+            continue;
+        }
+        if (!info.isFile()) {
+            errors.push(`attachment ${attachment.id || displayPath} is not a regular file or directory`);
+            continue;
+        }
+        const mime = attachment.mime || IMAGE_MIME_BY_EXT[extname(realPath).toLowerCase()];
+        if (attachment.kind === "image") {
+            hasStructuredImageAttachments = true;
+            if (!includeImageBytes || attachment.vision?.include === false) {
+                textBlocks.push(formatFileMetadata(attachment, displayPath, realPath, info.size, mime));
+                continue;
+            }
+            if (!mime ||
+                !mime.startsWith("image/") ||
+                !IMAGE_MIME_BY_EXT[extname(realPath).toLowerCase()]) {
+                errors.push(`image attachment ${attachment.id || displayPath} has unsupported image type`);
+                continue;
+            }
+            pendingImages.push({
+                attachment,
+                displayPath,
+                realPath,
+                mime,
+                size: info.size,
+            });
+            continue;
+        }
+        textBlocks.push(formatFileMetadata(attachment, displayPath, realPath, info.size, mime));
+    }
+    if (errors.length === 0 && includeImageBytes && pendingImages.length > 0) {
+        const verdict = enforceImageBytePolicy(pendingImages.map((image) => ({
+            name: image.attachment.originalName || image.displayPath,
+            mime: image.mime,
+            bytes: image.size,
+        })));
+        if (!verdict.ok) {
+            errors.push(`image attachment size policy failed: ${verdict.message}`);
+        }
+        else {
+            for (const image of pendingImages) {
+                let bytes;
+                try {
+                    bytes = await readFile(image.realPath);
+                }
+                catch (err) {
+                    errors.push(`image attachment ${image.attachment.id || image.displayPath} read failed: ${err.message}`);
+                    continue;
+                }
+                const sha256 = createHash("sha256").update(bytes).digest("hex");
+                const base64 = bytes.toString("base64");
+                images.push({
+                    mime: image.mime,
+                    name: image.attachment.originalName || image.displayPath,
+                    dataUrl: `data:${image.mime};base64,${base64}`,
+                    base64,
+                    path: image.displayPath,
+                    hash: `sha256:${sha256}`,
+                    size: image.size,
+                    origin: image.attachment.origin,
+                    sessionId: image.attachment.sessionId,
+                });
+            }
+        }
+    }
+    return { text: textBlocks.join("\n\n"), images, errors, hasStructuredImageAttachments };
+}
+function resolveAttachmentPath(attachment, cwd) {
+    const candidate = attachment.vision?.mediaPath || attachment.absPath || attachment.relPath || attachment.path;
+    if (isAbsolute(candidate))
+        return candidate;
+    return resolve(cwd, candidate);
+}
+async function validateStagedAttachmentPath(attachment, realPath, cwdReal, expectedSessionId, displayPath) {
+    if (!isStagedAttachmentReference(attachment, realPath, cwdReal))
+        return undefined;
+    const expectedDir = resolve(cwdReal, ".code-shell", "attachments", expectedSessionId);
+    let expectedDirReal;
+    try {
+        expectedDirReal = await realpath(expectedDir);
+    }
+    catch (err) {
+        return `attachment ${attachment.id || displayPath} staged session directory is unavailable: ${err.message}`;
+    }
+    if (isPathInside(realPath, expectedDirReal))
+        return undefined;
+    return `attachment ${attachment.id || displayPath} staged path is outside .code-shell/attachments/${expectedSessionId}`;
+}
+function isStagedAttachmentReference(attachment, realPath, cwdReal) {
+    const fields = [
+        attachment.path,
+        attachment.absPath,
+        attachment.relPath,
+        attachment.vision?.mediaPath,
+    ].filter((value) => typeof value === "string" && value.length > 0);
+    if (fields.some((value) => looksLikeStagedAttachmentPath(value)))
+        return true;
+    return isPathInside(realPath, resolve(cwdReal, ".code-shell", "attachments"));
+}
+function looksLikeStagedAttachmentPath(value) {
+    const normalized = normalizePath(value);
+    return (normalized === ".code-shell/attachments" ||
+        normalized.startsWith(".code-shell/attachments/") ||
+        normalized.includes("/.code-shell/attachments/"));
+}
+function isPathInside(child, parent) {
+    const rel = relative(parent, child);
+    return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
+}
+function isSafeSessionPathSegment(sessionId) {
+    if (!sessionId)
+        return false;
+    return (!sessionId.includes("/") && !sessionId.includes("\\") && sessionId !== "." && sessionId !== "..");
+}
+function normalizePath(value) {
+    return value.replace(/\\/g, "/");
+}
+function formatFileMetadata(attachment, displayPath, realPath, size, mime) {
+    const lines = [
+        `<attached-file path="${escapeText(displayPath)}">`,
+        `absolutePath: ${realPath}`,
+        ...(mime ? [`mime: ${mime}`] : []),
+        `size: ${size}`,
+        `sha256: ${attachment.sha256}`,
+        `origin: ${attachment.origin}`,
+        `</attached-file>`,
+    ];
+    return lines.join("\n");
+}
+async function directoryTree(dir, cwdReal) {
+    const lines = [];
+    let entryCount = 0;
+    let truncated = false;
+    async function walk(current, depth) {
+        if (entryCount >= MAX_DIRECTORY_TREE_ENTRIES) {
+            truncated = true;
+            return;
+        }
+        const entries = await readdir(current, { withFileTypes: true });
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            if (entryCount >= MAX_DIRECTORY_TREE_ENTRIES) {
+                truncated = true;
+                return;
+            }
+            if (entry.name === ".git" || entry.name === "node_modules")
+                continue;
+            const abs = join(current, entry.name);
+            const real = await realpath(abs).catch(() => null);
+            if (!real)
+                continue;
+            const rel = relative(cwdReal, real);
+            if (rel === ".." || rel.startsWith(`..${sep}`))
+                continue;
+            entryCount += 1;
+            lines.push(`${"  ".repeat(depth)}${entry.isDirectory() ? "dir " : "file "}${slash(rel)}`);
+            if (entry.isDirectory() && depth + 1 < MAX_DIRECTORY_TREE_DEPTH) {
+                await walk(real, depth + 1);
+            }
+        }
+    }
+    await walk(dir, 0);
+    return { lines, truncated, entryCount };
+}
+function escapeText(value) {
+    return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
+function slash(value) {
+    return sep === "\\" ? value.replace(/\\/g, "/") : value;
+}

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

@@ -4,6 +4,9 @@
 import type { LLMClientBase } from "../llm/client-base.js";
 import type { Message, ToolDefinition, LLMResponse, StreamCallback } from "../types.js";
 import { Transcript } from "../session/transcript.js";
+export interface ModelCallRecordingOptions {
+    sensitiveToolResultRedactions?: ReadonlyMap<string, string>;
+}
 /**
  * Prompt-cache hit rate for one request, as CC computes it:
  *   cacheRead / (cacheRead + cacheCreation + uncachedInput)
@@ -18,11 +21,11 @@ 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(systemPrompt: string, messages: Message[], tools: ToolDefinition[], onStream?: StreamCallback, signal?: AbortSignal, recordingOptions?: ModelCallRecordingOptions): Promise<LLMResponse>;
     /**
      * Call without streaming — used as fallback when streaming fails.
      */
-    callWithoutStreaming(systemPrompt: string, messages: Message[], tools: ToolDefinition[], signal?: AbortSignal): Promise<LLMResponse>;
+    callWithoutStreaming(systemPrompt: string, messages: Message[], tools: ToolDefinition[], signal?: AbortSignal, recordingOptions?: ModelCallRecordingOptions): Promise<LLMResponse>;
     /** Record API timing and token usage to bootstrap state. */
     private recordUsage;
     /** Optional summarize function for tool use summaries. */

package/dist/engine/model-facade.js

@@ -5,6 +5,7 @@ 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";
+import { cacheHitRateFromUsage } from "./session-usage.js";
 let _reqSeq = 0;
 function nextReqId() {
     _reqSeq += 1;
@@ -20,18 +21,7 @@ function nextReqId() {
  * any caching tuning (docs/todo/prompt-cache-optimization.md §四 step 1).
  */
 export function cacheHitRate(usage) {
-    if (!usage)
-        return undefined;
-    const read = usage.cacheReadTokens ?? 0;
-    const creation = usage.cacheCreationTokens ?? 0;
-    if (read === 0 && creation === 0)
-        return undefined;
-    const prompt = usage.promptTokens ?? 0;
-    const uncached = Math.max(0, prompt - read - creation);
-    const denom = read + creation + uncached;
-    if (denom === 0)
-        return undefined;
-    return read / denom;
+    return cacheHitRateFromUsage(usage);
 }
 export class ModelFacade {
     client;
@@ -40,7 +30,7 @@ export class ModelFacade {
         this.client = client;
         this.transcript = transcript;
     }
-    async call(systemPrompt, messages, tools, onStream, signal) {
+    async call(systemPrompt, messages, tools, onStream, signal, recordingOptions) {
         const startMs = Date.now();
         const msgCount = messages.length;
         const sid = getCurrentSid();
@@ -52,7 +42,7 @@ export class ModelFacade {
             // 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),
+            messages: sanitizeMessages(messages, recordingOptions),
             tools,
             systemPrompt,
         }, reqId);
@@ -121,7 +111,7 @@ export class ModelFacade {
     /**
      * Call without streaming — used as fallback when streaming fails.
      */
-    async callWithoutStreaming(systemPrompt, messages, tools, signal) {
+    async callWithoutStreaming(systemPrompt, messages, tools, signal, recordingOptions) {
         const startMs = Date.now();
         const msgCount = messages.length;
         const sid = getCurrentSid();
@@ -132,7 +122,7 @@ export class ModelFacade {
             stream: false,
             // Image base64 payloads stay out of recorded prompts — same rule
             // as the streaming path above.
-            messages: sanitizeMessages(messages),
+            messages: sanitizeMessages(messages, recordingOptions),
             tools,
             systemPrompt,
         }, reqId);

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

@@ -29,6 +29,16 @@ export interface ParsedImage {
     dataUrl: string;
     /** Just the base64 payload, with the data-URL prefix stripped. */
     base64: string;
+    /** Stable on-disk path, usually cwd-relative for staged desktop attachments. */
+    path?: string;
+    /** Wire hash attr, usually `sha256:<hex>`. */
+    hash?: string;
+    /** Size in bytes from wire metadata. Core must still verify with stat when reading. */
+    size?: number;
+    /** Source channel that produced this attachment. */
+    origin?: string;
+    /** Session directory that owns the staged attachment. */
+    sessionId?: string;
 }
 export interface ParsedTask {
     /** Remaining plain-text portion (image blocks removed, surrounding whitespace trimmed). */

package/dist/engine/parse-task.js

@@ -117,6 +117,11 @@ export function parseTaskWithImages(task) {
             name: attrs.name ?? "",
             dataUrl: `data:${finalMime};base64,${base64}`,
             base64,
+            ...(attrs.path ? { path: attrs.path } : {}),
+            ...(attrs.hash ? { hash: attrs.hash } : {}),
+            ...(attrs.size && Number.isFinite(Number(attrs.size)) ? { size: Number(attrs.size) } : {}),
+            ...(attrs.origin ? { origin: attrs.origin } : {}),
+            ...(attrs.sessionid ? { sessionId: attrs.sessionid } : {}),
         });
         return "";
     });

package/dist/engine/query.js

@@ -9,6 +9,7 @@
  */
 import { TurnLoop } from "./turn-loop.js";
 import { logger } from "../logging/logger.js";
+import { messageHasBase64ImagePayload } from "../context/compaction.js";
 // ─── Query generator ────────────────────────────────────────────────
 /**
  * Run an agentic query and yield stream events as they occur.
@@ -37,6 +38,7 @@ export async function* query(params) {
         maxToolCallsPerTurn,
         onStream,
         signal,
+        freshImageMessages: messages.filter(messageHasBase64ImagePayload),
     };
     // Local overhead store — query() is a standalone entry point without a real
     // session id, so per-call in-memory state is enough.

package/dist/engine/session-usage.d.ts

@@ -1,5 +1,17 @@
 import type { TokenUsage } from "../types.js";
 import type { LLMUsageTracker } from "../llm/types.js";
+export interface CumulativeUsageCounters {
+    cumulativePromptTokens: number;
+    cumulativeCacheReadTokens: number;
+    cumulativeCacheCreationTokens: number;
+}
+export declare function emptyCumulativeUsageCounters(): CumulativeUsageCounters;
+export declare function normalizeCumulativeUsageCounters(counters: Partial<CumulativeUsageCounters> | undefined, legacyUsage?: TokenUsage): CumulativeUsageCounters;
+export declare function addCumulativeUsage(counters: Partial<CumulativeUsageCounters> | undefined, usage: TokenUsage): CumulativeUsageCounters;
+export declare function addTokenUsage(left: TokenUsage, right: TokenUsage): TokenUsage;
+export declare function cacheHitRateFromTokens(promptTokens: number, cacheReadTokens: number | undefined, cacheCreationTokens: number | undefined): number | undefined;
+export declare function cacheHitRateFromUsage(usage: TokenUsage | undefined): number | undefined;
+export declare function cumulativeCacheHitRate(counters: CumulativeUsageCounters): number | undefined;
 /**
  * Fold one run's cumulative usage onto a session baseline, producing the new
  * session-cumulative TokenUsage.

package/dist/engine/session-usage.js

@@ -1,3 +1,59 @@
+export function emptyCumulativeUsageCounters() {
+    return {
+        cumulativePromptTokens: 0,
+        cumulativeCacheReadTokens: 0,
+        cumulativeCacheCreationTokens: 0,
+    };
+}
+export function normalizeCumulativeUsageCounters(counters, legacyUsage) {
+    return {
+        cumulativePromptTokens: typeof counters?.cumulativePromptTokens === "number"
+            ? counters.cumulativePromptTokens
+            : (legacyUsage?.promptTokens ?? 0),
+        cumulativeCacheReadTokens: typeof counters?.cumulativeCacheReadTokens === "number"
+            ? counters.cumulativeCacheReadTokens
+            : (legacyUsage?.cacheReadTokens ?? 0),
+        cumulativeCacheCreationTokens: typeof counters?.cumulativeCacheCreationTokens === "number"
+            ? counters.cumulativeCacheCreationTokens
+            : (legacyUsage?.cacheCreationTokens ?? 0),
+    };
+}
+export function addCumulativeUsage(counters, usage) {
+    const current = normalizeCumulativeUsageCounters(counters);
+    return {
+        cumulativePromptTokens: current.cumulativePromptTokens + (usage.promptTokens ?? 0),
+        cumulativeCacheReadTokens: current.cumulativeCacheReadTokens + (usage.cacheReadTokens ?? 0),
+        cumulativeCacheCreationTokens: current.cumulativeCacheCreationTokens + (usage.cacheCreationTokens ?? 0),
+    };
+}
+export function addTokenUsage(left, right) {
+    return {
+        promptTokens: left.promptTokens + (right.promptTokens ?? 0),
+        completionTokens: left.completionTokens + (right.completionTokens ?? 0),
+        totalTokens: left.totalTokens + (right.totalTokens ?? 0),
+        cacheReadTokens: (left.cacheReadTokens ?? 0) + (right.cacheReadTokens ?? 0),
+        cacheCreationTokens: (left.cacheCreationTokens ?? 0) + (right.cacheCreationTokens ?? 0),
+    };
+}
+export function cacheHitRateFromTokens(promptTokens, cacheReadTokens, cacheCreationTokens) {
+    const read = cacheReadTokens ?? 0;
+    const creation = cacheCreationTokens ?? 0;
+    if (read === 0 && creation === 0)
+        return undefined;
+    const uncached = Math.max(0, promptTokens - read - creation);
+    const denom = read + creation + uncached;
+    if (denom === 0)
+        return undefined;
+    return read / denom;
+}
+export function cacheHitRateFromUsage(usage) {
+    if (!usage)
+        return undefined;
+    return cacheHitRateFromTokens(usage.promptTokens ?? 0, usage.cacheReadTokens, usage.cacheCreationTokens);
+}
+export function cumulativeCacheHitRate(counters) {
+    return cacheHitRateFromTokens(counters.cumulativePromptTokens, counters.cumulativeCacheReadTokens, counters.cumulativeCacheCreationTokens);
+}
 /**
  * Fold one run's cumulative usage onto a session baseline, producing the new
  * session-cumulative TokenUsage.

package/dist/engine/steer-queue.d.ts

@@ -9,9 +9,10 @@
 export interface SteerItem {
     id: string;
     text: string;
+    clientMessageId?: string;
 }
 /** Append a steer entry. Blank text is dropped (returns the list unchanged). */
-export declare function enqueueSteerItem(list: SteerItem[], id: string, text: string): SteerItem[];
+export declare function enqueueSteerItem(list: SteerItem[], id: string, text: string, clientMessageId?: string): SteerItem[];
 /**
  * Take everything currently queued and clear the list. Returns the drained
  * entries (in order) and the now-empty remainder. The turn loop calls this at

package/dist/engine/steer-queue.js

@@ -1,9 +1,9 @@
 /** Append a steer entry. Blank text is dropped (returns the list unchanged). */
-export function enqueueSteerItem(list, id, text) {
+export function enqueueSteerItem(list, id, text, clientMessageId) {
     const t = text?.trim();
     if (!id || !t)
         return list;
-    return [...list, { id, text: t }];
+    return [...list, { id, text: t, ...(clientMessageId ? { clientMessageId } : {}) }];
 }
 /**
  * Take everything currently queued and clear the list. Returns the drained

package/dist/engine/streaming-tool-queue.d.ts

@@ -1,13 +1,16 @@
 /**
- * Streaming tool queue — enqueues tools for execution during streaming,
- * starts concurrency-safe tools immediately, queues unsafe tools for
- * sequential execution.
+ * Tool execution queue for a completed model response.
+ *
+ * Despite the historical name, TurnLoop currently enqueues tool calls only
+ * after `callModelWithFallback()` returns a complete LLMResponse. The queue's
+ * job is concurrency policy inside that post-response batch: start
+ * concurrency-safe tools as soon as they are enqueued, keep unsafe tools
+ * sequential, and return results in original tool-call order.
  *
  * Usage:
  *   const queue = new StreamingToolQueue(executor);
- *   // During streaming, as tool_use blocks arrive:
+ *   // After the full LLMResponse is available:
  *   queue.enqueue(toolCall);
- *   // After streaming completes:
  *   const results = await queue.drain();
  */
 import type { ToolCall, ToolResult } from "../types.js";
@@ -21,8 +24,9 @@ export declare class StreamingToolQueue {
     private draining;
     constructor(executor: ToolExecutor);
     /**
-     * Enqueue a tool for execution. Concurrency-safe tools start immediately;
-     * unsafe tools are queued for sequential execution during drain().
+     * Enqueue a tool from the completed response. Concurrency-safe tools start
+     * immediately within this post-response phase; unsafe tools are queued for
+     * sequential execution during drain().
      */
     enqueue(call: ToolCall): void;
     /**

package/dist/engine/streaming-tool-queue.js

@@ -1,13 +1,16 @@
 /**
- * Streaming tool queue — enqueues tools for execution during streaming,
- * starts concurrency-safe tools immediately, queues unsafe tools for
- * sequential execution.
+ * Tool execution queue for a completed model response.
+ *
+ * Despite the historical name, TurnLoop currently enqueues tool calls only
+ * after `callModelWithFallback()` returns a complete LLMResponse. The queue's
+ * job is concurrency policy inside that post-response batch: start
+ * concurrency-safe tools as soon as they are enqueued, keep unsafe tools
+ * sequential, and return results in original tool-call order.
  *
  * Usage:
  *   const queue = new StreamingToolQueue(executor);
- *   // During streaming, as tool_use blocks arrive:
+ *   // After the full LLMResponse is available:
  *   queue.enqueue(toolCall);
- *   // After streaming completes:
  *   const results = await queue.drain();
  */
 export class StreamingToolQueue {
@@ -21,8 +24,9 @@ export class StreamingToolQueue {
         this.executor = executor;
     }
     /**
-     * Enqueue a tool for execution. Concurrency-safe tools start immediately;
-     * unsafe tools are queued for sequential execution during drain().
+     * Enqueue a tool from the completed response. Concurrency-safe tools start
+     * immediately within this post-response phase; unsafe tools are queued for
+     * sequential execution during drain().
      */
     enqueue(call) {
         this.callOrder.push(call.id);