@dynamicagents/plugins 0.11.1 → 0.12.0

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,269 @@
+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 "./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 {
+        sb_exec: 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 a subagent 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.
+                 *
+                 * `sb_exec` reads its call's signal rather than leaving the wait to core,
+                 * and this is why: core's abandonment can say only that the command may
+                 * still be running. Core's `TOOL_CALL_GRACE_MS` is the window this answer
+                 * has to arrive in, and it covers sending the kill below.
+                 */
+                const stopped = (gateMs, started) => {
+                    const timedOut = abortSignal?.reason?.name ===
+                        "TimeoutError";
+                    console.info("[computer] sb_exec 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 `sb_exec` 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 subagent 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] sb_exec 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] sb_exec", {
+                            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] sb_exec 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,4 @@
+import type { ToolSet } from "ai";
+import type { ComputerContext } from "./context.js";
+/** One file at a time: reading it, replacing it, editing it in place. */
+export declare function fileTools(ctx: ComputerContext): ToolSet;

package/dist/computer/tools-file.js

@@ -0,0 +1,124 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { guardPath } from "./paths.js";
+import { withFileLock } from "./file-lock.js";
+import { readBounded, readWindow } from "./read.js";
+/** One file at a time: reading it, replacing it, editing it in place. */
+export function fileTools(ctx) {
+    const { maxChars, inWorkspace, refuseWrite, scope } = ctx;
+    return {
+        sb_read: tool({
+            description: "Read a file from the workspace. Returns the file's text, or a note if it does not exist. " +
+                "A large file comes back with its middle removed and a marker giving the `offset` that reaches the missing part. " +
+                "Pass `offset` (and optionally `length`) to read a specific byte window instead — the result states the window it returned and how many bytes follow, so you can page through a file. Byte offsets, not lines: to see the lines around a match, use sb_grep with `context`. " +
+                "Files under node_modules are not in the workspace — read them with sb_exec.",
+            inputSchema: z.object({
+                path: z
+                    .string()
+                    .describe("Absolute path, e.g. '/workspace/repo/src/a.ts'"),
+                offset: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .optional()
+                    .describe("Byte offset to start reading from"),
+                length: z
+                    .number()
+                    .int()
+                    .min(1)
+                    .optional()
+                    .describe("Maximum bytes to return from `offset`")
+            }),
+            execute: async ({ path, offset, length }) => {
+                const refusal = guardPath(path, "sb_read");
+                if (refusal)
+                    return refusal;
+                return inWorkspace("reading", path, async (fs) => {
+                    // Either knob means the model chose a region; only an unqualified read
+                    // gets the middle-out guess.
+                    return offset === undefined && length === undefined
+                        ? await readBounded(fs, path, maxChars)
+                        : await readWindow(fs, path, offset ?? 0, length ?? maxChars, maxChars);
+                });
+            }
+        }),
+        sb_write: tool({
+            description: "Create or overwrite a file in the workspace. Parent directories are created for you. For a small change to a large file prefer sb_edit, which does not require sending the whole file back.",
+            inputSchema: z.object({
+                path: z.string().describe("Absolute path"),
+                content: z
+                    .string()
+                    .describe("Full file content (overwrites any existing file)")
+            }),
+            execute: async ({ path, content }) => {
+                const refusal = guardPath(path, "sb_write");
+                if (refusal)
+                    return refusal;
+                // Before the write, not after: the point is to not report a success that
+                // did not happen.
+                const lost = await refuseWrite();
+                if (lost)
+                    return lost;
+                return inWorkspace("writing", path, (fs) => withFileLock(scope(), path, async () => {
+                    const dir = path.slice(0, path.lastIndexOf("/"));
+                    if (dir)
+                        await fs.mkdir(dir, { recursive: true });
+                    await fs.writeFile(path, content);
+                    // Characters, not bytes. `String.length` counts UTF-16 code units — the
+                    // distinction `readBounded` documents at length — so calling them bytes
+                    // was simply wrong for anything outside ASCII. The exact byte count
+                    // would cost a `TextEncoder` pass over the whole content for a number
+                    // nobody does arithmetic with, and "characters" is already this module's
+                    // word for the same count in `truncateOutput`'s omission marker.
+                    const written = content.length;
+                    return `wrote ${path} (${written} character${written === 1 ? "" : "s"})`;
+                }));
+            }
+        }),
+        sb_edit: tool({
+            description: "Replace an exact string in a file. The 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.",
+            inputSchema: z.object({
+                path: z.string().describe("Absolute path"),
+                find: 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 `replace` 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"),
+                replace: z.string().describe("Replacement text")
+            }),
+            execute: async ({ path, find, replace }) => {
+                const refusal = guardPath(path, "sb_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(find).length - 1;
+                    // Refusing an ambiguous edit is the whole value of this tool over
+                    // sb_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(find, () => replace));
+                    return `edited ${path}`;
+                }));
+            }
+        })
+    };
+}

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

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

package/dist/computer/tools-find.js

