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

package/dist/tool-system/builtin/read.js

@@ -1,8 +1,10 @@
 /**
  * Built-in Read file tool.
  */
-import { readFile, stat } from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { readFile, stat, open } from "node:fs/promises";
+import { createReadStream, existsSync } from "node:fs";
+import { extname, isAbsolute, relative, resolve, sep } from "node:path";
 import { fileCache } from "./file-cache.js";
 import { toLf } from "./eol.js";
 export const readToolDef = {
@@ -10,7 +12,8 @@ export const readToolDef = {
     description: "Read a file from the local filesystem. Returns the file content with line numbers. " +
         "By default reads up to 2000 lines from the beginning. " +
         "Use offset and limit to read specific portions of large files. " +
-        "For large files, consider using Grep first to find the relevant lines.\n\n" +
+        "For images and binary files, returns path/metadata instead of raw bytes. " +
+        "For large text files, consider using Grep first to find the relevant lines.\n\n" +
         "Do NOT re-read a file you just edited to verify — Edit/Write would have errored " +
         "if the change failed.\n" +
         "Do NOT re-read a file (or the same range of a file) you've already read earlier in " +
@@ -27,18 +30,42 @@ export const readToolDef = {
     },
 };
 const MAX_CONTENT_CHARS = 200_000;
+const LARGE_TEXT_BYTES = 5 * 1024 * 1024;
+const SAMPLE_BYTES = 8192;
+const IMAGE_EXT_MIME = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+};
 export async function readTool(args, ctx) {
-    const filePath = args.file_path;
-    if (!filePath)
+    const rawPath = args.file_path;
+    if (!rawPath)
         return "Error: file_path is required";
+    const cwd = ctx?.cwd ?? process.cwd();
+    const filePath = isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath);
     if (!existsSync(filePath))
         return `Error: File not found: ${filePath}`;
     try {
         // Get file info first
         const fileInfo = await stat(filePath);
         const sizeKB = Math.round(fileInfo.size / 1024);
+        const sample = await readSample(filePath, Math.min(fileInfo.size, SAMPLE_BYTES));
+        const binary = detectBinary(filePath, sample);
+        if (binary) {
+            const sha256 = await sha256File(filePath);
+            return formatBinaryReadResult({
+                filePath,
+                cwd,
+                size: fileInfo.size,
+                sha256,
+                mime: binary.mime,
+                isImage: binary.kind === "image",
+            });
+        }
         // Skip binary or excessively large files
-        if (fileInfo.size > 5 * 1024 * 1024) {
+        if (fileInfo.size > LARGE_TEXT_BYTES) {
             return `Error: File is too large (${sizeKB}KB). Use Grep to search for specific content, or provide offset and limit to read a portion.`;
         }
         // Try cache first, fall back to disk read
@@ -76,3 +103,88 @@ export async function readTool(args, ctx) {
         return `Error reading file: ${err.message}`;
     }
 }
+async function readSample(filePath, length) {
+    if (length <= 0)
+        return Buffer.alloc(0);
+    const handle = await open(filePath, "r");
+    try {
+        const buffer = Buffer.alloc(length);
+        const { bytesRead } = await handle.read(buffer, 0, length, 0);
+        return buffer.subarray(0, bytesRead);
+    }
+    finally {
+        await handle.close();
+    }
+}
+function detectBinary(filePath, sample) {
+    const imageMime = detectImageMime(filePath, sample);
+    if (imageMime)
+        return { kind: "image", mime: imageMime };
+    if (sample.length === 0)
+        return null;
+    if (sample.includes(0))
+        return { kind: "binary" };
+    try {
+        new TextDecoder("utf-8", { fatal: true }).decode(sample);
+    }
+    catch {
+        return { kind: "binary" };
+    }
+    let controls = 0;
+    for (const byte of sample) {
+        if (byte < 32 && byte !== 9 && byte !== 10 && byte !== 12 && byte !== 13)
+            controls += 1;
+    }
+    return controls > Math.max(8, sample.length * 0.01) ? { kind: "binary" } : null;
+}
+function detectImageMime(filePath, sample) {
+    if (sample.length >= 8 &&
+        sample[0] === 0x89 &&
+        sample[1] === 0x50 &&
+        sample[2] === 0x4e &&
+        sample[3] === 0x47 &&
+        sample[4] === 0x0d &&
+        sample[5] === 0x0a &&
+        sample[6] === 0x1a &&
+        sample[7] === 0x0a) {
+        return "image/png";
+    }
+    if (sample.length >= 3 && sample[0] === 0xff && sample[1] === 0xd8 && sample[2] === 0xff) {
+        return "image/jpeg";
+    }
+    const header = sample.subarray(0, 12).toString("ascii");
+    if (header.startsWith("GIF87a") || header.startsWith("GIF89a"))
+        return "image/gif";
+    if (header.startsWith("RIFF") && header.slice(8, 12) === "WEBP")
+        return "image/webp";
+    return IMAGE_EXT_MIME[extname(filePath).toLowerCase()];
+}
+async function sha256File(filePath) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(filePath)) {
+        hash.update(chunk);
+    }
+    return hash.digest("hex");
+}
+function formatBinaryReadResult(input) {
+    const path = displayPath(input.filePath, input.cwd);
+    const lines = [
+        input.isImage ? "Image file (not displayed by Read)." : "Binary file (not displayed by Read).",
+        `Path: ${path}`,
+        `Absolute path: ${input.filePath}`,
+        ...(input.mime ? [`MIME: ${input.mime}`] : []),
+        `Size: ${input.size} bytes`,
+        `SHA-256: ${input.sha256}`,
+    ];
+    if (input.isImage) {
+        lines.push(`Use view_image({ path: "${path}" }) to inspect pixels.`);
+    }
+    return lines.join("\n");
+}
+function displayPath(filePath, cwd) {
+    const rel = relative(cwd, filePath);
+    if (rel && rel !== ".." && !rel.startsWith(`..${sep}`)) {
+        return sep === "\\" ? rel.replace(/\\/g, "/") : rel;
+    }
+    return filePath;
+}

