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

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

@@ -17,6 +17,8 @@
 import { fileCache } from "../file-cache.js";
 import { applyPatch } from "./applier.js";
 import { parsePatch } from "./parser.js";
+import { enforcePathPolicy } from "../../path-policy.js";
+import { resolve as resolvePath } from "node:path";
 export const applyPatchToolDef = {
     name: "ApplyPatch",
     description: "Apply a V4A-format patch atomically across one or more files. " +
@@ -68,6 +70,20 @@ export async function applyPatchTool(args, ctx) {
     // A4: resolve relative patch paths against the Engine's cwd, not the
     // host process cwd. See standard §S5.
     const cwd = ctx?.cwd ?? process.cwd();
+    // Path-policy gate every target before any IO. A multi-file patch is
+    // atomic — if *any* target is blocked the whole patch must reject so we
+    // don't end up writing some files and refusing others.
+    for (const hunk of parsed.hunks) {
+        const targets = [resolvePath(cwd, hunk.path)];
+        if (hunk.kind === "update" && hunk.movePath) {
+            targets.push(resolvePath(cwd, hunk.movePath));
+        }
+        for (const t of targets) {
+            const blocked = enforcePathPolicy(t, "write", cwd);
+            if (blocked)
+                return blocked;
+        }
+    }
     let result;
     try {
         result = await applyPatch(parsed.hunks, { cwd });
@@ -75,11 +91,14 @@ export async function applyPatchTool(args, ctx) {
     catch (err) {
         return `Error applying patch: ${err.message}`;
     }
-    // Invalidate file cache for every touched path.
+    // Invalidate file cache for every touched path. The cache is keyed by
+    // ABSOLUTE path (see file-cache.ts), and patch paths are relative to the
+    // Engine cwd — resolve them the same way the path-policy gate did above, or
+    // the stale entry survives and a later Read returns pre-patch content.
     for (const hunk of parsed.hunks) {
-        fileCache.invalidate(hunk.path);
+        fileCache.invalidate(resolvePath(cwd, hunk.path));
         if (hunk.kind === "update" && hunk.movePath) {
-            fileCache.invalidate(hunk.movePath);
+            fileCache.invalidate(resolvePath(cwd, hunk.movePath));
         }
     }
     const parts = [];

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

@@ -123,9 +123,8 @@ function resolveParticipant(nameOrPath, llmConfig, pool) {
                 maxTokens: preset.maxOutputTokens,
                 baseUrl: fallbackBaseUrl,
                 apiKey: fallbackApiKey,
-                temperature: ARENA_TEMPERATURE,
-                enableStreaming: false,
             },
+            clientDefaults: { temperature: ARENA_TEMPERATURE },
         };
     }
     // (3) Raw model path
@@ -138,9 +137,8 @@ function resolveParticipant(nameOrPath, llmConfig, pool) {
             maxTokens: getMaxOutputTokens(nameOrPath),
             baseUrl: fallbackBaseUrl,
             apiKey: fallbackApiKey,
-            temperature: ARENA_TEMPERATURE,
-            enableStreaming: false,
         },
+        clientDefaults: { temperature: ARENA_TEMPERATURE },
     };
 }
 function participantFromPool(entry, llmConfig) {
@@ -156,9 +154,8 @@ function participantFromPool(entry, llmConfig) {
             maxTokens: entry.maxOutputTokens ?? getMaxOutputTokens(entry.model),
             baseUrl: entry.baseUrl ?? llmConfig.baseUrl,
             apiKey: entry.apiKey ?? llmConfig.apiKey,
-            temperature: ARENA_TEMPERATURE,
-            enableStreaming: false,
         },
+        clientDefaults: { temperature: ARENA_TEMPERATURE },
     };
 }
 /**
@@ -411,6 +408,8 @@ export async function arenaTool(args, ctx) {
     catch (err) {
         if (signal?.aborted)
             return "Arena aborted.";
-        return `Arena error: ${err.message}`;
+        // err may be a non-Error (string/null); `(err as Error).message` would be
+        // undefined → "Arena error: undefined", masking the real cause.
+        return `Arena error: ${err instanceof Error ? err.message : String(err)}`;
     }
 }

package/dist/tool-system/builtin/complete-goal.d.ts

@@ -0,0 +1,25 @@
+/**
+ * complete_goal — Goal mode P0.
+ *
+ * The model calls this to explicitly DECLARE the current goal complete
+ * (mirrors Codex's update_goal(status=Complete)). When the turn loop sees
+ * this tool call it short-circuits to a "completed" stop WITHOUT running the
+ * judge LLM (wired in Task 4). This tool itself just records an
+ * acknowledgement string into the transcript; the loop-level short-circuit
+ * lives in turn-loop.ts.
+ *
+ * Shape note: builtin tools in this codebase are a `ToolDefinition`
+ * (name/description/inputSchema only — see types.ts) plus a separate executor
+ * `(args: Record<string, unknown>) => Promise<string>`. The runtime metadata
+ * (source/permissionDefault/isReadOnly/...) is attached in builtin/index.ts at
+ * registration time, NOT on the def. Registration is Task 6.
+ */
+import type { ToolDefinition } from "../../types.js";
+/**
+ * The tool name, shared with turn-loop.ts's short-circuit check so a rename
+ * can't silently break completion detection (the name lives in exactly one
+ * place).
+ */
+export declare const COMPLETE_GOAL_TOOL_NAME = "complete_goal";
+export declare const completeGoalToolDef: ToolDefinition;
+export declare function completeGoalTool(args: Record<string, unknown>): Promise<string>;

