@cjhyy/code-shell-core 0.5.0-rc.0 → 0.5.0-rc.2

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

@@ -0,0 +1,146 @@
+/**
+ * Built-in GenerateImage tool — text-to-image via the OpenAI Images API
+ * (`gpt-image-2`).
+ *
+ * Credentials come from config, not env: the tool finds the `kind: "openai"`
+ * entry in `settings.providers[]` and uses its `apiKey` + `baseUrl`. No
+ * `OPENAI_API_KEY` required, no new config — an existing OpenAI provider is
+ * reused as-is.
+ *
+ * The generated PNG is decoded from the API's base64 payload and written to
+ * `<cwd>/.code-shell/generated_images/<timestamp>.png`; the tool returns the
+ * absolute path so the model can Read or reference it on later turns. This
+ * mirrors codex's imagegen CLI fallback (`scripts/image_gen.py`): call API →
+ * take b64_json → decode → write → report path.
+ *
+ * Scope is deliberately narrow (text-to-image only). Edit/mask/transparent/
+ * batch are out of scope — see the design doc.
+ *
+ * Uses the native `fetch` (codeshell does not depend on the `openai` SDK).
+ */
+import { writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { SettingsManager } from "../../settings/manager.js";
+const DEFAULT_SIZE = "1024x1024";
+const DEFAULT_QUALITY = "auto";
+const MODEL = "gpt-image-2";
+export const generateImageToolDef = {
+    name: "GenerateImage",
+    description: "Generate an image from a text prompt using the OpenAI Images API (gpt-image-2). " +
+        "Saves a PNG into the workspace and returns its absolute path; read or reference " +
+        "that path on later turns. Requires an OpenAI provider (kind: \"openai\") configured " +
+        "in settings. For raster assets (photos, illustrations, mockups, textures) — not for " +
+        "SVG/vector icons or anything better built directly in code.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            prompt: {
+                type: "string",
+                description: "Description of the image to generate",
+            },
+            size: {
+                type: "string",
+                enum: ["1024x1024", "1536x1024", "1024x1536", "auto"],
+                description: "Image dimensions (default 1024x1024)",
+            },
+            quality: {
+                type: "string",
+                enum: ["low", "medium", "high", "auto"],
+                description: "Render quality (default auto). Use low for drafts, high for final assets.",
+            },
+        },
+        required: ["prompt"],
+    },
+};
+/** Resolve the OpenAI provider's apiKey + baseUrl from settings, or null. */
+function resolveOpenAIProvider(cwd) {
+    const settings = new SettingsManager(cwd, "full").get();
+    const provider = settings.providers.find((p) => p.kind === "openai");
+    if (!provider || !provider.apiKey)
+        return null;
+    return { baseUrl: provider.baseUrl, apiKey: provider.apiKey };
+}
+/**
+ * Tool-visibility guard: GenerateImage needs a kind:"openai" provider with a
+ * key. resolveOpenAIProvider returns null when none is configured.
+ *
+ * Cached per-cwd with a short TTL: the guard runs on EVERY message's toolDefs
+ * assembly (engine.ts), and resolveOpenAIProvider reads + parses settings from
+ * disk each call. The 1s TTL collapses the back-to-back reads (same message,
+ * rapid turns) while still picking up a newly-configured key well within the
+ * gap before the user's next message. The execution path
+ * (resolveOpenAIProvider) is intentionally NOT cached — only this boolean.
+ */
+const availCache = new Map();
+const AVAIL_TTL_MS = 1000;
+export function isGenerateImageAvailable(cwd = process.cwd(), nowMs = Date.now()) {
+    const hit = availCache.get(cwd);
+    if (hit && nowMs - hit.at < AVAIL_TTL_MS)
+        return hit.value;
+    let value = false;
+    try {
+        value = resolveOpenAIProvider(cwd) !== null;
+    }
+    catch {
+        value = false;
+    }
+    availCache.set(cwd, { at: nowMs, value });
+    return value;
+}
+export async function generateImageTool(args, ctx) {
+    const prompt = args.prompt;
+    if (typeof prompt !== "string" || !prompt.trim()) {
+        return "Error: prompt is required";
+    }
+    const size = typeof args.size === "string" ? args.size : DEFAULT_SIZE;
+    const quality = typeof args.quality === "string" ? args.quality : DEFAULT_QUALITY;
+    const cwd = ctx?.cwd ?? process.cwd();
+    const provider = resolveOpenAIProvider(cwd);
+    if (!provider) {
+        return ('Error: no OpenAI provider available. Configure a provider with kind: "openai" ' +
+            "(including an apiKey) in your code-shell settings to use GenerateImage.");
+    }
+    // Trim a trailing slash so `${baseUrl}/images/generations` doesn't double up.
+    const baseUrl = provider.baseUrl.replace(/\/+$/, "");
+    let resp;
+    try {
+        resp = await fetch(`${baseUrl}/images/generations`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${provider.apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ model: MODEL, prompt, size, quality, n: 1 }),
+            signal: ctx?.signal,
+        });
+    }
+    catch (err) {
+        return `Error generating image: ${err.message}`;
+    }
+    if (!resp.ok) {
+        const body = (await resp.text().catch(() => "")).slice(0, 500);
+        return `Error: image API returned ${resp.status}: ${body}`;
+    }
+    let json;
+    try {
+        json = await resp.json();
+    }
+    catch (err) {
+        return `Error: could not parse image API response: ${err.message}`;
+    }
+    const b64 = json?.data?.[0]?.b64_json;
+    if (typeof b64 !== "string" || !b64) {
+        const preview = JSON.stringify(json).slice(0, 500);
+        return `Error: no image in response: ${preview}`;
+    }
+    try {
+        const dir = join(cwd, ".code-shell", "generated_images");
+        await mkdir(dir, { recursive: true });
+        const path = join(dir, `${Date.now()}.png`);
+        await writeFile(path, Buffer.from(b64, "base64"));
+        return `Generated image saved to ${path}`;
+    }
+    catch (err) {
+        return `Error saving generated image: ${err.message}`;
+    }
+}

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

