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

package/dist/tool-system/builtin/drive-claude-code.js

@@ -2,7 +2,12 @@ import { runAgentOnce } from "../../cc-orchestrator/external-agent-driver.js";
 import { claudeAdapter, codexAdapter } from "../../cc-orchestrator/agent-adapter.js";
 import { backgroundJobRegistry } from "./background-jobs.js";
 import { readExternalChangedFiles } from "../../cc-orchestrator/external-agent-changes.js";
+import { isExistingDirectory, normalizeCwdPath } from "../../cc-orchestrator/cwd-normalize.js";
 import { notificationQueue } from "./agent-notifications.js";
+import { externalAgentSessionStore, } from "../../cc-orchestrator/external-agent-session-store.js";
+import { logger } from "../../logging/logger.js";
+export const DRIVE_AGENT_FOREGROUND_HANDOFF_MS = 110_000;
+export const DRIVE_AGENT_TOOL_TIMEOUT_MS = 1_800_000;
 const CLI_ADAPTERS = {
     claude: { adapter: claudeAdapter, command: "claude" },
     codex: { adapter: codexAdapter, command: "codex" },
@@ -47,20 +52,144 @@ export const driveAgentToolDef = {
 };
 const defaultRunner = (opts) => {
     const { adapter, command } = CLI_ADAPTERS[opts.cli];
-    return runAgentOnce(adapter, { command, prompt: opts.prompt, resumeSessionId: opts.resumeSessionId, cwd: opts.cwd, permissionMode: opts.permissionMode ?? "default" });
+    return runAgentOnce(adapter, { command, prompt: opts.prompt, resumeSessionId: opts.resumeSessionId, cwd: opts.cwd, permissionMode: opts.permissionMode ?? "default" }, opts.signal);
 };
+function newDriveJobId() {
+    return `cc-${process.hrtime.bigint().toString(36)}`;
+}
+function isValidSessionId(sessionId) {
+    return typeof sessionId === "string" && sessionId.length > 0;
+}
+function argSignal(args) {
+    const signal = args.__signal;
+    return signal &&
+        typeof signal === "object" &&
+        typeof signal.aborted === "boolean" &&
+        typeof signal.addEventListener === "function"
+        ? signal
+        : undefined;
+}
+function startRun(runner, opts) {
+    return Promise.resolve().then(() => runner(opts));
+}
+function recordSuccessfulSession(store, cli, cwd, result) {
+    if (result.isError || !result.sessionId)
+        return;
+    try {
+        store.record({ cli, sessionId: result.sessionId, cwd });
+    }
+    catch (err) {
+        logger.warn("drive_agent.session_binding_record_failed", {
+            cat: "cc",
+            cli,
+            sessionId: result.sessionId,
+            cwd,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+function duplicateCwdWarning(cwd, writable) {
+    if (!writable)
+        return undefined;
+    const running = backgroundJobRegistry.listRunningByCwd(cwd);
+    if (running.length === 0)
+        return undefined;
+    const ids = running.map((j) => j.jobId).join(", ");
+    return `Warning: another DriveAgent job is already running in cwd ${cwd} (jobId ${ids}). Concurrent writable agents in the same directory can overwrite each other's work.`;
+}
+function attachDriveCompletion(params) {
+    const { jobId, sessionId, label, cli, cwd, run, sessionStore } = params;
+    void run
+        .then((r) => {
+        recordSuccessfulSession(sessionStore, cli, cwd, r);
+        // Deliver the result back so the woken agent actually sees the answer
+        // (not just "a job finished"). Mirrors the video/sub-agent completion
+        // path — enqueue lands in the same notificationQueue the wakeup drains.
+        notificationQueue.enqueue(r.isError
+            ? { agentId: jobId, description: label, status: "failed", workKind: "cc", error: r.finalText || "(no output)", ccSessionId: r.sessionId || undefined, enqueuedAt: Date.now() }
+            : { agentId: jobId, description: label, status: "completed", workKind: "cc", finalText: r.finalText, ccSessionId: r.sessionId || undefined, enqueuedAt: Date.now() }, sessionId);
+        // Attribute the files the external agent changed by parsing its own
+        // transcript (#6) — those Edit/Write calls are invisible to the host's
+        // in-session aggregator. Best-effort; [] on any failure.
+        const changedFiles = r.sessionId
+            ? readExternalChangedFiles(cli, cwd, r.sessionId)
+            : [];
+        // Retain the job in the panel with its result + the external CLI
+        // session id + changed files.
+        backgroundJobRegistry.finish(jobId, {
+            status: r.isError ? "failed" : "completed",
+            finalText: r.finalText || undefined,
+            ccSessionId: r.sessionId || undefined,
+            ...(changedFiles.length ? { changedFiles } : {}),
+        });
+    })
+        .catch((err) => {
+        const msg = err?.message ?? String(err);
+        notificationQueue.enqueue({ agentId: jobId, description: label, status: "failed", workKind: "cc", error: msg, enqueuedAt: Date.now() }, sessionId);
+        backgroundJobRegistry.finish(jobId, { status: "failed", finalText: msg });
+    });
+}
+function trackBackgroundRun(params) {
+    const warning = duplicateCwdWarning(params.cwd, params.writable);
+    const jobId = newDriveJobId();
+    backgroundJobRegistry.start(jobId, params.sessionId, params.label, { cwd: params.cwd });
+    attachDriveCompletion({ ...params, jobId });
+    return { jobId, ...(warning ? { warning } : {}) };
+}
+async function waitForForegroundOrHandoff(run, handoffMs) {
+    if (handoffMs < 0) {
+        return { kind: "completed", result: await run };
+    }
+    let timer;
+    try {
+        return await Promise.race([
+            run.then((result) => ({ kind: "completed", result })),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve({ kind: "handoff" }), handoffMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 /** Factory so tests can inject a fake runner. `fixedCli` (back-compat) forces a
  *  cli and hides the `cli` arg — that's how DriveClaudeCode stays a thin alias. */
-export function makeDriveAgentTool(runner = defaultRunner, fixedCli) {
+export function makeDriveAgentTool(runner = defaultRunner, fixedCli, options = {}) {
     return async (args, ctx) => {
         const prompt = typeof args.prompt === "string" ? args.prompt : "";
-        const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
+        const rawRequestedCwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
+        const requestedCwd = normalizeCwdPath(rawRequestedCwd);
         if (!prompt)
             return "Error: prompt is required";
         const cli = fixedCli ?? (args.cli === "codex" ? "codex" : args.cli === "claude" || args.cli === undefined ? "claude" : "invalid");
         if (cli === "invalid")
             return `Error: unknown cli "${String(args.cli)}" (expected "claude" or "codex")`;
         const resumeSessionId = typeof args.resumeSessionId === "string" ? args.resumeSessionId : undefined;
+        const sessionStore = options.sessionStore ?? externalAgentSessionStore;
+        let cwd = requestedCwd;
+        let resumeNote = "";
+        if (resumeSessionId) {
+            const binding = sessionStore.get(cli, resumeSessionId);
+            if (binding) {
+                const storedCwd = normalizeCwdPath(binding.cwd);
+                if (!isExistingDirectory(storedCwd)) {
+                    return `Error: cannot resume ${cli} session ${resumeSessionId}: stored cwd no longer exists or is not a directory: ${storedCwd}`;
+                }
+                if (storedCwd !== requestedCwd) {
+                    cwd = storedCwd;
+                    resumeNote = `Note: resume session ${resumeSessionId} is bound to stored cwd ${storedCwd}; ignoring requested cwd ${requestedCwd}.`;
+                    logger.info("drive_agent.resume_forced_stored_cwd", {
+                        cat: "cc",
+                        cli,
+                        sessionId: resumeSessionId,
+                        requestedCwd,
+                        storedCwd,
+                    });
+                }
+            }
+        }
         // Default to bypassPermissions: this tool is a fire-one-turn delegation to
         // an external CLI with nobody watching for approvals, and there is no
         // interactive approval loop here — so under "default" a tool that needs
@@ -75,6 +204,9 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli) {
             : "bypassPermissions";
         const cliName = cli === "codex" ? "Codex" : "Claude Code";
         const label = `DriveAgent(${cli}): ${prompt.slice(0, 40)}`;
+        const runOpts = { cli, prompt, resumeSessionId, cwd, permissionMode, signal: ctx?.signal ?? argSignal(args) };
+        const foregroundHandoffMs = options.foregroundHandoffMs ?? DRIVE_AGENT_FOREGROUND_HANDOFF_MS;
+        const isWritableRun = permissionMode !== "default";
         // Background by default (these tasks are typically long). Only an explicit
         // background:false runs in the foreground and returns the result inline.
         const background = args.background !== false;
@@ -87,42 +219,45 @@ export function makeDriveAgentTool(runner = defaultRunner, fixedCli) {
             if (typeof sessionId !== "string" || sessionId.length === 0) {
                 return `Error: cannot start a background ${cliName} job without a session — its result notification would be dropped. Retry with background:false, or ensure the tool runs inside a session.`;
             }
-            const jobId = `cc-${process.hrtime.bigint().toString(36)}`;
-            backgroundJobRegistry.start(jobId, sessionId, label);
-            void runner({ cli, prompt, resumeSessionId, cwd, permissionMode })
-                .then((r) => {
-                // Deliver the result back so the woken agent actually sees the answer
-                // (not just "a job finished"). Mirrors the video/sub-agent completion
-                // path — enqueue lands in the same notificationQueue the wakeup drains.
-                notificationQueue.enqueue(r.isError
-                    ? { agentId: jobId, description: label, status: "failed", workKind: "cc", error: r.finalText || "(no output)", ccSessionId: r.sessionId || undefined, enqueuedAt: Date.now() }
-                    : { agentId: jobId, description: label, status: "completed", workKind: "cc", finalText: r.finalText, ccSessionId: r.sessionId || undefined, enqueuedAt: Date.now() }, sessionId);
-                // Attribute the files the external agent changed by parsing its own
-                // transcript (#6) — those Edit/Write calls are invisible to the host's
-                // in-session aggregator. Best-effort; [] on any failure.
-                const changedFiles = r.sessionId
-                    ? readExternalChangedFiles(cli, cwd, r.sessionId)
-                    : [];
-                // Retain the job in the panel with its result + the external CLI
-                // session id + changed files.
-                backgroundJobRegistry.finish(jobId, {
-                    status: r.isError ? "failed" : "completed",
-                    finalText: r.finalText || undefined,
-                    ccSessionId: r.sessionId || undefined,
-                    ...(changedFiles.length ? { changedFiles } : {}),
-                });
-            })
-                .catch((err) => {
-                const msg = err?.message ?? String(err);
-                notificationQueue.enqueue({ agentId: jobId, description: label, status: "failed", workKind: "cc", error: msg, enqueuedAt: Date.now() }, sessionId);
-                backgroundJobRegistry.finish(jobId, { status: "failed", finalText: msg });
+            const tracked = trackBackgroundRun({
+                sessionId,
+                label,
+                cli,
+                cwd,
+                run: startRun(runner, runOpts),
+                sessionStore,
+                writable: isWritableRun,
+            });
+            return [
+                resumeNote,
+                `已在后台启动 ${cliName}（jobId ${tracked.jobId}）。完成后会通知你结果，无需轮询。`,
+                tracked.warning,
+            ].filter(Boolean).join("\n");
+        }
+        const run = startRun(runner, runOpts);
+        const result = await waitForForegroundOrHandoff(run, foregroundHandoffMs);
+        if (result.kind === "handoff" && isValidSessionId(ctx?.sessionId)) {
+            const tracked = trackBackgroundRun({
+                sessionId: ctx.sessionId,
+                label,
+                cli,
+                cwd,
+                run,
+                sessionStore,
+                writable: isWritableRun,
             });
-            return `已在后台启动 ${cliName}（jobId ${jobId}）。完成后会通知你结果，无需轮询。`;
+            return [
+                resumeNote,
+                `${cliName} foreground run exceeded ${foregroundHandoffMs}ms; moved it to background (jobId ${tracked.jobId}). Completion will notify this session, so do not poll.`,
+                tracked.warning,
+            ].filter(Boolean).join("\n");
         }
-        const r = await runner({ cli, prompt, resumeSessionId, cwd, permissionMode });
+        const r = result.kind === "completed" ? result.result : await run;
+        recordSuccessfulSession(sessionStore, cli, cwd, r);
+        const prefix = resumeNote ? `${resumeNote}\n` : "";
         if (r.isError)
-            return `${cliName} 运行出错（session ${r.sessionId}）：\n${r.finalText}`;
-        return `${cliName} 完成（session ${r.sessionId}）：\n${r.finalText}`;
+            return `${prefix}${cliName} 运行出错（session ${r.sessionId}）：\n${r.finalText}`;
+        return `${prefix}${cliName} 完成（session ${r.sessionId}）：\n${r.finalText}`;
     };
 }
 export const driveAgentTool = makeDriveAgentTool();
@@ -148,10 +283,10 @@ export const driveClaudeCodeToolDef = {
         required: ["prompt", "cwd"],
     },
 };
-export function makeDriveClaudeCodeTool(runner) {
+export function makeDriveClaudeCodeTool(runner, options) {
     const generic = runner
-        ? ({ prompt, resumeSessionId, cwd, permissionMode }) => runner({ prompt, resumeSessionId, cwd, permissionMode })
+        ? ({ prompt, resumeSessionId, cwd, permissionMode, signal }) => runner({ prompt, resumeSessionId, cwd, permissionMode, signal })
         : undefined;
-    return makeDriveAgentTool(generic ?? defaultRunner, "claude");
+    return makeDriveAgentTool(generic ?? defaultRunner, "claude", options);
 }
 export const driveClaudeCodeTool = makeDriveClaudeCodeTool();

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

@@ -3,6 +3,7 @@
  */
 import { readFile, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
 import { fileCache } from "./file-cache.js";
 import { detectEol, toLf, applyEol } from "./eol.js";
 export const editToolDef = {
@@ -32,11 +33,11 @@ export const editToolDef = {
     },
 };
 export async function editTool(args, ctx) {
-    const filePath = args.file_path;
+    const rawPath = args.file_path;
     const oldString = args.old_string;
     const newString = args.new_string;
     const replaceAll = args.replace_all ?? false;
-    if (!filePath)
+    if (!rawPath)
         return "Error: file_path is required";
     if (oldString === undefined)
         return "Error: old_string is required";
@@ -44,6 +45,8 @@ export async function editTool(args, ctx) {
         return "Error: new_string is required";
     if (oldString === newString)
         return "Error: old_string and new_string must be different";
+    const cwd = ctx?.cwd ?? process.cwd();
+    const filePath = isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath);
     if (!existsSync(filePath))
         return `Error: File not found: ${filePath}`;
     try {

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

@@ -18,6 +18,7 @@ import type { ToolDefinition } from "../../types.js";
 import type { ToolContext } from "../context.js";
 import { type VideoProvider, type VideoProviderCreds } from "./video-providers.js";
 import { type ImageUploader, type UploaderCreds } from "./image-uploader.js";
+export declare function __resolveLocalImageInputForTests(pathOrUrl: string, cwd: string): string;
 /**
  * Normalize image inputs (URLs or local paths) into public URLs the provider
  * can consume. `images[]` wins over the single `image`. Local paths are

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

@@ -15,17 +15,22 @@
  * "no video provider configured" message) rather than half-working.
  */
 import { writeFile, mkdir } from "node:fs/promises";
-import { join } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { SettingsManager } from "../../settings/manager.js";
 import { notificationQueue } from "./agent-notifications.js";
 import { backgroundJobRegistry } from "./background-jobs.js";
 import { logger } from "../../logging/logger.js";
 import { getVideoProvider, DEFAULT_VIDEO_MODEL, } from "./video-providers.js";
-import { getImageUploader } from "./image-uploader.js";
+import { getImageUploader, isHttpUrl } from "./image-uploader.js";
 import { effectiveApiKey } from "./generate-image.js";
 import { getMergedCatalog, findCatalogEntry } from "../../model-catalog/index.js";
 import { genInstancesFromConnections } from "../../model-catalog/gen-connections.js";
 const MAX_IMAGES = 9;
+export function __resolveLocalImageInputForTests(pathOrUrl, cwd) {
+    if (isHttpUrl(pathOrUrl))
+        return pathOrUrl;
+    return isAbsolute(pathOrUrl) ? pathOrUrl : resolve(cwd, pathOrUrl);
+}
 /**
  * Normalize image inputs (URLs or local paths) into public URLs the provider
  * can consume. `images[]` wins over the single `image`. Local paths are
@@ -230,9 +235,13 @@ export async function generateVideoTool(args, ctx) {
     const sessionId = ctx?.sessionId;
     const preferKind = typeof args.provider === "string" && args.provider ? args.provider : undefined;
     const overrideModel = typeof args.model === "string" && args.model ? args.model : undefined;
-    const image = typeof args.image === "string" && args.image ? args.image : undefined;
+    const image = typeof args.image === "string" && args.image
+        ? __resolveLocalImageInputForTests(args.image, cwd)
+        : undefined;
     const imagesArg = Array.isArray(args.images)
-        ? args.images.filter((x) => typeof x === "string")
+        ? args.images
+            .filter((x) => typeof x === "string")
+            .map((x) => __resolveLocalImageInputForTests(x, cwd))
         : undefined;
     // videos pass through verbatim to fal's video_urls (no upload) — http(s) only.
     const videosArg = Array.isArray(args.videos)

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

@@ -25,7 +25,7 @@ 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 { 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";
@@ -433,6 +433,7 @@ export const BUILTIN_TOOLS = [
             permissionDefault: "ask",
             isReadOnly: false,
             isConcurrencySafe: false,
+            timeoutMs: DRIVE_AGENT_TOOL_TIMEOUT_MS,
         },
         execute: driveAgentTool,
     },
@@ -445,6 +446,7 @@ export const BUILTIN_TOOLS = [
             permissionDefault: "ask",
             isReadOnly: false,
             isConcurrencySafe: false,
+            timeoutMs: DRIVE_AGENT_TOOL_TIMEOUT_MS,
         },
         execute: driveClaudeCodeTool,
     },
@@ -722,6 +724,8 @@ export const BUILTIN_TOOL_GUARDS = new Map([
     // 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)],
+    [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) {

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/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/read.js

@@ -3,6 +3,7 @@
  */
 import { readFile, stat } from "node:fs/promises";
 import { existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
 import { fileCache } from "./file-cache.js";
 import { toLf } from "./eol.js";
 export const readToolDef = {
@@ -28,9 +29,11 @@ export const readToolDef = {
 };
 const MAX_CONTENT_CHARS = 200_000;
 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 {

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

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

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

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

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

@@ -1,11 +1,9 @@
 /**
- * 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 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>;