@cjhyy/code-shell-core 0.7.0-beta.1 → 0.7.1

package/dist/engine/goal.d.ts

@@ -47,6 +47,23 @@ export interface GoalConfig {
      */
     setAtMs?: number;
 }
+/** A forced stop outcome for a Goal run. Some outcomes intentionally preserve the Goal. */
+export type GoalTerminationReason = "stop_blocks_exhausted" | "token_budget_exhausted" | "time_budget_exhausted" | "max_turns_exhausted" | "judge_prompt_too_large";
+/** Outcomes that permanently close one concrete persisted Goal instance. */
+export type PersistedGoalTerminationReason = Exclude<GoalTerminationReason, "judge_prompt_too_large">;
+/**
+ * Persisted terminal marker used to prevent a stale whole-state writer from
+ * making an exhausted goal armable again. `objective + setAtMs` is the goal
+ * instance identity; `terminatedAtMs` only orders competing tombstones.
+ */
+export interface GoalTerminal {
+    objective: string;
+    setAtMs?: number;
+    reason: PersistedGoalTerminationReason;
+    terminatedAtMs?: number;
+}
+/** True only when both values identify the same concrete goal instance. */
+export declare function isSameGoalInstance(left: Pick<GoalConfig, "objective" | "setAtMs"> | undefined, right: Pick<GoalConfig, "objective" | "setAtMs"> | undefined): boolean;
 /**
  * Default consecutive-stop-block cap for goal runs. The real safety net for an
  * unattended goal is the token/time budget + maxTurns; this cap only stops a
@@ -185,3 +202,5 @@ export declare function recordGoalUsage(tracker: GoalBudgetTracker, turnTokens:
  * pass the current clock (and tests pass a fixed value).
  */
 export declare function goalBudgetExceeded(tracker: GoalBudgetTracker, nowMs: number): boolean;
+/** Identify which goal budget forced termination, preserving token-first precedence. */
+export declare function goalBudgetTerminationReason(tracker: GoalBudgetTracker, nowMs: number): Extract<GoalTerminationReason, "token_budget_exhausted" | "time_budget_exhausted"> | undefined;

package/dist/engine/goal.js

@@ -10,6 +10,10 @@
  * it accumulates total tokens across turns and stamps a wall-clock start,
  * so an unattended goal run can't burn tokens or wall time without bound.
  */
+/** True only when both values identify the same concrete goal instance. */
+export function isSameGoalInstance(left, right) {
+    return !!left && !!right && left.objective === right.objective && left.setAtMs === right.setAtMs;
+}
 /**
  * Default consecutive-stop-block cap for goal runs. The real safety net for an
  * unattended goal is the token/time budget + maxTurns; this cap only stops a
@@ -94,7 +98,7 @@ export function normalizeGoal(raw) {
  */
 export function resolveGoalSetAt(explicitObjective, stored, nowMs) {
     const sameGoalContinues = !!stored && stored.objective === explicitObjective;
-    return sameGoalContinues ? stored.setAtMs ?? nowMs : nowMs;
+    return sameGoalContinues ? (stored.setAtMs ?? nowMs) : nowMs;
 }
 /** Interactive (no-goal) turn ceiling — a single prompt rarely needs more. */
 export const INTERACTIVE_DEFAULT_MAX_TURNS = 100;
