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

package/dist/runtime/safe-spawn.js

@@ -35,7 +35,7 @@
  */
 import { spawn } from "node:child_process";
 import { StringDecoder } from "node:string_decoder";
-import { resolveSpawnTarget, defaultShellBinary, killChildTree } from "./spawn-common.js";
+import { resolveSpawnTarget, defaultShellBinary, killChildTree, killProcessGroup } from "./spawn-common.js";
 export const DEFAULT_MAX_OUTPUT_BYTES = 1_000_000;
 export const DEFAULT_IO_DRAIN_GRACE_MS = 100;
 const TIMEOUT_SIGKILL_GRACE_MS = 2000;
@@ -50,6 +50,7 @@ export function safeSpawn(file, args, opts) {
         args,
         opts,
         cleanup: undefined,
+        resolveMs: undefined,
     });
 }
 /**
@@ -60,6 +61,7 @@ export function safeSpawn(file, args, opts) {
  * abort, timeout, pre-spawn-abort. Used by the Bash tool.
  */
 export function safeSpawnShell(command, opts) {
+    const resolveStartedAt = spawnProfileEnabled() ? performance.now() : 0;
     // Don't hardcode a POSIX default here — resolveSpawnTarget →
     // resolveShellInvocation picks the platform shell (cmd.exe on Windows,
     // $SHELL/bin/bash on POSIX) when opts.shell is omitted.
@@ -69,11 +71,24 @@ export function safeSpawnShell(command, opts) {
         shell,
         sandbox: opts.sandbox,
     });
-    return runLifecycle({ file, args, opts, cleanup });
+    // Shell commands run free-form LLM strings that routinely background
+    // grandchildren (`pytest &`, `sh → npm → node`). Spawn as a process-group
+    // leader (detached) so a timeout/abort kill reaches the WHOLE subtree, not
+    // just the direct shell — otherwise an orphaned grandchild keeps the
+    // inherited stdout pipe open and Node's `close` never fires (the hang).
+    return runLifecycle({
+        file,
+        args,
+        opts,
+        cleanup,
+        resolveMs: elapsedMs(resolveStartedAt),
+        detached: true,
+    });
 }
