@cjhyy/code-shell-core 0.6.0-rc.13 → 0.6.0-rc.14

package/dist/context/compaction.d.ts

@@ -10,7 +10,7 @@
  * All slicing functions use adjustIndexToPreserveAPIInvariants()
  * to prevent splitting tool_use / tool_result pairs.
  */
-import type { Message } from "../types.js";
+import type { ContentBlock, Message } from "../types.js";
 /**
  * Estimate token count from messages.
  * Uses per-block-type estimation with 33% overhead padding.
@@ -34,6 +34,12 @@ export interface DowngradeImageHistoryResult {
     messages: Message[];
     replacedCount: number;
 }
+export interface Base64ImageHistoryEntry {
+    imageNumber: number;
+    block: ContentBlock;
+}
+export declare function collectBase64Images(messages: Message[]): Base64ImageHistoryEntry[];
+export declare function findImageByNumber(messages: Message[], imageNumber: number): Base64ImageHistoryEntry | undefined;
 /**
  * Replace already-consumed image payload blocks with compact text markers.
  *
@@ -45,6 +51,7 @@ export interface DowngradeImageHistoryResult {
  */
 export declare function downgradeImagePayloadsInHistory(messages: Message[], options?: DowngradeImageHistoryOptions): DowngradeImageHistoryResult;
 export declare function messageHasBase64ImagePayload(message: Message): boolean;
