@dynamicagents/plugins 0.11.0 → 0.12.0

package/dist/computer/index.js

@@ -50,14 +50,14 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     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 { definePlugin, withAbort } from "@dynamicagents/core";
-import { getWorkspace, shellQuote } from "@cloudflare/computer";
-import { guardPath } from "./paths.js";
-import { cancelledNote, humanBytes, packBlocks, renderGrepMatches, renderResult } from "./render.js";
-import { collectVisible, listingNote, pathExists, readBounded, readWindow } from "./read.js";
-import { execGate, execLostNote, writeGate } from "./gate.js";
+import { definePlugin } from "@dynamicagents/core";
+import { getWorkspace } from "@cloudflare/computer";
+import { cancelledNote } from "./render.js";
+import { computerContext, DEFAULT_CWD, DEFAULT_TIMEOUT_MS } from "./context.js";
+import { withShell } from "./shell.js";
+import { execTools } from "./tools-exec.js";
+import { fileTools } from "./tools-file.js";
+import { findTools } from "./tools-find.js";
 /**
  * `@dynamicagents/plugins/computer` — a Linux container whose filesystem outlives it.
  *
@@ -71,18 +71,13 @@ import { execGate, execLostNote, writeGate } from "./gate.js";
  * filesystem plugin — an agent holding two gives the model no way to know which
  * one a path refers to.
  *
- * ## `node_modules` is **not** in the workspace
+ * ## The dependency tree is not in the workspace
  *
- * The one thing to internalise before reading further. `computerd` excludes it
- * from the sync, and the exclusion is right: pushing a real one (429 MB, 22,470
- * files) into the object exceeds the Durable Object's 128 MB isolate memory
- * limit, leaving the tree silently short — and the reconciliation that follows
- * propagates the shortfall back into the container.
- *
- * So dependencies live in the container and die with it, while source and `.git`
- * are durable. Two consequences run through everything below: an install has to
- * be re-run on a cold container, and `sb_read` cannot see a path under
- * `node_modules` even though a shell in the same container can.
+ * The one thing to internalise before reading further. A package root's
+ * `node_modules` is a bind mount of the container's disk, so installs never
+ * sync, and a new container reinstalls — see `./host/container-deps.ts`. The file tools read
+ * the workspace, so they refuse it; `sb_exec` reaches it. `paths.ts` owns what a
+ * path may be and what walks drop.
  *
  * Requires the Workers **Paid** plan (containers) and a Durable Object binding
  * whose class owns the workspace — see the README for the wrangler block.
@@ -105,8 +100,8 @@ export { DEFAULT_INSTALL_PLAN, installFingerprint, resolveInstallCommand } from
  * `verify:exports` treats `./computer` as one realm, and everything below stays
  * inside `dist/computer/`.
  */
-export { isContainerOnly, isGitInternal } from "./paths.js";
-export { cancelledNote, packBlocks, renderGrepMatches, renderResult, truncateOutput } from "./render.js";
+export { isGitInternal, WALK_SKIPS } from "./paths.js";
+export { cancelledNote, packBlocks, renderGrepMatches, renderResult, syncPendingNote, truncateOutput } from "./render.js";
 export { execGate, needsDependencies, writeGate } from "./gate.js";
 /**
  * The workspace-advisory vocabulary, which a host needs all of: the type to
@@ -159,49 +154,7 @@ export function workspaceNameFromRuntime(runtime) {
     const value = runtime?.[WORKSPACE_RUNTIME_KEY];
     return typeof value === "string" && value.length > 0 ? value : undefined;
 }
-/**
- * How much command output the model is allowed to see, in characters.
- *
- * One `npm install` prints more than a small context window holds, and the
- * interesting part of a failing build is the first error and the last summary —
- * never the middle. So output is truncated from the middle rather than the end,
- * which is what a naive `slice` would do and would drop the exit summary that
- * says what actually failed.
- */
-const DEFAULT_MAX_OUTPUT_CHARS = 16_000;
-/**
- * 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 real `node_modules` 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` is in the workspace, so an unbounded search of
- * `/workspace` streams every loose object through the isolate before answering.
- * The limit is what stops that walk early.
- */
-const DEFAULT_MAX_MATCHES = 200;
-/** A command that has not finished in this long is a hung command. */
-const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
-/** Where checkouts live, in the container and in the workspace alike. */
-const DEFAULT_CWD = "/workspace";
-/**
- * How often the install gate re-reads the install's status.
- *
- * An interval rather than a subscription because the status lives in another
- * Durable Object with no event to wait on. Never slept past the gate itself —
- * see `awaitInstall`.
- */
-const INSTALL_POLL_MS = 3_000;
+export { withShell, withShellTranscript } from "./shell.js";
 /**
  * Open the workspace behind a Durable Object stub.
  *
@@ -213,706 +166,39 @@ const INSTALL_POLL_MS = 3_000;
  * of the class's private brand: runtime-compatible, type-incompatible. This is
  * the only place in the plugin that gap is crossed.
  */
