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

package/dist/tool-system/builtin/browser-tools.js

@@ -0,0 +1,312 @@
+/**
+ * Browser automation tools — drive the in-app webview via the BrowserBridge
+ * (CDP under the hood). Collapsed into THREE semantic tools (was 9 flat tools)
+ * to keep the LLM's tool list lean:
+ *
+ *   browser_observe  — observe the page: snapshot (a11y elements) / read (text) /
+ *                      extract (link+image+video URLs). [+ image/vision in P4]
+ *   browser_act      — interact: click / type / select / press_key / hover /
+ *                      scroll / wait / list_tabs / switch_tab (action-dispatched).
+ *   browser_navigate — load a URL (high-frequency, kept standalone).
+ *
+ * Spec: docs/superpowers/specs/2026-06-18-browser-module-redesign-design.md §4.1.
+ *
+ * snapshot returns interactive elements as a compact ref-tagged list (a11y tree,
+ * token-economical, no screenshots); act references elements by the ref the
+ * latest snapshot assigned. All tools degrade with a clear error when no browser
+ * is wired. isConcurrencySafe:false — a single webview is driven serially.
+ *
+ * Permission: browser_act is permissionDefault "allow"; the sensitive actions
+ * (click/type/select) are escalated to "ask" by a preset PermissionRule keyed on
+ * argsPattern { action }, so one tool can carry per-action gating (§4.6).
+ */
+import { renderElementList } from "../browser-bridge.js";
+import { capabilitiesFor } from "../../llm/capabilities/index.js";
+const NO_BROWSER = "Error: browser automation is not available (no browser panel in this session). " +
+    "It requires the desktop app with an open browser panel.";
+function bridge(ctx) {
+    return ctx?.browser;
+}
+const STALE = (ref) => `Error: ref ${ref} is no longer valid (page changed). Re-run browser_observe.`;
+// ════════════════════════════════════════════════════════════════════════════
+// browser_observe — observe the page (snapshot / read / extract)
+// ════════════════════════════════════════════════════════════════════════════
+export const browserObserveToolDef = {
+    name: "browser_observe",
+    description: "Observe the current page in the browser panel. Modes:\n" +
+        "- snapshot (default): URL/title + a compact list of interactive elements, each " +
+        "tagged [ref=eN] for browser_act. ALWAYS snapshot before acting, and re-snapshot " +
+        "after navigation/page changes (refs are only valid for the latest snapshot). " +
+        "Passwords show as [sensitive] with no value.\n" +
+        "- read: the page's main readable text (for summarizing/scraping an article/post; " +
+        "long pages truncate — scroll + read again).\n" +
+        "- extract: the real URLs on the page (hyperlink hrefs, image srcs, video srcs) " +
+        "that snapshot omits — each image/video is tagged [ref=imgN/vidN] for image mode.\n" +
+        "- image: SEE the actual pixels of page images (refs from extract, e.g. img3) — for " +
+        "reading what a photo/product image/小红书 笔记配图 actually shows. Fetched in-page so " +
+        "it works behind hotlink protection. A vidN ref grabs the video's current frame.\n" +
+        "- vision: screenshot the rendered page (or one element via ref) — for layout/canvas/" +
+        "charts the a11y tree can't convey. Use sparingly (images cost tokens; snapshot first).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            mode: {
+                type: "string",
+                enum: ["snapshot", "read", "extract", "image", "vision"],
+                description: "What to observe (default: snapshot)",
+            },
+            refs: {
+                type: "array",
+                items: { type: "string" },
+                description: "image mode: image refs (imgN/vidN from extract) to see, one or more",
+            },
+            ref: { type: "string", description: "vision mode (optional): screenshot just this element's region" },
+        },
+    },
+};
+/** Vision gate: only show images to a vision-capable model. Mirrors view_image —
+ *  no vision → never read pixels into context (your rule: 不支持就不给看). */
+function modelSupportsVision(ctx) {
+    if (!ctx?.llmConfig)
+        return false;
+    const kind = (ctx.llmConfig.providerKind ?? ctx.llmConfig.provider);
+    return capabilitiesFor(kind, ctx.llmConfig.model).supportsVision;
+}
+/** Wrap captured image data into a vision ContentBlock (or null if not usable). */
+function toImageBlock(d) {
+    if (!d.ok || !d.base64 || !d.mediaType)
+        return null;
+    return { type: "image", source: { type: "base64", media_type: d.mediaType, data: d.base64 } };
+}
+export async function browserObserveTool(args, ctx) {
+    const b = bridge(ctx);
+    if (!b)
+        return NO_BROWSER;
+    const mode = args.mode || "snapshot";
+    switch (mode) {
+        case "snapshot": {
+            const snap = await b.snapshot();
+            const header = `URL: ${snap.url}${snap.title ? `\nTitle: ${snap.title}` : ""}`;
+            const human = snap.needsHuman
+                ? `\n\n⚠ ${snap.needsHuman} — please complete it in the browser panel, then continue.`
+                : "";
+            return `${header}\n\n${renderElementList(snap.elements)}${human}`;
+        }
+        case "read": {
+            const c = await b.readContent();
+            if (!c.ok)
+                return `Error: ${c.detail ?? "could not read page content"}`;
+            const head = `URL: ${c.url}${c.title ? `\nTitle: ${c.title}` : ""}${c.truncated ? "\n(content truncated)" : ""}`;
+            return `${head}\n\n${c.text || "(no readable text)"}`;
+        }
+        case "extract": {
+            const r = await b.extractLinks();
+            if (!r.ok)
+                return `Error: ${r.detail ?? "could not extract URLs"}`;
+            const head = `URL: ${r.url}${r.title ? `\nTitle: ${r.title}` : ""}${r.truncated ? "\n(truncated — page had more; narrow it and re-extract)" : ""}`;
+            const links = r.links.length > 0
+                ? "Links:\n" + r.links.map((l) => `- ${l.text ? `${l.text} → ` : ""}${l.url}`).join("\n")
+                : "Links: (none)";
+            const images = r.images.length > 0
+                ? "Images (use the ref with browser_observe(image) to SEE one):\n" +
+                    r.images.map((im) => `- [${im.ref ?? "?"}] ${im.alt ? `${im.alt} → ` : ""}${im.url}`).join("\n")
+                : "Images: (none)";
+            const videos = r.videos && r.videos.length > 0
+                ? "Videos:\n" + r.videos.map((v) => `- ${v.url}`).join("\n")
+                : "Videos: (none)";
+            return `${head}\n\n${links}\n\n${images}\n\n${videos}`;
+        }
+        case "image": {
+            // Vision gate: don't fetch pixels for a non-vision model (your rule).
+            if (!modelSupportsVision(ctx)) {
+                return "[图片未加载 —— 当前模型不支持视觉输入,已跳过。切换到 vision 模型后再用 browser_observe(image)。]";
+            }
+            const refs = Array.isArray(args.refs) ? args.refs : [];
+            if (refs.length === 0)
+                return "Error: refs is required for image mode (image refs from browser_observe(extract), e.g. img3)";
+            const datas = await b.fetchImages(refs);
+            const blocks = [];
+            const notes = [];
+            for (const d of datas) {
+                const block = toImageBlock(d);
+                if (block) {
+                    blocks.push(block);
+                    notes.push(`${d.ref ?? "?"}: loaded`);
+                }
+                else {
+                    notes.push(`${d.ref ?? "?"}: ${d.detail ?? "could not load"}`);
+                }
+            }
+            if (blocks.length === 0)
+                return `Error: no images loaded — ${notes.join("; ")}`;
+            return { contentBlocks: blocks, result: `[loaded ${blocks.length} image(s): ${notes.join("; ")}]` };
+        }
+        case "vision": {
+            if (!modelSupportsVision(ctx)) {
+                return "[截图未加载 —— 当前模型不支持视觉输入,已跳过。切换到 vision 模型后再用 browser_observe(vision)。]";
+            }
+            const ref = args.ref;
+            const d = await b.screenshot(ref);
+            const block = toImageBlock(d);
+            if (!block)
+                return `Error: ${d.detail ?? "screenshot failed"}`;
+            return { contentBlocks: [block], result: `[screenshot loaded${ref ? ` of ${ref}` : ""}]` };
+        }
+        default:
+            return `Error: unknown observe mode "${mode}" (use snapshot | read | extract | image | vision)`;
+    }
+}
+// ════════════════════════════════════════════════════════════════════════════
+// browser_act — interact with the page (action-dispatched)
+// ════════════════════════════════════════════════════════════════════════════
+export const browserActToolDef = {
+    name: "browser_act",
+    description: "Act on the page in the browser panel. Use refs (eN) from the latest " +
+        "browser_observe(snapshot). Actions:\n" +
+        "- click {ref}: click an element.\n" +
+        "- type {ref, text}: type text into an input (focuses first).\n" +
+        "- select {ref, value}: choose an option in a NATIVE <select> (value = option " +
+        "value or visible text). Custom dropdowns: click to expand, then click the option.\n" +
+        "- press_key {key, ref?}: press a key/combo (Enter, Tab, Escape, ArrowDown, " +
+        "Control+a). Focuses ref first if given.\n" +
+        "- hover {ref}: hover to reveal menus/tooltips.\n" +
+        "- scroll {direction: up|down, amount?}: scroll the page, then re-observe.\n" +
+        "- wait {timeout_ms?}: wait for the page to finish loading before observing.\n" +
+        "- list_tabs: list open browser tabs (tabId, url, title, which is active).\n" +
+        "- switch_tab {tabId}: make another tab the active one that actions drive.\n" +
+        "Pass tabId on any action to target a specific tab (switches to it first). " +
+        "Re-observe after navigation/page/tab changes (refs go stale per tab).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            action: {
+                type: "string",
+                enum: ["click", "type", "select", "press_key", "hover", "scroll", "wait", "list_tabs", "switch_tab"],
+                description: "The interaction to perform",
+            },
+            ref: { type: "string", description: "Element ref (eN) — click/type/select/hover/press_key" },
+            text: { type: "string", description: "Text to type — type" },
+            value: { type: "string", description: "Option value or visible text — select" },
+            key: { type: "string", description: "Key name or combo (Enter/Tab/Control+a) — press_key" },
+            direction: { type: "string", enum: ["up", "down"], description: "Scroll direction — scroll" },
+            amount: { type: "number", description: "Pixels to scroll (default one viewport) — scroll" },
+            timeout_ms: { type: "number", description: "Max wait in ms (default 10000) — wait" },
+            tabId: { type: "string", description: "Target tab — required for switch_tab; optional on others (switches first)" },
+        },
+        required: ["action"],
+    },
+};
+export async function browserActTool(args, ctx) {
+    const b = bridge(ctx);
+    if (!b)
+        return NO_BROWSER;
+    const action = args.action;
+    const ref = args.ref;
+    const tabId = args.tabId;
+    // Optional tabId on a non-tab action → switch to that tab first, then act.
+    if (tabId && action !== "switch_tab" && action !== "list_tabs") {
+        const sw = await b.switchTab(tabId);
+        if (!sw.ok)
+            return `Error: could not switch to tab ${tabId} — ${sw.detail ?? "not found"}`;
+    }
+    switch (action) {
+        case "list_tabs": {
+            const tabs = await b.listTabs();
+            if (tabs.length === 0)
+                return "(no open browser tabs)";
+            return ("Open tabs:\n" +
+                tabs.map((t) => `- [${t.tabId}]${t.active ? " (active)" : ""} ${t.title || "(untitled)"} — ${t.url || "(blank)"}`).join("\n"));
+        }
+        case "switch_tab": {
+            if (!tabId)
+                return "Error: tabId is required for switch_tab (see list_tabs)";
+            const r = await b.switchTab(tabId);
+            return r.ok ? `Switched to tab ${tabId} — re-observe to see it` : `Error: ${r.detail ?? "switch failed"}`;
+        }
+        case "click": {
+            if (!ref)
+                return "Error: ref is required for click";
+            const r = await b.click(ref);
+            if (r.ok)
+                return `Clicked ${ref}${r.detail ? ` — ${r.detail}` : ""}`;
+            return r.staleRef ? STALE(ref) : `Error: ${r.detail ?? "click failed"}`;
+        }
+        case "type": {
+            const text = args.text;
+            if (!ref)
+                return "Error: ref is required for type";
+            if (typeof text !== "string")
+                return "Error: text is required for type";
+            const r = await b.type(ref, text);
+            if (r.ok)
+                return `Typed into ${ref}`;
+            return r.staleRef ? STALE(ref) : `Error: ${r.detail ?? "type failed"}`;
+        }
+        case "select": {
+            const value = args.value;
+            if (!ref)
+                return "Error: ref is required for select";
+            if (typeof value !== "string")
+                return "Error: value is required for select";
+            const r = await b.selectOption(ref, value);
+            if (r.ok)
+                return `Selected${r.detail ? ` ${r.detail}` : ""} in ${ref}`;
+            return r.staleRef ? STALE(ref) : `Error: ${r.detail ?? "select failed"}`;
+        }
+        case "press_key": {
+            const key = args.key || "Enter";
+            const r = await b.pressKey(key, ref);
+            if (r.ok)
+                return `Pressed ${key}`;
+            return r.staleRef && ref ? STALE(ref) : `Error: ${r.detail ?? "press_key failed"}`;
+        }
+        case "hover": {
+            if (!ref)
+                return "Error: ref is required for hover";
+            const r = await b.hover(ref);
+            if (r.ok)
+                return `Hovered ${ref}`;
+            return r.staleRef ? STALE(ref) : `Error: ${r.detail ?? "hover failed"}`;
+        }
+        case "scroll": {
+            const dir = args.direction;
+            if (dir !== "up" && dir !== "down")
+                return "Error: direction must be 'up' or 'down'";
+            const r = await b.scroll(dir, args.amount);
+            return r.ok ? `Scrolled ${dir}` : `Error: ${r.detail ?? "scroll failed"}`;
+        }
+        case "wait": {
+            const r = await b.waitForLoad(args.timeout_ms);
+            return r.ok ? `Page ready${r.detail ? ` (${r.detail})` : ""}` : `Error: ${r.detail ?? "wait failed"}`;
+        }
+        default:
+            return `Error: unknown action "${action}"`;
+    }
+}
+// ════════════════════════════════════════════════════════════════════════════
+// browser_navigate — load a URL (kept standalone: high-frequency, distinct)
+// ════════════════════════════════════════════════════════════════════════════
+export const browserNavigateToolDef = {
+    name: "browser_navigate",
+    description: "Navigate the browser panel to a URL (opens the panel automatically if none " +
+        "is open). Then call browser_act(wait) + browser_observe to see the page.",
+    inputSchema: {
+        type: "object",
+        properties: { url: { type: "string", description: "Absolute URL to open" } },
+        required: ["url"],
+    },
+};
+export async function browserNavigateTool(args, ctx) {
+    const b = bridge(ctx);
+    if (!b)
+        return NO_BROWSER;
+    const url = args.url;
+    if (!url)
+        return "Error: url is required";
+    const r = await b.navigate(url);
+    return r.ok ? `Navigated to ${url}` : `Error: ${r.detail ?? "navigation failed"}`;
+}
+/** True when the session has a browser bridge wired (used to gate visibility). */
+export function isBrowserAutomationAvailable(ctx) {
+    return bridge(ctx) !== undefined;
+}

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

