@cjhyy/code-shell-core 0.6.0-rc.13 → 0.6.0-rc.15

package/dist/settings/manager.js

@@ -51,14 +51,35 @@ export function isProtectedSettingKey(key) {
     return PROTECTED_SETTING_ROOTS.has(root);
 }
 const FORBIDDEN_SETTING_KEY_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
+function isForbiddenSettingKeySegment(key) {
+    return FORBIDDEN_SETTING_KEY_SEGMENTS.has(key);
+}
 function parseDottedSettingKey(key) {
     const parts = key.split(".");
     if (parts.length === 0 ||
-        parts.some((seg) => seg.length === 0 || FORBIDDEN_SETTING_KEY_SEGMENTS.has(seg))) {
+        parts.some((seg) => seg.length === 0 || isForbiddenSettingKeySegment(seg))) {
         throw new Error(`invalid setting key: ${key}`);
     }
     return parts;
 }
+function sanitizeSettingsValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => sanitizeSettingsValue(entry));
+    }
+    if (!value || typeof value !== "object") {
+        return value;
+    }
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+        if (isForbiddenSettingKeySegment(key))
+            continue;
+        out[key] = sanitizeSettingsValue(child);
+    }
+    return out;
+}
+function sanitizeSettingsObject(data) {
+    return sanitizeSettingsValue(data);
+}
 function isOwnPlainObject(parent, key) {
     if (!Object.prototype.hasOwnProperty.call(parent, key))
         return false;
@@ -174,7 +195,7 @@ export class SettingsManager {
         }
         // 5. CLI flags (highest priority)
         if (flagOverrides && Object.keys(flagOverrides).length > 0) {
-            this.sources.push({ name: "flag", priority: 4, data: flagOverrides });
+            this.sources.push({ name: "flag", priority: 4, data: sanitizeSettingsObject(flagOverrides) });
         }
         // Sort by priority ascending (merge in order, later wins)
         this.sources.sort((a, b) => a.priority - b.priority);
@@ -215,7 +236,7 @@ export class SettingsManager {
         const userPath = join(userHome(), ".code-shell", "settings.json");
         if (readUser && existsSync(userPath)) {
             try {
-                const userRaw = JSON.parse(readFileSync(userPath, "utf-8"));
+                const userRaw = sanitizeSettingsObject(JSON.parse(readFileSync(userPath, "utf-8")));
                 const result = migrateModels({
                     providers: userRaw.providers ?? [],
                     models: userRaw.models ?? [],
@@ -227,14 +248,15 @@ export class SettingsManager {
                         providers: result.providers,
                         models: result.models,
                     };
+                    const sanitized = sanitizeSettingsObject(migrated);
                     // Atomic write (tmp+rename) — a concurrent load must not see a
                     // half-written file. File exists here (existsSync guard above).
-                    this.atomicWriteJson(userPath, migrated);
+                    this.atomicWriteJson(userPath, sanitized);
                     // Re-deep-merge with the migrated user data so the validate
                     // call sees the new shape rather than the legacy one.
                     const userSource = this.sources.find((s) => s.name === "user");
                     if (userSource)
-                        userSource.data = migrated;
+                        userSource.data = sanitized;
                     const remerged = this.deepMerge();
                     this.merged = validateSettings(remerged);
                     return this.merged;
@@ -263,7 +285,7 @@ export class SettingsManager {
             const parsed = JSON.parse(readFileSync(path, "utf-8"));
             if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
                 return;
-            const raw = parsed;
+            const raw = sanitizeSettingsObject(parsed);
             const result = migrateConfig(raw);
             if (!result.changed)
                 return;
@@ -279,10 +301,11 @@ export class SettingsManager {
             // Atomic write (tmp+rename) so a concurrent load can't read a half-written
             // migrated file — matches the normal save path (atomicWriteJson). The file
             // exists here (existsSync guard above), so the recursive mkdir is a no-op.
-            this.atomicWriteJson(path, result.config);
+            const sanitized = sanitizeSettingsObject(result.config);
+            this.atomicWriteJson(path, sanitized);
             const source = this.sources.find((s) => s.name === sourceName);
             if (source)
-                source.data = result.config;
+                source.data = sanitized;
         }
         catch {
             // Best-effort — fall through to normal merge/validate.
@@ -318,7 +341,7 @@ export class SettingsManager {
                 const raw = readFileSync(path, "utf-8");
                 const parsed = JSON.parse(raw);
                 if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-                    current = parsed;
+                    current = sanitizeSettingsObject(parsed);
                 }
             }
             catch {
@@ -500,7 +523,7 @@ function parseConfigFile(path) {
         const ext = extname(path).toLowerCase();
         const parsed = ext === ".yaml" || ext === ".yml" ? parseYaml(content) : JSON.parse(content);
         if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-            return parsed;
+            return sanitizeSettingsObject(parsed);
         }
     }
     catch {
@@ -527,9 +550,17 @@ function resolveConfigPath(jsonPath) {
     return null;
 }
 function merge(base, override) {
-    const result = { ...base };
+    const result = {};
+    for (const [key, value] of Object.entries(base)) {
+        if (isForbiddenSettingKeySegment(key))
+            continue;
+        result[key] = value;
+    }
     for (const [key, value] of Object.entries(override)) {
-        if (value === null) {
+        if (isForbiddenSettingKeySegment(key)) {
+            continue;
+        }
+        else if (value === null) {
             delete result[key];
         }
         else if (typeof value === "object" &&

package/dist/settings/schema.d.ts

@@ -366,6 +366,13 @@ export declare const SettingsSchema: z.ZodObject<{
         storageDir?: string | undefined;
         maxHistory?: number | undefined;
     }>>;
+    worktree: z.ZodDefault<z.ZodObject<{
+        branchPrefix: z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+    }, "strip", z.ZodTypeAny, {
+        branchPrefix: string;
+    }, {
+        branchPrefix?: string | undefined;
+    }>>;
     mcpServers: z.ZodDefault<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodObject<{
         name: z.ZodString;
         command: z.ZodOptional<z.ZodString>;
@@ -1240,6 +1247,13 @@ export declare const SettingsSchema: z.ZodObject<{
         storageDir?: string | undefined;
         maxHistory?: number | undefined;
     }>>;
+    worktree: z.ZodDefault<z.ZodObject<{
+        branchPrefix: z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+    }, "strip", z.ZodTypeAny, {
+        branchPrefix: string;
+    }, {
+        branchPrefix?: string | undefined;
+    }>>;
     mcpServers: z.ZodDefault<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodObject<{
         name: z.ZodString;
         command: z.ZodOptional<z.ZodString>;
@@ -2114,6 +2128,13 @@ export declare const SettingsSchema: z.ZodObject<{
         storageDir?: string | undefined;
         maxHistory?: number | undefined;
     }>>;
+    worktree: z.ZodDefault<z.ZodObject<{
+        branchPrefix: z.ZodDefault<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+    }, "strip", z.ZodTypeAny, {
+        branchPrefix: string;
+    }, {
+        branchPrefix?: string | undefined;
+    }>>;
     mcpServers: z.ZodDefault<z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodObject<{
         name: z.ZodString;
         command: z.ZodOptional<z.ZodString>;

package/dist/settings/schema.js

@@ -2,6 +2,7 @@
  * Settings schema with Zod validation.
  */
 import { z } from "zod";
+import { DEFAULT_WORKTREE_BRANCH_PREFIX, isValidWorktreeBranchPrefix, normalizeWorktreeBranchPrefix, } from "../git/worktree/slug.js";
 /**
  * Tri-state project capability overlay. Lives in PROJECT settings only and
  * layers over the global baseline (disabledSkills / disabledPlugins /
@@ -30,6 +31,12 @@ export const CapabilityOverridesSchema = z
     pluginHooks: z.record(CapabilityOverrideSchema).optional(),
 })
     .optional();
+const WorktreeBranchPrefixSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .refine(isValidWorktreeBranchPrefix, "Invalid git branch prefix")
+    .transform((value) => normalizeWorktreeBranchPrefix(value));
 export const SettingsSchema = z
     .object({
     agent: z
@@ -214,6 +221,11 @@ export const SettingsSchema = z
         maxHistory: z.number().default(100),
     })
         .default({}),
+    worktree: z
+        .object({
+        branchPrefix: WorktreeBranchPrefixSchema.default(DEFAULT_WORKTREE_BRANCH_PREFIX),
+    })
+        .default({}),
     // The record key IS the server name at runtime (MCPManager.connectAll
     // uses Object.entries keys; desktop's persist strips the `name` field and
     // keys by it via stripNameFromServer). So `name` here is optional and

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

@@ -3,9 +3,9 @@
  */
 import { readToolDef, readTool } from "./read.js";
 import { writeToolDef, writeTool } from "./write.js";
-import { generateImageToolDef, generateImageTool, isGenerateImageAvailable } from "./generate-image.js";
+import { generateImageToolDef, generateImageTool, isGenerateImageAvailable, } from "./generate-image.js";
 import { editModelCatalogToolDef, editModelCatalogTool } from "./edit-model-catalog.js";
-import { generateVideoToolDef, generateVideoTool, isGenerateVideoAvailable } from "./generate-video.js";
+import { generateVideoToolDef, generateVideoTool, isGenerateVideoAvailable, } from "./generate-video.js";
 import { viewImageToolDef, viewImageTool } from "./view-image.js";
 import { editToolDef, editTool } from "./edit.js";
 import { applyPatchToolDef, applyPatchTool } from "./apply-patch/index.js";
@@ -16,19 +16,19 @@ import { webSearchToolDef, webSearchTool, isWebSearchAvailable } from "./web-sea
 import { webFetchToolDef, webFetchTool } from "./web-fetch.js";
 import { askUserToolDef, askUserTool } from "./ask-user.js";
 import { agentToolDef, agentTool, agentStatusToolDef, agentStatusTool, agentCancelToolDef, agentCancelTool, agentSendInputToolDef, agentSendInputTool, } from "./agent.js";
-import { enterPlanModeToolDef, enterPlanModeTool, exitPlanModeToolDef, exitPlanModeTool } from "./plan.js";
+import { enterPlanModeToolDef, enterPlanModeTool, exitPlanModeToolDef, exitPlanModeTool, } from "./plan.js";
 import { toolSearchToolDef, toolSearchTool } from "./tool-search.js";
 import { todoWriteToolDef, todoWriteTool } from "./task.js";
-import { enterWorktreeToolDef, enterWorktreeTool, exitWorktreeToolDef, exitWorktreeTool } from "./worktree.js";
+import { enterWorktreeToolDef, enterWorktreeTool, exitWorktreeToolDef, exitWorktreeTool, switchSessionWorkspaceToolDef, switchSessionWorkspaceTool, } from "./worktree.js";
 import { sleepToolDef, sleepTool } from "./sleep.js";
 import { configToolDef, configTool } from "./config.js";
 import { notebookEditToolDef, notebookEditTool } from "./notebook-edit.js";
 import { lspToolDef, lspTool } from "./lsp.js";
-import { cronCreateToolDef, cronCreateTool, cronDeleteToolDef, cronDeleteTool, cronListToolDef, cronListTool } from "./cron.js";
-import { driveClaudeCodeToolDef, driveClaudeCodeTool, driveAgentToolDef, driveAgentTool, DRIVE_AGENT_TOOL_TIMEOUT_MS } from "./drive-claude-code.js";
+import { cronCreateToolDef, cronCreateTool, cronDeleteToolDef, cronDeleteTool, cronListToolDef, cronListTool, } from "./cron.js";
+import { driveClaudeCodeToolDef, driveClaudeCodeTool, driveAgentToolDef, driveAgentTool, DRIVE_AGENT_TOOL_TIMEOUT_MS, } from "./drive-claude-code.js";
 import { checkQuotaToolDef, checkQuotaTool } from "./check-quota.js";
 import { skillToolDef, skillTool } from "./skill.js";
-import { mcpToolDef, mcpToolExecute, listMcpResourcesToolDef, listMcpResourcesTool, readMcpResourceToolDef, readMcpResourceTool } from "./mcp-tools.js";
+import { mcpToolDef, mcpToolExecute, listMcpResourcesToolDef, listMcpResourcesTool, readMcpResourceToolDef, readMcpResourceTool, } from "./mcp-tools.js";
 import { replToolDef, replTool } from "./repl.js";
 import { briefToolDef, briefTool } from "./brief.js";
 import { powershellToolDef, powershellTool } from "./powershell.js";
@@ -344,6 +344,16 @@ export const BUILTIN_TOOLS = [
         },
         execute: exitWorktreeTool,
     },
+    {
+        definition: {
+            ...switchSessionWorkspaceToolDef,
+            source: "builtin",
+            permissionDefault: "ask",
+            isReadOnly: false,
+            isConcurrencySafe: false,
+        },
+        execute: switchSessionWorkspaceTool,
+    },
     // ─── Phase 5: Utility Tools ────────────────────────────────────
     {
         definition: {
@@ -723,7 +733,7 @@ export const BUILTIN_TOOL_GUARDS = new Map([
     [useCredentialToolDef.name, (ctx) => isUseCredentialAvailable(ctx.cwd)],
     // InjectCredential hidden until ≥1 cookie credential exists (browser injection
     // is cookie-only). Also degrades at call time if no browser bridge is wired.
-    [injectCredentialToolDef.name, (ctx) => isInjectCredentialAvailable(ctx.cwd)],
+    [injectCredentialToolDef.name, (ctx) => isInjectCredentialAvailable(ctx.cwd, ctx.settingsScope)],
     [completeGoalToolDef.name, (ctx) => ctx.hasGoal === true],
     [cancelGoalToolDef.name, (ctx) => ctx.hasGoal === true],
 ]);

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

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

package/dist/tool-system/builtin/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

@@ -3,6 +3,8 @@
  */
 import type { ToolDefinition } from "../../types.js";
 import type { ToolContext } from "../context.js";
+export declare const switchSessionWorkspaceToolDef: ToolDefinition;
+export declare function switchSessionWorkspaceTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
 export declare const enterWorktreeToolDef: ToolDefinition;
 export declare function enterWorktreeTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
 export declare const exitWorktreeToolDef: ToolDefinition;