@@ -0,0 +1,216 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { guardPath, isSkipped, skipNames, WALK_SKIPS } from "./paths.js";
+import { humanBytes, packBlocks, renderGrepMatches } from "./render.js";
+import { collectVisible, listingNote, pathExists } from "./read.js";
+/** Finding things: what is in a directory, what a file contains, what exists. */
+/**
+ * How many directory entries one `sb_ls` returns.
+ *
+ * A bound on the *listing*, not on the rendered text — `maxOutputChars` still
+ * applies on top, and the order matters. Bounding only the text means `readdir`
+ * returns every entry and the isolate holds all of them before the ceiling
+ * discards the tail; a dependency tree is 22,470 files, and a misbehaving build
+ * is exactly when someone lists one. `readdir` takes a `limit`, so the bound is
+ * applied where the entries are read.
+ */
+const DEFAULT_MAX_ENTRIES = 1000;
+/**
+ * How many matches one `sb_grep` returns.
+ *
+ * Bounded at the source like {@link DEFAULT_MAX_ENTRIES}, and for a sharper reason
+ * than a listing: without a `limit`, `fs.grep` reads *every* file under the path
+ * looking for more. `.git` and the dependency tree are both in the workspace, so
+ * an unbounded search of `/workspace` streams every loose object and every
+ * vendored file through the isolate before answering. The limit is what stops
+ * that walk early, and the skip list is what keeps the matches worth reading.
+ */
+const DEFAULT_MAX_MATCHES = 200;
+export function findTools(ctx) {
+    const { cwd, maxChars, inWorkspace } = ctx;
+    return {
+        sb_ls: tool({
+            description: "List files in a workspace directory, or find files by name. Without `pattern` it lists one level: directories with a trailing slash, files with their size — check that before reading a large one, since sb_read truncates. " +
+                "`pattern` is a glob matched against paths relative to `path`, and searches the whole subtree: `*` stays within one path segment, `**/` crosses directories, `?` matches one character. So `*.ts` finds top-level TypeScript files and `**/*.ts` finds them at any depth. " +
+                "A cut listing reports the `offset` that continues it. Subtree listings leave out `.git` and `node_modules`.",
+            inputSchema: z.object({
+                path: z.string().describe("Absolute directory path"),
+                recursive: z
+                    .boolean()
+                    .optional()
+                    .describe("List the whole subtree rather than one level"),
+                pattern: z
+                    .string()
+                    .optional()
+                    .describe("Glob relative to path, e.g. '**/*.spec.ts'. Searches the subtree, so `recursive` is not needed with it."),
+                offset: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .optional()
+                    .describe("Entries to skip — use the offset a cut listing reports")
+            }),
+            execute: async ({ path, recursive, pattern, offset }) => {
+                const refusal = guardPath(path, "sb_ls");
+                if (refusal)
+                    return refusal;
+                const from = offset ?? 0;
+                return inWorkspace("listing", path, async (fs) => {
+                    if (recursive || pattern) {
+                        // `find` rather than `ls`, which took no bound: a prefix scan
+                        // returned every path in the subtree and the ceiling then threw most
+                        // of them away — the same read-everything-then-discard shape the
+                        // `readdir` limit below exists to avoid. Two differences follow from
+                        // the swap, both improvements: directories appear (rendered like the
+                        // arm below renders them), and order is the walk's — pre-order, by
+                        // name — rather than one flat sort.
+                        //
+                        // `.git` and `node_modules` are pruned by the store, not filtered
+                        // here: at a repo root either one outnumbers a page on its own.
+                        const entries = await fs.find(path, pattern, {
+                            limit: DEFAULT_MAX_ENTRIES + 1,
+                            offset: from,
+                            exclude: WALK_SKIPS.map((segment) => `**/${segment}`)
+                        });
+                        if (entries.length === 0)
+                            return pattern
+                                ? `(nothing under ${path} matches ${pattern})`
+                                : `(${path} is empty)`;
+                        const blocks = entries
+                            .slice(0, DEFAULT_MAX_ENTRIES)
+                            .map((e) => [e.type === "dir" ? `${e.path}/` : e.path]);
+                        const { body, shown } = packBlocks(blocks, maxChars);
+                        const page = {
+                            rawIndex: entries.map((_, i) => from + i),
+                            rawEnd: from + entries.length,
+                            exhausted: entries.length <= DEFAULT_MAX_ENTRIES,
+                            crowded: false
+                        };
+                        return body + listingNote(page, shown, "entries", "`pattern`");
+                    }
+                    // One over the ceiling: enough to know the listing was cut without a
+                    // second round trip to find out, and the extra entry is not shown.
+                    // Unfiltered on purpose — one line naming a directory that is really
+                    // there is honest, and costs a line rather than a page. It is the
+                    // *subtree* walk above that cannot afford to descend into them.
+                    const entries = await fs.readdir(path, {
+                        limit: DEFAULT_MAX_ENTRIES + 1,
+                        offset: from
+                    });
+                    if (entries.length === 0)
+                        return from > 0
+                            ? `(no entries in ${path} past offset ${from})`
+                            : `(${path} is empty)`;
+                    const blocks = entries
+                        .slice(0, DEFAULT_MAX_ENTRIES)
+                        .map((e) => [
+                        e.isDirectory ? `${e.name}/` : `${e.name}\t${humanBytes(e.size)}`
+                    ]);
+                    const { body, shown } = packBlocks(blocks, maxChars);
+                    const more = entries.length > shown;
+                    return (body +
+                        (more
+                            ? `\n… showed ${shown} entries; there are more. Continue with \`offset: ${from + shown}\`, or narrow with \`pattern\`.`
+                            : ""));
+                });
+            }
+        }),
+        /**
+         * Search, without the container.
+         *
+         * The tool this replaces is `sb_exec("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 a subagent with nothing to do. It is also why this
+         * tool is not gated: see {@link file://./context.ts awaitAdvisories}.
+         *
+         * 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.
+         */
+        sb_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 sb_exec.",
+            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)
+                    .max(3)
+                    .optional()
+                    .describe("Lines of surrounding context to include with each match"),
+                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, "sb_grep");
+                if (refusal)
+                    return refusal;
+                const from = offset ?? 0;
+                return inWorkspace("searching", target, async (fs) => {
+                    // Two rounds, because a `grep` retry re-reads and re-scans every file
+                    // it already looked at. `.git` rarely floods a page here — its bulk is
+                    // compressed objects, which a text query does not match — where a
+                    // `node_modules` left in the workspace is source and matches.
+                    const skips = WALK_SKIPS;
+                    const page = await collectVisible((at, limit) => fs.grep(query, target, {
+                        include,
+                        regex,
+                        ignoreCase,
+                        context,
+                        limit,
+                        offset: at
+                    }), (m) => m.path, (p) => isSkipped(skips, p), DEFAULT_MAX_MATCHES, from, 2);
+                    if (page.items.length === 0)
+                        return page.crowded
+                            ? `every match for ${JSON.stringify(query)} from offset ${from} is inside ${skipNames(skips)}, which ${skips.length > 1 ? "are" : "is"} not searched. Add \`include\` (e.g. '**/*.ts') to search the working tree instead, or use sb_exec to search \`node_modules\`.`
+                            : `no matches for ${JSON.stringify(query)} in ${target}${include ? ` (${include})` : ""}${from > 0 ? ` past offset ${from}` : ""}`;
+                    const { body, shown, capped } = renderGrepMatches(page.items.slice(0, DEFAULT_MAX_MATCHES), maxChars);
+                    return (body +
+                        listingNote(page, shown, "matches", "`include`") +
+                        (capped
+                            ? `\n(Some lines were shortened. Read one in full with \`sb_read\` and an \`offset\`.)`
+                            : ""));
+                });
+            }
+        }),
+        sb_exists: tool({
+            description: "Check whether a path exists in the workspace.",
+            inputSchema: z.object({ path: z.string().describe("Absolute path") }),
+            execute: async ({ path }) => {
+                const refusal = guardPath(path, "sb_exists");
+                if (refusal)
+                    return refusal;
+                return inWorkspace("checking", path, async (fs) => {
+                    return (await pathExists(fs, path))
+                        ? `${path} exists`
+                        : `${path} does not exist`;
+                });
+            }
+        })
+    };
+}

