@cjhyy/code-shell-core 0.6.0-rc.9 → 0.7.0

package/dist/engine/goal.d.ts

@@ -47,6 +47,21 @@ export interface GoalConfig {
      */
     setAtMs?: number;
 }
+/** A forced terminal outcome for one concrete persisted goal instance. */
+export type GoalTerminationReason = "stop_blocks_exhausted" | "token_budget_exhausted" | "time_budget_exhausted" | "max_turns_exhausted";
+/**
+ * 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: GoalTerminationReason;
+    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 +200,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/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,398 @@
+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 = {
+    ".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 = [];
+    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: [],
+            errors: ["input attachments require an expected sessionId"],
+            hasStructuredImageAttachments: false,
+        };
+    }
+    if (!isSafeSessionPathSegment(expectedSessionId)) {
+        logger.warn("engine.run.input_attachments.invalid_session", {
+            attachmentCount: attachments.length,
+            reason: "unsafe_expected_session_id",
+        });
+        return {
+            text: "",
+            images: [],
+            errors: [`expected sessionId "${expectedSessionId}" is not a safe path segment`],
+            hasStructuredImageAttachments: false,
+        };
+    }
+    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 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 ${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 ${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, displayPath);
+        let info;
+        try {
+            info = await stat(resolved);
+        }
+        catch (err) {
+            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 ${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()) {
+            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"));
+            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 ${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 = 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 ${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) => ({
+            name: image.attachment.originalName || image.displayPath,
+            mime: image.mime,
+            bytes: image.size,
+        })));
+        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) {
+                let bytes;
+                try {
+                    bytes = await readFile(image.realPath);
+                }
+                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");
+                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,
+                });
+                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, 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;
+    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

@@ -30,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();
@@ -42,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);
@@ -111,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();
@@ -122,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/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[];