-function openWorkspace(host) {
+export function openWorkspace(host) {
     return getWorkspace(host);
 }
 /**
- * The shell wrapper both variants share, minus the choice they differ on.
- *
- * One quoted argument, not string concatenation: the command is model-authored
- * and routinely contains quotes of its own (`git commit -m "…"`), so anything
- * less than `shellQuote` re-parses the model's quoting and mangles it.
- *
- * ## Why `-o pipefail`
- *
- * Without it a pipeline's exit status is its **last** stage's, so
- * `npm run check | tail -100` reports `exit 0` for a gate that failed outright —
- * and models pipe into `tail` constantly. A tool that reports success for a
- * failed build is worse than one that reports nothing. It also costs a re-run
- * every time: a model that cannot trust a piped exit code runs the whole thing
- * again unpiped to get one.
- *
- * The trade is worth stating. `pipefail` surfaces SIGPIPE too, so
- * `ls big-dir | head -1` reports 141 rather than 0 — noisy, but *visible*, where
- * the alternative is a failing gate that looks clean. The tool description tells
- * the model not to pipe into `head`/`tail` at all, since output is already
- * truncated with both ends kept.
- *
- * Requires a shell that implements it — `bash`, `zsh`, `ksh`, not `sh`/dash. A
- * host setting {@link ComputerConfig.shell} is choosing that shell explicitly.
- */
-function wrapped(command, shell) {
-    return `${shell} -o pipefail -c ${shellQuote(command)}`;
-}
-/**
- * Run a command under {@link ComputerConfig.shell} with its two output streams
- * left as they are, or hand it back untouched when no shell is configured.
- *
- * This is the variant for a caller that **reads the result in code**: `stdout` is
- * a data channel it compares or parses, and `stderr` is a separate diagnostic.
- * {@link computerExec} is that caller, on behalf of `@dynamicagents/plugins/repo`,
- * which asks git questions like `symbolic-ref --short refs/remotes/origin/HEAD`
- * and `rev-list --count` and needs the answer alone.
- *
- * Two functions rather than one with a flag, because the difference is a change
- * to the *output contract* and a boolean hides it at the call site. Merging the
- * streams here would give every `/repo` git command an empty `stderr` and a
- * `stdout` that is a transcript rather than an answer — which fails silently,
- * since the commands `/repo` parses are quiet ones and a single `warning:` is
- * enough to skip the empty-branch guard.
- */
-export function withShell(command, shell) {
-    return shell ? wrapped(command, shell) : command;
-}
-/**
- * Run a command under {@link ComputerConfig.shell} with its two output streams
- * merged into one transcript, in the order they were written.
- *
- * This is the variant for a caller whose consumer is **a model reading output**.
- * `sb_exec` is that caller. A project's check is a chain — `wrangler types &&
- * prettier && eslint && tsc` — and *which tool spoke last* is how you know which
- * one failed. A stdout block and a separate stderr block destroy that ordering,
- * and a model that wants it back re-runs the whole gate as
- * `npm run check > /tmp/out 2>&1; cat /tmp/out`. This is that workaround, done
- * once, for free.
+ * The same workspace, opened for filesystem work alone.
  *
- * The redirect binds to the wrapper process, so it applies to everything the
- * command writes however deeply nested — and there is no inner brace group or
- * subshell to mis-parse a command that already contains `&&`, quotes or redirects
- * of its own.
+ * `getWorkspace` calls exactly one method on what it is handed, so the host is
+ * wrapped in an object answering it from the other side of the seam — see
+ * {@link WorkspaceHost.__getWorkspaceFsStub}. Everything past that is identical.
  *
- * With no shell configured there is no wrapper process to redirect, so the
- * command goes to the runtime untouched and the two streams arrive separate.
- * That is not a gap: {@link renderResult} renders them as a labelled
- * `--- stderr ---` block for exactly this case. The transcript is the better
- * answer, not the only supported one.
+ * **Only the file tools take this.** `sb_exec` and {@link computerExec} need the
+ * container started and its CA installed, so they open it the other way.
  */
-export function withShellTranscript(command, shell) {
-    return shell ? `${wrapped(command, shell)} 2>&1` : command;
-}
-/**
- * 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(() => { });
+export function openWorkspaceFs(host) {
+    return getWorkspace({
+        __getWorkspaceStub: () => host.__getWorkspaceFsStub()
     });
 }
 /**
- * How an exec handle that arrived too late is released. Disposing only detaches
- * this side, so the process is killed first.
+ * @param workspace Opens the workspace for a command: container started, CA
+ *   installed.
+ * @param fsWorkspace Opens it for the file tools, which touch nothing but the
+ *   host's SQLite. Defaults to {@link workspace}, so a host with one way in
+ *   behaves as before. See {@link openWorkspaceFs}.
+ * @param lockScope Names the workspace a write locks within — see
+ *   {@link file://./file-lock.ts}. Defaults to this tool set alone.
  */
-async function killLate(handle) {
-    try {
-        await handle.kill("SIGTERM");
-    }
-    finally {
-        handle[Symbol.dispose]();
-    }
-}
-export function buildComputerTools(workspace, config, advisories) {
-    const cwd = config.cwd ?? DEFAULT_CWD;
-    const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    const maxChars = config.maxOutputChars ?? DEFAULT_MAX_OUTPUT_CHARS;
-    const gateMs = config.installGateMs ?? 90_000;
-    const env = config.env;
-    /**
-     * Wait out anything transient, up to the gate, and report whatever is left.
-     *
-     * Polled rather than subscribed: the state lives in another Durable Object,
-     * there is no event to wait on, and the whole window is under two minutes.
-     *
-     * **Read for every command, including the ones that need no dependencies.**
-     * That is a change of shape, not a slip. The filter that spares `cat
-     * README.md` from queueing behind an `npm ci` lives in `execGate`, where it
-     * applies per advisory — because a dependency install and a full workspace are
-     * not relevant to the same commands, and applying one filter to both is what
-     * made a workspace at its ceiling silent for exactly the commands whose writes
-     * it was dropping. The cost is one same-colo RPC on commands that previously
-     * skipped it, against a class of silent data loss.
-     */
-    const awaitAdvisories = async (command, signal) => {
-        if (!advisories)
-            return {};
-        // Fails **open**, and that belongs here rather than at the call site: this
-        // is a read of another Durable Object's state. An error must not take out a
-        // working shell — running the command is exactly what would have happened
-        // before the gate existed, and a spurious blockage would strand the
-        // subagent.
-        const read = async () => {
-            try {
-                signal?.throwIfAborted();
-                return await withAbort(signal, advisories());
-            }
-            catch (err) {
-                // Open on a failed read, never on a cancel: failing open here would go on
-                // to run the command the caller just gave up on.
-                if (signal?.aborted)
-                    throw err;
-                return [];
-            }
-        };
-        // Clamped to whatever is left of the gate, not the bare interval. A fixed
-        // sleep makes `installGateMs` a floor rather than the ceiling it is
-        // documented to be: at a 100 ms gate the loop still slept the full three
-        // seconds before looking again, so a public timeout overshot by 30×.
-        const deadline = Date.now() + gateMs;
-        let current = await read();
-        // Keyed on the gate's own verdict rather than on a state name, so "what is
-        // worth waiting for" has one definition and it is the one that will decide
-        // the outcome.
-        while (execGate(current, command).block && Date.now() < deadline) {
-            const wait = Math.min(INSTALL_POLL_MS, deadline - Date.now());
-            // Throws on a cancel rather than returning the verdict so far: a gate that
-            // outlived its caller would otherwise go on to run the command it was holding.
-            await withAbort(signal, new Promise((resolve) => setTimeout(resolve, wait)));
-            current = await read();
-        }
-        return execGate(current, command);
-    };
-    /**
-     * Whether a write can succeed at all, asked once and not polled.
-     *
-     * Separate from {@link awaitAdvisories} because the question is different:
-     * there is no command to classify and nothing worth waiting for. An install in
-     * flight does not stop a file being written, and the one thing that does —
-     * a workspace that no longer accepts writes — never resolves on its own.
-     *
-     * Fails **open** for the same reason the exec gate does: a read of another
-     * Durable Object's state must not take out a working tool.
-     */
-    const refuseWrite = async () => {
-        if (!advisories)
-            return undefined;
-        try {
-            return writeGate(await advisories());
-        }
-        catch {
-            return undefined;
-        }
-    };
-    /**
-     * Host-supplied environment, with the undefined entries dropped.
-     *
-     * `RuntimeExecOptions.env` is `Record<string, string>`, and a config thunk
-     * that reads straight off `env` will hand back `undefined` for anything
-     * unset — which would otherwise arrive in the container as the string
-     * "undefined".
-     */
-    const definedEnv = () => {
-        if (!env)
-            return undefined;
-        const entries = Object.entries(env()).filter((entry) => entry[1] !== undefined);
-        return entries.length > 0 ? Object.fromEntries(entries) : undefined;
-    };
-    /**
-     * Open the workspace, run one file operation in it, and own the failure.
-     *
-     * Five lines every file tool would otherwise repeat with only the verb changed
-     * — five chances for the seventh to be written without them. The catch is the
-     * point: a failed file operation is the model's to recover from, and it can
-     * only recover from what it is told, so this returns the sentence rather than
-     * throwing it.
-     *
-     * `sb_exec` deliberately does not use it. That one recognises `EEXEC_LOST`,
-     * logs, and carries an install warning through the failure path — a bespoke
-     * catch saying something this cannot.
-     */
-    const inWorkspace = async (gerund, subject, body) => {
-        try {
-            const env_1 = { stack: [], error: void 0, hasError: false };
-            try {
-                const ws = __addDisposableResource(env_1, await workspace(), false);
-                return await body(ws.fs);
-            }
-            catch (e_1) {
-                env_1.error = e_1;
-                env_1.hasError = true;
-            }
-            finally {
-                __disposeResources(env_1);
-            }
-        }
-        catch (err) {
-            return `error ${gerund} ${subject}: ${String(err)}`;
-        }
-    };
+export function buildComputerTools(workspace, config, advisories, fsWorkspace = workspace, lockScope) {
+    const ctx = computerContext(workspace, config, advisories, fsWorkspace, lockScope);
     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 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. Diagnosing a 59-minute task on 2026-08-11
-                 * meant inferring the shape of each command from the *gaps between AI
-                 * Gateway calls*, because nothing logged the command itself. The three
-                 * numbers below — how long the install gate held, how long the command
-                 * took, what it exited with — would have answered 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_2 = { 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_2, 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_2, 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_2) {
-                        env_2.error = e_2;
-                        env_2.hasError = true;
-                    }
-                    finally {
-                        __disposeResources(env_2);
-                    }
-                }
-                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)}`);
-                }
-            }
-        }),
-        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 those 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, async (fs) => {
-                    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, async (fs) => {
-                    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}`;
-                });
-            }
-        }),
-        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. node_modules is not in the workspace — list it with sb_exec.",
-            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.
-                        //
-                        // Filtered rather than trusted, and this is the arm where it matters
-                        // most: at a repo root `.git` is walked *first* and holds thousands
-                        // of objects, so an unfiltered page is a page of `.git` and nothing
-                        // else. Four rounds because a `find` retry re-walks dirents, which is
-                        // cheap SQLite reads rather than file bytes.
-                        const page = await collectVisible((at, limit) => fs.find(path, pattern, { limit, offset: at }), (e) => e.path, DEFAULT_MAX_ENTRIES, from, 4);
-                        if (page.items.length === 0)
-                            return page.crowded
-                                ? `(everything under ${path} from offset ${from} is inside .git — try a \`pattern\`, or a \`path\` inside the working tree)`
-                                : pattern
-                                    ? `(nothing under ${path} matches ${pattern})`
-                                    : `(${path} is empty)`;
-                        const blocks = page.items
-                            .slice(0, DEFAULT_MAX_ENTRIES)
-                            .map((e) => [e.type === "dir" ? `${e.path}/` : e.path]);
-                        const { body, shown } = packBlocks(blocks, maxChars);
-                        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 — `.git/` shows here exactly as `node_modules`
-                    // does, because one line naming a directory that is really there is
-                    // honest, and it is access rather than existence that is refused.
-                    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 awaitInstall}.
-         *
-         * 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. " +
-                "node_modules is not in the workspace — search it 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, not four: a `grep` retry re-reads and re-scans every file
-                    // it already looked at, where the `find` retry in `sb_ls` only re-walks
-                    // dirents. `.git` is also far less likely to flood a page here — its
-                    // bulk is compressed objects, which a text query does not match.
-                    const page = await collectVisible((at, limit) => fs.grep(query, target, {
-                        include,
-                        regex,
-                        ignoreCase,
-                        context,
-                        limit,
-                        offset: at
-                    }), (m) => m.path, DEFAULT_MAX_MATCHES, from, 2);
-                    if (page.items.length === 0)
-                        return page.crowded
-                            ? `every match for ${JSON.stringify(query)} from offset ${from} is inside .git, which is not searched. Add \`include\` (e.g. '**/*.ts') to search the working tree instead.`
-                            : `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`;
-                });
-            }
-        })
+        ...execTools(ctx),
+        ...fileTools(ctx),
+        ...findTools(ctx)
     };
 }
 /**
@@ -952,13 +238,13 @@ export function buildComputerTools(workspace, config, advisories) {
  */
 export function computerExec(config) {
     return async (command, options) => {
-        const env_3 = { stack: [], error: void 0, hasError: false };
+        const env_1 = { stack: [], error: void 0, hasError: false };
         try {
             // The caller forwards its execution's runtime state opaquely; only this side
             // knows the key it might carry. That is what lets `/repo` reach a subagent's
             // shared workspace without importing anything from here.
             const name = workspaceNameFromRuntime(options?.runtime) ?? config.workspaceName();
-            const ws = __addDisposableResource(env_3, await openWorkspace(config.binding.get(config.binding.idFromName(name))), false);
+            const ws = __addDisposableResource(env_1, await openWorkspace(config.binding.get(config.binding.idFromName(name))), false);
             const env = options?.env
                 ? Object.fromEntries(Object.entries(options.env).filter((entry) => entry[1] !== undefined))
                 : undefined;
@@ -970,7 +256,7 @@ export function computerExec(config) {
             // decide a tree is clean, and reads a sha out of it to push — all of which
             // need `stdout` to carry the answer alone, with git's diagnostics on the
             // channel git put them on.
-            const handle = __addDisposableResource(env_3, await ws.runtime.exec(withShell(command, config.shell), {
+            const handle = __addDisposableResource(env_1, await ws.runtime.exec(withShell(command, config.shell), {
                 cwd: options?.cwd ?? config.cwd ?? DEFAULT_CWD,
                 encoding: "utf8",
                 timeoutMs,
@@ -994,12 +280,12 @@ export function computerExec(config) {
                 exitCode: result.exitCode
             };
         }
-        catch (e_3) {
-            env_3.error = e_3;
-            env_3.hasError = true;
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
         }
         finally {
-            __disposeResources(env_3);
+            __disposeResources(env_1);
         }
     };
 }
@@ -1007,15 +293,13 @@ export function computer(config) {
     // Resolved per call, not memoized: `workspaceName` is a thunk precisely
     // because the name is not knowable at construction, and a stale stub would
     // silently route a second caller's commands into the first caller's files.
-    const host = (runtime) => {
-        const name = workspaceNameFromRuntime(runtime) ?? config.workspaceName();
-        return config.binding.get(config.binding.idFromName(name));
-    };
+    const nameOf = (runtime) => workspaceNameFromRuntime(runtime) ?? config.workspaceName();
+    const host = (runtime) => config.binding.get(config.binding.idFromName(nameOf(runtime)));
     const tools = (runtime) => buildComputerTools(() => openWorkspace(host(runtime)), config, 
     // No try/catch here: `buildComputerTools` fails the gate open itself, so
     // wrapping again would only make it look like the guarantee lives in two
     // places.
-    () => host(runtime).advisories());
+    () => host(runtime).advisories(), () => openWorkspaceFs(host(runtime)), () => nameOf(runtime));
     return definePlugin({
         key: "computer",
         mainAgentTools: () => tools(),
@@ -1033,13 +317,13 @@ export function computer(config) {
             // The reason to prefer them is the one thing the model cannot infer from a
             // tool description: these read the durable workspace directly, so they are
             // the only tools that still answer while the container is unavailable.
-            "Search with `sb_grep` and `sb_ls` rather than running `grep` or `find` through `sb_exec`. They read the workspace directly, so they keep working while the container is restarting or dependencies are still installing, and they come back with line numbers and a bounded result instead of a wall of text.",
+            "Search with `sb_grep` and `sb_ls` rather than running `grep` or `find` through `sb_exec`. They read the workspace directly, so they keep working while the container is restarting or an install is still running, and they come back with line numbers and a bounded result instead of a wall of text.",
             "Command output is truncated from the middle when large, so run targeted commands and read specific files rather than printing everything.",
             // Both halves of this matter and they pull in opposite directions, which
             // is why they are stated together rather than left for the model to work
             // out from a confusing result.
             "The checkout is durable: it survives between tasks and is still there after the container restarts, so it may already contain work from an earlier task — check before assuming it is empty.",
-            "`node_modules` is the exception. It lives only in the container, so it is rebuilt whenever the container restarts, and the file tools cannot see inside it — use `sb_exec` to read a dependency's source.",
+            "`node_modules` is not durable: it lives on the container's disk, so a new container reinstalls it, and the file tools cannot see inside it — use `sb_exec` there. It is a mount point, so `rm -rf node_modules` fails; `npm ci` clears it itself.",
             // Stated up front rather than left to a refusal, so the model does not spend
             // a turn discovering it. The destination matters as much as the rule: a
             // prohibition with nowhere to go gets worked around.
@@ -1047,3 +331,31 @@ export function computer(config) {
         ].join("\n")
     });
 }
+// --- the host half ----------------------------------------------------------
+/**
+ * The Durable Object everything above talks to.
+ *
+ * `./host/` is a directory rather than a subpath of its own, and that is the
+ * point: one capability is one import path, so a consumer cannot install the
+ * tools and miss the object they address. The two halves have opposite bundle
+ * costs — an agent that only calls `sb_exec` carries no container backend and no
+ * isomorphic-git — and `"sideEffects": false` is what keeps that true, since
+ * nothing here references the host unless the consumer does.
+ *
+ * The dependency runs one way for a mechanical reason: `./host/` imports the
+ * leaf modules beside this file, never this barrel, because this barrel
+ * re-exports `./host/` and a cycle through a module that builds a class at
+ * import time is a base that evaluates `undefined`.
+ */
+export { WorkspaceObjectBase, WORKSPACE_DIR, workspaceName } from "./host/workspace.js";
+// The dependency install, exported because a host that wants to report on one —
+// or a spec that drives it — needs the type, not because anything but
+// `./host/workspace.ts` constructs it.
+export { InstallJob } from "./host/install-job.js";
+// The pull the library owns no alarm for. Its constants are exported because a
+// host deferring to a drain has to back off at the same rate this does.
+export { WorkspaceSync, SYNC_DRAIN_BUDGET_MS, SYNC_DRAIN_RESUME_MS, SYNC_DRAIN_MAX_BACKOFF_MS, syncRetryDelayMs } from "./host/sync.js";
+// `TRUST_CA_COMMAND` is exported so a host can assert what its image will be
+// asked to run — see the file for why this cannot live in an entrypoint.
+export { ContainerTrust, TRUST_CA_COMMAND } from "./host/ca-trust.js";
+export { WorkspaceGitHost } from "./host/git-host.js";