oakode 0.0.0-stage → 0.5.0

package/dist/tools.js

@@ -0,0 +1,480 @@
+/** read / write / edit / grep / ls / bash. All file tools are confined to the working directory. */
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { HeadTail, condenseOutput, keepEnds, stripEscapes } from "./output.js";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { MAX_BYTES, MAX_IMAGE_BYTES, MAX_LINES, ToolError, applyEdits, atomicWrite, encodeLike, globWorkspace, grepWorkspace, imageMime, listDir, optInt, readTextFile, realRel, rel, requireFile, safePath, truncate } from "./fileio.js";
+import { syntaxProblem } from "./syntax.js";
+import { killTreeOf, spawnShell, untrackChild } from "./proc.js";
+import { MAX_JOBS, allJobs, jobById, outputFile, report, saveOutput, startJob, stateOf } from "./jobs.js";
+export { MAX_BYTES, MAX_LINES, ToolError, safePath, truncate };
+/** Appended to a write/edit result when the file no longer parses. */
+async function syntaxNote(file, text, ctx) {
+    const problem = await syntaxProblem(file, text, ctx.cwd, ctx.signal);
+    return problem ? `\n[Syntax check: the file does not parse. Fix this before moving on:\n${problem}]` : "";
+}
+const MAX_READ_PATHS = 10;
+/** Several files in one call share this much output, so a batch costs about as much as two single reads. */
+const MULTI_READ_BYTES = 100 * 1024;
+/** macOS only (its built-in `sips`): a JPEG of at most 2048 px on the long side (1024 px if that is still too big), or undefined. */
+function shrinkImage(p) {
+    if (process.platform !== "darwin" || !existsSync("/usr/bin/sips"))
+        return undefined;
+    const out = join(tmpdir(), `oakode-img-${randomBytes(6).toString("hex")}.jpg`);
+    try {
+        let data;
+        for (const px of ["2048", "1024"]) {
+            const r = spawnSync("/usr/bin/sips", ["-Z", px, "-s", "format", "jpeg", "-s", "formatOptions", "75", p, "--out", out], { stdio: "ignore", timeout: 20_000 });
+            data = r.status === 0 && existsSync(out) ? readFileSync(out) : undefined;
+            if (!data || data.length <= MAX_IMAGE_BYTES)
+                break;
+        }
+        return data;
+    }
+    finally {
+        rmSync(out, { force: true });
+    }
+}
+function readOne(a, ctx, maxBytes = MAX_BYTES) {
+    const p = outputFile(a.path) ?? safePath(ctx.cwd, a.path); // the session's saved command output is readable too
+    if (!existsSync(p))
+        throw new ToolError(`No such file: ${a.path}`);
+    requireFile(p, a.path);
+    const mime = imageMime(p);
+    if (mime) {
+        const size = statSync(p).size;
+        const kb = `${Math.max(1, Math.round(size / 1024))} KB`;
+        if (!ctx.vision?.())
+            throw new ToolError(`${a.path} is an image (${mime}, ${kb}), but the current model cannot receive images, so it cannot be shown. Tell the user; they can choose a vision-capable model with /model. Do not try to approximate the image with scripts, conversions or character dumps.`);
+        if (!ctx.attach)
+            throw new ToolError("This session cannot deliver images to the model.");
+        const data = size <= MAX_IMAGE_BYTES ? readFileSync(p) : shrinkImage(p);
+        if (!data || data.length > MAX_IMAGE_BYTES)
+            throw new ToolError(`${a.path} is too large to send (${kb}; limit ${MAX_IMAGE_BYTES / 1024 / 1024} MB${process.platform === "darwin" ? ", even after scaling down" : ""}). Ask the user for a smaller image.`);
+        const shrunk = data.length !== size;
+        ctx.attach({ mime: shrunk ? "image/jpeg" : mime, data: data.toString("base64"), path: rel(ctx.cwd, p) });
+        return `Image ${rel(ctx.cwd, p)} (${mime}, ${kb}${shrunk ? `, scaled down to a ${Math.max(1, Math.round(data.length / 1024))} KB JPEG` : ""}) is attached to the next message.`;
+    }
+    const offset = optInt(a.offset, "offset");
+    const limit = optInt(a.limit, "limit");
+    const f = readTextFile(p, a.path);
+    const all = f.text.split("\n");
+    const start = offset ?? 1;
+    if (start > all.length)
+        throw new ToolError(`offset ${start} is past the end of the file (${all.length} lines)`);
+    const slice = all.slice(start - 1, limit ? start - 1 + limit : undefined);
+    const numbered = slice.map((l, i) => `${String(start + i).padStart(5)}\t${l}`).join("\n");
+    const { text, truncated } = truncate(numbered, "head", maxBytes);
+    const shown = text.split("\n").length;
+    const more = start - 1 + shown < all.length;
+    const meta = [f.eol === "\r\n" ? "CRLF line endings" : "", f.bom ? "UTF-8 BOM" : "", f.mixed ? "mixed line endings" : ""].filter(Boolean);
+    return (text +
+        (truncated || more ? `\n[showing lines ${start}-${start + shown - 1} of ${all.length}; use offset=${start + shown} to continue]` : "") +
+        (meta.length ? `\n[file has ${meta.join(" and ")}; write and edit preserve them]` : ""));
+}
+const read = {
+    readOnly: true,
+    def: {
+        type: "function",
+        function: {
+            name: "read",
+            description: `Read a text file (relative to the working directory), or several at once with \`paths\` (up to ${MAX_READ_PATHS}; read all the files you need in one call). Output is line-numbered and limited to ${MAX_LINES} lines / ${MAX_BYTES / 1024}KB per file (${MULTI_READ_BYTES / 1024}KB shared across \`paths\`); use offset/limit to page through large files. Also shows png/jpeg/gif/webp images (up to 1.5 MB; larger ones are scaled down on macOS) when the model supports images; otherwise it says so.`,
+            parameters: {
+                type: "object",
+                properties: {
+                    path: { type: "string" },
+                    paths: { type: "array", items: { type: "string" }, description: "Several files to read in one call (instead of path)" },
+                    offset: { type: "integer", description: "1-based first line (default 1); single path only" },
+                    limit: { type: "integer", description: "Max lines to return; single path only" },
+                },
+            },
+        },
+    },
+    summarize: (a) => (Array.isArray(a?.paths) ? `read ${a.paths.length > 3 ? `${a.paths.slice(0, 3).join(", ")} +${a.paths.length - 3}` : a.paths.join(", ")}` : `read ${a?.path ?? "?"}${a?.offset ? `:${a.offset}` : ""}`),
+    async run(a, ctx) {
+        if (a.paths === undefined) {
+            if (typeof a.path !== "string")
+                throw new ToolError("Pass `path` (one file) or `paths` (several).");
+            return readOne(a, ctx);
+        }
+        if (!Array.isArray(a.paths) || !a.paths.length || a.paths.some((x) => typeof x !== "string"))
+            throw new ToolError("`paths` must be a non-empty array of strings");
+        const paths = [...new Set(a.paths)];
+        if (typeof a.path === "string" && !paths.includes(a.path))
+            paths.unshift(a.path);
+        if (paths.length > MAX_READ_PATHS)
+            throw new ToolError(`At most ${MAX_READ_PATHS} paths per call (got ${paths.length}); split them.`);
+        if (paths.length === 1)
+            return readOne({ path: paths[0] }, ctx);
+        const each = Math.max(8 * 1024, Math.floor(MULTI_READ_BYTES / paths.length));
+        return paths
+            .map((p) => {
+            let body;
+            try {
+                body = readOne({ path: p }, ctx, each);
+            }
+            catch (e) {
+                body = `Error: ${e instanceof ToolError ? e.message : e.message}`;
+            }
+            return `==> ${p} <==\n${body}`;
+        })
+            .join("\n\n");
+    },
+};
+const glob = {
+    readOnly: true,
+    def: {
+        type: "function",
+        function: {
+            name: "glob",
+            description: "Find files by name pattern, e.g. **/*.test.ts, src/**/*.{js,jsx}, *config*. A pattern without / matches file names anywhere. In a git repository, files ignored by .gitignore are left out. Returns workspace-relative paths.",
+            parameters: {
+                type: "object",
+                properties: { pattern: { type: "string" }, path: { type: "string", description: "Directory to search (default: workspace root)" } },
+                required: ["pattern"],
+            },
+        },
+    },
+    summarize: (a) => `glob ${a?.pattern ?? "?"}${a?.path ? ` in ${a.path}` : ""}`,
+    run: (a, ctx) => globWorkspace(ctx.cwd, a, ctx.signal),
+};
+const write = {
+    def: {
+        type: "function",
+        function: {
+            name: "write",
+            description: "Create or overwrite a file with the given content (atomically). Parent directories are created. Prefer `edit` for changing existing files. Line endings and BOM of an existing file are preserved. " +
+                "For a file longer than ~200 lines, write the first part, then add each further part with `append: true` (one part per call). Always create and change files with write/edit, not bash.",
+            parameters: {
+                type: "object",
+                properties: { path: { type: "string" }, content: { type: "string" }, append: { type: "boolean", description: "Add `content` to the end of the file (creating it if missing) instead of replacing it" } },
+                required: ["path", "content"],
+            },
+        },
+    },
+    summarize: (a) => `write ${a?.path ?? "?"}${a?.append ? " (append)" : ""}`,
+    async run(a, ctx) {
+        const p = safePath(ctx.cwd, a.path);
+        if (typeof a.content !== "string")
+            throw new ToolError("`content` must be a string");
+        if (a.append !== undefined && typeof a.append !== "boolean")
+            throw new ToolError("`append` must be true or false");
+        const append = a.append === true;
+        const exists = existsSync(p);
+        if (exists)
+            requireFile(p, a.path);
+        const preview = a.content.split("\n").slice(0, 6).join("\n");
+        let orig;
+        if (exists) {
+            try {
+                orig = readTextFile(p, a.path);
+            }
+            catch (e) {
+                if (append)
+                    throw e;
+            } // appending to something unreadable would corrupt it
+        }
+        const relPath = rel(ctx.cwd, p);
+        const added = a.content.replace(/\r\n/g, "\n");
+        const proposed = append && orig ? orig.text + added : added;
+        const lines = a.content.split("\n").length;
+        const ok = await ctx.confirm({
+            title: append && exists ? `Append ${lines} lines to ${relPath}` : `${exists ? "Overwrite" : "Create"} ${relPath} (${lines} lines)`,
+            detail: preview,
+            note: exists && !append ? "replaces existing contents" : undefined,
+            action: { tool: "write", path: realRel(ctx.cwd, p) }, // decided on the real path: a symlink cannot launder a protected file
+            diff: { path: relPath, old: orig ? orig.text : exists ? "" : null, new: proposed },
+        });
+        if (!ok)
+            throw new ToolError("The user declined this write.");
+        safePath(ctx.cwd, a.path); // re-check: the tree may have changed while waiting for approval
+        const data = append && orig ? encodeLike(orig, proposed) : /\r/.test(a.content) ? a.content : encodeLike(orig, a.content);
+        mkdirSync(dirname(p), { recursive: true });
+        atomicWrite(p, data);
+        ctx.changed?.({ tool: "write", path: relPath, old: orig ? orig.text : exists ? "" : null, new: proposed });
+        return `${append && exists ? "Appended to" : exists ? "Overwrote" : "Created"} ${relPath} (${Buffer.byteLength(data)} bytes${append && exists ? `, ${lines} lines added` : ""})` + (await syntaxNote(p, proposed, ctx));
+    },
+};
+const edit = {
+    def: {
+        type: "function",
+        function: {
+            name: "edit",
+            description: "Replace exact text in an existing file. Pass one or more edits in `edits`; each `old_text` is located in the ORIGINAL file (not after other edits), must be unique unless replace_all is true, and edits must not overlap. " +
+                "Matching ignores trailing whitespace, line-ending style and smart quotes/dashes if there is no exact match. CRLF and BOM are preserved. Read the file first. Use this (not sed/python/heredocs in bash) to change existing files.",
+            parameters: {
+                type: "object",
+                properties: {
+                    path: { type: "string" },
+                    edits: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: { old_text: { type: "string" }, new_text: { type: "string" }, replace_all: { type: "boolean" } },
+                            required: ["old_text", "new_text"],
+                        },
+                    },
+                },
+                required: ["path", "edits"],
+            },
+        },
+    },
+    summarize: (a) => `edit ${a?.path ?? "?"}${Array.isArray(a?.edits) && a.edits.length > 1 ? ` (${a.edits.length} edits)` : ""}`,
+    async run(a, ctx) {
+        const p = safePath(ctx.cwd, a.path);
+        if (!existsSync(p))
+            throw new ToolError(`No such file: ${a.path} (use \`write\` to create it)`);
+        requireFile(p, a.path);
+        const edits = Array.isArray(a.edits) ? a.edits : typeof a.old_text === "string" ? [{ old_text: a.old_text, new_text: a.new_text, replace_all: a.replace_all }] : undefined;
+        if (!edits)
+            throw new ToolError("`edits` must be an array of {old_text, new_text}");
+        const file = readTextFile(p, a.path, { strict: true });
+        const r = applyEdits(file.text, edits); // throws a precise error before anything is shown or written
+        const shown = edits.slice(0, 6).flatMap((e, i) => [`${edits.length > 1 ? `#${i + 1} ` : ""}- ${String(e.old_text).split("\n")[0].slice(0, 100)}`, `${edits.length > 1 ? "   " : ""}+ ${String(e.new_text).split("\n")[0].slice(0, 100)}`]);
+        const ok = await ctx.confirm({
+            title: `Edit ${rel(ctx.cwd, p)} (${r.replacements} replacement${r.replacements > 1 ? "s" : ""})`,
+            detail: shown.join("\n") + (edits.length > 6 ? `\n… and ${edits.length - 6} more edits` : ""),
+            note: r.notes.length ? r.notes.join("; ") : undefined,
+            action: { tool: "edit", path: realRel(ctx.cwd, p) },
+            diff: { path: rel(ctx.cwd, p), old: file.text, new: r.text },
+        });
+        if (!ok)
+            throw new ToolError("The user declined this edit.");
+        safePath(ctx.cwd, a.path);
+        const again = readTextFile(p, a.path, { strict: true }); // the file may have changed while the prompt was open
+        if (again.text !== file.text)
+            throw new ToolError(`${a.path} changed while waiting for approval; nothing was written. Re-read it and retry.`);
+        atomicWrite(p, encodeLike(file, r.text));
+        ctx.changed?.({ tool: "edit", path: rel(ctx.cwd, p), old: file.text, new: r.text });
+        const note = await syntaxNote(p, r.text, ctx);
+        // where the new text now is, and for a small change the lines themselves: a next nearby edit needs no re-read
+        const where = r.spans.slice(0, 20).map((x) => (x.to > x.from ? `${x.from}-${x.to}` : `${x.from}`)).join(", ") + (r.spans.length > 20 ? `, and ${r.spans.length - 20} more places` : "");
+        const total = r.spans.reduce((n, x) => n + x.to - x.from + 1, 0);
+        const after = r.text.split("\n");
+        const size = r.spans.reduce((n, x) => n + after.slice(x.from - 1, x.to).join("\n").length, 0);
+        const lines = total <= 15 && size <= 3000 ? "\n" + r.spans.map((x) => after.slice(x.from - 1, x.to).map((l, k) => `${String(x.from + k).padStart(5)}\t${l}`).join("\n")).join("\n   …\n") : "";
+        return `Edited ${rel(ctx.cwd, p)}: ${r.replacements} replacement${r.replacements > 1 ? "s" : ""}, now at line${where.includes(",") || where.includes("-") ? "s" : ""} ${where}` + (r.notes.length ? ` (${r.notes.join("; ")})` : "") + (file.mixed ? " (line endings were mixed; normalized to " + (file.eol === "\r\n" ? "CRLF" : "LF") + ")" : "") + note + lines;
+    },
+};
+const grep = {
+    readOnly: true,
+    def: {
+        type: "function",
+        function: {
+            name: "grep",
+            description: "Search file contents in the workspace with a regular expression (or literal text). In a git repository, files ignored by .gitignore are skipped; also skips node_modules, binary and very large files; never follows symlinks. Returns path:line: text. Use `context` to see surrounding lines instead of reading whole files, and `files_only` to just find which files match.",
+            parameters: {
+                type: "object",
+                properties: {
+                    pattern: { type: "string", description: "JavaScript regular expression (or literal text if `literal` is true)" },
+                    path: { type: "string", description: "File or directory to search (default: workspace root)" },
+                    glob: { type: "string", description: "Only files matching this glob, e.g. **/*.ts or *.{js,ts}" },
+                    ignore_case: { type: "boolean" },
+                    literal: { type: "boolean" },
+                    context: { type: "integer", description: "Lines of context before and after each match (0-10, default 0)" },
+                    files_only: { type: "boolean", description: "List matching files with match counts instead of lines" },
+                    max_results: { type: "integer", description: "Default 100, max 500" },
+                },
+                required: ["pattern"],
+            },
+        },
+    },
+    summarize: (a) => `grep ${JSON.stringify(a?.pattern ?? "?")}${a?.path ? ` in ${a.path}` : ""}${a?.glob ? ` (${a.glob})` : ""}`,
+    run: (a, ctx) => {
+        const log = outputFile(a?.path); // a saved command or job log (from a shortened result)
+        return log ? grepWorkspace(dirname(log), { ...a, path: basename(log) }, ctx.signal) : grepWorkspace(ctx.cwd, a, ctx.signal);
+    },
+};
+const ls = {
+    readOnly: true,
+    def: {
+        type: "function",
+        function: {
+            name: "ls",
+            description: "List a directory in the workspace (directories first, file sizes, symlinks marked with @). depth 1-3 lists subdirectories too; .git and node_modules are not expanded.",
+            parameters: {
+                type: "object",
+                properties: { path: { type: "string", description: "Default: workspace root" }, depth: { type: "integer", description: "1-3, default 1" } },
+            },
+        },
+    },
+    summarize: (a) => `ls ${a?.path ?? "."}`,
+    async run(a, ctx) {
+        return listDir(ctx.cwd, a);
+    },
+};
+export { childEnv, killAllChildren, killTreeOf, trackChild, untrackChild } from "./proc.js";
+const bash = {
+    def: {
+        type: "function",
+        function: {
+            name: "bash",
+            description: `Run a shell command in the working directory and return combined stdout/stderr (escapes removed, repeated lines collapsed, long output shortened to its start and end; the full text is saved to a file that read and grep can open) and the exit code. Default timeout 120s. For servers, watchers and anything slower than the timeout, set background: true: it returns once \`until\` matches, the command ends, or after \`wait\` seconds, and you check it later with the job tool. Never run interactive commands. Not for creating or editing files: use write and edit, which show a diff and respect the permission mode. Keep output small (quiet flags, tail, grep).`,
+            parameters: {
+                type: "object",
+                properties: {
+                    command: { type: "string" },
+                    timeout: { type: "integer", description: "Seconds (1-600), default 120. Not for background commands" },
+                    background: { type: "boolean", description: `Run as a background job (at most ${MAX_JOBS}); stopped when OAKODE exits` },
+                    wait: { type: "integer", description: "Background: seconds to wait before returning (0-240, default 10)" },
+                    until: { type: "string", description: "Background: a regular expression; return as soon as the output matches, e.g. \"listening|ready|error\"" },
+                },
+                required: ["command"],
+            },
+        },
+    },
+    summarize: (a) => `$ ${String(a?.command ?? "?").split("\n")[0].slice(0, 120)}${a?.background === true ? " (background)" : ""}`,
+    async run(a, ctx) {
+        const cmd = a.command;
+        if (typeof cmd !== "string" || !cmd.trim())
+            throw new ToolError("`command` must be a non-empty string");
+        // models often pass milliseconds (120000): taken as such rather than refused, which costs a round trip
+        const t = a.timeout === undefined ? 120 : typeof a.timeout === "number" && a.timeout >= 1000 && a.timeout <= 600_000 ? Math.ceil(a.timeout / 1000) : a.timeout;
+        if (typeof t !== "number" || !Number.isFinite(t) || t < 1 || t > 600)
+            throw new ToolError("`timeout` must be 1-600 seconds");
+        if (a.background !== undefined && typeof a.background !== "boolean")
+            throw new ToolError("`background` must be true or false");
+        const wait = a.background ? waitArg(a.wait, 10) : 0;
+        const until = a.background ? untilArg(a.until) : undefined;
+        // Every command needs explicit approval. There is deliberately no command classifier.
+        const ok = await ctx.confirm({
+            title: "Run command",
+            detail: cmd,
+            note: "Approval only, not a sandbox: the command runs with your user's full permissions.",
+            action: { tool: "bash", command: cmd },
+        });
+        if (!ok)
+            throw new ToolError("The user declined to run this command.");
+        if (a.background) {
+            const j = startJob(cmd, ctx.cwd);
+            return report(j, await j.wait(wait * 1000, until, ctx.signal, ctx.onOutput));
+        }
+        return runShell(cmd, ctx, t * 1000);
+    },
+};
+/** A command the person typed themselves (`!npm test`): no approval, the same capture and shortening as bash. */
+export const runUserCommand = (cmd, cwd, signal, onOutput) => runShell(cmd, { cwd, signal, onOutput, confirm: async () => true }, 600_000);
+function runShell(cmd, ctx, timeoutMs) {
+    return new Promise((resolveP) => {
+        const child = spawnShell(cmd, ctx.cwd);
+        const captured = new HeadTail(1024 * 1024, 7 * 1024 * 1024); // bounded memory, and the start is never lost
+        let status = "";
+        let done = false;
+        const take = (b) => {
+            if (done)
+                return; // a background process still writing after the command returned: drained, not kept
+            captured.push(b);
+            ctx.onOutput?.(stripEscapes(b.toString()));
+        };
+        child.stdout.on("data", take);
+        child.stderr.on("data", take);
+        const kill = (why) => {
+            status = why;
+            killTreeOf(child, "SIGTERM");
+            setTimeout(() => killTreeOf(child, "SIGKILL"), 2000).unref();
+        };
+        const timer = setTimeout(() => kill(`timed out after ${timeoutMs / 1000}s`), timeoutMs);
+        const onAbort = () => kill("interrupted by user");
+        ctx.signal.addEventListener("abort", onAbort, { once: true });
+        if (ctx.signal.aborted)
+            onAbort();
+        const finish = (suffix, background = false) => {
+            if (done)
+                return;
+            done = true;
+            // with processes left running in the background, the child stays tracked so OAKODE stops them when it exits
+            if (!background)
+                untrackChild(child);
+            clearTimeout(timer);
+            clearTimeout(exitWait);
+            ctx.signal.removeEventListener("abort", onAbort);
+            const full = captured.text();
+            const c = condenseOutput(full);
+            const { text, truncated } = keepEnds(c.text, MAX_BYTES);
+            let note = "";
+            if (truncated || c.changed || captured.omitted) {
+                let f = "";
+                try {
+                    f = saveOutput(`bash-${randomBytes(4).toString("hex")}.log`, full);
+                }
+                catch { } // could not be saved: the result says only that it was shortened
+                note = `[output shortened (${truncated || captured.omitted ? "the middle was cut; the start and the end are kept" : "repeats collapsed / middle omitted"})${f ? `; ${captured.omitted ? "the start and end of the" : "full"} output saved to ${f}` : ""}]\n`;
+            }
+            const bg = background ? " [the command finished, but processes it started in the background are still running and holding its output; they are stopped when OAKODE exits]" : "";
+            resolveP(`${note}${text}${text && !text.endsWith("\n") ? "\n" : ""}${status ? `[${status}] ` : ""}${suffix}${bg}`);
+        };
+        // Return when the shell exits, not when its output pipes close: `server &` leaves a background process holding
+        // them, and waiting for that would hang until the timeout (and then kill the server). Normal commands close their
+        // pipes right after exiting, so the short grace only matters for those.
+        let exitWait;
+        child.on("exit", (code, sig) => {
+            exitWait = setTimeout(() => finish(`[exit code ${code ?? `signal ${sig}`}]`, true), 250);
+        });
+        child.on("error", (e) => finish(`[failed to start: ${e.message}]`));
+        child.on("close", (code, sig) => finish(`[exit code ${code ?? `signal ${sig}`}]`));
+    });
+}
+const waitArg = (v, dflt) => {
+    if (v === undefined)
+        return dflt;
+    if (typeof v !== "number" || !Number.isInteger(v) || v < 0 || v > 240)
+        throw new ToolError("`wait` must be 0-240 seconds");
+    return v;
+};
+const untilArg = (v) => {
+    if (v === undefined || v === "")
+        return undefined;
+    if (typeof v !== "string" || v.length > 500)
+        throw new ToolError("`until` must be a regular expression (at most 500 characters)");
+    // patterns that can backtrack for minutes on one line (nested quantifiers, backreferences) would stall OAKODE
+    if (/\([^()]*[+*}|][^()]*\)\s*[+*{]/.test(v) || /\\[1-9]|\\k</.test(v))
+        throw new ToolError("`until` must be a simple pattern: no repeated group that itself repeats or has alternatives, and no backreferences. Plain alternatives like \"ready|listening|error\" are fine.");
+    try {
+        return new RegExp(v, "m");
+    }
+    catch (e) {
+        throw new ToolError(`\`until\` is not a valid regular expression: ${e.message}`);
+    }
+};
+/** Checks on or stops background jobs. It starts nothing, so it asks nothing. */
+const job = {
+    def: {
+        type: "function",
+        function: {
+            name: "job",
+            description: `Check on or stop a command started with bash {background: true}. poll returns the job's output since the last poll; it waits up to \`wait\` seconds (default 30), returning early when the job ends or its output matches \`until\`. Waiting costs nothing, but each poll is a round trip: prefer one long wait with \`until\` over many short polls. interrupt sends Ctrl+C (SIGINT; on Windows it stops the job); kill stops the job and everything it started; list shows all jobs. Full logs are saved to files read and grep can open.`,
+            parameters: {
+                type: "object",
+                properties: {
+                    action: { type: "string", enum: ["poll", "interrupt", "kill", "list"] },
+                    id: { type: "integer", description: "The job id (not for list)" },
+                    wait: { type: "integer", description: "poll: seconds to wait (0-240, default 30)" },
+                    until: { type: "string", description: "poll: a regular expression to return on as soon as the output matches" },
+                },
+                required: ["action"],
+            },
+        },
+    },
+    summarize: (a) => (a?.action === "list" ? "job list" : `job ${a?.action ?? "?"} ${a?.id ?? "?"}${a?.until ? ` until /${String(a.until).slice(0, 40)}/` : ""}`),
+    async run(a, ctx) {
+        if (a?.action === "list") {
+            const all = allJobs();
+            return all.length ? all.map((j) => `${j.id}: ${stateOf(j)} · ${j.command.split("\n")[0].slice(0, 100)} · log ${j.log}`).join("\n") : "No background jobs.";
+        }
+        const j = jobById(a?.id);
+        if (!j)
+            throw new ToolError(`No job ${JSON.stringify(a?.id)}. ${allJobs().length ? `Jobs: ${allJobs().map((x) => x.id).join(", ")}.` : "There are no background jobs."}`);
+        if (a.action === "poll")
+            return report(j, await j.wait(waitArg(a.wait, 30) * 1000, untilArg(a.until), ctx.signal, ctx.onOutput));
+        if (a.action === "interrupt" || a.action === "kill") {
+            const was = j.alive;
+            await j.stop(a.action);
+            return report(j) + (was && j.alive ? `\n[it did not stop after ${a.action === "interrupt" ? "Ctrl+C; try kill" : "SIGKILL"}]` : "");
+        }
+        throw new ToolError("`action` must be poll, interrupt, kill or list");
+    },
+};
+export const TOOLS = [read, write, edit, grep, glob, ls, bash, job];
+export const toolByName = (name) => TOOLS.find((t) => t.def.function.name === name);