package/dist/tool-system/builtin/sleep.d.ts

@@ -1,6 +1,5 @@
 /**
  * SleepTool — pause execution for a specified duration.
  */
-import type { ToolDefinition } from "../../types.js";
-export declare const sleepToolDef: ToolDefinition;
+export { sleepToolDef } from "./sleep.definition.js";
 export declare function sleepTool(args: Record<string, unknown>): Promise<string>;

package/dist/tool-system/builtin/sleep.definition.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Sleep tool metadata.
+ *
+ * Kept separate from the executor so registration and presets can consume the
+ * definition without importing implementation code.
+ */
+import type { ToolDefinition } from "../../types.js";
+export declare const sleepToolDef: ToolDefinition;

package/dist/tool-system/builtin/sleep.definition.js

@@ -0,0 +1,28 @@
+/**
+ * Sleep tool metadata.
+ *
+ * Kept separate from the executor so registration and presets can consume the
+ * definition without importing implementation code.
+ */
+export const sleepToolDef = {
+    name: "Sleep",
+    description: "Pause execution for a brief, deterministic wait (e.g. letting a just-started service settle for a few seconds). " +
+        "Do NOT use Sleep to poll for or wait on background work (background shells, async sub-agents, video generation): " +
+        "the system wakes you automatically when that work completes — just end your turn instead of looping Sleep. " +
+        "If you want a safety net in case a background task hangs and never signals completion, do NOT loop Sleep either — " +
+        "instead end your turn and schedule a one-shot self-wakeup with CronCreate " +
+        "({ schedule: '5m', once: true, continueInSession: true, permissionLevel: 'read-only', " +
+        "prompt: 'check whether <that task> finished; if still running, wait again' }). " +
+        "That returns control to you at the interval without burning a turn spinning. " +
+        "Maximum duration is 300 seconds (5 minutes).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            seconds: {
+                type: "number",
+                description: "Number of seconds to sleep (max 300)",
+            },
+        },
+        required: ["seconds"],
+    },
+};

package/dist/tool-system/builtin/sleep.js

@@ -1,28 +1,7 @@
 /**
  * SleepTool — pause execution for a specified duration.
  */
-export const sleepToolDef = {
-    name: "Sleep",
-    description: "Pause execution for a brief, deterministic wait (e.g. letting a just-started service settle for a few seconds). " +
-        "Do NOT use Sleep to poll for or wait on background work (background shells, async sub-agents, video generation): " +
-        "the system wakes you automatically when that work completes — just end your turn instead of looping Sleep. " +
-        "If you want a safety net in case a background task hangs and never signals completion, do NOT loop Sleep either — " +
-        "instead end your turn and schedule a one-shot self-wakeup with CronCreate " +
-        "({ schedule: '5m', once: true, continueInSession: true, permissionLevel: 'read-only', " +
-        "prompt: 'check whether <that task> finished; if still running, wait again' }). " +
-        "That returns control to you at the interval without burning a turn spinning. " +
-        "Maximum duration is 300 seconds (5 minutes).",
-    inputSchema: {
-        type: "object",
-        properties: {
-            seconds: {
-                type: "number",
-                description: "Number of seconds to sleep (max 300)",
-            },
-        },
-        required: ["seconds"],
-    },
-};
+export { sleepToolDef } from "./sleep.definition.js";
 export async function sleepTool(args) {
     const seconds = Math.min(Math.max(Number(args.seconds) || 1, 0.1), 300);
     const signal = args.__signal;

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,40 @@ 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.",
+            },
+            detail: {
+                type: "string",
+                enum: ["low", "standard", "high"],
+                description: "Optional image detail preference. Accepted for compatibility; current providers use the runtime image detail default.",
+            },
         },
-        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";
+    }
+    const detail = args.detail;
+    if (detail !== undefined && detail !== "low" && detail !== "standard" && detail !== "high") {
+        return "Error: detail must be one of low, standard, high";
+    }
+    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 +78,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 +109,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/dist/tool-system/builtin/worktree.d.ts

@@ -1,11 +1,11 @@
 /**
- * EnterWorktree / ExitWorktree tools — create and manage isolated git worktrees.
+ * EnterWorktree / ExitWorktree tools — switch a session between git workspaces.
  */
 import type { ToolDefinition } from "../../types.js";
 import type { ToolContext } from "../context.js";
-import { type WorktreeSession } from "../../git/worktree.js";
-export declare function getActiveWorktree(): WorktreeSession | undefined;
+export declare const switchSessionWorkspaceToolDef: ToolDefinition;
+export declare function switchSessionWorkspaceTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
 export declare const enterWorktreeToolDef: ToolDefinition;
 export declare function enterWorktreeTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
 export declare const exitWorktreeToolDef: ToolDefinition;
-export declare function exitWorktreeTool(args: Record<string, unknown>): Promise<string>;
+export declare function exitWorktreeTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;