package/dist/tool-system/builtin/complete-goal.js

@@ -0,0 +1,45 @@
+/**
+ * complete_goal — Goal mode P0.
+ *
+ * The model calls this to explicitly DECLARE the current goal complete
+ * (mirrors Codex's update_goal(status=Complete)). When the turn loop sees
+ * this tool call it short-circuits to a "completed" stop WITHOUT running the
+ * judge LLM (wired in Task 4). This tool itself just records an
+ * acknowledgement string into the transcript; the loop-level short-circuit
+ * lives in turn-loop.ts.
+ *
+ * Shape note: builtin tools in this codebase are a `ToolDefinition`
+ * (name/description/inputSchema only — see types.ts) plus a separate executor
+ * `(args: Record<string, unknown>) => Promise<string>`. The runtime metadata
+ * (source/permissionDefault/isReadOnly/...) is attached in builtin/index.ts at
+ * registration time, NOT on the def. Registration is Task 6.
+ */
+/**
+ * The tool name, shared with turn-loop.ts's short-circuit check so a rename
+ * can't silently break completion detection (the name lives in exactly one
+ * place).
+ */
+export const COMPLETE_GOAL_TOOL_NAME = "complete_goal";
+export const completeGoalToolDef = {
+    name: COMPLETE_GOAL_TOOL_NAME,
+    description: "声明当前目标已完全达成。仅当目标确实完整完成时才调用本工具(模型在目标完全达成时显式调用以声明完成)。" +
+        "调用后应当停止。可选传入 summary 作为一句话完成总结。\n" +
+        "Declare the current goal complete. Call this ONLY when the goal is fully achieved. " +
+        "After calling, you should stop. Optionally pass a one-line summary of what was accomplished.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            summary: {
+                type: "string",
+                description: "可选:一句话总结所完成的工作。Optional one-line summary of what was accomplished.",
+            },
+        },
+        required: [],
+    },
+};
+export async function completeGoalTool(args) {
+    const summary = typeof args.summary === "string" ? args.summary.trim() : "";
+    return summary
+        ? `目标已完成 (goal complete). Summary: ${summary}`
+        : "目标已完成 (goal complete).";
+}

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

@@ -1,17 +1,41 @@
 /**
  * Cron tools — CronCreate, CronDelete, CronList.
  */
