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

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

@@ -1,17 +1,70 @@
 /**
  * Cron tools — CronCreate, CronDelete, CronList.
  */
-import { cronScheduler } from "../../cron/scheduler.js";
+import { cronScheduler } from "../../automation/scheduler.js";
+import { getCurrentSid } from "../../logging/logger.js";
+let cronChangedSink = null;
+export function setCronChangedSink(sink) {
+    cronChangedSink = sink;
+}
+function fireCronChanged() {
+    try {
+        cronChangedSink?.();
+    }
+    catch {
+        // Notifying the host is best-effort; never break the tool on it.
+    }
+}
 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 the host system's timezone.",
+            },
+            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.",
+            },
+            once: {
+                type: "boolean",
+                description: "true = one-shot: run once at the scheduled time, then auto-delete (for 'in N minutes / " +
+                    "at <time>, do X once' reminders or tasks). Default false = recurring per `schedule`. " +
+                    "A one-shot still uses `schedule` for its time: interval '10m' = 10 minutes from now; " +
+                    "cron '0 7 25 6 *' = once at 07:00 on June 25.",
+            },
+            continueInSession: {
+                type: "boolean",
+                description: "true = when the job fires, CONTINUE THE CURRENT conversation: the prompt is appended as " +
+                    "a new user turn to THIS chat session (restored from disk if needed), carrying its full " +
+                    "transcript / goal / context. Set this when the user says things like '一小时后接着做 / " +
+                    "继续 / in this conversation'. Default false = a fresh standalone session per run (right " +
+                    "for independent recurring tasks like daily reports). The current session id is resolved " +
+                    "automatically — you do NOT supply it.",
+            },
         },
         required: ["name", "schedule", "prompt"],
     },