package/dist/recall/index.d.ts

@@ -1,5 +1,5 @@
-import type { SessionMessage } from "agents/experimental/memory/session";
 import type { AgentPlugin } from "@dynamicagents/core";
+import type { SessionMessage } from "@dynamicagents/core/agent";
 /**
  * The subset of the Vectorize binding recall drives — structurally satisfied by
  * `Vectorize`/`VectorizeIndex`, so nothing here names the binding type and a
@@ -57,12 +57,13 @@ export declare function recallSearch(index: RecallIndex, namespace: string, quer
  *
  * // plugins.ts — the bindings, and the values spread
  * recall({ ai: host.env.AI, index: host.env.VECTORIZE,
- *          namespace: host.callerKey, aiGatewayId: host.aiGatewayId, ...RECALL })
+ *          namespace: host.callerKey, aiGatewayId: host.aiGatewayId,
+ *          agentName: host.agentName, ...RECALL })
  * ```
  *
  * Field-by-field re-typing is not just verbose — it silently drops any option
  * added later, so a new default lands everywhere except the deployments that
- * enumerated the old set.
+ * enumerated the fields by hand.
  */
 export interface RecallTuning {
     /**
@@ -72,6 +73,11 @@ export interface RecallTuning {
      * override is dropped in favour of core's default.
      */
     aiGatewayId?: string;
+    /**
+     * The `agent` key on embedding calls' AI Gateway log rows. Pass the host's
+     * `PluginHost.agentName`, for the reason given on {@link aiGatewayId}.
+     */
+    agentName?: string;
     /** Workers-AI embedding model. Must match the index's dimension. */
     embeddingModelId?: string;
     /** Matches returned by a search. Defaults to 5. */