@@ -0,0 +1,31 @@
+/**
+ * cancel_goal — user-initiated goal ABANDONMENT (distinct from complete_goal).
+ *
+ * complete_goal = "the goal is fully achieved, stop." cancel_goal = "the user
+ * explicitly asked to STOP pursuing this goal even though it isn't done." Both
+ * short-circuit the turn loop to a stop and clear the persisted goal so a later
+ * bare send won't re-inherit it — but cancel_goal is a controlled escape hatch,
+ * NOT a self-judgment the model may make on its own.
+ *
+ * "Strong intent" guard (the whole point of this tool): the model must NOT
+ * cancel a goal on its own initiative — only when the user has clearly asked to
+ * stop/abandon it. To make that hard to do accidentally, the schema REQUIRES:
+ *   - confirm: true         — an explicit boolean gate (a bare call is invalid)
+ *   - reason: string        — the user's own words / paraphrase of the request
+ * The turn loop only honors the cancellation when confirm === true; anything
+ * else records a refusal string and does NOT stop or clear the goal.
+ *
+ * Shape note: like complete_goal, this is a ToolDefinition + a separate executor
+ * returning a string. The loop-level short-circuit lives in turn-loop.ts and
+ * keys off CANCEL_GOAL_TOOL_NAME.
+ */
+import type { ToolDefinition } from "../../types.js";
+/** Shared with turn-loop.ts's short-circuit check — the name lives in one place. */
+export declare const CANCEL_GOAL_TOOL_NAME = "cancel_goal";
+export declare const cancelGoalToolDef: ToolDefinition;
+/**
+ * Executor. Returns a human-readable acknowledgement. The ACTUAL cancellation
+ * (stop + clear persisted goal) is enforced in turn-loop.ts, which re-checks
+ * confirm===true — this executor's string is only what lands in the transcript.
+ */
+export declare function cancelGoalTool(args: Record<string, unknown>): Promise<string>;

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