-function runLifecycle({ file, args, opts, cleanup }) {
+function runLifecycle({ file, args, opts, cleanup, resolveMs, detached }) {
     const maxBytes = opts.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
     const abortGrace = opts.ioDrainGraceMs ?? DEFAULT_IO_DRAIN_GRACE_MS;
+    const lifecycleStartedAt = spawnProfileEnabled() ? performance.now() : 0;
     // Pre-spawn abort: don't pay spawn cost.
     if (opts.signal?.aborted) {
         safeCleanup(cleanup);
@@ -81,10 +96,20 @@ function runLifecycle({ file, args, opts, cleanup }) {
     }
     return new Promise((resolve) => {
         let settled = false;
+        // Declared before finish() so the spawn-failed early-return (which calls
+        // finish before these are assigned) doesn't hit a TDZ reference.
+        let timer;
+        let settleTimer;
+        let onAbort;
         const finish = (result) => {
             if (settled)
                 return;
             settled = true;
+            if (timer)
+                clearTimeout(timer);
+            if (settleTimer)
+                clearTimeout(settleTimer);
+            logSpawnProfile(file, args, resolveMs, elapsedMs(lifecycleStartedAt), result.reason);
             // Always release backend-allocated resources, regardless of exit path.
             // cleanup is best-effort — see seatbelt backend for rationale.
             safeCleanup(cleanup);
@@ -97,7 +122,7 @@ function runLifecycle({ file, args, opts, cleanup }) {
         };
         let child;
         try {
-            child = spawn(file, args, { cwd: opts.cwd, env: opts.env });
+            child = spawn(file, args, { cwd: opts.cwd, env: opts.env, detached });
         }
         catch (err) {
             finish(emptyResult({ reason: "spawn_failed", spawnFailed: true, error: err.message }));
@@ -111,21 +136,63 @@ function runLifecycle({ file, args, opts, cleanup }) {
         let stderrTruncated = false;
         let timedOut = false;
         let aborted = false;
-        const timer = setTimeout(() => {
+        let lastExitCode = null;
+        let lastExitSignal = null;
+        // Terminate the child on timeout/abort. When detached (shell mode) the
+        // child leads its own process group, so kill the WHOLE group — this reaps
+        // backgrounded grandchildren (`pytest &`, `sh → npm → node`) that a bare
+        // child.kill() would orphan. After the kill, arm a settle deadline:
+        // Node's `close` waits for every inherited stdio pipe to close, and an
+        // orphaned grandchild can hold stdout open forever, so `close` may never
+        // fire. Force a resolve via the last-seen `exit` code once the kill grace
+        // has elapsed — the promise must never hang past terminate().
+        const terminate = (graceMs) => {
+            if (detached && typeof child.pid === "number") {
+                void killProcessGroup(child.pid, { graceMs });
+            }
+            else {
+                killChildTree(child, graceMs);
+            }
+            if (settleTimer)
+                return;
+            settleTimer = setTimeout(() => {
+                finishFromExit();
+            }, graceMs + 500);
+            settleTimer.unref?.();
+        };
+        timer = setTimeout(() => {
             timedOut = true;
-            // win32: taskkill /T reaps the whole tree (a foreground `npm test`
-            // spawns node children that child.kill() alone would orphan). POSIX:
-            // SIGTERM → grace → SIGKILL. See killChildTree.
-            killChildTree(child, TIMEOUT_SIGKILL_GRACE_MS);
+            terminate(TIMEOUT_SIGKILL_GRACE_MS);
         }, opts.timeoutMs);
-        let onAbort;
         if (opts.signal) {
             onAbort = () => {
                 aborted = true;
-                killChildTree(child, abortGrace);
+                terminate(abortGrace);
             };
             opts.signal.addEventListener("abort", onAbort, { once: true });
         }
+        // Fallback finish when `close` never arrives because a killed process's
+        // orphaned grandchild still holds a stdio pipe. Uses whatever `exit` code
+        // we saw (exit fires when the direct child dies, independent of stdio).
+        const finishFromExit = () => {
+            const reason = timedOut ? "timeout" : aborted ? "aborted" : "ok";
+            finish({
+                reason,
+                stdout,
+                stderr,
+                exitCode: lastExitCode,
+                signal: lastExitSignal,
+                stdoutTruncated,
+                stderrTruncated,
+                timedOut,
+                aborted,
+                spawnFailed: false,
+            });
+        };
+        child.on("exit", (code, sig) => {
+            lastExitCode = code;
+            lastExitSignal = sig;
+        });
         child.stdout?.on("data", (chunk) => {
             if (stdoutTruncated)
                 return;
@@ -221,6 +288,17 @@ function runLifecycle({ file, args, opts, cleanup }) {
         });
     });
 }
+function spawnProfileEnabled() {
+    return process.env.CODESHELL_SPAWN_PROFILE === "1";
+}
+function elapsedMs(startedAt) {
+    return startedAt > 0 ? Math.round(performance.now() - startedAt) : undefined;
+}
+function logSpawnProfile(file, args, resolveMs, lifecycleMs, reason) {
+    if (!spawnProfileEnabled())
+        return;
+    console.error(`[spawn-profile] shell=${JSON.stringify(file)} flag=${JSON.stringify(args[0] ?? "")} resolveMs=${resolveMs ?? "n/a"} lifecycleMs=${lifecycleMs ?? "n/a"} reason=${reason}`);
+}
 function safeCleanup(cleanup) {
     if (!cleanup)
         return;

package/dist/runtime/spawn-common.d.ts

@@ -72,9 +72,11 @@ export interface SpawnTarget {
  * in five places (bash.ts, safe-spawn.ts, background-shell.ts, worktree.ts):
  *
  *   - POSIX: `<explicit ?? $SHELL ?? /bin/bash> -c "<command>"`
- *   - Windows: `cmd.exe /c "<command>"` (the `-c` flag does not exist on cmd;
- *     a bare `-c` would be taken as a filename and fail). PowerShell uses
- *     `-Command`, but cmd.exe is the safe default present on every Windows.
+ *   - Windows: `<explicit shell ?? Git Bash ?? PowerShell ?? ComSpec ?? cmd.exe>` with the
+ *     shell-appropriate flag: Git Bash/POSIX shells use `-c`, PowerShell uses
+ *     `-Command`, and cmd.exe uses `/c` (`-c` would be taken as a filename and
+ *     fail/hang). Git Bash is preferred because the Bash tool receives POSIX
+ *     syntax from the model.
  *
  * `$SHELL` is ignored on Windows — it is virtually never set there, and when
  * it is (e.g. a stray value from a Unix-y env) it points at a POSIX path that
@@ -85,8 +87,17 @@ export declare function resolveShellInvocation(command: string, shell?: string):
     file: string;
     args: string[];
 };
+export declare function resolveGitBash(): string | undefined;
+/** Reset the Git Bash probe cache. Test-only (platform is stubbed per test). */
+export declare function _resetGitBashCache(): void;
+export declare function resolvePowerShell(): string | undefined;
+/** Reset the PowerShell probe cache. Test-only (platform is stubbed per test). */
+export declare function _resetPowerShellCache(): void;
 /** The platform's default interactive shell binary, for spawning a bare shell
- *  (no `-c`/`/c` command). Windows → ComSpec/cmd.exe; POSIX → $SHELL/bin/bash. */
+ *  (no `-c`/`/c` command). Windows → Git Bash if present, else PowerShell,
+ *  else ComSpec/cmd.exe;
+ *  POSIX → $SHELL/bin/bash. Windows prefers Git Bash so the model's bash-syntax
+ *  commands actually run (cmd.exe can't). */
 export declare function defaultShellBinary(shell?: string): string;
 /**
  * Resolve the actual (file, args) for a shell `command` under an optional

package/dist/runtime/spawn-common.js

@@ -20,7 +20,9 @@
  * spawn detached, so there's no separate process group to reap); it shares
  * (1) and (2) here. The background manager uses all three.
  */
-import { spawn } from "node:child_process";
+import { spawn, execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
 /**
  * Env vars that are always safe to forward into a sandboxed shell. Mirrors
  * the allowlist that previously lived in bash.ts — kept here so foreground
@@ -103,9 +105,11 @@ export function mergeShellEnv(base, projectEnv) {
  * in five places (bash.ts, safe-spawn.ts, background-shell.ts, worktree.ts):
  *
  *   - POSIX: `<explicit ?? $SHELL ?? /bin/bash> -c "<command>"`
- *   - Windows: `cmd.exe /c "<command>"` (the `-c` flag does not exist on cmd;
- *     a bare `-c` would be taken as a filename and fail). PowerShell uses
- *     `-Command`, but cmd.exe is the safe default present on every Windows.
+ *   - Windows: `<explicit shell ?? Git Bash ?? PowerShell ?? ComSpec ?? cmd.exe>` with the
+ *     shell-appropriate flag: Git Bash/POSIX shells use `-c`, PowerShell uses
+ *     `-Command`, and cmd.exe uses `/c` (`-c` would be taken as a filename and
+ *     fail/hang). Git Bash is preferred because the Bash tool receives POSIX
+ *     syntax from the model.
  *
  * `$SHELL` is ignored on Windows — it is virtually never set there, and when
  * it is (e.g. a stray value from a Unix-y env) it points at a POSIX path that
@@ -114,21 +118,116 @@ export function mergeShellEnv(base, projectEnv) {
  */
 export function resolveShellInvocation(command, shell) {
     if (process.platform === "win32") {
-        const file = shell ?? process.env.ComSpec ?? "cmd.exe";
-        // PowerShell variants take -Command; cmd.exe (and cmd-like) take /c.
+        const file = shell ?? defaultShellBinary();
+        // Flag form depends on the shell: PowerShell → -Command; a POSIX shell such
+        // as Git Bash's bash.exe / sh → -c (it does NOT understand cmd's /c); cmd.exe
+        // (and cmd-like) → /c. Detecting bash/sh matters now that defaultShellBinary
+        // prefers Git Bash on Windows — feeding it /c would break every command.
         const isPwsh = /(^|[\\/])(pwsh|powershell)(\.exe)?$/i.test(file);
-        return isPwsh ? { file, args: ["-Command", command] } : { file, args: ["/c", command] };
+        if (isPwsh)
+            return { file, args: ["-Command", command] };
+        const isPosixShell = /(^|[\\/])(bash|sh|zsh|dash)(\.exe)?$/i.test(file);
+        return { file, args: [isPosixShell ? "-c" : "/c", command] };
     }
     const file = shell ?? process.env.SHELL ?? "/bin/bash";
     return { file, args: ["-c", command] };
 }
+/**
+ * Best-effort locate Git Bash's `bash.exe` on Windows. Returns undefined on
+ * non-Windows, when git isn't installed, or when no bash.exe is found.
+ *
+ * WHY: The Bash tool and background shells feed the model's *bash* commands
+ * (`ls`, `&&`, `$(…)`, pipes, quoting) to the shell. On Windows the historical
+ * default is `cmd.exe`, which can't run any of that — so "Bash" was effectively
+ * broken on Windows. Git for Windows (which most devs already have — we detect
+ * it for repo ops anyway) ships a full bash at `<git>\bin\bash.exe`, so prefer
+ * it. Falls back to PowerShell before cmd.exe when Git Bash truly isn't present.
+ *
+ * Resolution order:
+ *   1. CODE_SHELL_GIT_BASH_PATH env override (explicit user config wins).
+ *   2. Reverse-engineer from the git binary's location: `where git` gives e.g.
+ *      `C:\Program Files\Git\cmd\git.exe` → `…\Git\bin\bash.exe`.
+ *   3. The two default install locations (Program Files / Program Files (x86)).
+ * Cached after first probe (a spawn per command would be wasteful).
+ */
+let gitBashCache;
+export function resolveGitBash() {
+    if (process.platform !== "win32")
+        return undefined;
+    if (gitBashCache !== undefined)
+        return gitBashCache ?? undefined;
+    const override = process.env.CODE_SHELL_GIT_BASH_PATH;
+    if (override && existsSync(override))
+        return (gitBashCache = override);
+    const candidates = [];
+    // (2) derive from `where git`. Git installs git.exe under either \cmd\ or
+    // \bin\; bash.exe lives under the sibling \bin\. Walk up to the Git root.
+    try {
+        const out = execFileSync("where", ["git"], { encoding: "utf-8", timeout: 3000 });
+        const gitExe = out.split(/\r?\n/).find((l) => l.trim().toLowerCase().endsWith("git.exe"));
+        if (gitExe) {
+            const gitRoot = dirname(dirname(gitExe.trim())); // …\Git\cmd\git.exe → …\Git
+            candidates.push(join(gitRoot, "bin", "bash.exe"));
+        }
+    }
+    catch {
+        // git not on PATH — fall through to the well-known locations.
+    }
+    // (3) default install locations.
+    const pf = process.env["ProgramFiles"] ?? "C:\\Program Files";
+    const pf86 = process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
+    candidates.push(join(pf, "Git", "bin", "bash.exe"));
+    candidates.push(join(pf86, "Git", "bin", "bash.exe"));
+    const found = candidates.find((p) => existsSync(p));
+    return (gitBashCache = found ?? null) ?? undefined;
+}
+/** Reset the Git Bash probe cache. Test-only (platform is stubbed per test). */
+export function _resetGitBashCache() {
+    gitBashCache = undefined;
+}
+let powerShellCache;
+export function resolvePowerShell() {
+    if (process.platform !== "win32")
+        return undefined;
+    if (powerShellCache !== undefined)
+        return powerShellCache ?? undefined;
+    const override = process.env.CODE_SHELL_POWERSHELL_PATH;
+    if (override && existsSync(override))
+        return (powerShellCache = override);
+    const candidates = [];
+    for (const exe of ["pwsh", "powershell"]) {
+        try {
+            const out = execFileSync("where", [exe], { encoding: "utf-8", timeout: 3000 });
+            const found = out.split(/\r?\n/).find((l) => l.trim().toLowerCase().endsWith(`${exe}.exe`));
+            if (found)
+                candidates.push(found.trim());
+        }
+        catch {
+            // Not on PATH; try the next shell / well-known locations.
+        }
+    }
+    const pf = process.env["ProgramFiles"] ?? "C:\\Program Files";
+    const systemRoot = process.env.SystemRoot ?? "C:\\Windows";
+    candidates.push(join(pf, "PowerShell", "7", "pwsh.exe"));
+    candidates.push(join(systemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe"));
+    const found = candidates.find((p) => existsSync(p));
+    return (powerShellCache = found ?? null) ?? undefined;
+}
+/** Reset the PowerShell probe cache. Test-only (platform is stubbed per test). */
+export function _resetPowerShellCache() {
+    powerShellCache = undefined;
+}
 /** The platform's default interactive shell binary, for spawning a bare shell
- *  (no `-c`/`/c` command). Windows → ComSpec/cmd.exe; POSIX → $SHELL/bin/bash. */
+ *  (no `-c`/`/c` command). Windows → Git Bash if present, else PowerShell,
+ *  else ComSpec/cmd.exe;
+ *  POSIX → $SHELL/bin/bash. Windows prefers Git Bash so the model's bash-syntax
+ *  commands actually run (cmd.exe can't). */
 export function defaultShellBinary(shell) {
     if (shell)
         return shell;
-    if (process.platform === "win32")
-        return process.env.ComSpec ?? "cmd.exe";
+    if (process.platform === "win32") {
+        return resolveGitBash() ?? resolvePowerShell() ?? process.env.ComSpec ?? "cmd.exe";
+    }
     return process.env.SHELL ?? "/bin/bash";
 }
 /**
@@ -143,8 +242,10 @@ export function resolveSpawnTarget(command, opts) {
         const wrapped = opts.sandbox.wrap(command, { cwd: opts.cwd, shell: opts.shell });
         return { file: wrapped.file, args: wrapped.args, cleanup: wrapped.cleanup };
     }
-    // No sandbox (the `off` backend / Windows): pick the shell + command-flag
-    // form for the platform instead of assuming POSIX `-c`.
+    // No sandbox configured: pick the shell + command-flag form for the
+    // platform instead of assuming POSIX `-c`. Note Bash always passes a
+    // backend (off at minimum), so it never reaches this line — the off
+    // backend's wrap() delegates to resolveShellInvocation itself.
     return resolveShellInvocation(command, opts.shell);
 }
 /**

package/dist/session/session-manager.js

@@ -7,6 +7,7 @@ import { homedir } from "node:os";
 import { nanoid } from "nanoid";
 import { Transcript } from "./transcript.js";
 import { SessionError } from "../exceptions.js";
+import { normalizeCumulativeUsageCounters } from "../engine/session-usage.js";
 /**
  * Validate a session ID before it is joined into a filesystem path.
  *
@@ -83,6 +84,9 @@ export class SessionManager {
             model,
             provider,
             tokenUsage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+            cumulativePromptTokens: 0,
+            cumulativeCacheReadTokens: 0,
+            cumulativeCacheCreationTokens: 0,
             turnCount: 0,
             invokedSkills: [],
             status: "active",
@@ -245,6 +249,7 @@ export class SessionManager {
         const transcriptFile = join(sessionDir, "transcript.jsonl");
         const transcript = Transcript.loadFromFile(transcriptFile);
         state.status = "active";
+        Object.assign(state, normalizeCumulativeUsageCounters(state, state.tokenUsage));
         return { state, transcript };
     }
     saveState(state) {
@@ -275,7 +280,8 @@ export class SessionManager {
         newBundle.state.parentSessionId = sourceSessionId;
         // Copy events up to the fork point
         for (const event of events) {
-            if (event.type === "turn_boundary" && (event.data.turnNumber ?? -1) > forkTurn) {
+            if (event.type === "turn_boundary" &&
+                (event.data.turnNumber ?? -1) > forkTurn) {
                 break;
             }
             newBundle.transcript.append(event.type, event.data);

package/dist/session/transcript.d.ts

@@ -22,7 +22,10 @@ export declare class Transcript {
      */
     appendMessage(role: string, content: string | ContentBlock[], opts?: {
         injected?: boolean;
+        steerId?: string;
+        clientMessageId?: string;
     }): TranscriptEvent;
+    hasClientMessageId(clientMessageId: string): boolean;
     appendToolUse(toolName: string, toolCallId: string, args: Record<string, unknown>): TranscriptEvent;
     appendToolResult(toolCallId: string, toolName: string, result?: string, error?: string): TranscriptEvent;
     /** Anchor for a spawned sub-agent (see TranscriptEventType "subagent").
@@ -52,6 +55,7 @@ export declare class Transcript {
     getEvents(type?: TranscriptEventType): TranscriptEvent[];
     get turnNumber(): number;
     get eventCount(): number;
+    private findMessageByClientId;
     private flush;
     /**
      * Repair tool_result pairing issues:

package/dist/session/transcript.js

@@ -5,6 +5,7 @@
 import { appendFileSync, readFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { nanoid } from "nanoid";
+import { logger } from "../logging/logger.js";
 export class Transcript {
     events = [];
     filePath;
@@ -40,12 +41,28 @@ export class Transcript {
      * step-gap steering messages are left unmarked so they render normally.
      */
     appendMessage(role, content, opts) {
+        if (opts?.clientMessageId) {
+            const existing = this.findMessageByClientId(opts.clientMessageId);
+            if (existing) {
+                logger.info("steer.submit.duplicate_ignored", {
+                    clientMessageId: opts.clientMessageId,
+                    role,
+                    transcript: this.filePath,
+                });
+                return existing;
+            }
+        }
         return this.append("message", {
             role,
             content,
             ...(opts?.injected ? { injected: true } : {}),
+            ...(opts?.steerId ? { steerId: opts.steerId } : {}),
+            ...(opts?.clientMessageId ? { clientMessageId: opts.clientMessageId } : {}),
         });
     }
+    hasClientMessageId(clientMessageId) {
+        return this.findMessageByClientId(clientMessageId) !== undefined;
+    }
     appendToolUse(toolName, toolCallId, args) {
         return this.append("tool_use", { toolName, toolCallId, args });
     }
@@ -150,6 +167,10 @@ export class Transcript {
     get eventCount() {
         return this.events.length;
     }
+    findMessageByClientId(clientMessageId) {
+        return this.events.find((event) => event.type === "message" &&
+            event.data.clientMessageId === clientMessageId);
+    }
     flush(event) {
         try {
             appendFileSync(this.filePath, JSON.stringify(event) + "\n", "utf-8");

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

@@ -29,8 +29,9 @@ function sandboxMark(backend) {
 export const bashToolDef = {
     name: "Bash",
     description: "Execute a shell command and return its output. " +
-        "Commands run in the user's default shell. Use for system operations, " +
-        "git commands, running tests, installing packages, etc.",
+        "Use for ordinary shell commands, system operations, git commands, " +
+        "package-manager commands, running tests, installing packages, etc. Prefer Bash " +
+        "over PowerShell unless the task needs PowerShell-specific syntax or APIs.",
     inputSchema: {
         type: "object",
         properties: {

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

@@ -27,7 +27,14 @@ export const cronCreateToolDef = {
         "'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.",
+        "Leave `permissionLevel` as 'read-only' unless the user explicitly wants the job to modify code.\n\n" +
+        "SELF-WAKEUP / background-task safety net: you can also schedule THIS job for yourself, with no user " +
+        "request, to re-check on a long-running background task (a download, a build, a background shell/agent) " +
+        "that might hang and never signal completion. Use a short interval + `once: true` + `continueInSession: true` " +
+        "and a `prompt` that reminds you what to check, e.g. schedule '5m', once true, continueInSession true, " +
+        "prompt 'check whether the yt-dlp download finished (BashOutput/ListShells); if still running, wait again'. " +
+        "You wake back in THIS conversation with full context, inspect the task, and either finish or reschedule. " +
+        "This is the right pattern for a simple poll-until-done loop or a hang safety net — prefer it over looping Sleep.",
     inputSchema: {
         type: "object",
         properties: {
@@ -52,7 +59,8 @@ export const cronCreateToolDef = {
             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`. " +
+                    "at <time>, do X once' reminders, tasks, or a self-wakeup to re-check a background task). " +
+                    "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.",
             },

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

@@ -10,11 +10,13 @@
 import { randomBytes } from "node:crypto";
 import { userCatalogPath } from "../../model-catalog/index.js";
 import { saveCatalogEntry } from "../../model-catalog/save-entry.js";
+import { catalogEntrySchema } from "../../model-catalog/types.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 " +
+        "appears in the connection page (text/image/video). Keyed by `id`: a new id " +
+        "adds a provider, an existing id replaces that user-catalog entry. 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 " +
@@ -31,7 +33,8 @@ export const editModelCatalogToolDef = {
                     "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).",
+                    "params per-model (only what that model supports). To keep a custom provider " +
+                    "beside a built-in one, use a distinct id.",
             },
         },
         required: ["entry"],
@@ -42,11 +45,18 @@ export async function editModelCatalogTool(args) {
     if (!entry || typeof entry !== "object") {
         return "Error: `entry` (a CatalogEntry object) is required.";
     }
+    const parsed = catalogEntrySchema.safeParse(entry);
+    if (!parsed.success) {
+        return `Error: invalid catalog entry: ${parsed.error.issues.map((i) => i.message).join("; ")}`;
+    }
     const stamp = `${Date.now()}-${randomBytes(3).toString("hex")}`;
-    const r = saveCatalogEntry(entry, { path: userCatalogPath(), stamp });
+    const r = saveCatalogEntry(parsed.data, {
+        path: userCatalogPath(),
+        stamp,
+    });
     if (!r.ok)
         return `Error: ${r.error}`;
-    return summarizeWrite(entry, r.action ?? "added", r.backup);
+    return summarizeWrite(parsed.data, r.action ?? "added", r.backup);
 }
 /**
  * Build a structured completion summary so the user can SEE exactly what was

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

@@ -86,6 +86,7 @@ export const generateVideoToolDef = {
 let injectedProvider = null;
 export function __setVideoProviderForTests(p) {
     injectedProvider = p;
+    availCache.clear();
 }
 /**
  * Tool-visibility guard: GenerateVideo is hidden until a video provider is
@@ -97,6 +98,8 @@ export function __setVideoProviderForTests(p) {
 const availCache = new Map();
 const AVAIL_TTL_MS = 1000;
 export function isGenerateVideoAvailable(cwd = process.cwd(), nowMs = Date.now()) {
+    if (injectedProvider)
+        return true;
     const hit = availCache.get(cwd);
     if (hit && nowMs - hit.at < AVAIL_TTL_MS)
         return hit.value;

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

@@ -3,5 +3,14 @@
  */
 import type { ToolDefinition } from "../../types.js";
 import type { ToolContext } from "../context.js";
+type ExecFileForGrep = (file: string, args: readonly string[], options: {
+    maxBuffer: number;
+    timeout: number;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare function _setGrepExecFileForTest(fn?: ExecFileForGrep): void;
 export declare const grepToolDef: ToolDefinition;
 export declare function grepTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+export {};