+export declare function isBase64ImageBlock(block: ContentBlock): boolean;
 /**
  * Reconcile user-supplied compaction ratios into a safe ordering.
  *

package/dist/context/compaction.js

@@ -20,6 +20,36 @@ export function estimateTokens(messages) {
 }
 export const IMAGE_HISTORY_PLACEHOLDER_PREFIX = "[image #";
 export const IMAGE_HISTORY_PLACEHOLDER_SUFFIX = ", 已处理 / already provided earlier]";
+export function collectBase64Images(messages) {
+    const entries = [];
+    let nextImageNumber = 1;
+    const visitBlocks = (blocks) => {
+        for (const block of blocks) {
+            const placeholderNumber = imageHistoryPlaceholderNumber(block);
+            if (placeholderNumber !== undefined) {
+                nextImageNumber = Math.max(nextImageNumber, placeholderNumber + 1);
+                continue;
+            }
+            if (isBase64ImageBlock(block)) {
+                entries.push({ imageNumber: nextImageNumber++, block });
+                continue;
+            }
+            if (block.type === "tool_result" && Array.isArray(block.content)) {
+                visitBlocks(block.content);
+            }
+        }
+    };
+    for (const msg of messages) {
+        if (Array.isArray(msg.content))
+            visitBlocks(msg.content);
+    }
+    return entries;
+}
+export function findImageByNumber(messages, imageNumber) {
+    if (!Number.isSafeInteger(imageNumber) || imageNumber <= 0)
+        return undefined;
+    return collectBase64Images(messages).find((entry) => entry.imageNumber === imageNumber);
+}
 /**
  * Replace already-consumed image payload blocks with compact text markers.
  *
@@ -30,9 +60,23 @@ export const IMAGE_HISTORY_PLACEHOLDER_SUFFIX = ", 已处理 / already provided
  * nested inside tool_result.content arrays (view_image / browser screenshots).
  */
 export function downgradeImagePayloadsInHistory(messages, options = {}) {
-    let nextImageNumber = 1;
     let replacedCount = 0;
     let changed = false;
+    const imageNumberQueues = new WeakMap();
+    for (const entry of collectBase64Images(messages)) {
+        const key = entry.block;
+        const existing = imageNumberQueues.get(key);
+        if (existing) {
+            existing.push(entry.imageNumber);
+        }
+        else {
+            imageNumberQueues.set(key, [entry.imageNumber]);
+        }
+    }
+    const takeImageNumber = (block) => {
+        const queue = imageNumberQueues.get(block);
+        return queue?.shift();
+    };
     const placeholderFor = (imageNumber) => ({
         type: "text",
         text: `${IMAGE_HISTORY_PLACEHOLDER_PREFIX}${imageNumber}${IMAGE_HISTORY_PLACEHOLDER_SUFFIX}`,
@@ -42,11 +86,12 @@ export function downgradeImagePayloadsInHistory(messages, options = {}) {
         const out = blocks.map((block) => {
             const placeholderNumber = imageHistoryPlaceholderNumber(block);
             if (placeholderNumber !== undefined) {
-                nextImageNumber = Math.max(nextImageNumber, placeholderNumber + 1);
                 return block;
             }
             if (isBase64ImageBlock(block)) {
-                const imageNumber = nextImageNumber++;
+                const imageNumber = takeImageNumber(block);
+                if (imageNumber === undefined)
+                    return block;
                 if (preserve)
                     return block;
                 replacedCount++;
@@ -99,7 +144,7 @@ function imageHistoryPlaceholderNumber(block) {
     const n = Number(match[1]);
     return Number.isSafeInteger(n) && n > 0 ? n : undefined;
 }
-function isBase64ImageBlock(block) {
+export function isBase64ImageBlock(block) {
     if (block.type === "image" &&
         block.source?.type === "base64" &&
         typeof block.source.data === "string" &&

package/dist/engine/turn-loop.js

@@ -800,7 +800,7 @@ export class TurnLoop {
                 const resultBlocks = [];
                 for (const result of results) {
                     resultBlocks.push(toolResultToBlock(result));
-                    this.deps.transcript.appendToolResult(result.id, result.toolName, result.result, result.error);
+                    this.deps.transcript.appendToolResult(result.id, result.toolName, result.result, result.error, result.contentBlocks);
                     this.config.onStream?.({ type: "tool_result", result });
                 }
                 // Fire-and-forget tool use summary (non-blocking). The whole chain is

package/dist/session/transcript.d.ts

@@ -27,7 +27,7 @@ export declare class Transcript {
     }): TranscriptEvent;
     hasClientMessageId(clientMessageId: string): boolean;
     appendToolUse(toolName: string, toolCallId: string, args: Record<string, unknown>): TranscriptEvent;
-    appendToolResult(toolCallId: string, toolName: string, result?: string, error?: string): TranscriptEvent;
+    appendToolResult(toolCallId: string, toolName: string, result?: string, error?: string, contentBlocks?: ContentBlock[]): TranscriptEvent;
     /** Anchor for a spawned sub-agent (see TranscriptEventType "subagent").
      *  Written at spawn time so replay can rebuild the sub-agent's card from
      *  sessions/<agentId>/ — agentId === the sub-agent's session id. */

package/dist/session/transcript.js

@@ -10,7 +10,9 @@ export class Transcript {
     events = [];
     filePath;
     currentTurn = 0;
-    getFilePath() { return this.filePath; }
+    getFilePath() {
+        return this.filePath;
+    }
     constructor(filePath) {
         this.filePath = filePath;
         mkdirSync(dirname(filePath), { recursive: true });
@@ -66,8 +68,14 @@ export class Transcript {
     appendToolUse(toolName, toolCallId, args) {
         return this.append("tool_use", { toolName, toolCallId, args });
     }
-    appendToolResult(toolCallId, toolName, result, error) {
-        return this.append("tool_result", { toolCallId, toolName, result, error });
+    appendToolResult(toolCallId, toolName, result, error, contentBlocks) {
+        return this.append("tool_result", {
+            toolCallId,
+            toolName,
+            result,
+            error,
+            ...(contentBlocks && contentBlocks.length > 0 ? { contentBlocks } : {}),
+        });
     }
     /** Anchor for a spawned sub-agent (see TranscriptEventType "subagent").
      *  Written at spawn time so replay can rebuild the sub-agent's card from
@@ -125,13 +133,17 @@ export class Transcript {
                     break;
                 }
                 case "tool_result": {
-                    const { toolCallId, result, error } = event.data;
+                    const { toolCallId, result, error, contentBlocks } = event.data;
                     // Find if there's already a user message with tool_results to append to
                     const lastMsg = messages[messages.length - 1];
                     const block = {
                         type: "tool_result",
                         tool_use_id: toolCallId,
-                        content: error ? `Error: ${error}` : result ?? "(no output)",
+                        content: error
+                            ? `Error: ${error}`
+                            : Array.isArray(contentBlocks) && contentBlocks.length > 0
+                                ? contentBlocks
+                                : (result ?? "(no output)"),
                     };
                     if (lastMsg?.role === "user" && Array.isArray(lastMsg.content)) {
                         lastMsg.content.push(block);

package/dist/tool-system/builtin/view-image.d.ts

@@ -1,6 +1,6 @@
 /**
- * Built-in view_image tool — 把一个本地图片文件以 base64 image ContentBlock
- * 回传进上下文,让 vision 模型「看」它(对照 codex 的 view_image)。
+ * Built-in view_image tool — 把一个本地图片文件或历史图片以 base64 image
+ * ContentBlock 回传进上下文,让 vision 模型「看」它(对照 codex 的 view_image)。
  *
  * 典型用法:模型先写 SVG/Mermaid 并用 shell 转成 PNG,再调 view_image(png)
  * 检查图画对没有(标签是否重叠、文字是否溢出),不对就改源再重转。

package/dist/tool-system/builtin/view-image.js

@@ -1,6 +1,6 @@
 /**
- * Built-in view_image tool — 把一个本地图片文件以 base64 image ContentBlock
- * 回传进上下文,让 vision 模型「看」它(对照 codex 的 view_image)。
+ * Built-in view_image tool — 把一个本地图片文件或历史图片以 base64 image
+ * ContentBlock 回传进上下文,让 vision 模型「看」它(对照 codex 的 view_image)。
  *
  * 典型用法:模型先写 SVG/Mermaid 并用 shell 转成 PNG,再调 view_image(png)
  * 检查图画对没有(标签是否重叠、文字是否溢出),不对就改源再重转。
@@ -14,6 +14,7 @@
 import { readFile, stat } from "node:fs/promises";
 import { extname, isAbsolute, resolve } from "node:path";
 import { capabilitiesFor } from "../../llm/capabilities/index.js";
+import { collectBase64Images, findImageByNumber } from "../../context/compaction.js";
 const MAX_BYTES = 5 * 1024 * 1024; // 5MB —— vision 模型按 tile 计 token,大图无益且撑大请求
 const MEDIA_TYPES = {
     ".png": "image/png",
@@ -24,11 +25,11 @@ const MEDIA_TYPES = {
 };
 export const viewImageToolDef = {
     name: "view_image",
-    description: "Load a local image file into the conversation so you can SEE it (vision). " +
-        "Use after generating or rendering an image (e.g. SVG/Mermaid → PNG) to verify it " +
-        "looks right — check for overlapping labels, clipped text, wrong layout — then fix the " +
-        "source and re-render if needed. Supports PNG/JPEG/GIF/WebP only; convert SVG/PDF to PNG " +
-        "first. Requires a vision-capable model; otherwise the image is skipped.",
+    description: "Load an image into the conversation so you can SEE it (vision). Pass path to view a " +
+        "workspace image file, or pass imageNumber to retrieve the original image behind an " +
+        "earlier [image #N, already provided] history placeholder. Use exactly one of path or " +
+        "imageNumber. File paths support PNG/JPEG/GIF/WebP only; convert SVG/PDF to PNG first. " +
+        "Requires a vision-capable model; otherwise the image is skipped.",
     inputSchema: {
         type: "object",
         properties: {
@@ -36,14 +37,31 @@ export const viewImageToolDef = {
                 type: "string",
                 description: "Path to the image file (absolute, or relative to the working directory).",
             },
+            imageNumber: {
+                type: "number",
+                description: "Image history number N from an earlier [image #N, already provided] placeholder.",
+            },
         },
-        required: ["path"],
     },
 };
 export async function viewImageTool(args, ctx) {
     const rawPath = args.path;
+    const rawImageNumber = args.imageNumber;
+    const hasPath = typeof rawPath === "string" && rawPath.trim().length > 0;
+    const hasImageNumber = rawImageNumber !== undefined && rawImageNumber !== null;
+    if (hasPath === hasImageNumber) {
+        return "Error: provide exactly one of path or imageNumber";
+    }
+    if (hasImageNumber) {
+        if (typeof rawImageNumber !== "number" ||
+            !Number.isSafeInteger(rawImageNumber) ||
+            rawImageNumber <= 0) {
+            return "Error: imageNumber must be a positive integer";
+        }
+        return viewHistoricalImage(rawImageNumber, ctx);
+    }
     if (typeof rawPath !== "string" || !rawPath.trim()) {
-        return "Error: path is required";
+        return "Error: path must be a non-empty string";
     }
     const cwd = ctx?.cwd ?? process.cwd();
     const abs = isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath);
@@ -51,13 +69,7 @@ export async function viewImageTool(args, ctx) {
     // 缺 llmConfig 时按「非视觉」处理(fail closed),对齐 DEFAULT_CAPABILITY
     // 的保守姿态:运行时 ToolContext.llmConfig 必有,缺失只发生在测试 / 异常
     // 装配下,此时绝不把 base64 读进上下文。
-    const supportsVision = (() => {
-        if (!ctx?.llmConfig)
-            return false;
-        const kind = (ctx.llmConfig.providerKind ?? ctx.llmConfig.provider);
-        return capabilitiesFor(kind, ctx.llmConfig.model).supportsVision;
-    })();
-    if (!supportsVision) {
+    if (!supportsVision(ctx)) {
         return `[图片未加载: ${abs} —— 当前模型不支持视觉输入,已跳过。切换到 vision 模型后再 view_image。]`;
     }
     // 闸门 2:格式 gate
@@ -88,9 +100,78 @@ export async function viewImageTool(args, ctx) {
     const data = buf.toString("base64");
     const kb = Math.round(buf.length / 1024);
     return {
-        contentBlocks: [
-            { type: "image", source: { type: "base64", media_type: mediaType, data } },
-        ],
+        contentBlocks: [{ type: "image", source: { type: "base64", media_type: mediaType, data } }],
         result: `[已加载图片: ${abs} (${mediaType}, ${kb} KB)]`,
     };
 }
+function supportsVision(ctx) {
+    if (!ctx?.llmConfig)
+        return false;
+    const kind = (ctx.llmConfig.providerKind ?? ctx.llmConfig.provider);
+    return capabilitiesFor(kind, ctx.llmConfig.model).supportsVision;
+}
+async function viewHistoricalImage(imageNumber, ctx) {
+    if (!supportsVision(ctx)) {
+        return `[图片未取回: image #${imageNumber} —— 当前模型不支持视觉输入,已跳过。切换到 vision 模型后再 view_image。]`;
+    }
+    const sessionManager = ctx?.engine?.getSessionManager?.();
+    const sessionId = ctx?.sessionId;
+    if (!sessionManager || !sessionId) {
+        return `Error: 无法取回 image #${imageNumber}: 当前工具上下文没有可读取的 session 历史。`;
+    }
+    let messages;
+    try {
+        messages = sessionManager.resume(sessionId).transcript.toMessages();
+    }
+    catch (err) {
+        return `Error: 无法读取 session 历史以取回 image #${imageNumber}: ${err.message}`;
+    }
+    const images = collectBase64Images(messages);
+    const found = findImageByNumber(messages, imageNumber);
+    if (!found) {
+        return `Error: 未找到 image #${imageNumber}; 当前 session 历史中共有 ${images.length} 张可取回图片。`;
+    }
+    const block = normalizeImageBlockForReturn(found.block);
+    const size = decodedImageBlockBytes(block);
+    if (size !== undefined && size > MAX_BYTES) {
+        const mb = (size / 1024 / 1024).toFixed(1);
+        return `[图片未取回: image #${imageNumber} —— 图片过大 (${mb} MB > 5 MB),请先压缩或缩放原图。]`;
+    }
+    const kb = size === undefined ? "unknown" : String(Math.round(size / 1024));
+    const mediaType = mediaTypeOfImageBlock(block) ?? "base64 image";
+    return {
+        contentBlocks: [block],
+        result: `[已取回 image #${imageNumber}: ${mediaType}, ${kb} KB]`,
+    };
+}
+function normalizeImageBlockForReturn(block) {
+    if (block.type === "image" && block.source?.type === "base64")
+        return block;
+    const source = openAIDataUrlImageSource(block);
+    return source ? { type: "image", source } : block;
+}
+function decodedImageBlockBytes(block) {
+    const data = base64DataOfImageBlock(block);
+    if (!data)
+        return undefined;
+    return Buffer.byteLength(data, "base64");
+}
+function base64DataOfImageBlock(block) {
+    if (block.type === "image" && block.source?.type === "base64") {
+        return block.source.data;
+    }
+    return openAIDataUrlImageSource(block)?.data;
+}
+function mediaTypeOfImageBlock(block) {
+    if (block.type === "image" && block.source?.type === "base64") {
+        return block.source.media_type;
+    }
+    return openAIDataUrlImageSource(block)?.media_type;
+}
+function openAIDataUrlImageSource(block) {
+    const maybeOpenAI = block;
+    const match = maybeOpenAI.image_url?.url?.match(/^data:(image\/[^;,]+);base64,(.+)$/i);
+    if (maybeOpenAI.type !== "image_url" || !match?.[1] || !match[2])
+        return undefined;
+    return { type: "base64", media_type: match[1], data: match[2] };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cjhyy/code-shell-core",
-  "version": "0.6.0-rc.13",
+  "version": "0.6.0-rc.14",
   "description": "Core engine for code-shell — agent orchestration, tool execution, hooks, protocol. UI-agnostic.",
   "type": "module",
   "main": "./dist/index.js",