-import { cronScheduler } from "../../cron/scheduler.js";
+import { cronScheduler } from "../../automation/scheduler.js";
 export const cronCreateToolDef = {
     name: "CronCreate",
-    description: "Create a scheduled recurring task. The task will run automatically at the specified interval. " +
-        "Schedule format: '30s', '5m', '1h', '1d'.",
+    description: "Create a scheduled automation job that runs a prompt on a recurring schedule. " +
+        "Use this when the user asks to set up a recurring/automated/scheduled task " +
+        "(monitoring, daily reports, periodic checks, etc.).\n\n" +
+        "Translate the user's natural-language timing into the `schedule` field. Two forms:\n" +
+        "  • Interval: '30s', '5m', '1h', '1d' (runs every N from creation).\n" +
+        "  • Cron expression (5 fields: minute hour day-of-month month day-of-week) for " +
+        "calendar times. Examples: '0 9 * * 1-5' = 9am every weekday; '0 */6 * * *' = every 6 hours; " +
+        "'30 8 * * 1' = 8:30am every Monday. Day-of-week: 0=Sunday..6=Saturday.\n\n" +
+        "For calendar schedules, set `timezone` to the user's IANA zone (e.g. 'Asia/Shanghai', " +
+        "'America/New_York'); ask the user if unknown. Set `cwd` to the project the job operates on. " +
+        "Leave `permissionLevel` as 'read-only' unless the user explicitly wants the job to modify code.",
     inputSchema: {
         type: "object",
         properties: {
-            name: { type: "string", description: "Name for the cron job" },
-            schedule: { type: "string", description: "Interval (e.g. '5m', '1h', '30s')" },
-            prompt: { type: "string", description: "The task prompt to run on each execution" },
+            name: { type: "string", description: "Short human-readable name for the job (e.g. '工作日晨间简报')" },
+            schedule: {
+                type: "string",
+                description: "Interval ('5m','1h','1d') or a 5-field cron expression ('0 9 * * 1-5'). " +
+                    "Derive this from the user's described timing.",
+            },
+            prompt: { type: "string", description: "The task prompt the agent runs on each execution" },
+            timezone: {
+                type: "string",
+                description: "IANA timezone for cron-expression schedules (e.g. 'Asia/Shanghai'). Optional; defaults to UTC.",
+            },
+            cwd: { type: "string", description: "Working directory / project the job runs in. Optional." },
+            permissionLevel: {
+                type: "string",
+                enum: ["read-only", "workspace-write", "full"],
+                description: "What the job may do: 'read-only' (monitoring; default), 'workspace-write' (edit files), " +
+                    "'full' (edit + run git/gh to open PRs). Use the least privilege the task needs.",
+            },
         },
         required: ["name", "schedule", "prompt"],
     },
@@ -22,8 +46,27 @@ export async function cronCreateTool(args) {
     const prompt = args.prompt;
     if (!name || !schedule || !prompt)
         return "Error: name, schedule, and prompt are required";
-    const job = cronScheduler.create(name, schedule, prompt);
-    return `Cron job #${job.id} "${job.name}" created. Schedule: every ${job.schedule}.`;
+    const timezone = typeof args.timezone === "string" ? args.timezone : undefined;
+    const cwd = typeof args.cwd === "string" ? args.cwd : undefined;
+    const permissionLevel = args.permissionLevel === "read-only" ||
+        args.permissionLevel === "workspace-write" ||
+        args.permissionLevel === "full"
+        ? args.permissionLevel
+        : undefined;
+    let job;
+    try {
+        job = cronScheduler.create(name, schedule, prompt, {
+            ...(timezone !== undefined ? { timezone } : {}),
+            ...(cwd !== undefined ? { cwd } : {}),
+            ...(permissionLevel !== undefined ? { permissionLevel } : {}),
+        });
+    }
+    catch (err) {
+        return `Error: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    const tz = job.timezone ? ` (${job.timezone})` : "";
+    const next = job.nextRun ? new Date(job.nextRun).toLocaleString() : "n/a";
+    return `Cron job #${job.id} "${job.name}" created. Schedule: ${job.schedule}${tz}. Next run: ${next}.`;
 }
 export const cronDeleteToolDef = {
     name: "CronDelete",
@@ -55,7 +98,8 @@ export async function cronListTool(_args) {
     const lines = jobs.map((j) => {
         const status = j.enabled ? "active" : "paused";
         const lastRun = j.lastRun ? new Date(j.lastRun).toLocaleString() : "never";
-        return `  #${j.id} "${j.name}" [${status}] every ${j.schedule} | runs: ${j.runCount} | last: ${lastRun}`;
+        const tz = j.timezone ? ` ${j.timezone}` : "";
+        return `  #${j.id} "${j.name}" [${status}] ${j.schedule}${tz} | runs: ${j.runCount} | last: ${lastRun}`;
     });
     return `Cron Jobs (${jobs.length}):\n${lines.join("\n")}`;
 }

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

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

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

@@ -4,6 +4,7 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { fileCache } from "./file-cache.js";
+import { enforcePathPolicy } from "../path-policy.js";
 export const editToolDef = {
     name: "Edit",
     description: "Perform exact string replacements in a file. " +
@@ -30,7 +31,7 @@ export const editToolDef = {
         required: ["file_path", "old_string", "new_string"],
     },
 };
-export async function editTool(args) {
+export async function editTool(args, ctx) {
     const filePath = args.file_path;
     const oldString = args.old_string;
     const newString = args.new_string;
@@ -45,6 +46,10 @@ export async function editTool(args) {
         return "Error: old_string and new_string must be different";
     if (!existsSync(filePath))
         return `Error: File not found: ${filePath}`;
+    // Path policy gate before any IO.
+    const blocked = enforcePathPolicy(filePath, "write", ctx?.cwd);
+    if (blocked)
+        return blocked;
     try {
         const content = await readFile(filePath, "utf-8");
         if (!content.includes(oldString)) {

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

@@ -0,0 +1,25 @@
+/**
+ * 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 type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+export declare const generateImageToolDef: ToolDefinition;
+export declare function isGenerateImageAvailable(cwd?: string, nowMs?: number): boolean;
+export declare function generateImageTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

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>;