@dynamicagents/plugins 0.11.1 → 0.13.0

package/dist/computer/render.js

@@ -1,3 +1,4 @@
+import { truncateOutput } from "../workspace/format.js";
 /**
  * Turning a result into the text a model reads.
  *
@@ -15,43 +16,9 @@
  * A grep match carries the whole line, and a minified bundle is one line of
  * megabytes — a single match in `dist/` would otherwise be the entire result. The
  * head is kept because a match's file and line number are what the model acts on;
- * it reads the region with `sb_read` next.
+ * it reads the region with `read` next.
  */
 const MAX_MATCH_LINE_CHARS = 200;
-/**
- * Middle-out truncation, so both the first error and the final summary survive.
- *
- * The guard is not defensive padding. Without it a `max` at or below the marker's
- * own length makes `half` zero or negative, and `slice(-0)` is `slice(0)` — the
- * *whole* string — so the function returns more than it was given: 500 characters
- * in, 543 out at `max: 80`. A silent inversion of the one thing it does,
- * reachable from a public config field.
- */
-export function truncateOutput(text, max) {
-    if (text.length <= max)
-        return text;
-    const marker = (dropped) => `\n\n… [${dropped} characters omitted from the middle] …\n\n`;
-    // No budget for two halves plus the marker: keep the head, which is where the
-    // first error is, and say nothing clever.
-    const half = Math.floor((max - marker(text.length).length) / 2);
-    if (half < 1)
-        return text.slice(0, Math.max(0, max));
-    return (text.slice(0, half) + marker(text.length - half * 2) + text.slice(-half));
-}
-/**
- * A byte count in the form a model can act on.
- *
- * A listing that says a file is 4.2 MB tells the model the read it is about to do
- * comes back with a hole in the middle — the one thing it cannot infer from the
- * truncated result itself.
- */
-export function humanBytes(bytes) {
-    if (bytes < 1024)
-        return `${bytes} B`;
-    if (bytes < 1024 * 1024)
-        return `${(bytes / 1024).toFixed(1)} KB`;
-    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-}
 /** One matching line, bounded — see {@link MAX_MATCH_LINE_CHARS}. */
 function capLine(text) {
     // A CRLF file leaves the carriage return on every line, since the reader splits
@@ -135,13 +102,6 @@ export function renderGrepMatches(matches, maxChars) {
     // Only a line that actually made it out is worth explaining.
     return { body, shown, capped: hasLongLine.slice(0, shown).includes(true) };
 }
-/** Elapsed time in the shape a sentence wants. */
-export function humanMs(ms) {
-    const s = Math.round(ms / 1000);
-    return s < 60
-        ? `${s}s`
-        : `${Math.floor(s / 60)}m${String(s % 60).padStart(2, "0")}s`;
-}
 /**
  * Render a completed command the way a terminal would, minus the noise.
  *
@@ -177,31 +137,38 @@ export function renderResult(result, maxChars) {
     const body = truncateOutput(parts.join("\n"), maxChars);
     const state = result.status && result.status !== "completed" ? ` (${result.status})` : "";
     const verdict = `--- exit ${result.exitCode}${state} ---`;
-    return body ? `${body}\n${verdict}` : `(no output)\n${verdict}`;
+    const pending = syncPendingNote(result.sync);
+    const transcript = body ? `${body}\n${verdict}` : `(no output)\n${verdict}`;
+    return pending ? `${transcript}\n${pending}` : transcript;
 }
 /**
- * Why a command has nothing to show for itself.
- *
- * {@link renderResult} states a non-`completed` status on its verdict line;
- * {@link computerExec} has no verdict line, only the four fields its caller
- * branches on. A *killed* process writes nothing, so without this a `git clone`
- * that hit the ten-minute ceiling reaches the model through
- * `@dynamicagents/plugins/repo` as `clone failed:` with an empty reason — which reads
- * like a bug in the plugin rather than a limit it can work within.
- *
- * Only `cancelled`. A `failed` status is an ordinary non-zero exit, where the
- * command's own stderr is the better explanation and this would be noise on top
- * of it.
- *
- * Both plausible causes are named because the exit code cannot separate them:
- * 137 is SIGKILL, which is what the timeout sends *and* what the kernel sends a
- * container that ran out of memory.
+ * The command ran; its changes have not landed in the workspace yet.
+ *
+ * Every command is bracketed by a sync, and the pull afterwards is what moves
+ * what it wrote from the container into the Durable Object. That pull can fail
+ * while the command itself succeeds — a transport that dropped, a container
+ * replaced underneath — and the runtime reports it in `sync` rather than in the
+ * exit code, because the command genuinely did run.
+ *
+ * Worth a sentence to the model because the *next* thing it does is usually read
+ * what it just wrote, and the file tools read the workspace rather than the
+ * container. Without this the file looks unchanged and the obvious conclusion is
+ * that the command did not work, which is the one conclusion that is wrong.
+ *
+ * Recovery is deliberately not the model's, and is not automatic either: the
+ * runtime schedules no retry of its own, so an outstanding pull lands when the
+ * host drives one or when a later command's own bracket carries it. What the
+ * model is told therefore stops short of "it will be there in a moment" — it is
+ * told the read may be stale, that re-running the command is the wrong fix
+ * because it would repeat the side effects, and to say so in its result if the
+ * workspace still disagrees with what it wrote.
  */
-export function cancelledNote(status, exitCode, timeoutMs) {
-    if (status !== "cancelled")
+export function syncPendingNote(sync) {
+    if (sync?.status !== "pending")
         return undefined;
-    return (`the command was killed rather than exiting on its own (exit ${exitCode}), so ` +
-        `anything it had not yet written is gone. The two usual causes are the ` +
-        `per-command time limit — ${humanMs(timeoutMs)} here — and the container ` +
-        `running out of memory.`);
+    return ("(The command finished, but what it wrote has not reached the workspace " +
+        "yet, so the file tools may still show the previous contents. Do not re-run " +
+        "the command to force it — that repeats whatever it already did. Read again " +
+        "in a moment, and if the workspace still disagrees with what the command " +
+        "wrote, say so in your result rather than working around it.)");
 }

package/dist/computer/tools-exec.d.ts

@@ -0,0 +1,3 @@
+import type { ToolSet } from "ai";
+import type { ComputerContext } from "./context.js";
+export declare function execTools(ctx: ComputerContext): ToolSet;

package/dist/computer/tools-exec.js

@@ -0,0 +1,268 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { tool } from "ai";
+import { z } from "zod";
+import { withAbort } from "@dynamicagents/core";
+import { renderResult } from "./render.js";
+import { execLostNote } from "./gate.js";
+import { withShellTranscript } from "../workspace/shell.js";
+/** Running one command in the container. */
+/**
+ * Wait for a disposable resource without outliving `signal`.
+ *
+ * `withAbort` can abandon the wait but not the resource, and one that arrives
+ * after its caller has given up has nobody left to dispose it. So it is released
+ * on arrival instead — disposed by default, or handed to `release` where
+ * disposing alone would leave work running.
+ */
+function acquire(signal, opening, release = (resource) => resource[Symbol.dispose]()) {
+    return withAbort(signal, opening, () => {
+        void opening.then(release).catch(() => { });
+    });
+}
+/**
+ * How an exec handle that arrived too late is released. Disposing only detaches
+ * this side, so the process is killed first.
+ */
+async function killLate(handle) {
+    try {
+        await handle.kill("SIGTERM");
+    }
+    finally {
+        handle[Symbol.dispose]();
+    }
+}
+export function execTools(ctx) {
+    const { config, cwd, timeoutMs, maxChars, workspace, awaitAdvisories, definedEnv } = ctx;
+    return {
+        bash: tool({
+            /**
+             * States what the tool guarantees, rather than what it might withhold.
+             *
+             * A description that leads with "output is truncated if it is large" and
+             * gives no exit code hands the model two independent reasons to re-run a
+             * command and capture the output "properly" — at 60 seconds a go on a real
+             * gate, whose few hundred characters were never near the ceiling anyway.
+             *
+             * Two of these sentences are only true when a shell is configured, so the
+             * description says whichever is. `withShellTranscript` is a no-op without
+             * {@link file://./index.ts ComputerConfig.shell}: no `2>&1`, so the
+             * streams arrive separate and {@link renderResult} labels them; no
+             * `-o pipefail`, so `/bin/sh` reports a pipeline's *last* stage. Promising
+             * a transcript and first-failure semantics there would be the lie
+             * `wrapped` explains the cost of.
+             */
+            description: "Run a shell command in the container and return its output. Use this for builds, tests, package installs, git, and anything else a terminal can do. " +
+                (config.shell
+                    ? "The result is the command's full transcript — stdout and stderr interleaved in the order they were written — followed by a line reporting the exit code, e.g. `--- exit 0 ---`. A command killed at the time limit says so on that line. " +
+                        "You do not need to append `echo $?`, add `2>&1`, or redirect to a file to see any of this. " +
+                        "Do not pipe into `head` or `tail` to shorten output: long output is already truncated from the middle, keeping the beginning and the end, and piping costs you the parts you wanted. Pipelines report the first failing stage, so a piped command reports its real failure rather than the pipe's — but `cmd | head` may report 141 when `head` closes the pipe early, which is not a failure of `cmd`. "
+                    : "The result is the command's stdout, then any stderr under a `--- stderr ---` heading, then a line reporting the exit code, e.g. `--- exit 0 ---`. A command killed at the time limit says so on that line. " +
+                        "You do not need to append `echo $?` to see the exit code. Add `2>&1` yourself if you need the two streams in the order they were written. " +
+                        "Do not pipe into `head` or `tail` to shorten output: long output is already truncated from the middle, keeping the beginning and the end, and piping costs you the parts you wanted. A pipeline reports its **last** stage, so check the exit code of the command you care about rather than the pipe's. ") +
+                "Prefer targeted commands over ones that print everything.",
+            inputSchema: z.object({
+                command: z.string().describe("The shell command, e.g. 'npm test'"),
+                cwd: z
+                    .string()
+                    .optional()
+                    .describe(`Working directory (default: ${cwd})`)
+            }),
+            execute: async ({ command, cwd: overrideCwd }, { abortSignal }) => {
+                /**
+                 * One line per command, and it is the only view of where a task's wall
+                 * clock actually goes.
+                 *
+                 * Everything on the Worker side of a container command is an `await`, so
+                 * Workers Observability records the invocation at ~0% CPU and a long wall
+                 * time and cannot say what ran. Without this line, diagnosing a 59-minute
+                 * task means inferring the shape of each command from the *gaps between
+                 * AI Gateway calls*. The three numbers below — how long the install gate
+                 * held, how long the command took, what it exited with — answer it
+                 * directly.
+                 *
+                 * Timed around the gate as well as the command, since an agent blocked
+                 * waiting for `npm ci` and one running a slow test suite are
+                 * indistinguishable from the outside and want opposite fixes.
+                 */
+                const startedAtMs = Date.now();
+                /**
+                 * What the model is told when this call stops before the command
+                 * finishes. Said plainly, because the likeliest next move after a bare
+                 * error is the same command again — and whether that is right depends on
+                 * where the call stopped. A command that outran the limit once will again;
+                 * one that never started because the workspace did not answer may not.
+                 *
+                 * `bash` reads its call's signal rather than leaving the wait to Think,
+                 * and this is why: an abandoned wait can say only that the command may
+                 * still be running, and the kill below is what stops it.
+                 */
+                const stopped = (gateMs, started) => {
+                    const timedOut = abortSignal?.reason?.name ===
+                        "TimeoutError";
+                    console.info("[computer] bash stopped", {
+                        command,
+                        gateMs,
+                        durationMs: Date.now() - startedAtMs - gateMs,
+                        started,
+                        reason: timedOut ? "time limit" : "cancelled"
+                    });
+                    if (!timedOut)
+                        return "the command was stopped because this call was cancelled. Anything it changed before then is still changed.";
+                    return started
+                        ? "the command was stopped: it ran past this call's time limit. Anything it changed before then is still changed. Try something narrower."
+                        : "the command did not run: this call reached its time limit while the workspace was still getting ready, so nothing was changed. Try again; if it happens again, the workspace is not responding.";
+                };
+                // Only `bash` waits on an install. The file tools read and write
+                // source, which is in the workspace and unaffected by an install in
+                // flight — blocking them would stop the agent doing the reading it
+                // could usefully do while it waits. They do consult `writeGate`, which
+                // is a different question: not "is the tree ready" but "does a write
+                // survive at all".
+                let gate;
+                try {
+                    gate = await awaitAdvisories(command, abortSignal);
+                }
+                catch (err) {
+                    // Only a cancel gets out of the gate; a failed advisory read opens it.
+                    if (abortSignal?.aborted)
+                        return stopped(Date.now() - startedAtMs, false);
+                    throw err;
+                }
+                const gateMsWaited = Date.now() - startedAtMs;
+                if (gate.block) {
+                    console.info("[computer] bash blocked by a workspace advisory", {
+                        command,
+                        gateMs: gateMsWaited
+                    });
+                    return gate.block;
+                }
+                // Prepended to whatever happens next, success or failure. The warning
+                // is context for the output, not a substitute for it — which is why it
+                // is carried through the catch as well.
+                const note = (body) => gate.warn ? `${gate.warn}\n\n${body}` : body;
+                // Set once the exec is sent. See `stopped`.
+                let started = false;
+                try {
+                    const env_1 = { stack: [], error: void 0, hasError: false };
+                    try {
+                        // A workspace that stops answering would hold the call before any of the
+                        // cancellation below is reached.
+                        abortSignal?.throwIfAborted();
+                        const ws = __addDisposableResource(env_1, await acquire(abortSignal, workspace()), false);
+                        // Read once per command. This is the *host's* thunk, so calling it
+                        // twice in the construction of one command's options is two chances to
+                        // disagree — the check and the value would come from different reads.
+                        const commandEnv = definedEnv();
+                        const options = {
+                            cwd: overrideCwd ?? cwd,
+                            encoding: "utf8",
+                            timeoutMs,
+                            ...(commandEnv ? { env: commandEnv } : {})
+                        };
+                        // Transcript, not two streams: this result goes to a model, which
+                        // reads it as a terminal session rather than parsing it.
+                        // Not started at all on a signal that has already fired: a process that
+                        // is killed on the next line still ran long enough to change something.
+                        abortSignal?.throwIfAborted();
+                        // From here a stop cannot promise nothing ran: the exec may reach the
+                        // container before its handle reaches this side.
+                        started = true;
+                        const handle = __addDisposableResource(env_1, await acquire(abortSignal, ws.runtime.exec(withShellTranscript(command, config.shell), options), killLate), false);
+                        // The runtime takes no signal, so stopping the wait and stopping the
+                        // process are two acts. Disposing the handle is neither — it releases
+                        // this side's attachment and leaves the command running.
+                        const result = await withAbort(abortSignal, handle.result(), () => handle.kill("SIGTERM"));
+                        console.info("[computer] bash", {
+                            command,
+                            exitCode: result.exitCode,
+                            // Split so a slow command and a slow *wait* never look alike.
+                            gateMs: gateMsWaited,
+                            durationMs: Date.now() - startedAtMs - gateMsWaited,
+                            // The ceiling this was measured against — a duration sitting on it is
+                            // a timeout wearing a normal-looking number.
+                            timeoutMs
+                        });
+                        return note(renderResult(result, maxChars));
+                    }
+                    catch (e_1) {
+                        env_1.error = e_1;
+                        env_1.hasError = true;
+                    }
+                    finally {
+                        __disposeResources(env_1);
+                    }
+                }
+                catch (err) {
+                    if (abortSignal?.aborted)
+                        return note(stopped(gateMsWaited, started));
+                    const lost = execLostNote(err);
+                    console.warn("[computer] bash failed", {
+                        command,
+                        gateMs: gateMsWaited,
+                        durationMs: Date.now() - startedAtMs - gateMsWaited,
+                        timeoutMs,
+                        // Distinguished in the log for the same reason it is distinguished
+                        // for the model: a container replacement and a broken command want
+                        // different people looking at them.
+                        ...(lost ? { lost: true } : {}),
+                        err: String(err)
+                    });
+                    // Returned, not thrown: a failed command is usually the model's to
+                    // recover from, and it can only recover from what it is told.
+                    return note(lost ?? `error running command: ${String(err)}`);
+                }
+            }
+        })
+    };
+}

package/dist/computer/tools-file.d.ts

@@ -0,0 +1,12 @@
+import type { ToolSet } from "ai";
+import type { ComputerContext } from "./context.js";
+/**
+ * Editing a file in place — the one file tool this plugin keeps. Think's
+ * `read`, `write` and `delete` reach the workspace through the agent's own
+ * `this.workspace`, which is `computerWorkspace` (`./proxy.ts`).
+ *
+ * Not Think's `edit`, because that one is two calls through the workspace — a
+ * `readFile`, then a `writeFile` — and a lock inside the workspace cannot span
+ * the pair. See `./file-lock.ts`.
+ */
+export declare function fileTools(ctx: ComputerContext): ToolSet;

package/dist/computer/tools-file.js

@@ -0,0 +1,64 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { guardPath } from "./paths.js";
+import { withFileLock } from "./file-lock.js";
+/**
+ * Editing a file in place — the one file tool this plugin keeps. Think's
+ * `read`, `write` and `delete` reach the workspace through the agent's own
+ * `this.workspace`, which is `computerWorkspace` (`./proxy.ts`).
+ *
+ * Not Think's `edit`, because that one is two calls through the workspace — a
+ * `readFile`, then a `writeFile` — and a lock inside the workspace cannot span
+ * the pair. See `./file-lock.ts`.
+ */
+export function fileTools(ctx) {
+    const { inWorkspace, refuseWrite, scope } = ctx;
+    return {
+        edit: tool({
+            description: "Replace an exact string in a file. old_string must be non-empty and must appear exactly once — if it appears zero times or more than once the edit is refused, so include enough surrounding context to make it unique. To create a file, use write.",
+            inputSchema: z.object({
+                path: z.string().describe("Absolute path"),
+                old_string: z
+                    .string()
+                    // Empty is refused at the schema rather than in the body, because
+                    // `split("")` does not count empty-string occurrences: on a file of
+                    // one character it reports none, on a longer one it reports one per
+                    // character, and on an *empty* file it reports -1 — which slips past
+                    // both guards below and writes `new_string` into the file as if an
+                    // edit had been found. A write tool must not write what nobody asked
+                    // for.
+                    .min(1)
+                    .describe("Exact text to replace, unique within the file"),
+                new_string: z.string().describe("Replacement text")
+            }),
+            execute: async ({ path, old_string, new_string }) => {
+                const refusal = guardPath(path, "edit");
+                if (refusal)
+                    return refusal;
+                const lost = await refuseWrite();
+                if (lost)
+                    return lost;
+                return inWorkspace("editing", path, (fs) => withFileLock(scope(), path, async () => {
+                    const content = await fs.readFile(path, "utf8");
+                    const occurrences = content.split(old_string).length - 1;
+                    // Refusing an ambiguous edit is the whole value of this tool over
+                    // `write`: a silent first-match replace corrupts the file in a way
+                    // that surfaces much later, usually as a confusing test failure.
+                    if (occurrences === 0)
+                        return `no match for that text in ${path}`;
+                    if (occurrences > 1)
+                        return `that text appears ${occurrences} times in ${path} — add surrounding context to make it unique`;
+                    // A replacer function, not the string itself. `String.replace`
+                    // interprets `$$`, `$&`, `` $` `` and `$'` in a *string* replacement
+                    // even when the pattern is a plain string, so the text written is not
+                    // the text the model sent: `echo $$` becomes `echo $`, and `$'` splices
+                    // in everything before the match. Those two are not exotic — `$$`
+                    // escapes a dollar in a Makefile and reads a PID in shell, and `$'…'`
+                    // is bash ANSI-C quoting. A function's return value is used verbatim.
+                    await fs.writeFile(path, content.replace(old_string, () => new_string));
+                    return `edited ${path}`;
+                }));
+            }
+        })
+    };
+}

package/dist/computer/tools-grep.d.ts

@@ -0,0 +1,3 @@
+import type { ToolSet } from "ai";
+import type { ComputerContext } from "./context.js";
+export declare function grepTools(ctx: ComputerContext): ToolSet;

package/dist/computer/tools-grep.js

@@ -0,0 +1,129 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { guardPath, WALK_SKIPS } from "./paths.js";
+import { renderGrepMatches } from "./render.js";
+/**
+ * Searching file contents, under Think's name so it replaces Think's `grep` —
+ * which lists every file under the root and reads each one through the
+ * workspace, one round trip per file. Think's `find` and `list` stay Think's:
+ * over `computerWorkspace` they walk with `.git` and `node_modules` pruned.
+ */
+/**
+ * How many matches one `grep` returns.
+ *
+ * Bounded at the source: without a `limit`, `fs.grep` reads *every* file under
+ * the path looking for more, so an unbounded search of `/workspace` answers only
+ * after streaming the whole tree through the isolate. The limit stops that walk
+ * early; `exclude` keeps it out of `.git` and the dependency tree entirely.
+ */
+const DEFAULT_MAX_MATCHES = 200;
+/**
+ * The most `context` lines one `grep` shows around each match.
+ *
+ * Clamped rather than refused, since a refusal costs the model a step to retry.
+ * The bound is {@link file://./render.ts packBlocks}: it ships the first match's
+ * block whole, so a block has to stay well inside the output budget.
+ */
+const MAX_CONTEXT_LINES = 10;
+export function grepTools(ctx) {
+    const { cwd, maxChars, inWorkspace } = ctx;
+    return {
+        /**
+         * Search, without the container.
+         *
+         * The alternative is `bash("grep -rn …")`, and the case for a native one is
+         * not that shelling out fails — it is where the search runs. `fs.grep` reads
+         * the Durable Object's SQLite, so it answers while the container is being
+         * replaced or an install is still running, which is exactly the window the
+         * install gate leaves an agent with nothing to do. It is also why this tool
+         * is not gated: see {@link file://./context.ts awaitAdvisories}.
+         *
+         * And not Think's `grep`, which globs every file under the root and reads
+         * each one through the workspace.
+         *
+         * Two lesser reasons that still matter. The query arrives as a value rather
+         * than through `shellQuote` and a shell that would re-parse it. And the result
+         * is bounded by a `limit` at the source instead of being middle-truncated
+         * afterwards, which for a match list means losing whole files silently.
+         */
+        grep: tool({
+            description: "Search file contents across the workspace. Returns matching lines grouped by file, each with its line number. " +
+                "The query is matched literally — set `regex` to interpret it as a regular expression. " +
+                "Pass `include` to limit which files are searched, e.g. '**/*.ts' — without it every file under `path` is read, which is slower and rarely what you meant. " +
+                "A cut result reports the `offset` that continues it. Use `context` to see the lines around a match. " +
+                "Results from `.git` and `node_modules` are left out — search node_modules with bash.",
+            inputSchema: z.object({
+                query: z.string().describe("Text to find, e.g. 'buildComputerTools'"),
+                path: z
+                    .string()
+                    .optional()
+                    .describe(`Absolute file or directory to search (default: ${cwd})`),
+                include: z
+                    .string()
+                    .optional()
+                    .describe("Glob relative to path limiting which files are searched, e.g. '**/*.ts'"),
+                regex: z
+                    .boolean()
+                    .optional()
+                    .describe("Interpret query as a regular expression"),
+                ignoreCase: z.boolean().optional().describe("Ignore letter case"),
+                context: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .optional()
+                    .describe(`Lines of surrounding context to include with each match, at most ${MAX_CONTEXT_LINES}`),
+                offset: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .optional()
+                    .describe("Matches to skip — use the offset a cut result reports")
+            }),
+            execute: async ({ query, path, include, regex, ignoreCase, context, offset }) => {
+                const target = path ?? cwd;
+                const refusal = guardPath(target, "grep");
+                if (refusal)
+                    return refusal;
+                const from = offset ?? 0;
+                const around = context === undefined
+                    ? undefined
+                    : Math.min(context, MAX_CONTEXT_LINES);
+                return inWorkspace("searching", target, async (fs) => {
+                    // Pruned in the store, not filtered here: an excluded directory is
+                    // never descended into, so `node_modules` costs nothing to skip and
+                    // `offset` counts only matches the model can actually be shown. A
+                    // filter on this side could not do either — it pages blind, so a
+                    // crowded page could hide every real match behind skipped ones.
+                    const matches = await fs.grep(query, target, {
+                        include,
+                        regex,
+                        ignoreCase,
+                        context: around,
+                        limit: DEFAULT_MAX_MATCHES + 1,
+                        offset: from,
+                        exclude: WALK_SKIPS.map((segment) => `**/${segment}`)
+                    });
+                    if (matches.length === 0)
+                        return `no matches for ${JSON.stringify(query)} in ${target}${include ? ` (${include})` : ""}${from > 0 ? ` past offset ${from}` : ""}`;
+                    const { body, shown, capped } = renderGrepMatches(matches.slice(0, DEFAULT_MAX_MATCHES), maxChars);
+                    return (body +
+                        // `shown` falls short of what came back either because the page was
+                        // capped or because the render budget ran out; both continue here.
+                        (shown < matches.length
+                            ? `\n\n… showed ${shown} matches; there are more. Continue with ` +
+                                `\`offset: ${from + shown}\`, or narrow with \`include\` — ` +
+                                `narrowing is cheaper, since an offset still walks everything ` +
+                                `it skips.`
+                            : "") +
+                        (capped
+                            ? `\n(Some lines were shortened. Read one in full with \`read\`, passing its line number as \`offset\`.)`
+                            : "") +
+                        (around !== context
+                            ? `\n(\`context\` is at most ${MAX_CONTEXT_LINES}, so ${context} was clamped to ${MAX_CONTEXT_LINES}. Read a wider region with \`read\`.)`
+                            : ""));
+                });
+            }
+        })
+    };
+}