@@ -0,0 +1,64 @@
+/**
+ * cancel_goal — user-initiated goal ABANDONMENT (distinct from complete_goal).
+ *
+ * complete_goal = "the goal is fully achieved, stop." cancel_goal = "the user
+ * explicitly asked to STOP pursuing this goal even though it isn't done." Both
+ * short-circuit the turn loop to a stop and clear the persisted goal so a later
+ * bare send won't re-inherit it — but cancel_goal is a controlled escape hatch,
+ * NOT a self-judgment the model may make on its own.
+ *
+ * "Strong intent" guard (the whole point of this tool): the model must NOT
+ * cancel a goal on its own initiative — only when the user has clearly asked to
+ * stop/abandon it. To make that hard to do accidentally, the schema REQUIRES:
+ *   - confirm: true         — an explicit boolean gate (a bare call is invalid)
+ *   - reason: string        — the user's own words / paraphrase of the request
+ * The turn loop only honors the cancellation when confirm === true; anything
+ * else records a refusal string and does NOT stop or clear the goal.
+ *
+ * Shape note: like complete_goal, this is a ToolDefinition + a separate executor
+ * returning a string. The loop-level short-circuit lives in turn-loop.ts and
+ * keys off CANCEL_GOAL_TOOL_NAME.
+ */
+/** Shared with turn-loop.ts's short-circuit check — the name lives in one place. */
+export const CANCEL_GOAL_TOOL_NAME = "cancel_goal";
+export const cancelGoalToolDef = {
+    name: CANCEL_GOAL_TOOL_NAME,
+    description: "取消(放弃)当前的持久目标。⚠️ 仅当用户明确要求停止/取消/放弃当前目标时才调用本工具;" +
+        "绝不要自行判断放弃目标(“目标太难”“暂时做不完”都不是取消理由——那种情况应继续或用 complete_goal)。" +
+        "必须传 confirm=true 并在 reason 里复述用户要求取消的原话/意图。调用后目标会被清除,agent 停止。\n" +
+        "Cancel (abandon) the current persistent goal. ⚠️ Call this ONLY when the user has EXPLICITLY asked to " +
+        "stop/cancel/abandon the goal. NEVER decide to abandon a goal on your own (a hard or unfinished goal is " +
+        "NOT a reason to cancel). You MUST pass confirm=true and put the user's own words/intent in `reason`. " +
+        "After calling, the goal is cleared and the agent stops.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            confirm: {
+                type: "boolean",
+                description: "必须为 true 才会真正取消目标。缺省或 false 视为无效调用,不会取消。" +
+                    "Must be true to actually cancel. Missing/false is treated as an invalid call and cancels nothing.",
+            },
+            reason: {
+                type: "string",
+                description: "用户要求取消目标的原话或意图复述(必填)。Required: the user's own words / paraphrased request to cancel.",
+            },
+        },
+        required: ["confirm", "reason"],
+    },
+};
+/**
+ * Executor. Returns a human-readable acknowledgement. The ACTUAL cancellation
+ * (stop + clear persisted goal) is enforced in turn-loop.ts, which re-checks
+ * confirm===true — this executor's string is only what lands in the transcript.
+ */
+export async function cancelGoalTool(args) {
+    const confirmed = args.confirm === true;
+    const reason = typeof args.reason === "string" ? args.reason.trim() : "";
+    if (!confirmed) {
+        return ("cancel_goal 未生效:confirm 必须为 true 且需说明用户要求取消的原因。" +
+            "(cancel_goal ignored: confirm must be true and a reason is required.)");
+    }
+    return reason
+        ? `目标已按用户要求取消 (goal cancelled by user). Reason: ${reason}`
+        : "目标已按用户要求取消 (goal cancelled by user).";
+}