@@ -22,8 +75,48 @@ 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
+        : (() => {
+            try {
+                return Intl.DateTimeFormat().resolvedOptions().timeZone || undefined;
+            }
+            catch {
+                return undefined;
+            }
+        })();
+    const cwd = typeof args.cwd === "string" ? args.cwd : undefined;
+    const once = args.once === true;
+    const permissionLevel = args.permissionLevel === "read-only" ||
+        args.permissionLevel === "workspace-write" ||
+        args.permissionLevel === "full"
+        ? args.permissionLevel
+        : undefined;
+    // Resolve "continue this conversation" to the current session id at create
+    // time (the model never supplies it — getCurrentSid() reads the running
+    // Engine's ALS context). Empty/unknown sid → treat as standalone.
+    const resumeSessionId = args.continueInSession === true && getCurrentSid() ? getCurrentSid() : undefined;
+    let job;
+    try {
+        job = cronScheduler.create(name, schedule, prompt, {
+            ...(timezone !== undefined ? { timezone } : {}),
+            ...(cwd !== undefined ? { cwd } : {}),
+            ...(permissionLevel !== undefined ? { permissionLevel } : {}),
+            ...(once ? { once: true } : {}),
+            ...(resumeSessionId !== undefined ? { resumeSessionId } : {}),
+        });
+    }
+    catch (err) {
+        return `Error: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    fireCronChanged();
+    const tz = job.timezone ? ` (${job.timezone})` : "";
+    const next = job.nextRun ? new Date(job.nextRun).toLocaleString() : "n/a";
+    const cont = job.resumeSessionId ? "(到点续接当前对话,带上下文)" : "";
+    if (job.once) {
+        return `一次性任务 #${job.id} "${job.name}" 已创建${cont}。将于 ${next}${tz} 执行一次后自动删除。`;
+    }
+    return `Cron job #${job.id} "${job.name}" created${cont}. Schedule: ${job.schedule}${tz}. Next run: ${next}.`;
 }
 export const cronDeleteToolDef = {
     name: "CronDelete",
@@ -41,6 +134,8 @@ export async function cronDeleteTool(args) {
     if (!id)
         return "Error: jobId is required";
     const deleted = cronScheduler.delete(id);
+    if (deleted)
+        fireCronChanged();
     return deleted ? `Cron job #${id} deleted.` : `Cron job #${id} not found.`;
 }
 export const cronListToolDef = {
@@ -55,7 +150,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/drive-claude-code.d.ts

@@ -0,0 +1,30 @@
+import type { ToolDefinition } from "../../types.js";
+import type { AgentRunResult } from "../../cc-orchestrator/external-agent-driver.js";
+import type { ToolContext } from "../context.js";
+export type DriveCli = "claude" | "codex";
+export declare const driveAgentToolDef: ToolDefinition;
+type PermMode = "default" | "acceptEdits" | "bypassPermissions";
+type Runner = (opts: {
+    cli: DriveCli;
+    prompt: string;
+    resumeSessionId?: string;
+    cwd: string;
+    permissionMode?: PermMode;
+}) => Promise<AgentRunResult>;
+/** 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 declare function makeDriveAgentTool(runner?: Runner, fixedCli?: DriveCli): (args: Record<string, unknown>, ctx?: ToolContext) => Promise<string>;
+export declare const driveAgentTool: (args: Record<string, unknown>, ctx?: ToolContext) => Promise<string>;
+export declare const driveClaudeCodeToolDef: ToolDefinition;
+/** Back-compat factory: a DriveAgent pinned to cli:"claude" with the `cli` arg
+ *  hidden. The injected `runner` here keeps the old shape (no `cli` field); we
+ *  adapt it to the generic Runner so existing tests' fakes still work. */
+type LegacyRunner = (opts: {
+    prompt: string;
+    resumeSessionId?: string;
+    cwd: string;
+    permissionMode?: PermMode;
+}) => Promise<AgentRunResult>;
+export declare function makeDriveClaudeCodeTool(runner?: LegacyRunner): (args: Record<string, unknown>, ctx?: ToolContext) => Promise<string>;
+export declare const driveClaudeCodeTool: (args: Record<string, unknown>, ctx?: ToolContext) => Promise<string>;
+export {};

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

@@ -0,0 +1,157 @@
+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 { notificationQueue } from "./agent-notifications.js";
+const CLI_ADAPTERS = {
+    claude: { adapter: claudeAdapter, command: "claude" },
+    codex: { adapter: codexAdapter, command: "codex" },
+};
+export const driveAgentToolDef = {
+    name: "DriveAgent",
+    description: "Delegate a task to an external coding-agent CLI — drives `claude` (Claude Code) or `codex` " +
+        "(OpenAI Codex) for one turn. Pick with `cli` (defaults to claude). Use to hand a coding/" +
+        "research task to the agent, or continue an existing session of it. " +
+        "Runs in the BACKGROUND by default — these tasks are typically long (minutes to hours), so this " +
+        "returns immediately and the result is delivered to you later via a completion notification " +
+        "that wakes you. Do NOT sleep-poll for it; just continue or end your turn — you'll be woken " +
+        "with the result. For a quick task where you want the answer inline, pass background:false. " +
+        "It has NO time concept of its own: for 'in N minutes' / 'every N' / looping, use CronCreate " +
+        "instead (never sleep). A scheduled CronCreate job runs one codeshell turn whose prompt can " +
+        "instruct it to call DriveAgent; to continue a prior session across runs, have that turn pass " +
+        "the sessionId this tool returned as resumeSessionId (same cli). To make the single turn work " +
+        "longer/deeper, write that into `prompt` (e.g. 'keep working until done'). " +
+        "Pass `resumeSessionId` to continue a prior session of the SAME cli (keeps context); omit to start fresh.\n" +
+        "SCOPE & BUDGET (read before fanning out): each driven agent consumes a large, SHARED token budget. " +
+        "Do NOT launch many agents at once to 'cover more ground' — that burns the budget and leaves every " +
+        "task half-done. Default to ONE agent at a time; only run a few in parallel when the work TRULY splits " +
+        "into independent pieces, and even then keep the count small (≈2-3). Prefer finishing one task before " +
+        "starting the next. " +
+        "Make each `prompt` a COMPLETE, self-contained task that instructs the agent to finish the whole thing " +
+        "end-to-end and verify its own work before returning — never a vague 'start looking into X'. " +
+        "Give it a concrete definition of done and, for open-ended work, a bound (files/scope/steps) so it " +
+        "doesn't sprawl. If a big job must be split, split it into a SEQUENCE you drive one at a time (resume " +
+        "the same session), not a swarm launched simultaneously.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            prompt: { type: "string", description: "The task for the agent. Make it COMPLETE and self-contained: state the goal, a concrete definition of done, and (for open-ended work) an explicit scope bound so it finishes end-to-end and verifies its own work rather than sprawling or stopping half-way." },
+            cli: { type: "string", enum: ["claude", "codex"], description: "Which external CLI to drive. 'claude' = Claude Code (default), 'codex' = OpenAI Codex. resumeSessionId is only valid against the same cli that produced it." },
+            resumeSessionId: { type: "string", description: "Existing session id to resume (keeps context). Must come from a prior run of the SAME cli. Omit for a fresh session." },
+            cwd: { type: "string", description: "Working directory the run operates in." },
+            permissionMode: { type: "string", enum: ["default", "acceptEdits", "bypassPermissions"], description: "Permission/sandbox level. Defaults to 'bypassPermissions' (full auto — needed so the agent's tools run unattended; there is no interactive approval loop here). For codex: default→read-only sandbox, acceptEdits→workspace-write, bypassPermissions→no sandbox. Pass 'default'/'acceptEdits' to gate." },
+            background: { type: "boolean", description: "Defaults to TRUE: run in the background and notify you on completion (right for long tasks). Pass false to run in the foreground and get the result inline (only for quick tasks)." },
+        },
+        required: ["prompt", "cwd"],
+    },
+};
+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" });
+};
+/** 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) {
+    return async (args, ctx) => {
+        const prompt = typeof args.prompt === "string" ? args.prompt : "";
+        const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
+        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;
+        // 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
+        // approval (WebSearch/WebFetch/Write) silently can't run (the
+        // "DriveClaudeCode 没有联网能力" report). A caller that wants gating passes
+        // an explicit mode, which is honored. (For codex, the mode maps to a sandbox
+        // tier inside codexAdapter.)
+        const permissionMode = args.permissionMode === "default" ||
+            args.permissionMode === "acceptEdits" ||
+            args.permissionMode === "bypassPermissions"
+            ? args.permissionMode
+            : "bypassPermissions";
+        const cliName = cli === "codex" ? "Codex" : "Claude Code";
+        const label = `DriveAgent(${cli}): ${prompt.slice(0, 40)}`;
+        // 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;
+        if (background) {
+            // Fail loud on a missing sessionId: a background job whose completion
+            // notification can't be routed (enqueue drops invalid/empty sessionId)
+            // would run to completion and then silently vanish — nobody gets woken
+            // with the result. Refuse up front instead of launching disappearing work.
+            const sessionId = ctx?.sessionId;
+            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 });
+            });
+            return `已在后台启动 ${cliName}（jobId ${jobId}）。完成后会通知你结果，无需轮询。`;
+        }
+        const r = await runner({ cli, prompt, resumeSessionId, cwd, permissionMode });
+        if (r.isError)
+            return `${cliName} 运行出错（session ${r.sessionId}）：\n${r.finalText}`;
+        return `${cliName} 完成（session ${r.sessionId}）：\n${r.finalText}`;
+    };
+}
+export const driveAgentTool = makeDriveAgentTool();
+// ── Back-compat: DriveClaudeCode = DriveAgent pinned to cli:"claude" ──────────
+// Kept so old prompts / memories / call sites that reference DriveClaudeCode
+// keep working. It's a thin alias over the same machinery (fixedCli "claude").
+export const driveClaudeCodeToolDef = {
+    ...driveAgentToolDef,
+    name: "DriveClaudeCode",
+    description: "(Alias of DriveAgent with cli:claude.) Delegate a task to the external Claude Code CLI " +
+        "(drives `claude` for one turn). Prefer DriveAgent for new calls; this name is kept for " +
+        "compatibility. " + driveAgentToolDef.description,
+    inputSchema: {
+        type: "object",
+        properties: {
+            // intentionally omit `cli` — this alias is always claude
+            prompt: driveAgentToolDef.inputSchema.properties.prompt,
+            resumeSessionId: { type: "string", description: "Existing CC session id to resume (keeps context). Omit for a fresh session." },
+            cwd: driveAgentToolDef.inputSchema.properties.cwd,
+            permissionMode: driveAgentToolDef.inputSchema.properties.permissionMode,
+            background: driveAgentToolDef.inputSchema.properties.background,
+        },
+        required: ["prompt", "cwd"],
+    },
+};
+export function makeDriveClaudeCodeTool(runner) {
+    const generic = runner
+        ? ({ prompt, resumeSessionId, cwd, permissionMode }) => runner({ prompt, resumeSessionId, cwd, permissionMode })
+        : undefined;
+    return makeDriveAgentTool(generic ?? defaultRunner, "claude");
+}
+export const driveClaudeCodeTool = makeDriveClaudeCodeTool();

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

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from "../../types.js";
+export declare const editModelCatalogToolDef: ToolDefinition;
+export declare function editModelCatalogTool(args: Record<string, unknown>): Promise<string>;

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

@@ -0,0 +1,94 @@
+/**
+ * EditModelCatalog tool — add or update a provider/model template in the user
+ * model catalog (~/.code-shell/model-catalog.user.json). Pairs with the
+ * model-fact-finder skill: the skill researches a model's facts (modalities,
+ * params, context), then this tool writes them into a CatalogEntry so the
+ * connection page picks it up. Backs up before writing; validates against the
+ * schema; never touches API keys/credentials (those go through the user's own
+ * Edit, by design). See docs/.../2026-06-15-unified-model-catalog-design.md §7.
+ */
+import { randomBytes } from "node:crypto";
+import { userCatalogPath } from "../../model-catalog/index.js";
+import { saveCatalogEntry } from "../../model-catalog/save-entry.js";
+export const editModelCatalogToolDef = {
+    name: "EditModelCatalog",
+    description: "Add or update a provider/model template in the user model catalog so it " +
+        "appears in the connection page (text/image/video). Keyed by `id` — a new id " +
+        "adds, an existing id updates (in place). Backs up the file before writing and " +
+        "validates the entry. Use after researching a model's real facts (id, context " +
+        "window, supported params, modalities) — do NOT guess; verify against the " +
+        "provider's official docs first (see the model-fact-finder skill). Does NOT set " +
+        "API keys: the user enters keys in the connection page (credentials), not here.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            entry: {
+                type: "object",
+                description: "A full CatalogEntry. Required: id, tag (text|image|video), adapterKind " +
+                    "(an already-wired adapter: openai|anthropic|google|fal), displayName, " +
+                    "description, defaultBaseUrl. Optional: protocol (openai-compat|anthropic-style), " +
+                    "defaultModel, needsKey, signupUrl, test, modelPresets[] (each {value, label?, " +
+                    "maxContextTokens?, maxOutputTokens?, supportsVision?, params?[]}). Each param: " +
+                    "{name, label?, control (enum|number|toggle|text), options?[], min?, max?, default?, " +
+                    "doc?, wire?{field}}. Fill maxContextTokens with the model's REAL window; declare " +
+                    "params per-model (only what that model supports).",
+            },
+        },
+        required: ["entry"],
+    },
+};
+export async function editModelCatalogTool(args) {
+    const entry = args.entry;
+    if (!entry || typeof entry !== "object") {
+        return "Error: `entry` (a CatalogEntry object) is required.";
+    }
+    const stamp = `${Date.now()}-${randomBytes(3).toString("hex")}`;
+    const r = saveCatalogEntry(entry, { path: userCatalogPath(), stamp });
+    if (!r.ok)
+        return `Error: ${r.error}`;
+    return summarizeWrite(entry, r.action ?? "added", r.backup);
+}
+/**
+ * Build a structured completion summary so the user can SEE exactly what was
+ * written and catch a wrong value at a glance — every param's options/default
+ * is echoed back, because that's where catalog entries go wrong (e.g. listing a
+ * gateway's input aliases as if they were the model's native effort levels).
+ * The LLM is told to relay this and ask the user to verify against the docs.
+ */
+function summarizeWrite(entry, action, backup) {
+    const id = entry.id ?? "(unknown)";
+    const lines = [];
+    lines.push(`✅ ${action === "updated" ? "Updated" : "Added"} catalog entry "${id}".`);
+    lines.push(`tag: ${entry.tag ?? "?"} | adapter: ${entry.adapterKind ?? "?"}` +
+        (entry.defaultModel ? ` | defaultModel: ${entry.defaultModel}` : "") +
+        (entry.defaultBaseUrl ? ` | baseUrl: ${entry.defaultBaseUrl}` : ""));
+    const presets = entry.modelPresets ?? [];
+    if (presets.length === 0) {
+        lines.push("(no modelPresets)");
+    }
+    for (const p of presets) {
+        const ctx = p.maxContextTokens ? `ctx ${p.maxContextTokens}` : "";
+        const out = p.maxOutputTokens ? `out ${p.maxOutputTokens}` : "";
+        const limits = [ctx, out].filter(Boolean).join(", ");
+        lines.push(`\nmodel: ${p.value ?? "?"}${p.label ? ` (${p.label})` : ""}${limits ? ` — ${limits}` : ""}`);
+        const params = p.params ?? [];
+        if (params.length === 0) {
+            lines.push("  (no params declared)");
+        }
+        for (const pa of params) {
+            let detail = "";
+            if (pa.control === "enum")
+                detail = `options=[${(pa.options ?? []).join(", ")}]`;
+            else if (pa.control === "number")
+                detail = `range ${pa.min ?? "?"}..${pa.max ?? "?"}`;
+            const def = pa.default !== undefined ? ` default=${JSON.stringify(pa.default)}` : "";
+            lines.push(`  - ${pa.name ?? "?"} (${pa.control ?? "?"}) ${detail}${def}`.trimEnd());
+        }
+    }
+    lines.push(`\nWritten to ${userCatalogPath()}.` + (backup ? ` Backup: ${backup}.` : ""));
+    lines.push("Hot-reloads — the connection page refreshes once this turn completes.");
+    lines.push("⚠️ Relay this summary to the user and ask them to verify each param's options/default " +
+        "match the provider's OFFICIAL docs — especially enum levels (a gateway's input aliases " +
+        "are NOT the model's native values). To fix: edit this file directly, or ask me to.");
+    return 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 { detectEol, toLf, applyEol } from "./eol.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;
@@ -46,28 +47,36 @@ export async function editTool(args) {
     if (!existsSync(filePath))
         return `Error: File not found: ${filePath}`;
     try {
-        const content = await readFile(filePath, "utf-8");
-        if (!content.includes(oldString)) {
+        const raw = await readFile(filePath, "utf-8");
+        // CRLF handling: detect the file's line ending, then match/replace in LF
+        // space (the model emits LF, so a CRLF file would never match otherwise),
+        // and write back in the ORIGINAL EOL so a CRLF file stays CRLF (no whole-
+        // file diff churn). See eol.ts.
+        const eol = detectEol(raw);
+        const content = toLf(raw);
+        const oldLf = toLf(oldString);
+        const newLf = toLf(newString);
+        if (!content.includes(oldLf)) {
             return "Error: old_string not found in file";
         }
         if (!replaceAll) {
-            const firstIdx = content.indexOf(oldString);
-            const lastIdx = content.lastIndexOf(oldString);
+            const firstIdx = content.indexOf(oldLf);
+            const lastIdx = content.lastIndexOf(oldLf);
             if (firstIdx !== lastIdx) {
                 return "Error: old_string is not unique in the file. Provide more context or use replace_all.";
             }
         }
-        const updated = replaceAll
-            ? content.split(oldString).join(newString)
-            : content.replace(oldString, newString);
-        await writeFile(filePath, updated, "utf-8");
+        const updatedLf = replaceAll
+            ? content.split(oldLf).join(newLf)
+            : content.replace(oldLf, newLf);
+        await writeFile(filePath, applyEol(updatedLf, eol), "utf-8");
         fileCache.invalidate(filePath);
         const count = replaceAll
-            ? (content.split(oldString).length - 1)
+            ? (content.split(oldLf).length - 1)
             : 1;
         // Generate a compact diff summary
-        const oldLines = oldString.split("\n");
-        const newLines = newString.split("\n");
+        const oldLines = oldLf.split("\n");
+        const newLines = newLf.split("\n");
         const diffSummary = generateCompactDiff(oldLines, newLines, filePath);
         return `Successfully edited ${filePath} (${count} replacement${count > 1 ? "s" : ""})\n${diffSummary}`;
     }

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

@@ -0,0 +1,29 @@
+/**
+ * EOL (line-ending) helpers for file-editing tools.
+ *
+ * Windows files are typically CRLF (`\r\n`); the model emits LF (`\n`). The
+ * file tools match the model's strings against file content and write the
+ * result back. Without normalization:
+ *   - an LF `old_string` never matches a CRLF file → "old_string not found";
+ *   - a successful write that re-joins with LF silently converts a CRLF file
+ *     to LF, so `git diff` shows the whole file changed (and an .editorconfig
+ *     /prettier may flip it right back → churn).
+ *
+ * The contract these helpers enforce:
+ *   1. Detect the file's dominant EOL.
+ *   2. Compare/replace in LF space (normalize both file content and the
+ *      model's needle to LF first).
+ *   3. Write back in the ORIGINAL EOL so the file's line-ending style is
+ *      preserved.
+ */
+export type Eol = "\r\n" | "\n";
+/**
+ * The file's dominant line ending. CRLF if the content contains ANY `\r\n`
+ * (Windows editors are all-or-nothing in practice); otherwise LF. Empty/no-
+ * newline content defaults to LF.
+ */
+export declare function detectEol(content: string): Eol;
+/** Collapse all CRLF (and lone CR) to LF for comparison/replacement. */
+export declare function toLf(s: string): string;
+/** Re-apply an EOL to LF-normalized text. No-op for LF. */
+export declare function applyEol(s: string, eol: Eol): string;

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

@@ -0,0 +1,37 @@
+/**
+ * EOL (line-ending) helpers for file-editing tools.
+ *
+ * Windows files are typically CRLF (`\r\n`); the model emits LF (`\n`). The
+ * file tools match the model's strings against file content and write the
+ * result back. Without normalization:
+ *   - an LF `old_string` never matches a CRLF file → "old_string not found";
+ *   - a successful write that re-joins with LF silently converts a CRLF file
+ *     to LF, so `git diff` shows the whole file changed (and an .editorconfig
+ *     /prettier may flip it right back → churn).
+ *
+ * The contract these helpers enforce:
+ *   1. Detect the file's dominant EOL.
+ *   2. Compare/replace in LF space (normalize both file content and the
+ *      model's needle to LF first).
+ *   3. Write back in the ORIGINAL EOL so the file's line-ending style is
+ *      preserved.
+ */
+/**
+ * The file's dominant line ending. CRLF if the content contains ANY `\r\n`
+ * (Windows editors are all-or-nothing in practice); otherwise LF. Empty/no-
+ * newline content defaults to LF.
+ */
+export function detectEol(content) {
+    return content.includes("\r\n") ? "\r\n" : "\n";
+}
+/** Collapse all CRLF (and lone CR) to LF for comparison/replacement. */
+export function toLf(s) {
+    return s.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+/** Re-apply an EOL to LF-normalized text. No-op for LF. */
+export function applyEol(s, eol) {
+    if (eol === "\n")
+        return s;
+    // s is already LF-normalized by callers; map every LF back to CRLF.
+    return s.replace(/\n/g, "\r\n");
+}

package/dist/tool-system/builtin/file-cache.d.ts

@@ -5,6 +5,12 @@ declare class FileStateCache {
     /** Invalidate a specific path (after Write/Edit). */
     invalidate(filePath: string): void;
     clear(): void;
+    /**
+     * True if a cache entry for `filePath` is currently held. Pure key-presence
+     * check — does NOT stat/self-heal like `get()`, so a test can assert a manual
+     * `invalidate()` actually removed the key without the mtime path masking it.
+     */
+    has(filePath: string): boolean;
     get size(): number;
 }
 export declare const fileCache: FileStateCache;

package/dist/tool-system/builtin/file-cache.js

@@ -32,6 +32,14 @@ class FileStateCache {
     clear() {
         this.cache.clear();
     }
+    /**
+     * True if a cache entry for `filePath` is currently held. Pure key-presence
+     * check — does NOT stat/self-heal like `get()`, so a test can assert a manual
+     * `invalidate()` actually removed the key without the mtime path masking it.
+     */
+    has(filePath) {
+        return this.cache.has(filePath);
+    }
     get size() {
         return this.cache.size;
     }