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

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

@@ -3,9 +3,9 @@
  */
 import { readToolDef, readTool } from "./read.js";
 import { writeToolDef, writeTool } from "./write.js";
-import { generateImageToolDef, generateImageTool, isGenerateImageAvailable } from "./generate-image.js";
+import { generateImageToolDef, generateImageTool, isGenerateImageAvailable, } from "./generate-image.js";
 import { editModelCatalogToolDef, editModelCatalogTool } from "./edit-model-catalog.js";
-import { generateVideoToolDef, generateVideoTool, isGenerateVideoAvailable } from "./generate-video.js";
+import { generateVideoToolDef, generateVideoTool, isGenerateVideoAvailable, } from "./generate-video.js";
 import { viewImageToolDef, viewImageTool } from "./view-image.js";
 import { editToolDef, editTool } from "./edit.js";
 import { applyPatchToolDef, applyPatchTool } from "./apply-patch/index.js";
@@ -16,19 +16,19 @@ import { webSearchToolDef, webSearchTool, isWebSearchAvailable } from "./web-sea
 import { webFetchToolDef, webFetchTool } from "./web-fetch.js";
 import { askUserToolDef, askUserTool } from "./ask-user.js";
 import { agentToolDef, agentTool, agentStatusToolDef, agentStatusTool, agentCancelToolDef, agentCancelTool, agentSendInputToolDef, agentSendInputTool, } from "./agent.js";
-import { enterPlanModeToolDef, enterPlanModeTool, exitPlanModeToolDef, exitPlanModeTool } from "./plan.js";
+import { enterPlanModeToolDef, enterPlanModeTool, exitPlanModeToolDef, exitPlanModeTool, } from "./plan.js";
 import { toolSearchToolDef, toolSearchTool } from "./tool-search.js";
 import { todoWriteToolDef, todoWriteTool } from "./task.js";
-import { enterWorktreeToolDef, enterWorktreeTool, exitWorktreeToolDef, exitWorktreeTool } from "./worktree.js";
+import { enterWorktreeToolDef, enterWorktreeTool, exitWorktreeToolDef, exitWorktreeTool, switchSessionWorkspaceToolDef, switchSessionWorkspaceTool, } from "./worktree.js";
 import { sleepToolDef, sleepTool } from "./sleep.js";
 import { configToolDef, configTool } from "./config.js";
 import { notebookEditToolDef, notebookEditTool } from "./notebook-edit.js";
 import { lspToolDef, lspTool } from "./lsp.js";
-import { cronCreateToolDef, cronCreateTool, cronDeleteToolDef, cronDeleteTool, cronListToolDef, cronListTool } from "./cron.js";
-import { driveClaudeCodeToolDef, driveClaudeCodeTool, driveAgentToolDef, driveAgentTool } from "./drive-claude-code.js";
+import { cronCreateToolDef, cronCreateTool, cronDeleteToolDef, cronDeleteTool, cronListToolDef, cronListTool, } from "./cron.js";
+import { driveClaudeCodeToolDef, driveClaudeCodeTool, driveAgentToolDef, driveAgentTool, DRIVE_AGENT_TOOL_TIMEOUT_MS, } from "./drive-claude-code.js";
 import { checkQuotaToolDef, checkQuotaTool } from "./check-quota.js";
 import { skillToolDef, skillTool } from "./skill.js";
-import { mcpToolDef, mcpToolExecute, listMcpResourcesToolDef, listMcpResourcesTool, readMcpResourceToolDef, readMcpResourceTool } from "./mcp-tools.js";
+import { mcpToolDef, mcpToolExecute, listMcpResourcesToolDef, listMcpResourcesTool, readMcpResourceToolDef, readMcpResourceTool, } from "./mcp-tools.js";
 import { replToolDef, replTool } from "./repl.js";
 import { briefToolDef, briefTool } from "./brief.js";
 import { powershellToolDef, powershellTool } from "./powershell.js";
@@ -39,9 +39,9 @@ import { cancelGoalToolDef, cancelGoalTool } from "./cancel-goal.js";
 import { addMarketplaceToolDef, addMarketplaceTool } from "./add-marketplace.js";
 import { bashOutputToolDef, bashOutputTool, killShellToolDef, killShellTool, listShellsToolDef, listShellsTool, } from "./background-shell-tools.js";
 import { browserObserveToolDef, browserObserveTool, browserActToolDef, browserActTool, browserNavigateToolDef, browserNavigateTool, } from "./browser-tools.js";