package/dist/tool-system/builtin/check-quota.d.ts

@@ -0,0 +1,15 @@
+/**
+ * CheckQuota builtin — thin shell over the `quota/` module.
+ *
+ * Lets an orchestrating agent read how much CC/Codex quota is left before/while
+ * delegating work (DriveAgent), so it can plan: how many to spawn, whether to
+ * wait for a reset, or switch providers. See quota/index.ts for the sources.
+ *
+ * NOTE the cost asymmetry (surfaced in the description): Codex is a free GET;
+ * Claude costs ~1 output token because Anthropic only returns quota via
+ * response headers. So restrict with `provider` when you only need one.
+ */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+export declare const checkQuotaToolDef: ToolDefinition;
+export declare function checkQuotaTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

package/dist/tool-system/builtin/check-quota.js

@@ -0,0 +1,34 @@
+import { checkQuota, formatQuota } from "../../quota/index.js";
+import { resolveQuotaCredentials } from "../../quota/credentials.js";
+export const checkQuotaToolDef = {
+    name: "CheckQuota",
+    description: "Check remaining usage/rate-limit quota for the external coding-agent CLIs (Claude Code and/or " +
+        "Codex) — the same 5h/7d subscription windows their status lines show. Use before or during " +
+        "orchestration (DriveAgent) to plan how much work to hand off, whether to wait for a reset, or " +
+        "which provider to use. Returns each provider's 5h/7d used-% and reset time. " +
+        "COST: 'codex' is free (reads a usage endpoint). 'claude' costs ~1 token (Anthropic exposes " +
+        "quota only via a response header, so this sends a 1-token probe). Pass `provider` to query " +
+        "just one and avoid the other's cost/latency.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            provider: {
+                type: "string",
+                enum: ["claude", "codex", "both"],
+                description: "Which to check. 'both' (default) queries Claude Code and Codex. 'claude' sends a 1-token probe; 'codex' is free.",
+            },
+        },
+        required: [],
+    },
+};
+export async function checkQuotaTool(args, ctx) {
+    const which = args.provider === "claude" ? ["claude"] : args.provider === "codex" ? ["codex"] : ["claude", "codex"];
+    const creds = await resolveQuotaCredentials();
+    const result = await checkQuota({
+        creds,
+        providers: which,
+        signal: ctx?.signal,
+    });
+    const nowSec = Math.floor(Date.now() / 1000);
+    return formatQuota(result, nowSec);
+}

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