@@ -4,6 +4,7 @@
 import { glob } from "glob";
 import { stat } from "node:fs/promises";
 import * as path from "node:path";
+import { enforcePathPolicy } from "../path-policy.js";
 export const globToolDef = {
     name: "Glob",
     description: "Fast file pattern matching. Returns matching file paths sorted by modification time. " +
@@ -31,6 +32,12 @@ export async function globTool(args, ctx) {
             ? argPath
             : path.resolve(baseDir, argPath)
         : baseDir;
+    // Path policy: refuse to glob a search root the policy classifies as
+    // ask/deny for read. Stops a Glob("**/*", "/home/user/.ssh") from
+    // enumerating the keys directory under the existence-check radar.
+    const blocked = enforcePathPolicy(cwd, "read", ctx?.cwd);
+    if (blocked)
+        return blocked;
     try {
         const matches = await glob(pattern, {
             cwd,

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

@@ -4,6 +4,7 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { resolve, sep, isAbsolute } from "node:path";
+import { enforcePathPolicy } from "../path-policy.js";
 const execFileAsync = promisify(execFile);
 /**
  * Strip the cwd prefix from each line so results display as relative
@@ -58,6 +59,11 @@ export async function grepTool(args, ctx) {
             ? argPath
             : resolve(baseDir, argPath)
         : baseDir;
+    // Path policy: reading file contents under ~/.ssh, ~/.aws etc. by way
+    // of grep is the same exfiltration risk as Read. Gate the search root.
+    const blocked = enforcePathPolicy(searchPath, "read", ctx?.cwd);
+    if (blocked)
+        return blocked;
     const fileGlob = args.glob;
     const context = args.context || 0;
     const maxResults = args.max_results || 50;

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

@@ -12,9 +12,26 @@ import type { RegisteredTool } from "../../types.js";
  * ctx is optional in the signature so legacy call sites (and tests) that
  * pass only args still type-check; ToolRegistry always passes ctx at runtime.
  */
-export type BuiltinToolFn = (args: Record<string, unknown>, ctx?: import("../context.js").ToolContext) => Promise<string>;
+/**
+ * 内置工具返回值:大多数返回纯文本字符串。需要回传图片(或其它结构化
+ * 内容块)的工具(view_image)可改为返回 `{ contentBlocks }`;此时
+ * registry 会把它放进 ToolResult.contentBlocks。可选的 `result` 字段是给
+ * transcript / 摘要用的纯文本镜像。
+ */
+export type BuiltinToolResult = string | {
+    contentBlocks: import("../../types.js").ContentBlock[];
+    result?: string;
+};
+export type BuiltinToolFn = (args: Record<string, unknown>, ctx?: import("../context.js").ToolContext) => Promise<BuiltinToolResult>;
 export interface BuiltinTool {
     definition: RegisteredTool;
     execute: BuiltinToolFn;
 }
 export declare const BUILTIN_TOOLS: BuiltinTool[];
+/**
+ * Per-tool availability predicates. A tool listed here is filtered OUT of the
+ * exposed toolDefs when its predicate returns false for the active cwd (see
+ * engine.ts toolDefs assembly). Tools NOT listed here are always visible.
+ * Keyed by the tool's `name` (must match the toolDef name).
+ */
+export declare const BUILTIN_TOOL_GUARDS: Map<string, (cwd: string) => boolean>;

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

@@ -3,12 +3,14 @@
  */
 import { readToolDef, readTool } from "./read.js";
 import { writeToolDef, writeTool } from "./write.js";
+import { generateImageToolDef, generateImageTool, isGenerateImageAvailable } from "./generate-image.js";
+import { viewImageToolDef, viewImageTool } from "./view-image.js";
 import { editToolDef, editTool } from "./edit.js";
 import { applyPatchToolDef, applyPatchTool } from "./apply-patch/index.js";
 import { globToolDef, globTool } from "./glob.js";
 import { grepToolDef, grepTool } from "./grep.js";
 import { bashToolDef, bashTool } from "./bash.js";
-import { webSearchToolDef, webSearchTool } from "./web-search.js";
+import { webSearchToolDef, webSearchTool, isWebSearchAvailable } from "./web-search.js";
 import { webFetchToolDef, webFetchTool } from "./web-fetch.js";
 import { askUserToolDef, askUserTool } from "./ask-user.js";
 import { agentToolDef, agentTool, agentStatusToolDef, agentStatusTool, agentCancelToolDef, agentCancelTool, } from "./agent.js";
@@ -30,6 +32,8 @@ import { briefToolDef, briefTool } from "./brief.js";
 import { powershellToolDef, powershellTool } from "./powershell.js";
 import { arenaToolDef, arenaTool } from "./arena.js";
 import { memoryListToolDef, memoryListTool, memoryReadToolDef, memoryReadTool, memorySaveToolDef, memorySaveTool, memoryDeleteToolDef, memoryDeleteTool, } from "./memory.js";
+import { completeGoalToolDef, completeGoalTool } from "./complete-goal.js";
+import { addMarketplaceToolDef, addMarketplaceTool } from "./add-marketplace.js";
 export const BUILTIN_TOOLS = [
     {
         definition: {
@@ -51,6 +55,27 @@ export const BUILTIN_TOOLS = [
         },
         execute: writeTool,
     },
+    {
+        definition: {
+            ...generateImageToolDef,
+            source: "builtin",
+            permissionDefault: "ask",
+            isReadOnly: false,
+            isConcurrencySafe: false,
+            timeoutMs: 600_000, // 10min — high-quality / large image generation routinely exceeds the 120s default; give slow renders ample room while still bounding a hung request (Stop / ctx.signal cancels sooner)
+        },
+        execute: generateImageTool,
+    },
+    {
+        definition: {
+            ...viewImageToolDef,
+            source: "builtin",
+            permissionDefault: "allow",
+            isReadOnly: true,
+            isConcurrencySafe: true,
+        },
+        execute: viewImageTool,
+    },
     {
         definition: {
             ...editToolDef,
@@ -446,4 +471,40 @@ export const BUILTIN_TOOLS = [
         },
         execute: memoryDeleteTool,
     },
+    // ─── Goal mode: model-declared completion ──────────────────────
+    // Lets the model explicitly declare the active goal complete. The
+    // turn-loop short-circuits on this call; the tool itself only records an
+    // acknowledgement string, so it's read-only and concurrency-safe.
+    {
+        definition: {
+            ...completeGoalToolDef,
+            source: "builtin",
+            permissionDefault: "allow",
+            isReadOnly: true,
+            isConcurrencySafe: true,
+        },
+        execute: completeGoalTool,
+    },
+    // ─── Plugin marketplace: model-driven source registration ──────
+    {
+        definition: {
+            ...addMarketplaceToolDef,
+            source: "builtin",
+            permissionDefault: "ask",
+            isReadOnly: false,
+            isConcurrencySafe: false,
+            timeoutMs: 120_000, // git clone over network
+        },
+        execute: addMarketplaceTool,
+    },
 ];
+/**
+ * Per-tool availability predicates. A tool listed here is filtered OUT of the
+ * exposed toolDefs when its predicate returns false for the active cwd (see
+ * engine.ts toolDefs assembly). Tools NOT listed here are always visible.
+ * Keyed by the tool's `name` (must match the toolDef name).
+ */
+export const BUILTIN_TOOL_GUARDS = new Map([
+    [webSearchToolDef.name, isWebSearchAvailable],
+    [generateImageToolDef.name, isGenerateImageAvailable],
+]);

package/dist/tool-system/builtin/notebook-edit.d.ts

@@ -2,5 +2,6 @@
  * NotebookEditTool — read and edit Jupyter notebook (.ipynb) cells.
  */
 import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
 export declare const notebookEditToolDef: ToolDefinition;
-export declare function notebookEditTool(args: Record<string, unknown>): Promise<string>;
+export declare function notebookEditTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

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 { enforcePathPolicy } from "../path-policy.js";
 export const notebookEditToolDef = {
     name: "NotebookEdit",
     description: "Edit a Jupyter notebook (.ipynb) file. Supports actions: " +
@@ -36,13 +37,19 @@ export const notebookEditToolDef = {
         required: ["file_path", "action"],
     },
 };
-export async function notebookEditTool(args) {
+export async function notebookEditTool(args, ctx) {
     const filePath = args.file_path;
     const action = args.action;
     if (!filePath)
         return "Error: file_path is required";
     if (!filePath.endsWith(".ipynb"))
         return "Error: file must be a .ipynb file";
+    // Path policy: 'read' goes through the read-side rules (sensitive paths
+    // still ask), all other actions are writes and use the stricter rules.
+    const op = action === "read" ? "read" : "write";
+    const blocked = enforcePathPolicy(filePath, op, ctx?.cwd);
+    if (blocked)
+        return blocked;
     if (action === "read") {
         if (!existsSync(filePath))
             return `Error: File not found: ${filePath}`;

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

@@ -2,5 +2,6 @@
  * Built-in Read file tool.
  */
 import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
 export declare const readToolDef: ToolDefinition;
-export declare function readTool(args: Record<string, unknown>): Promise<string>;
+export declare function readTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

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

@@ -4,6 +4,7 @@
 import { readFile, stat } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { fileCache } from "./file-cache.js";
+import { enforcePathPolicy } from "../path-policy.js";
 export const readToolDef = {
     name: "Read",
     description: "Read a file from the local filesystem. Returns the file content with line numbers. " +
@@ -26,10 +27,17 @@ export const readToolDef = {
     },
 };
 const MAX_CONTENT_CHARS = 200_000;
-export async function readTool(args) {
+export async function readTool(args, ctx) {
     const filePath = args.file_path;
     if (!filePath)
         return "Error: file_path is required";
+    // Path policy: in-workspace reads pass through; sensitive paths (~/.ssh,
+    // .env, etc.) and outside-workspace reads are refused with an explanatory
+    // error. existsSync check stays AFTER the policy gate — we don't want to
+    // probe sensitive paths' existence as a side-channel.
+    const blocked = enforcePathPolicy(filePath, "read", ctx?.cwd);
+    if (blocked)
+        return blocked;
     if (!existsSync(filePath))
         return `Error: File not found: ${filePath}`;
     try {

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

@@ -31,16 +31,34 @@ export async function skillTool(args, ctx) {
     if (!skillName) {
         return "Error: skill name is required.";
     }
-    // Reject disabled skills before scanning so the user gets a clear
-    // message that distinguishes "disabled" from "not found" — matches
-    // the UI's toggle semantics. The scanner would also filter the entry
-    // out, which alone would produce a misleading "not found" reply.
+    // Reject disabled skills/plugins before scanning so the user gets a
+    // clear message that distinguishes "disabled" from "not found" —
+    // matches the UI's toggle semantics. The scanner would also filter
+    // these entries out, which alone would produce a misleading "not
+    // found" reply.
+    //
+    // Ordering: per-skill check fires BEFORE plugin-level check so the
+    // more-specific match wins. Both produce distinct error strings so
+    // ordering is observable but not load-bearing.
     const disabledSkills = ctx?.disabledSkills;
+    const disabledPlugins = ctx?.disabledPlugins;
     if (disabledSkills && disabledSkills.includes(skillName)) {
         return `Skill "${skillName}" is disabled. Enable it in Customize or remove it from settings.disabledSkills.`;
     }
+    if (disabledPlugins && disabledPlugins.length > 0) {
+        const colon = skillName.indexOf(":");
+        if (colon > 0) {
+            const pluginName = skillName.slice(0, colon);
+            if (disabledPlugins.includes(pluginName)) {
+                return `Skill "${skillName}" is in disabled plugin "${pluginName}". Enable the plugin in Customize or remove "${pluginName}" from settings.disabledPlugins.`;
+            }
+        }
+    }
     // A4: scan skills from the Engine's cwd, not the host process cwd.
-    const skills = scanSkills(ctx?.cwd ?? process.cwd(), { disabledSkills });
+    const skills = scanSkills(ctx?.cwd ?? process.cwd(), {
+        disabledSkills,
+        disabledPlugins,
+    });
     const found = skills.find((s) => s.name === skillName);
     if (!found) {
         return `Skill "${skillName}" not found. Run /skills to list available skills.`;

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

@@ -23,11 +23,17 @@ export async function sleepTool(args) {
     if (signal?.aborted)
         return "Sleep aborted.";
     await new Promise((resolve, reject) => {
-        const timer = setTimeout(resolve, seconds * 1000);
-        signal?.addEventListener("abort", () => {
+        const onAbort = () => {
             clearTimeout(timer);
             reject(new Error("Sleep aborted"));
-        });
+        };
+        const timer = setTimeout(() => {
+            // Remove the abort listener on normal completion — otherwise every Sleep
+            // call leaks a listener on the (shared, per-turn) signal.
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, seconds * 1000);
+        signal?.addEventListener("abort", onAbort, { once: true });
     }).catch(() => { });
     return `Slept for ${seconds} seconds.`;
 }

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

@@ -30,7 +30,10 @@ export const todoWriteToolDef = {
     name: "TodoWrite",
     description: "Manage the session todo list. Pass the COMPLETE list each call — there's no per-item update API, you rewrite the entire snapshot. " +
         "Use proactively for tasks with 3+ steps. Exactly one item should be in_progress at a time. " +
-        "Always provide both `content` (imperative) and `activeForm` (present continuous) so the UI can show what's happening right now.",
+        "Always provide both `content` (imperative) and `activeForm` (present continuous) so the UI can show what's happening right now. " +
+        "Skip the todo list for straightforward tasks (roughly the easiest 25%) and don't make single-step lists. " +
+        "Update the list immediately after finishing a sub-task — mark it completed in the same turn you completed it, don't batch updates across turns. " +
+        "If you change direction and a planned item will no longer be done, rewrite the list with that item dropped rather than leaving it pending; the list must reflect what you're actually going to do next.",
     inputSchema: {
         type: "object",
         properties: {

package/dist/tool-system/builtin/update-automation-memory.d.ts

@@ -0,0 +1,24 @@
+/**
+ * UpdateAutomationMemory — lets an automation (cron/scheduled) run persist a
+ * one-paragraph summary of what it did, so the NEXT run starts with context.
+ *
+ * This is a FACTORY: core must not depend on desktop's filesystem layer, so the
+ * actual persistence is supplied by an injected `sink` callback. A later task
+ * (the desktop automation runner) injects a sink that appends to the task's
+ * memory.md; this module only builds the tool + validates input.
+ */
+import type { BuiltinTool } from "./index.js";
+import type { ToolDefinition } from "../../types.js";
+/**
+ * Bare tool definition (name/description/inputSchema) — mirrors the export
+ * style of the other builtin tool defs (e.g. cron.ts). The factory below wraps
+ * this into a registry-ready RegisteredTool.
+ */
+export declare const updateAutomationMemoryToolDef: ToolDefinition;
+/**
+ * Build an UpdateAutomationMemory tool bound to a persistence `sink`.
+ *
+ * @param sink Called with the trimmed summary when a non-empty summary is given.
+ *             The caller decides where/how to persist it.
+ */
+export declare function makeUpdateAutomationMemoryTool(sink: (summary: string) => void): BuiltinTool;

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

@@ -0,0 +1,60 @@
+/**
+ * UpdateAutomationMemory — lets an automation (cron/scheduled) run persist a
+ * one-paragraph summary of what it did, so the NEXT run starts with context.
+ *
+ * This is a FACTORY: core must not depend on desktop's filesystem layer, so the
+ * actual persistence is supplied by an injected `sink` callback. A later task
+ * (the desktop automation runner) injects a sink that appends to the task's
+ * memory.md; this module only builds the tool + validates input.
+ */
+/**
+ * Bare tool definition (name/description/inputSchema) — mirrors the export
+ * style of the other builtin tool defs (e.g. cron.ts). The factory below wraps
+ * this into a registry-ready RegisteredTool.
+ */
+export const updateAutomationMemoryToolDef = {
+    name: "UpdateAutomationMemory",
+    description: "Persist a short memory note for this automation task so your NEXT scheduled run " +
+        "starts with context. Call this EXACTLY ONCE, at the very end of the run, with a " +
+        "concise one-paragraph summary of what you did, what you found, and anything the " +
+        "next run should know or continue (e.g. items processed, last cursor/timestamp, " +
+        "open issues). Keep it to a few sentences — it is prepended to your future prompts.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            summary: {
+                type: "string",
+                description: "A concise one-paragraph summary of this run for the next run to build on.",
+            },
+        },
+        required: ["summary"],
+    },
+};
+/**
+ * Build an UpdateAutomationMemory tool bound to a persistence `sink`.
+ *
+ * @param sink Called with the trimmed summary when a non-empty summary is given.
+ *             The caller decides where/how to persist it.
+ */
+export function makeUpdateAutomationMemoryTool(sink) {
+    return {
+        definition: {
+            ...updateAutomationMemoryToolDef,
+            source: "builtin",
+            // The summary is automation-internal bookkeeping (not user code); no prompt.
+            permissionDefault: "allow",
+            // Writes (via the injected sink), so not read-only / not concurrency-safe.
+            isReadOnly: false,
+            isConcurrencySafe: false,
+        },
+        execute: async (args) => {
+            const raw = typeof args.summary === "string" ? args.summary : "";
+            const summary = raw.trim();
+            if (!summary) {
+                return "Error: summary is required and must not be empty";
+            }
+            sink(summary);
+            return "Automation memory saved for the next run.";
+        },
+    };
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Built-in view_image tool — 把一个本地图片文件以 base64 image ContentBlock
+ * 回传进上下文,让 vision 模型「看」它(对照 codex 的 view_image)。
+ *
+ * 典型用法:模型先写 SVG/Mermaid 并用 shell 转成 PNG,再调 view_image(png)
+ * 检查图画对没有(标签是否重叠、文字是否溢出),不对就改源再重转。
+ *
+ * 三道闸门,避免污染上下文 / 浪费 token:
+ *   1. vision gate —— 当前模型不支持视觉时不读文件,只回文字占位。
+ *   2. 格式 gate —— 只支持 png/jpeg/gif/webp(provider image 块能吃的);
+ *      svg/pdf 等回文字提示「先转 PNG」。
+ *   3. 大小 gate —— 超过 MAX_BYTES 回文字提示,不读进 base64。
+ */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+import type { BuiltinToolResult } from "./index.js";
+export declare const viewImageToolDef: ToolDefinition;
+export declare function viewImageTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<BuiltinToolResult>;

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

@@ -0,0 +1,96 @@
+/**
+ * Built-in view_image tool — 把一个本地图片文件以 base64 image ContentBlock
+ * 回传进上下文,让 vision 模型「看」它(对照 codex 的 view_image)。
+ *
+ * 典型用法:模型先写 SVG/Mermaid 并用 shell 转成 PNG,再调 view_image(png)
+ * 检查图画对没有(标签是否重叠、文字是否溢出),不对就改源再重转。
+ *
+ * 三道闸门,避免污染上下文 / 浪费 token:
+ *   1. vision gate —— 当前模型不支持视觉时不读文件,只回文字占位。
+ *   2. 格式 gate —— 只支持 png/jpeg/gif/webp(provider image 块能吃的);
+ *      svg/pdf 等回文字提示「先转 PNG」。
+ *   3. 大小 gate —— 超过 MAX_BYTES 回文字提示,不读进 base64。
+ */
+import { readFile, stat } from "node:fs/promises";
+import { extname, isAbsolute, resolve } from "node:path";
+import { capabilitiesFor } from "../../llm/capabilities/index.js";
+const MAX_BYTES = 5 * 1024 * 1024; // 5MB —— vision 模型按 tile 计 token,大图无益且撑大请求
+const MEDIA_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+};
+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.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            path: {
+                type: "string",
+                description: "Path to the image file (absolute, or relative to the working directory).",
+            },
+        },
+        required: ["path"],
+    },
+};
+export async function viewImageTool(args, ctx) {
+    const rawPath = args.path;
+    if (typeof rawPath !== "string" || !rawPath.trim()) {
+        return "Error: path is required";
+    }
+    const cwd = ctx?.cwd ?? process.cwd();
+    const abs = isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath);
+    // 闸门 1:vision gate —— 不支持视觉就不读文件。
+    // 缺 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) {
+        return `[图片未加载: ${abs} —— 当前模型不支持视觉输入,已跳过。切换到 vision 模型后再 view_image。]`;
+    }
+    // 闸门 2:格式 gate
+    const ext = extname(abs).toLowerCase();
+    const mediaType = MEDIA_TYPES[ext];
+    if (!mediaType) {
+        return `[图片未加载: ${abs} —— 格式 ${ext || "(无扩展名)"} 不支持视觉预览,请先转成 PNG/JPEG。]`;
+    }
+    // 闸门 3:大小 gate(读 stat,不读全文件)
+    let size;
+    try {
+        size = (await stat(abs)).size;
+    }
+    catch (err) {
+        return `Error: 无法读取 ${abs}: ${err.message}`;
+    }
+    if (size > MAX_BYTES) {
+        const mb = (size / 1024 / 1024).toFixed(1);
+        return `[图片未加载: ${abs} —— 文件过大 (${mb} MB > 5 MB),请先压缩或缩放再 view_image。]`;
+    }
+    let buf;
+    try {
+        buf = await readFile(abs);
+    }
+    catch (err) {
+        return `Error: 无法读取 ${abs}: ${err.message}`;
+    }
+    const data = buf.toString("base64");
+    const kb = Math.round(buf.length / 1024);
+    return {
+        contentBlocks: [
+            { type: "image", source: { type: "base64", media_type: mediaType, data } },
+        ],
+        result: `[已加载图片: ${abs} (${mediaType}, ${kb} KB)]`,
+    };
+}