-import { useCredentialToolDef, useCredentialTool } from "../../credentials/use-credential-tool.js";
+import { useCredentialToolDef, useCredentialBuiltinTool, } from "../../credentials/use-credential-tool.js";
 import { injectCredentialToolDef, injectCredentialTool, isInjectCredentialAvailable, } from "../../credentials/inject-credential-tool.js";
-import { CredentialStore } from "../../credentials/store.js";
+import { credentialAccessScope, getCredentialAccess } from "../../credentials/access.js";
 export const BUILTIN_TOOLS = [
     {
         definition: {
@@ -69,7 +69,7 @@ export const BUILTIN_TOOLS = [
         definition: {
             ...editModelCatalogToolDef,
             source: "builtin",
-            permissionDefault: "ask", // writes user config — confirm before each write
+            permissionDefault: "ask", // UI hint; default classifier fallback confirms writes.
             isReadOnly: false,
             isConcurrencySafe: false, // serializes writes to the single catalog file
         },
@@ -344,6 +344,16 @@ export const BUILTIN_TOOLS = [
         },
         execute: exitWorktreeTool,
     },
+    {
+        definition: {
+            ...switchSessionWorkspaceToolDef,
+            source: "builtin",
+            permissionDefault: "ask",
+            isReadOnly: false,
+            isConcurrencySafe: false,
+        },
+        execute: switchSessionWorkspaceTool,
+    },
     // ─── Phase 5: Utility Tools ────────────────────────────────────
     {
         definition: {
@@ -433,6 +443,8 @@ export const BUILTIN_TOOLS = [
             permissionDefault: "ask",
             isReadOnly: false,
             isConcurrencySafe: false,
+            timeoutMs: DRIVE_AGENT_TOOL_TIMEOUT_MS,
+            pathPolicy: [{ kind: "arg", arg: "attachmentPaths", operation: "read" }],
         },
         execute: driveAgentTool,
     },
@@ -445,6 +457,8 @@ export const BUILTIN_TOOLS = [
             permissionDefault: "ask",
             isReadOnly: false,
             isConcurrencySafe: false,
+            timeoutMs: DRIVE_AGENT_TOOL_TIMEOUT_MS,
+            pathPolicy: [{ kind: "arg", arg: "attachmentPaths", operation: "read" }],
         },
         execute: driveClaudeCodeTool,
     },
@@ -638,7 +652,7 @@ export const BUILTIN_TOOLS = [
     },
     // Browser automation — 3 semantic tools driving the in-app webview via the
     // BrowserBridge (CDP). All serial on one webview (isConcurrencySafe:false).
-    // browser_observe is read-only. browser_act is permissionDefault "allow"; its
+    // browser_observe is read-only. browser_act declares a UI hint of allow; its
     // sensitive actions (click/type/select) are escalated to "ask" by a preset
     // PermissionRule keyed on argsPattern { action } (see preset/index.ts §4.6) —
     // so one tool carries per-action gating. Sensitive-action + domain-whitelist
@@ -659,7 +673,7 @@ export const BUILTIN_TOOLS = [
         definition: {
             ...browserActToolDef,
             source: "builtin",
-            permissionDefault: "allow", // per-action gating via preset rule (argsPattern.action)
+            permissionDefault: "allow", // UI hint; per-action execution gating is the preset rule.
             isReadOnly: false,
             isConcurrencySafe: false,
             timeoutMs: 30_000, // the wait action internally bounds; give RPC headroom
@@ -677,8 +691,8 @@ export const BUILTIN_TOOLS = [
         execute: browserNavigateTool,
     },
     // ─── Credentials: AI 取用已存凭证(token/link/cookie) ──────────
-    // permissionDefault:"allow" —— 取用审批由工具内部的 CredentialUseGate 负责
-    // (默认问/本会话记住/全自动),不走工具级权限层,避免双重弹窗。
+    // permissionDefault:"allow" 是展示/声明 hint；取用审批由工具内部的
+    // CredentialUseGate 负责(默认问/本会话记住/全自动),避免双重弹窗。
     // 读取凭证库本身不写文件(cookie 物化成临时 cookies.txt 是用完即弃的副产物)。
     {
         definition: {
@@ -688,10 +702,10 @@ export const BUILTIN_TOOLS = [
             isReadOnly: true,
             isConcurrencySafe: true,
         },
-        execute: useCredentialTool,
+        execute: useCredentialBuiltinTool,
     },
     // InjectCredential:把 cookie 凭证注入内置浏览器(恢复登录态)。审批由工具内部
-    // CredentialUseGate 负责(逐条 autoInjectByAI),故 permissionDefault:"allow"。
+    // CredentialUseGate 负责(逐条 autoInjectByAI),permissionDefault:"allow" 仅作展示 hint。
     // 改浏览器登录态有副作用 → 非 read-only。
     {
         definition: {
@@ -718,15 +732,17 @@ export const BUILTIN_TOOL_GUARDS = new Map([
     // of the tool list (and the context) for the common no-credentials case,
     // matching the spec's "quiet when empty" intent (true ToolSearch-deferral for
     // builtins isn't wired in the engine).
-    [useCredentialToolDef.name, (ctx) => isUseCredentialAvailable(ctx.cwd)],
+    [useCredentialToolDef.name, (ctx) => isUseCredentialAvailable(ctx.cwd, ctx.settingsScope)],
     // InjectCredential hidden until ≥1 cookie credential exists (browser injection
     // is cookie-only). Also degrades at call time if no browser bridge is wired.
-    [injectCredentialToolDef.name, (ctx) => isInjectCredentialAvailable(ctx.cwd)],
+    [injectCredentialToolDef.name, (ctx) => isInjectCredentialAvailable(ctx.cwd, ctx.settingsScope)],
+    [completeGoalToolDef.name, (ctx) => ctx.hasGoal === true],
+    [cancelGoalToolDef.name, (ctx) => ctx.hasGoal === true],
 ]);
-/** UseCredential is available when the cwd's CredentialStore has ≥1 credential. */
-export function isUseCredentialAvailable(cwd) {
+/** UseCredential is available when the cwd's credential metadata has ≥1 entry. */
+export function isUseCredentialAvailable(cwd, settingsScope) {
     try {
-        return new CredentialStore(cwd).listMasked().length > 0;
+        return getCredentialAccess().listMasked(cwd, credentialAccessScope(settingsScope)).length > 0;
     }
     catch {
         return false;

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

@@ -2,5 +2,6 @@
  * LSPTool — language server protocol operations for code intelligence.
  */
 import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
 export declare const lspToolDef: ToolDefinition;
-export declare function lspTool(args: Record<string, unknown>): Promise<string>;
+export declare function lspTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

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

@@ -4,6 +4,7 @@
 import { getLSPManager } from "../../lsp/manager.js";
 import { detectLSPServer } from "../../lsp/servers.js";
 import { pathToFileURL } from "node:url";
+import { isAbsolute, resolve } from "node:path";
 export const lspToolDef = {
     name: "LSP",
     description: "Use Language Server Protocol for code intelligence operations. " +
@@ -33,13 +34,15 @@ export const lspToolDef = {
         required: ["action", "file_path"],
     },
 };
-export async function lspTool(args) {
+export async function lspTool(args, ctx) {
     const action = args.action;
-    const filePath = args.file_path;
+    const rawPath = args.file_path;
     const line = args.line ?? 0;
     const character = args.character ?? 0;
-    if (!filePath)
+    if (!rawPath)
         return "Error: file_path is required";
+    const cwd = ctx?.cwd ?? process.cwd();
+    const filePath = isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath);
     const manager = getLSPManager();
     if (!manager)
         return "Error: LSP is not initialized. Language servers are not available.";

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

@@ -17,9 +17,10 @@
 import { MemoryManager } from "../../session/memory.js";
 const VALID_SCOPES = ["user", "dream"];
 const VALID_TYPES = ["user", "feedback", "project", "reference"];
+const VALID_ORIGINS = ["auto", "manual", "dream"];
 function parseScope(raw) {
     if (typeof raw !== "string")
-        return "Error: scope is required (\"user\" or \"dream\")";
+        return 'Error: scope is required ("user" or "dream")';
     if (!VALID_SCOPES.includes(raw)) {
         return `Error: scope must be "user" or "dream", got "${raw}"`;
     }
@@ -30,6 +31,11 @@ function parseScope(raw) {
 function parseLocation(raw) {
     return raw === "global" ? "global" : "project";
 }
+function parseOrigin(raw) {
+    return typeof raw === "string" && VALID_ORIGINS.includes(raw)
+        ? raw
+        : undefined;
+}
 function mmFor(ctx, scope, location = "project") {
     // location=global → omit projectDir so the manager points at the global store.
     return new MemoryManager({
@@ -46,7 +52,7 @@ const LOCATION_SCHEMA = {
 export const memoryListToolDef = {
     name: "MemoryList",
     description: "List persistent memory entries from one scope. " +
-        "Returns each entry's name, type, and short description (not the full content — use MemoryRead for that). " +
+        "Returns each entry's id, origin, counts, name, type, and short description (not the full content — use MemoryRead for that). " +
         "Use this before MemorySave/MemoryDelete to find the exact name to target. " +
         'Scopes: "user" (entries the user owns; you need permission to modify) or "dream" (auto-consolidation workspace; you may freely modify).',
     inputSchema: {
@@ -73,7 +79,9 @@ export async function memoryListTool(args, ctx) {
         if (entries.length === 0)
             return `(no memories in scope "${scope}")`;
         return entries
-            .map((e) => `- [${e.type}] ${e.name} — ${e.description}`)
+            .map((e) => `- [${e.type}] ${e.name} ` +
+            `(id:${e.id ?? "(none)"}, origin:${e.origin ?? "manual"}, use:${e.useCount ?? 0}, updates:${e.updateCount ?? 0}) — ` +
+            e.description)
             .join("\n");
     }
     catch (err) {
@@ -127,15 +135,24 @@ export async function memoryReadTool(args, ctx) {
             if (cb) {
                 // scope here is always "user"|"dream" (validated above); pending is
                 // never tool-readable, so the narrower event type is correct.
-                void cb({ type: "memory_recalled", name: entry.name, scope: scope, location });
+                void cb({
+                    type: "memory_recalled",
+                    name: entry.name,
+                    scope: scope,
+                    location,
+                });
             }
         }
         catch {
             // ignore — the read result below is what matters
         }
         return (`name: ${entry.name}\n` +
+            `id: ${entry.id ?? ""}\n` +
             `description: ${entry.description}\n` +
             `type: ${entry.type}\n` +
+            `origin: ${entry.origin ?? "manual"}\n` +
+            `useCount: ${entry.useCount ?? 0}\n` +
+            `updateCount: ${entry.updateCount ?? 0}\n` +
             `\n${entry.content}`);
     }
     catch (err) {
@@ -145,7 +162,7 @@ export async function memoryReadTool(args, ctx) {
 // ─── MemorySave ────────────────────────────────────────────────────────────
 export const memorySaveToolDef = {
     name: "MemorySave",
-    description: "Create or overwrite a memory entry. Same name → overwrite. " +
+    description: "Create or update a memory entry. Before saving, scan the injected memory index and/or call MemoryList; for the same durable topic, update the existing entry by id instead of creating date-stamped variants. " +
         'Saving to scope "user" requires user permission (you will see a confirmation prompt). ' +
         'Saving to scope "dream" is automatic — it is your auto-consolidation workspace. ' +
         "Pick `type` carefully: " +
@@ -154,7 +171,7 @@ export const memorySaveToolDef = {
         "project (non-obvious facts about ongoing work), " +
         "reference (pointers to external resources). " +
         "Pick `location`: global (a lesson/preference true in ANY project) vs project (this repo only). " +
-        "If a memory in the injected index is now stale or wrong, overwrite it (same name) or MemoryDelete it — keep the store correct rather than letting contradictions pile up. " +
+        "If a memory in the injected index is now stale or wrong, update it by id or MemoryDelete it — keep the store correct rather than letting contradictions pile up. " +
         "The `description` is a one-line summary shown in the index; the `content` is the full body.",
     inputSchema: {
         type: "object",
@@ -165,9 +182,13 @@ export const memorySaveToolDef = {
                 description: "Which scope to save to",
             },
             location: LOCATION_SCHEMA,
+            id: {
+                type: "string",
+                description: "Stable id from MemoryList/MemoryRead when updating an existing memory. Omit only for genuinely new topics.",
+            },
             name: {
                 type: "string",
-                description: "Short kebab-case identifier (also becomes the filename slug)",
+                description: "Short stable topic identifier; avoid dates, versions, or batch suffixes",
             },
             description: {
                 type: "string",
@@ -192,11 +213,14 @@ export async function memorySaveTool(args, ctx) {
         return scope;
     }
     const name = args.name;
+    const id = args.id;
     const description = args.description;
     const type = args.type;
     const content = args.content;
     if (typeof name !== "string" || !name)
         return "Error: name is required";
+    if (id !== undefined && typeof id !== "string")
+        return "Error: id must be a string";
     if (typeof description !== "string")
         return "Error: description is required";
     if (typeof content !== "string")
@@ -207,12 +231,20 @@ export async function memorySaveTool(args, ctx) {
     try {
         const location = parseLocation(args.location);
         const mm = mmFor(ctx, scope, location);
+        const dreamLoop = ctx?.__dreamLoop === true;
+        const forcedOrigin = dreamLoop
+            ? "dream"
+            : scope === "user"
+                ? "manual"
+                : (parseOrigin(args.origin) ?? "manual");
         const fileName = mm.save({
+            id,
             name,
             description,
             type: type,
             content,
-        });
+            origin: forcedOrigin,
+        }, { forceOrigin: forcedOrigin });
         return `Saved memory "${name}" → ${location}/${scope}/${fileName}`;
     }
     catch (err) {

package/dist/tool-system/builtin/notebook-edit.js

@@ -2,6 +2,7 @@
  * NotebookEditTool — read and edit Jupyter notebook (.ipynb) cells.
  */
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
 export const notebookEditToolDef = {
     name: "NotebookEdit",
     description: "Edit a Jupyter notebook (.ipynb) file. Supports actions: " +
@@ -37,10 +38,12 @@ export const notebookEditToolDef = {
     },
 };
 export async function notebookEditTool(args, ctx) {
-    const filePath = args.file_path;
+    const rawPath = args.file_path;
     const action = args.action;
-    if (!filePath)
+    if (!rawPath)
         return "Error: file_path is required";
+    const cwd = ctx?.cwd ?? process.cwd();
+    const filePath = isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath);
     if (!filePath.endsWith(".ipynb"))
         return "Error: file must be a .ipynb file";
     if (action === "read") {

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

@@ -5,7 +5,10 @@
  * centralized in {@link safeSpawn}; this file only carries the pwsh /
  * powershell.exe selection + the PowerShell-specific output formatting.
  */
-import type { ToolDefinition } from "../../types.js";
+import type { ToolDefinition, ToolResult } from "../../types.js";
 import type { ToolContext } from "../context.js";
 export declare const powershellToolDef: ToolDefinition;
-export declare function powershellTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export declare function powershellTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string | {
+    result: string;
+    sandbox: ToolResult["sandbox"];
+}>;

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

@@ -28,6 +28,10 @@ export const powershellToolDef = {
     },
 };
 const PS_MAX_BUFFER = 5 * 1024 * 1024;
+const POWERSHELL_SANDBOX_MARK = { backend: "off" };
+function markPowerShellResult(result) {
+    return { result, sandbox: POWERSHELL_SANDBOX_MARK };
+}
 export async function powershellTool(args, ctx) {
     const command = args.command;
     // `??` only catches null/undefined — a non-positive timeout (0/-5) would slip
@@ -35,7 +39,7 @@ export async function powershellTool(args, ctx) {
     const rawTimeout = args.timeout;
     const timeout = typeof rawTimeout === "number" && rawTimeout > 0 ? rawTimeout : 120_000;
     if (!command.trim()) {
-        return "Error: command is required.";
+        return markPowerShellResult("Error: command is required.");
     }
     // Determine PowerShell executable.
     const psCmd = process.platform === "win32" ? "powershell.exe" : "pwsh";
@@ -52,19 +56,19 @@ export async function powershellTool(args, ctx) {
         signal: ctx?.signal,
     });
     if (result.aborted) {
-        return wasAbortedBeforeStart
+        return markPowerShellResult(wasAbortedBeforeStart
             ? "PowerShell aborted before starting."
-            : "PowerShell aborted by signal.";
+            : "PowerShell aborted by signal.");
     }
     if (result.timedOut) {
-        return `PowerShell timed out after ${timeout}ms`;
+        return markPowerShellResult(`PowerShell timed out after ${timeout}ms`);
     }
     if (result.spawnFailed) {
-        return `PowerShell spawn error: ${result.error ?? "unknown error"}`;
+        return markPowerShellResult(`PowerShell spawn error: ${result.error ?? "unknown error"}`);
     }
     if (result.exitCode !== 0) {
         const out = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join("\n");
-        return `PowerShell error:\n${out || `exit code ${result.exitCode}`}`;
+        return markPowerShellResult(`PowerShell error:\n${out || `exit code ${result.exitCode}`}`);
     }
-    return result.stdout.trim() || "(no output)";
+    return markPowerShellResult(result.stdout.trim() || "(no output)");
 }

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/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)
  * 检查图画对没有(标签是否重叠、文字是否溢出),不对就改源再重转。