@@ -187,10 +191,16 @@ export function recordGoalUsage(tracker, turnTokens) {
  * pass the current clock (and tests pass a fixed value).
  */
 export function goalBudgetExceeded(tracker, nowMs) {
+    return goalBudgetTerminationReason(tracker, nowMs) !== undefined;
+}
+/** Identify which goal budget forced termination, preserving token-first precedence. */
+export function goalBudgetTerminationReason(tracker, nowMs) {
     const { tokenBudget, timeBudgetMs } = tracker.goal;
-    if (typeof tokenBudget === "number" && tracker.tokensUsed > tokenBudget)
-        return true;
-    if (typeof timeBudgetMs === "number" && nowMs - tracker.startedAtMs > timeBudgetMs)
-        return true;
-    return false;
+    if (typeof tokenBudget === "number" && tracker.tokensUsed > tokenBudget) {
+        return "token_budget_exhausted";
+    }
+    if (typeof timeBudgetMs === "number" && nowMs - tracker.startedAtMs > timeBudgetMs) {
+        return "time_budget_exhausted";
+    }
+    return undefined;
 }

package/dist/engine/input-attachments.js

@@ -1,6 +1,7 @@
 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 { logger } from "../logging/logger.js";
 import { classifyPath } from "../tool-system/path-policy.js";
 import { enforceImageBytePolicy } from "./image-policy.js";
 const IMAGE_MIME_BY_EXT = {
@@ -23,8 +24,18 @@ export async function buildInputAttachmentContext(attachments, cwd, options = {}
     const images = [];
     const errors = [];
     const pendingImages = [];
+    const diagnostics = [];
     let hasStructuredImageAttachments = false;
+    logger.info("engine.run.input_attachments.start", {
+        attachmentCount: attachments.length,
+        expectedSessionId: expectedSessionId ?? null,
+        includeImageBytes,
+    });
     if (!expectedSessionId) {
+        logger.warn("engine.run.input_attachments.invalid_session", {
+            attachmentCount: attachments.length,
+            reason: "missing_expected_session_id",
+        });
         return {
             text: "",
             images: [],
@@ -33,6 +44,10 @@ export async function buildInputAttachmentContext(attachments, cwd, options = {}
         };
     }
     if (!isSafeSessionPathSegment(expectedSessionId)) {
+        logger.warn("engine.run.input_attachments.invalid_session", {
+            attachmentCount: attachments.length,
+            reason: "unsafe_expected_session_id",
+        });
         return {
             text: "",
             images: [],
@@ -40,36 +55,89 @@ export async function buildInputAttachmentContext(attachments, cwd, options = {}
             hasStructuredImageAttachments: false,
         };
     }
-    for (const attachment of attachments) {
-        if (!attachment || typeof attachment !== "object")
+    for (const [index, attachment] of attachments.entries()) {
+        if (!attachment || typeof attachment !== "object") {
+            errors.push(`attachment at index ${index} is not an object`);
+            diagnostics.push({
+                index,
+                id: "(unknown)",
+                kind: typeof attachment,
+                path: null,
+                mime: null,
+                stage: "invalid_metadata",
+            });
             continue;
-        const displayPath = attachment.path || attachment.relPath || attachment.absPath;
+        }
+        const id = stringField(attachment.id) ?? "(unknown)";
+        const kind = stringField(attachment.kind) ?? "(unknown)";
+        const declaredMime = stringField(attachment.mime);
+        const displayPath = firstString(attachment.path, attachment.relPath, attachment.absPath);
         if (!displayPath) {
-            errors.push(`attachment ${attachment.id || "(unknown)"} has no path`);
+            errors.push(`attachment ${id} has no valid path`);
+            diagnostics.push({
+                index,
+                id,
+                kind,
+                path: null,
+                mime: declaredMime ?? null,
+                stage: "invalid_path_metadata",
+            });
             continue;
         }
         if (attachment.sessionId !== expectedSessionId) {
-            errors.push(`attachment ${attachment.id || displayPath} session mismatch: expected ${expectedSessionId}, got ${attachment.sessionId}`);
+            errors.push(`attachment ${id === "(unknown)" ? displayPath : id} session mismatch: expected ${expectedSessionId}, got ${attachment.sessionId}`);
+            diagnostics.push({
+                index,
+                id,
+                kind,
+                path: displayPath,
+                mime: declaredMime ?? null,
+                stage: "session_mismatch",
+            });
             continue;
         }
-        const resolved = resolveAttachmentPath(attachment, cwd);
+        const resolved = resolveAttachmentPath(attachment, cwd, displayPath);
         let info;
         try {
             info = await stat(resolved);
         }
         catch (err) {
-            errors.push(`attachment ${attachment.id || displayPath} stat failed: ${err.message}`);
+            errors.push(`attachment ${id === "(unknown)" ? displayPath : id} stat failed: ${err.message}`);
+            diagnostics.push({
+                index,
+                id,
+                kind,
+                path: displayPath,
+                mime: declaredMime ?? null,
+                stage: "stat_failed",
+            });
             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}`);
+            errors.push(`attachment ${id === "(unknown)" ? displayPath : id} blocked by path policy: ${policy.reason}`);
+            diagnostics.push({
+                index,
+                id,
+                kind,
+                path: displayPath,
+                mime: declaredMime ?? null,
+                stage: "path_policy_blocked",
+            });
             continue;
         }
         const realPath = policy.resolvedPath;
         const stagedPathError = await validateStagedAttachmentPath(attachment, realPath, cwdReal, expectedSessionId, displayPath);
         if (stagedPathError) {
             errors.push(stagedPathError);
+            diagnostics.push({
+                index,
+                id,
+                kind,
+                path: displayPath,
+                mime: declaredMime ?? null,
+                stage: "staged_path_blocked",
+            });
             continue;
         }
         if (attachment.kind === "directory" || info.isDirectory()) {
@@ -83,35 +151,85 @@ export async function buildInputAttachmentContext(attachments, cwd, options = {}
                 ...tree.lines,
                 `</attached-directory>`,
             ].join("\n"));
+            diagnostics.push({
+                index,
+                id,
+                kind: "directory",
+                path: displayPath,
+                mime: declaredMime ?? null,
+                stage: tree.truncated ? "directory_metadata_truncated" : "directory_metadata",
+            });
             continue;
         }
         if (!info.isFile()) {
-            errors.push(`attachment ${attachment.id || displayPath} is not a regular file or directory`);
+            errors.push(`attachment ${id === "(unknown)" ? displayPath : id} is not a regular file or directory`);
+            diagnostics.push({
+                index,
+                id,
+                kind,
+                path: displayPath,
+                mime: declaredMime ?? null,
+                stage: "unsupported_filesystem_entry",
+            });
             continue;
         }
-        const mime = attachment.mime || IMAGE_MIME_BY_EXT[extname(realPath).toLowerCase()];
+        const mime = declaredMime || 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));
+                diagnostics.push({
+                    index,
+                    id,
+                    kind,
+                    path: displayPath,
+                    mime: mime ?? null,
+                    stage: "image_metadata_only",
+                });
                 continue;
             }
             if (!mime ||
                 !mime.startsWith("image/") ||
                 !IMAGE_MIME_BY_EXT[extname(realPath).toLowerCase()]) {
-                errors.push(`image attachment ${attachment.id || displayPath} has unsupported image type`);
+                errors.push(`image attachment ${id === "(unknown)" ? displayPath : id} has unsupported image type`);
+                diagnostics.push({
+                    index,
+                    id,
+                    kind,
+                    path: displayPath,
+                    mime: mime ?? null,
+                    stage: "unsupported_image_type",
+                });
                 continue;
             }
+            const diagnostic = {
+                index,
+                id,
+                kind,
+                path: displayPath,
+                mime,
+                stage: "image_pending_bytes",
+            };
             pendingImages.push({
                 attachment,
                 displayPath,
                 realPath,
                 mime,
                 size: info.size,
+                diagnostic,
             });
+            diagnostics.push(diagnostic);
             continue;
         }
         textBlocks.push(formatFileMetadata(attachment, displayPath, realPath, info.size, mime));
+        diagnostics.push({
+            index,
+            id,
+            kind,
+            path: displayPath,
+            mime: mime ?? null,
+            stage: "file_metadata",
+        });
     }
     if (errors.length === 0 && includeImageBytes && pendingImages.length > 0) {
         const verdict = enforceImageBytePolicy(pendingImages.map((image) => ({
@@ -121,6 +239,11 @@ export async function buildInputAttachmentContext(attachments, cwd, options = {}
         })));
         if (!verdict.ok) {
             errors.push(`image attachment size policy failed: ${verdict.message}`);
+            for (const diagnostic of diagnostics) {
+                if (diagnostic.stage === "image_pending_bytes") {
+                    diagnostic.stage = "image_size_policy_failed";
+                }
+            }
         }
         else {
             for (const image of pendingImages) {
@@ -130,6 +253,7 @@ export async function buildInputAttachmentContext(attachments, cwd, options = {}
                 }
                 catch (err) {
                     errors.push(`image attachment ${image.attachment.id || image.displayPath} read failed: ${err.message}`);
+                    image.diagnostic.stage = "image_read_failed";
                     continue;
                 }
                 const sha256 = createHash("sha256").update(bytes).digest("hex");
@@ -145,17 +269,36 @@ export async function buildInputAttachmentContext(attachments, cwd, options = {}
                     origin: image.attachment.origin,
                     sessionId: image.attachment.sessionId,
                 });
+                image.diagnostic.stage = "image_bytes_loaded";
             }
         }
     }
+    logger.info("engine.run.input_attachments.complete", {
+        attachmentCount: attachments.length,
+        textBlockCount: textBlocks.length,
+        imageCount: images.length,
+        errorCount: errors.length,
+        attachments: diagnostics,
+    });
     return { text: textBlocks.join("\n\n"), images, errors, hasStructuredImageAttachments };
 }
-function resolveAttachmentPath(attachment, cwd) {
-    const candidate = attachment.vision?.mediaPath || attachment.absPath || attachment.relPath || attachment.path;
+function resolveAttachmentPath(attachment, cwd, displayPath) {
+    const visionPath = attachment.vision && typeof attachment.vision === "object"
+        ? stringField(attachment.vision.mediaPath)
+        : undefined;
+    const candidate = visionPath ??
+        firstString(attachment.absPath, attachment.relPath, attachment.path) ??
+        displayPath;
     if (isAbsolute(candidate))
         return candidate;
     return resolve(cwd, candidate);
 }
+function firstString(...values) {
+    return values.find((value) => typeof value === "string" && value.length > 0);
+}
+function stringField(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
 async function validateStagedAttachmentPath(attachment, realPath, cwdReal, expectedSessionId, displayPath) {
     if (!isStagedAttachmentReference(attachment, realPath, cwdReal))
         return undefined;

package/dist/engine/run-image-input.d.ts

@@ -0,0 +1,22 @@
+import type { InputAttachmentMeta } from "../protocol/types.js";
+import type { ContentBlock, LLMConfig } from "../types.js";
+import { type ParsedTask } from "./parse-task.js";
+import type { EngineResult } from "./types.js";
+export interface PreparedRunImageInput {
+    parsedTask: ParsedTask;
+    taskText: string;
+}
+export type PrepareRunImageInputResult = ({
+    ok: true;
+} & PreparedRunImageInput) | {
+    ok: false;
+    result: EngineResult;
+};
+export declare function prepareRunImageInput(args: {
+    task: string;
+    cwd: string;
+    llm: Pick<LLMConfig, "provider" | "providerKind" | "model">;
+    sessionId?: string;
+    attachments?: readonly InputAttachmentMeta[];
+}): Promise<PrepareRunImageInputResult>;
+export declare function buildRunUserMessageContent(parsedTask: ParsedTask, cwd: string, taskText: string): string | ContentBlock[];

package/dist/engine/run-image-input.js

@@ -0,0 +1,195 @@
+import { existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { capabilitiesFor } from "../llm/capabilities/index.js";
+import { logger } from "../logging/logger.js";
+import { tryCompressImages } from "./image-compression.js";
+import { byteLengthFromBase64, collectAttachedImagePaths, dropOversizedImages, enforceImagePolicy, } from "./image-policy.js";
+import { buildInputAttachmentContext } from "./input-attachments.js";
+import { parseTaskWithImages } from "./parse-task.js";
+export async function prepareRunImageInput(args) {
+    const { task, cwd, llm, sessionId } = args;
+    // Parse `<codeshell-image>` blocks out of the raw task string before
+    // any other gate looks at it. Two concerns:
+    //   1. The noise detector sees raw base64 as gibberish and would reject the
+    //      whole turn — split images out first so it only inspects prose.
+    //   2. Models that don't accept vision must be refused immediately, with the
+    //      image bytes intact for the user to retry on another model.
+    let parsedTask;
+    try {
+        parsedTask = parseTaskWithImages(task);
+    }
+    catch (err) {
+        const msg = err.message;
+        logger.warn("engine.run.image_parse_failed", { error: msg });
+        return {
+            ok: false,
+            result: {
+                text: `ERROR: image attachment is malformed (${msg}). Drop the image and try again, or re-attach it.`,
+                reason: "image_error",
+                sessionId: sessionId ?? "image-parse-failed",
+                turnCount: 0,
+                usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+            },
+        };
+    }
+    const cap = capabilitiesFor((llm.providerKind ?? llm.provider), llm.model);
+    let attachmentContext;
+    try {
+        attachmentContext = await buildInputAttachmentContext(args.attachments, cwd, {
+            includeImageBytes: cap.supportsVision,
+            expectedSessionId: sessionId,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.error("engine.run.input_attachment_exception", {
+            stage: "build_input_attachment_context",
+            attachmentCount: args.attachments?.length ?? 0,
+            error: message,
+        });
+        return {
+            ok: false,
+            result: {
+                text: `ERROR: input attachment could not be prepared (${message}). Re-attach it or choose a path inside the workspace.`,
+                reason: "image_error",
+                sessionId: sessionId ?? "input-attachment-exception",
+                turnCount: 0,
+                usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+            },
+        };
+    }
+    if (attachmentContext.errors.length > 0) {
+        const detail = attachmentContext.errors.join("; ");
+        logger.warn("engine.run.input_attachment_failed", { error: detail });
+        return {
+            ok: false,
+            result: {
+                text: `ERROR: input attachment could not be read (${detail}). Re-attach it or choose a path inside the workspace.`,
+                reason: "image_error",
+                sessionId: sessionId ?? "input-attachment-failed",
+                turnCount: 0,
+                usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+            },
+        };
+    }
+    if (attachmentContext.text || attachmentContext.hasStructuredImageAttachments) {
+        parsedTask = {
+            text: [parsedTask.text, attachmentContext.text].filter(Boolean).join("\n\n"),
+            images: [...parsedTask.images, ...attachmentContext.images],
+            hasImages: parsedTask.hasImages ||
+                attachmentContext.images.length > 0 ||
+                attachmentContext.hasStructuredImageAttachments,
+        };
+    }
+    if (parsedTask.hasImages) {
+        if (!cap.supportsVision) {
+            logger.warn("engine.run.vision_not_supported", {
+                provider: llm.provider,
+                model: llm.model,
+                imageCount: parsedTask.images.length,
+            });
+            return {
+                ok: false,
+                result: {
+                    text: `ERROR: model "${llm.model}" does not accept image input. ` +
+                        `Switch to a vision-capable model (e.g. gpt-4o, claude-sonnet, gemini-1.5-pro) and resend.`,
+                    reason: "image_error",
+                    sessionId: sessionId ?? "vision-not-supported",
+                    turnCount: 0,
+                    usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+                },
+            };
+        }
+        // Size gate. Hosts are expected to pre-compress to IMAGE_TARGETS; this is
+        // the last cheap refusal point before a provider request carries the bytes.
+        let verdict = enforceImagePolicy(parsedTask.images);
+        if (!verdict.ok && verdict.code === "image_too_large") {
+            const compressed = await tryCompressImages(parsedTask.images);
+            if (compressed.anyCompressed) {
+                parsedTask.images = compressed.images;
+                logger.info("engine.run.image_compressed", {
+                    before: verdict.offender?.bytes,
+                    after: compressed.images.reduce((s, i) => s + byteLengthFromBase64(i.base64), 0),
+                });
+                verdict = enforceImagePolicy(parsedTask.images);
+            }
+        }
+        // After compression, anything still over the per-image cap is dropped with
+        // a textual placeholder so oversized bytes do not poison conversation history.
+        if (!verdict.ok && verdict.code === "image_too_large") {
+            const drop = dropOversizedImages(parsedTask.images);
+            if (drop.droppedCount > 0) {
+                parsedTask.images = drop.kept;
+                parsedTask.hasImages = drop.kept.length > 0;
+                parsedTask.text = drop.placeholder + "\n\n" + parsedTask.text;
+                logger.warn("engine.run.image_dropped", {
+                    droppedCount: drop.droppedCount,
+                    keptCount: drop.kept.length,
+                });
+                verdict = enforceImagePolicy(parsedTask.images);
+            }
+        }
+        if (!verdict.ok) {
+            logger.warn("engine.run.image_policy_failed", {
+                code: verdict.code,
+                imageCount: verdict.totals.imageCount,
+                totalBytes: verdict.totals.totalBytes,
+                offender: verdict.offender,
+            });
+            return {
+                ok: false,
+                result: {
+                    text: `ERROR: ${verdict.message}`,
+                    reason: "image_error",
+                    sessionId: sessionId ?? `image-policy-${verdict.code}`,
+                    turnCount: 0,
+                    usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+                },
+            };
+        }
+    }
+    // For downstream noise-detection + transcript persistence we want the text
+    // portion only. Image bytes ride in parsedTask.images and re-enter the message
+    // tree below.
+    const taskText = parsedTask.text;
+    return { ok: true, parsedTask, taskText };
+}
+export function buildRunUserMessageContent(parsedTask, cwd, taskText) {
+    // Compose the user-turn payload once so resume + cold paths agree on shape.
+    // When an attached image came from a workspace file, surface that path to the
+    // model as text so file-oriented tools can use the real on-disk path.
+    const attachedPaths = collectAttachedImagePaths(parsedTask.images, (name) => (isAbsolute(name) ? name : join(cwd, name)), existsSync);
+    const pathHint = attachedPaths.length > 0
+        ? `\n\n<attached-image-paths>\n${attachedPaths.join("\n")}\n</attached-image-paths>\n` +
+            `(上面附带的图片在工作区的真实路径，如需把它们作为工具输入（例如 GenerateImage 的 referenceImages、图生图参考图），直接使用这些路径。)`
+        : "";
+    const userMessageContent = parsedTask.hasImages
+        ? [
+            ...(parsedTask.text || pathHint
+                ? [{ type: "text", text: `${parsedTask.text}${pathHint}` }]
+                : []),
+            ...parsedTask.images.map((img) => ({
+                type: "image",
+                source: {
+                    type: "base64",
+                    media_type: img.mime,
+                    data: img.base64,
+                },
+            })),
+        ]
+        : taskText;
+    logger.info("engine.run.user_message_content_built", {
+        contentShape: Array.isArray(userMessageContent) ? "content_blocks" : "text",
+        textBlockCount: Array.isArray(userMessageContent)
+            ? userMessageContent.filter((block) => block.type === "text").length
+            : userMessageContent
+                ? 1
+                : 0,
+        imageBlockCount: Array.isArray(userMessageContent)
+            ? userMessageContent.filter((block) => block.type === "image").length
+            : 0,
+        attachedPathCount: attachedPaths.length,
+        textLength: taskText.length,
+    });
+    return userMessageContent;
+}

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

@@ -5,9 +5,10 @@
  * resolves the aux client and wiring; this only does the LLM call + cleanup.
  */
 import type { LLMClientBase } from "../llm/client-base.js";
+import type { TokenUsage } from "../types.js";
 /**
  * Ask the aux client for a one-line title from the first user message + first
  * assistant reply. Returns the cleaned title, or null on any failure / empty
  * output (caller treats null as "keep existing title").
  */
-export declare function buildSessionTitle(client: LLMClientBase, firstUserText: string, firstAssistantText: string): Promise<string | null>;
+export declare function buildSessionTitle(client: LLMClientBase, firstUserText: string, firstAssistantText: string, recordBilledUsage?: (usage: TokenUsage) => void): Promise<string | null>;

package/dist/engine/session-title.js

@@ -13,7 +13,7 @@ function clean(raw) {
  * assistant reply. Returns the cleaned title, or null on any failure / empty
  * output (caller treats null as "keep existing title").
  */
-export async function buildSessionTitle(client, firstUserText, firstAssistantText) {
+export async function buildSessionTitle(client, firstUserText, firstAssistantText, recordBilledUsage) {
     try {
         const prompt = `User: ${firstUserText.slice(0, 2000)}\n\n` +
             `Assistant: ${firstAssistantText.slice(0, 2000)}\n\n` +
@@ -23,8 +23,11 @@ export async function buildSessionTitle(client, firstUserText, firstAssistantTex
             messages: [{ role: "user", content: prompt }],
             tools: [],
             maxTokens: 64,
+            requestVisible: false,
             reasoning: { mode: "off" },
         });
+        if (resp.usage)
+            recordBilledUsage?.(resp.usage);
         const title = clean(resp.text ?? "");
         return title.length > 0 ? title : null;
     }

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

@@ -6,13 +6,15 @@
  * it. Pure + side-effect-free so it unit-tests without the Engine/TurnLoop
  * harness (same rationale as the renderer's queuedInput.ts).
  */
+import type { InputAttachmentMeta } from "../protocol/types.js";
 export interface SteerItem {
     id: string;
     text: string;
     clientMessageId?: string;
+    attachments?: InputAttachmentMeta[];
 }
 /** Append a steer entry. Blank text is dropped (returns the list unchanged). */
-export declare function enqueueSteerItem(list: SteerItem[], id: string, text: string, clientMessageId?: string): SteerItem[];
+export declare function enqueueSteerItem(list: SteerItem[], id: string, text: string, clientMessageId?: string, attachments?: InputAttachmentMeta[]): 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,17 @@
 /** Append a steer entry. Blank text is dropped (returns the list unchanged). */
-export function enqueueSteerItem(list, id, text, clientMessageId) {
+export function enqueueSteerItem(list, id, text, clientMessageId, attachments) {
     const t = text?.trim();
     if (!id || !t)
         return list;
-    return [...list, { id, text: t, ...(clientMessageId ? { clientMessageId } : {}) }];
+    return [
+        ...list,
+        {
+            id,
+            text: t,
+            ...(clientMessageId ? { clientMessageId } : {}),
+            ...(attachments && attachments.length > 0 ? { attachments: [...attachments] } : {}),
+        },
+    ];
 }
 /**
  * Take everything currently queued and clear the list. Returns the drained