@@ -59,6 +59,13 @@ export async function configTool(args) {
             obj = obj[parts[i]];
         }
         obj[parts[parts.length - 1]] = value;
+        // Never resurrect a deleted project root: a recursive mkdir of
+        // <cwd>/.code-shell would recreate `cwd` itself as an empty shell when the
+        // directory has been deleted (e.g. a stale session pointing at a removed
+        // dir). If the project root is gone, the project is gone — don't write.
+        if (!existsSync(cwd)) {
+            return `Error: project directory does not exist: ${cwd}`;
+        }
         mkdirSync(join(cwd, ".code-shell"), { recursive: true });
         writeFileSync(configPath, JSON.stringify(settings, null, 2), "utf-8");
         return `Updated ${key} = ${JSON.stringify(value)}`;

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

@@ -2,9 +2,16 @@
  * Cron tools — CronCreate, CronDelete, CronList.
  */
 import type { ToolDefinition } from "../../types.js";
+/** Sink notified after a cron job is created/deleted, so the host (Electron
+ *  main) can reload+arm the scheduler that actually executes jobs. The worker
+ *  process only persists cron jobs (executionEnabled=false); without this the
+ *  host never learns about an AI-created job until the user opens the UI. */
+type CronChangedSink = () => void;
+export declare function setCronChangedSink(sink: CronChangedSink | null): void;
 export declare const cronCreateToolDef: ToolDefinition;
 export declare function cronCreateTool(args: Record<string, unknown>): Promise<string>;
 export declare const cronDeleteToolDef: ToolDefinition;
 export declare function cronDeleteTool(args: Record<string, unknown>): Promise<string>;
 export declare const cronListToolDef: ToolDefinition;
 export declare function cronListTool(_args: Record<string, unknown>): Promise<string>;
+export {};