@dynamicagents/plugins 0.16.0 → 0.17.0

package/README.md

@@ -68,7 +68,7 @@ plugin to the tools an install names.
 | ---------------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
 | [`/browser`](src/browser/)         | Read web pages via Browser Rendering Quick Actions                                                        | `BROWSER` (paid plan)                              |
 | [`/claude-code`](src/claude-code/) | Sub-agents whose model is a Claude Code session in a sandbox                                              | one or more `claude setup-token` credentials       |
-| [`/computer`](src/computer/)       | An agent's tools over a sandbox — `bash`, `grep`, `edit` — and the workspace Think's file tools use       | a `/sandbox` object                                |
+| [`/computer`](src/computer/)       | An agent's tools over a sandbox — `exec`, `grep`, `edit` — and the workspace Think's file tools use       | a `/sandbox` object                                |
 | [`/repo-github`](src/repo-github/) | Clone, commit, push a branch, open a pull request on GitHub — over any container                          | `GITHUB_TOKEN`                                     |
 | [`/sandbox`](src/sandbox/)         | A container whose disk is the checkout, driven from a Durable Object through `agents`' `ContainerHarness` | `@cloudflare/sandbox`, an image running its daemon |
 | [`/scratch`](src/scratch/)         | A throwaway git repository with no remote, for work that needs a container but no checkout                | —                                                  |

package/dist/claude-code/cards.d.ts

@@ -48,10 +48,15 @@ export declare function toolResultCard(event: ToolResultEvent): Card;
 export declare function thinkingCard(durationMs: number | undefined, messageId: string | undefined): Card;
 /** A session starting — every exec, a resume or a follow-up included. */
 export declare function initCard(event: InitEvent): Card;
-/** A session's end, with what its `result` line says about it. */
+/**
+ * A session's end, with what its `result` line says about it. A session the API
+ * failed reports `success` as its subtype, so the card names the API instead.
+ */
 export declare function resultCard(result: ClaudeCodeResult): Card;
 /** A session its run gave up on before reading its end, and why. */
 export declare function lostCard(why: string): Card;
 /** A session's container lost mid-turn, and the session resuming in a new one. */
 export declare function containerLostCard(reason: string): Card;
+/** A session the API failed, resuming after `waitMs`. */
+export declare function apiErrorCard(error: string, waitMs: number): Card;
 export {};

package/dist/claude-code/cards.js

@@ -241,11 +241,19 @@ export function initCard(event) {
     ].filter(Boolean);
     return { text: parts.join(" · "), detail: { title: "Session" } };
 }
-/** A session's end, with what its `result` line says about it. */
+/**
+ * A session's end, with what its `result` line says about it. A session the API
+ * failed reports `success` as its subtype, so the card names the API instead.
+ */
 export function resultCard(result) {
     const failed = result.isError || result.subtype !== "success";
+    const why = result.subtype !== "success"
+        ? result.subtype
+        : result.apiErrorStatus === null
+            ? "API error"
+            : `API ${result.apiErrorStatus}`;
     const parts = [
-        failed ? `Session failed (${result.subtype})` : "Session finished",
+        failed ? `Session failed (${why})` : "Session finished",
         result.numTurns
             ? `${result.numTurns} turn${result.numTurns === 1 ? "" : "s"}`
             : undefined,
@@ -283,6 +291,17 @@ export function containerLostCard(reason) {
         }
     };
 }
+/** A session the API failed, resuming after `waitMs`. */
+export function apiErrorCard(error, waitMs) {
+    return {
+        text: `Model call failed — the session resumes in ${duration(waitMs)}`,
+        detail: {
+            title: "Session",
+            status: "error",
+            sections: [section("Why", error, "text")]
+        }
+    };
+}
 function duration(ms) {
     const s = Math.round(ms / 1000);
     if (s < 60)

package/dist/claude-code/model.d.ts

@@ -64,6 +64,8 @@ export interface SessionOutcome {
  *   `container_lost`, and this submits the next attempt to the same harness
  *   session, whose CLI conversation the harness kept: the session is told what
  *   happened, not briefed again.
+ * - **So does an API error the CLI gave up on** — see {@link transientApiError}
+ *   — after a backoff.
  */
 /** The sandbox RPCs a run uses. */
 export interface SandboxRuns {
@@ -156,4 +158,6 @@ export interface ClaudeCodeModelOptions {
 export declare const DEFAULT_TIMEOUT_MS: number;
 /** What a session is told when it resumes in a new container. */
 export declare const CONTAINER_LOST_PROMPT: string;
+/** What a session is told when it resumes after an API error. */
+export declare const API_ERROR_PROMPT: string;
 export declare function claudeCodeModel(options: ClaudeCodeModelOptions): LanguageModelV3;

package/dist/claude-code/model.js

@@ -1,7 +1,7 @@
 import { isPlatformTransientError } from "agents";
 import { SANDBOX_CONTRACT } from "../sandbox/constants.js";
 import { withRunHeader } from "../sandbox/header.js";
-import { containerLostCard, lostCard } from "./cards.js";
+import { apiErrorCard, containerLostCard, lostCard } from "./cards.js";
 import { decodeNote, decodeRunEnd, decodeSessionId } from "./harness-wire.js";
 import { lastUserText, reportingModel } from "./language-model.js";
 /**
@@ -22,6 +22,17 @@ export const CONTAINER_LOST_PROMPT = "The container this session was running in
 const LOST_RESUBMITS = 3;
 /** Why an operation settled that a new attempt may get past. */
 const LOST_REASONS = new Set(["container_lost", "container_unavailable"]);
+/** What a session is told when it resumes after an API error. */
+export const API_ERROR_PROMPT = "Your last response was cut off by an API error, and the session has " +
+    "resumed. What you completed before it is kept, but a tool call it " +
+    "interrupted never ran. Carry on with the task from your last completed step.";
+/**
+ * Resumes after an API error. One that recurs on every attempt would otherwise
+ * be resumed, a full-context call each time, until the session's limit.
+ */
+const API_ERROR_RESUMES = 5;
+/** The first resume's wait, doubled for each after it. Every wait follows the CLI's own retries. */
+const API_ERROR_BACKOFF_MS = 15_000;
 /** Polls in a row a note may fail to file before it is given up on. */
 const NOTE_TRIES = 3;
 /** The sandbox's own ceiling on one poll's wait. */
@@ -122,6 +133,12 @@ export function claudeCodeModel(options) {
             await file(`${operationId}:lost`, card.text, card.detail);
             throw reason;
         };
+        /** Stop the session, unless it is still within its limit. */
+        const withinLimit = async (operationId, startedAt) => {
+            if (Date.now() - startedAt <= timeoutMs)
+                return;
+            await stop(operationId, new Error(`the session ran past its limit of ${Math.round(timeoutMs / 60_000)} minutes`));
+        };
         /**
          * One step of the run, to its end: the brief's session, or the follow-up.
          * Both count against one limit, from the session's first submission.
@@ -161,11 +178,21 @@ export function claudeCodeModel(options) {
             }
             for (;;) {
                 const operationId = `${runId}:${step}:a${state.attempt}`;
+                if (state.retryAt !== undefined && state.retryAt > Date.now()) {
+                    await untilAborted(sleep(state.retryAt - Date.now()), signal).catch(() => undefined);
+                    if (signal?.aborted)
+                        await stop(operationId, signal.reason ?? new Error("the session was stopped"));
+                }
+                // Before the submission, which starts a model call: a turn recovered
+                // past its limit would otherwise start one only for the poll to stop it.
+                await withinLimit(operationId, state.startedAt);
                 // A resubmission that reached the CLI is told what happened, in the
                 // conversation it already had; one that never did is the step again.
                 const { fork: _fork, ...resumed } = header;
                 const text = state.attempt > 0 && state.sessionId
-                    ? withRunHeader(resumed, CONTAINER_LOST_PROMPT)
+                    ? withRunHeader(resumed, state.resumeWith === "api-error"
+                        ? API_ERROR_PROMPT
+                        : CONTAINER_LOST_PROMPT)
                     : withRunHeader(header, prompt);
                 try {
                     await rpc((sandbox) => sandbox.submit(runId, text, operationId));
@@ -182,9 +209,7 @@ export function claudeCodeModel(options) {
                 while (!result) {
                     if (signal?.aborted)
                         await stop(operationId, signal.reason ?? new Error("the session was stopped"));
-                    if (Date.now() - state.startedAt > timeoutMs) {
-                        await stop(operationId, new Error(`the session ran past its limit of ${Math.round(timeoutMs / 60_000)} minutes`));
-                    }
+                    await withinLimit(operationId, state.startedAt);
                     let polled;
                     try {
                         polled = await rpc((sandbox) => sandbox.poll(runId, operationId, POLL_WAIT_MS, state.from));
@@ -232,6 +257,26 @@ export function claudeCodeModel(options) {
                     if (!end?.result) {
                         throw new Error(`claude-code: the sandbox settled the session with no end it could read: ${String(result.text).slice(0, 200)}`);
                     }
+                    const apiErrors = state.apiErrors ?? 0;
+                    const waitMs = API_ERROR_BACKOFF_MS * 2 ** apiErrors;
+                    const retryAt = Date.now() + waitMs;
+                    if (transientApiError(end.result) &&
+                        apiErrors < API_ERROR_RESUMES &&
+                        retryAt - state.startedAt < timeoutMs &&
+                        !signal?.aborted) {
+                        console.warn("[claude-code] the session ended on an API error — resuming", { runId, operationId, error: end.result.text, waitMs });
+                        const card = apiErrorCard(end.result.text, waitMs);
+                        await file(`${operationId}:api-error`, card.text, card.detail);
+                        await save({
+                            ...state,
+                            attempt: state.attempt + 1,
+                            from: 0,
+                            apiErrors: apiErrors + 1,
+                            resumeWith: "api-error",
+                            retryAt
+                        });
+                        continue;
+                    }
                     // No code is a process a signal ended.
                     return sessionEnd(end, end.exitCode ?? -1, state.sessionId);
                 }
@@ -241,7 +286,8 @@ export function claudeCodeModel(options) {
                     return sessionEnd(end, end.exitCode ?? 1, state.sessionId);
                 if (signal?.aborted)
                     await stop(operationId, signal.reason ?? new Error("the session was stopped"));
-                if (!LOST_REASONS.has(reason) || state.attempt >= LOST_RESUBMITS) {
+                const lost = state.lost ?? 0;
+                if (!LOST_REASONS.has(reason) || lost >= LOST_RESUBMITS) {
                     const card = lostCard(reason || "the sandbox gave no reason");
                     await file(`${operationId}:lost`, card.text, card.detail);
                     throw new Error(`claude-code: the sandbox ended the session: ${reason || "no reason given"}`);
@@ -253,7 +299,13 @@ export function claudeCodeModel(options) {
                 });
                 const card = containerLostCard(reason);
                 await file(`${operationId}:container-lost`, card.text, card.detail);
-                await save({ ...state, attempt: state.attempt + 1, from: 0 });
+                await save({
+                    ...state,
+                    attempt: state.attempt + 1,
+                    from: 0,
+                    lost: lost + 1,
+                    resumeWith: "container-lost"
+                });
             }
         };
         /** File one polled message's note, or read the session id it carries. */
@@ -335,6 +387,21 @@ export function claudeCodeModel(options) {
     };
     return reportingModel(options.model ?? "claude-code", run);
 }
+/**
+ * Whether a step's end is an API error another attempt may get past.
+ *
+ * The CLI retries a failed call itself, but never one cut off after a block of
+ * the response was complete, since a resend could run a tool call twice; its
+ * documented recovery is to resume the session. No status is the transport — a
+ * dropped or stalled stream, a body that would not decompress — and a 5xx or
+ * 529 the API's own. A 4xx is the request's, 429 included: the egress has
+ * already moved the credential pool on (`./egress.ts`).
+ */
+function transientApiError(result) {
+    if (!result.isError || !result.text.startsWith("API Error"))
+        return false;
+    return result.apiErrorStatus === null || result.apiErrorStatus >= 500;
+}
 function sessionEnd(end, exitCode, seen) {
     const sessionId = end.sessionId ?? seen;
     return {

package/dist/claude-code/verified.d.ts

@@ -12,4 +12,4 @@
  * and the capture move together. AGENTS.md's "Updating Claude Code" is the
  * procedure.
  */
-export declare const VERIFIED_CLAUDE_CODE_VERSION = "2.1.296";
+export declare const VERIFIED_CLAUDE_CODE_VERSION = "2.1.310";

package/dist/claude-code/verified.js

@@ -12,4 +12,4 @@
  * and the capture move together. AGENTS.md's "Updating Claude Code" is the
  * procedure.
  */
-export const VERIFIED_CLAUDE_CODE_VERSION = "2.1.296";
+export const VERIFIED_CLAUDE_CODE_VERSION = "2.1.310";

package/dist/computer/client.d.ts

@@ -27,8 +27,11 @@ export interface FoundEntry {
     type: "file" | "dir";
 }
 export interface StatResult {
+    name: string;
     size: number;
     mtime: number;
+    /** The file's Linux mode, as the container reports it. */
+    mode: number;
     isFile: boolean;
     isDirectory: boolean;
     isSymbolicLink: boolean;
@@ -39,6 +42,7 @@ export interface DirEntry {
     mtime?: number;
     isFile: boolean;
     isDirectory: boolean;
+    isSymbolicLink?: boolean;
 }
 export interface ComputerFs {
     readFile(path: string): Promise<ReadableStream<Uint8Array>>;
@@ -54,7 +58,11 @@ export interface ComputerFs {
         exclude?: string[];
     }): Promise<FoundEntry[]>;
     grep(pattern: string, path: string, options?: GrepOptions): Promise<GrepMatch[]>;
-    writeFile(path: string, content: string): Promise<void>;
+    /**
+     * Bytes as well as text: Think writes evicted media through this, and the
+     * `read` tool hands the model back an image it can look at again.
+     */
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
     mkdir(path: string, options?: {
         recursive?: boolean;
     }): Promise<void>;

package/dist/computer/context.js

@@ -180,7 +180,7 @@ export function computerContext(workspace, config, advisories, lockScope) {
      * only recover from what it is told, so this returns the sentence rather than
      * throwing it.
      *
-     * `bash` deliberately does not use it: it logs, and carries an install
+     * `exec` deliberately does not use it: it logs, and carries an install
      * warning through the failure path — a bespoke catch saying something this
      * cannot.
      */

package/dist/computer/index.d.ts

@@ -4,7 +4,7 @@ import type { SandboxAdvisory } from "../sandbox/advisory.js";
 import type { ComputerClient } from "./client.js";
 /**
  * `@dynamicagents/plugins/computer` — an agent's tools over a `/sandbox`
- * container: `bash`, `grep` and `edit`, and `computerWorkspace`, the agent's own
+ * container: `exec`, `grep` and `edit`, and `computerWorkspace`, the agent's own
  * `this.workspace`, which Think's `read`, `write`, `delete`, `find` and `list`
  * go through.
  *
@@ -14,7 +14,7 @@ import type { ComputerClient } from "./client.js";
  * backend.
  *
  * The agent's own workspace has to be the sandbox's — `computerWorkspace` — or
- * Think's `read` and `write` would work on a different tree from `bash`. The
+ * Think's `read` and `write` would work on a different tree from `exec`. The
  * plugin refuses to start otherwise; see `./proxy.ts`. `paths.ts` owns what a
  * path may be and what walks drop.
  */
@@ -24,7 +24,7 @@ import type { ComputerClient } from "./client.js";
  * exports must not move when the files behind it do.
  */
 export { isGitInternal, WALK_SKIPS } from "./paths.js";
-export { packBlocks, renderGrepMatches, renderResult } from "./render.js";
+export { packBlocks, renderGrepMatches } from "./render.js";
 export { execGate, needsDependencies, writeGate, type ExecGate } from "./gate.js";
 export { sandboxClient, computerWorkspace, type SandboxComputerConfig, type SandboxComputerHost } from "./sandbox.js";
 export type { ComputerClient } from "./client.js";
@@ -60,10 +60,14 @@ export interface ComputerToolsConfig {
      * characters far better than they track UTF-8 bytes. So the name moved to meet
      * the implementation rather than the other way round.
      *
+     * `exec` is the exception, and spends this as **bytes**: the ceiling there is
+     * Computer's own tool's, which takes no character form. The two coincide
+     * until the output is not ASCII, where the model is shown a little less than
+     * this asked for.
      */
     maxOutputChars?: number;
     /**
-     * How long `bash` waits for a running dependency install before giving the
+     * How long `exec` waits for a running dependency install before giving the
      * turn back. Defaults to 90 seconds.
      *
      * Bounded rather than open-ended because the wait happens inside a turn, and
@@ -78,8 +82,8 @@ export interface ComputerToolsConfig {
      *
      * ## Put no secret here
      *
-     * *Every* command gets this environment, and `bash`'s command is written by
-     * the model: `bash("printenv")` prints all of it, and so does a
+     * *Every* command gets this environment, and `exec`'s command is written by
+     * the model: `exec("printenv")` prints all of it, and so does a
      * `postinstall` script in a repository the agent was asked to clone, which
      * nobody vetted.
      *

package/dist/computer/index.js

@@ -6,7 +6,7 @@ import { fileTools } from "./tools-file.js";
 import { grepTools } from "./tools-grep.js";
 /**
  * `@dynamicagents/plugins/computer` — an agent's tools over a `/sandbox`
- * container: `bash`, `grep` and `edit`, and `computerWorkspace`, the agent's own
+ * container: `exec`, `grep` and `edit`, and `computerWorkspace`, the agent's own
  * `this.workspace`, which Think's `read`, `write`, `delete`, `find` and `list`
  * go through.
  *
@@ -16,7 +16,7 @@ import { grepTools } from "./tools-grep.js";
  * backend.
  *
  * The agent's own workspace has to be the sandbox's — `computerWorkspace` — or
- * Think's `read` and `write` would work on a different tree from `bash`. The
+ * Think's `read` and `write` would work on a different tree from `exec`. The
  * plugin refuses to start otherwise; see `./proxy.ts`. `paths.ts` owns what a
  * path may be and what walks drop.
  */
@@ -26,7 +26,7 @@ import { grepTools } from "./tools-grep.js";
  * exports must not move when the files behind it do.
  */
 export { isGitInternal, WALK_SKIPS } from "./paths.js";
-export { packBlocks, renderGrepMatches, renderResult } from "./render.js";
+export { packBlocks, renderGrepMatches } from "./render.js";
 export { execGate, needsDependencies, writeGate } from "./gate.js";
 export { sandboxClient, computerWorkspace } from "./sandbox.js";
 /**
@@ -42,18 +42,35 @@ export function buildComputerTools(workspace, config, advisories, lockScope) {
         ...grepTools(ctx)
     };
 }
-/** What the model is told about the container, once per turn. */
-const CONTEXT = [
-    "You have a Linux container with a shell, a package manager and network access:",
-    "- `bash` runs any shell command — builds, tests, installs, git.",
-    "- `read` / `write` / `edit` / `delete` work on files; `edit` replaces an exact unique string and is the right tool for a small change.",
-    "- `grep` searches file contents; `list` lists a directory; `find` finds files by glob.",
-    "Search with `grep` and `find` rather than running them through `bash`: 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.",
-    "The checkout is the container's own disk, and it is kept between tasks: a stopped container starts again from it, so it may already contain work from an earlier task — check before assuming it is empty.",
-    "`node_modules` is on that disk beside the checkout and is kept with it. The file tools leave it out — use `bash` there.",
-    "`.git` is off limits to these tools, and searches and recursive listings skip it. It is git's internal state — reading it tells you less than the repository tools do, and writing it corrupts the checkout. Repository work goes through the repo tools (`repo_status`, `repo_diff`, `repo_commit`, `repo_push`); if a task needs git state you cannot get that way, say so in your result rather than reaching into `.git` yourself."
-].join("\n");
+/**
+ * What the model is told about the container, once per turn.
+ *
+ * A function of the config rather than a constant, because two of the
+ * guarantees here are the configured shell's: without one, a pipeline reports
+ * its last stage and a promise of first-failure reporting would be false.
+ */
+function contextFor(config) {
+    return [
+        "You have a Linux container with a shell, a package manager and network access:",
+        "- `exec` runs any shell command — builds, tests, installs, git.",
+        "- `read` / `write` / `edit` / `delete` work on files; `edit` replaces an exact unique string and is the right tool for a small change.",
+        "- `grep` searches file contents; `ls` lists a directory; `find` finds files by glob.",
+        "Search with `grep` and `find` rather than running them through `exec`: they come back with line numbers and a bounded result instead of a wall of text.",
+        "A command's output is cut to its last lines when it is large, so an error printed early in a long run is gone from what you read: run targeted commands, and read specific files rather than printing everything.",
+        // Two of these are the configured shell's, not this plugin's: `-o pipefail`
+        // is what makes a pipeline report its first failing stage, and without a
+        // shell the wrapper that would carry it does not exist. Promising it anyway
+        // is the failure `./shell.ts` documents at length — a model that cannot
+        // trust a piped exit code re-runs the whole gate to get one.
+        config.shell
+            ? "Do not pipe into `head` or `tail` to shorten output: it is already cut, and piping costs you the end you wanted. A pipeline reports its first failing stage, so a piped command reports its real failure — but `cmd | head` may report 141 when `head` closes the pipe early, which is not a failure of `cmd`."
+            : "Do not pipe into `head` or `tail` to shorten output: it is already cut, and piping costs you the end you wanted. A pipeline reports only its **last** stage, so `npm run check | cat` reports the `cat` and says nothing about the check: read the exit code of the command you care about rather than the pipe's.",
+        "The checkout is the container's own disk, and it is kept between tasks: a stopped container starts again from it, so it may already contain work from an earlier task — check before assuming it is empty.",
+        "`/workspace` holds one directory per checkout, plus directories of your own that are not part of any repository: `attachments/` keeps media taken out of the conversation, `fetched/` keeps fetched pages, `.agents/` keeps projected skills. A message that says a file was preserved at one of those paths means you can read it back. Searches from `/workspace` skip them; repository work happens inside a checkout.",
+        "`node_modules` is on that disk beside the checkout and is kept with it. The file tools leave it out — use `exec` there.",
+        "`.git` is off limits to these tools, and searches and recursive listings skip it. It is git's internal state — reading it tells you less than the repository tools do, and writing it corrupts the checkout. Repository work goes through the repo tools (`repo_status`, `repo_diff`, `repo_commit`, `repo_push`); if a task needs git state you cannot get that way, say so in your result rather than reaching into `.git` yourself."
+    ].join("\n");
+}
 /**
  * The container plugin over a `/sandbox` object. Its tools reach the sandbox
  * through the agent's own `computerWorkspace` — the one Think's `read` and
@@ -68,7 +85,7 @@ export function computer(config) {
             // so a missing workspace fails the start rather than a turn.
             const route = workspaceRoute(ctx.workspace());
             if (!route)
-                throw new PluginSetupError(`plugin "computer" runs \`bash\` in a container, but ${ctx.agentName}'s ` +
+                throw new PluginSetupError(`plugin "computer" runs \`exec\` in a container, but ${ctx.agentName}'s ` +
                     "workspace is not that container's, so Think's `read` and `write` " +
                     "would work on a different tree. Set it on the agent class: " +
                     "`override workspace = computerWorkspace(config, () => this.pluginContext().runtime())`.");
@@ -82,6 +99,6 @@ export function computer(config) {
             // two places.
             () => route.advisories(route.name()), route.name);
         },
-        context: [{ provider: { get: async () => CONTEXT } }]
+        context: [{ provider: { get: async () => contextFor(config) } }]
     });
 }

package/dist/computer/paths.d.ts

@@ -21,11 +21,35 @@
  */
 export declare function isGitInternal(path: string): boolean;
 /**
- * What every walk steps over, as directory names. Both the workspace's `glob`
+ * What every walk steps over, as directory names. Both the workspace's `find`
  * and the `grep` tool hand these on as `**\/<name>` exclusions, which prunes
  * them: no directory named here is descended into, so none costs a read.
  */
 export declare const WALK_SKIPS: readonly [".git", "node_modules"];
+/**
+ * The directories Think writes on its own account, directly under the
+ * workspace root: evicted media under `attachments/evicted/`, a fetch tool's
+ * spilled responses under `fetched/`, projected skills under `.agents/skills`.
+ * Think builds those paths from a root of its own and offers no way to move
+ * them, so a walk of the root reaches them.
+ *
+ * Pruned from a walk of the root and from nowhere else, which is what
+ * {@link walkSkips} spells: these are *names at the root*, not names anywhere,
+ * so a checkout with its own `attachments/` is still searched. A direct read is
+ * not refused either, because an eviction marker hands the model one of these
+ * paths and expects it to be readable.
+ */
+export declare const AGENT_OWNED: readonly ["attachments", "fetched", ".agents"];
+/**
+ * The exclusions one walk hands on, for a walk rooted at `directory` inside a
+ * workspace whose root is `root`.
+ *
+ * Every pattern is matched against the walked directory's *relative* path, so a
+ * root-anchored absolute pattern would match nothing. {@link AGENT_OWNED} is
+ * therefore relative to `directory` and only added when the walk starts at the
+ * root; {@link WALK_SKIPS} is a name at any depth.
+ */
+export declare function walkSkips(directory: string, root: string): string[];
 /**
  * The path check every file tool and every workspace call makes, before it
  * opens anything.
@@ -40,7 +64,7 @@ export declare const WALK_SKIPS: readonly [".git", "node_modules"];
  * actually happens is a model reaching into `.git/HEAD` to fix a merge.
  *
  * It is not containment, and this is the only place worth saying so. An agent
- * that can write files here almost always holds `bash` too, which reads and
+ * that can write files here almost always holds `exec` too, which reads and
  * writes `.git` directly.
  *
  * Symlinks are not resolved, for the same reason: a tracked

package/dist/computer/paths.js

@@ -10,6 +10,7 @@
  * Everything here is a string comparison: no filesystem, no `await`, which is
  * what lets {@link guardPath} run before a tool opens the workspace at all.
  */
+import { normalizeAbsolute } from "../sandbox/header.js";
 /** Whether any segment of `path` is exactly `segment`. */
 function hasSegment(path, segment) {
     return path.split("/").includes(segment);
@@ -27,15 +28,60 @@ export function isGitInternal(path) {
     return hasSegment(path, ".git");
 }
 /**
- * What every walk steps over, as directory names. Both the workspace's `glob`
+ * What every walk steps over, as directory names. Both the workspace's `find`
  * and the `grep` tool hand these on as `**\/<name>` exclusions, which prunes
  * them: no directory named here is descended into, so none costs a read.
  */
 export const WALK_SKIPS = [".git", "node_modules"];
+/**
+ * The directories Think writes on its own account, directly under the
+ * workspace root: evicted media under `attachments/evicted/`, a fetch tool's
+ * spilled responses under `fetched/`, projected skills under `.agents/skills`.
+ * Think builds those paths from a root of its own and offers no way to move
+ * them, so a walk of the root reaches them.
+ *
+ * Pruned from a walk of the root and from nowhere else, which is what
+ * {@link walkSkips} spells: these are *names at the root*, not names anywhere,
+ * so a checkout with its own `attachments/` is still searched. A direct read is
+ * not refused either, because an eviction marker hands the model one of these
+ * paths and expects it to be readable.
+ */
+export const AGENT_OWNED = ["attachments", "fetched", ".agents"];
+/**
+ * The exclusions one walk hands on, for a walk rooted at `directory` inside a
+ * workspace whose root is `root`.
+ *
+ * Every pattern is matched against the walked directory's *relative* path, so a
+ * root-anchored absolute pattern would match nothing. {@link AGENT_OWNED} is
+ * therefore relative to `directory` and only added when the walk starts at the
+ * root; {@link WALK_SKIPS} is a name at any depth.
+ */
+export function walkSkips(directory, root) {
+    const anywhere = WALK_SKIPS.map((segment) => `**/${segment}`);
+    return atRoot(directory, root)
+        ? [...anywhere, ...AGENT_OWNED.map((name) => `${name}/**`)]
+        : anywhere;
+}
+/**
+ * Whether a walk starts at the workspace root, by what the two paths mean
+ * rather than by how they are spelled.
+ *
+ * The directory is the model's to spell, and `/workspace/`, `/workspace/.` and
+ * `/workspace/repo/..` are all spellings it produces. Every one of them is this
+ * root to the sandbox, which normalises before it confines, so a comparison
+ * here that read them literally would answer no to a walk that then went ahead
+ * from the root and came back with the agent's own directories in it. The
+ * normaliser is {@link file://../sandbox/header.ts normalizeAbsolute}, shared
+ * with that confinement so the two cannot disagree.
+ */
+function atRoot(directory, root) {
+    const resolved = normalizeAbsolute(directory);
+    return resolved !== undefined && resolved === normalizeAbsolute(root);
+}
 /** The sentence a `node_modules` path gets. */
 function dependencyTreeNote(path, verb) {
     return (`${path} is inside node_modules, which ${verb} leaves out: it is installed ` +
-        `output, not source. Use bash there — \`cat\`, \`ls\`, \`rg\`.`);
+        `output, not source. Use exec there — \`cat\`, \`ls\`, \`rg\`.`);
 }
 /**
  * The sentence a `.git` path gets.
@@ -43,9 +89,9 @@ function dependencyTreeNote(path, verb) {
  * Names a route deliberately: a refusal with no destination is worse than no
  * refusal, because the model retries and then works around it.
  *
- * What it must never name is `bash`. That hands back the exact capability
+ * What it must never name is `exec`. That hands back the exact capability
  * being withheld, in the one place the model is already looking for a way around
- * it, with the tool's own authority behind it. `bash` is unguarded because a
+ * it, with the tool's own authority behind it. `exec` is unguarded because a
  * shell takes an opaque command string and pattern-matching git out of one is
  * neither reliable nor this guard's job — a fact about the implementation, not a
  * route to advertise.
@@ -72,7 +118,7 @@ function gitInternalNote(path, verb) {
  * actually happens is a model reaching into `.git/HEAD` to fix a merge.
  *
  * It is not containment, and this is the only place worth saying so. An agent
- * that can write files here almost always holds `bash` too, which reads and
+ * that can write files here almost always holds `exec` too, which reads and
  * writes `.git` directly.
  *
  * Symlinks are not resolved, for the same reason: a tracked

package/dist/computer/proxy.d.ts

@@ -1,4 +1,4 @@
-import type { WorkspaceLike } from "@cloudflare/think";
+import type { ThinkWorkspace } from "@cloudflare/think";
 import type { SandboxAdvisory } from "../sandbox/advisory.js";
 import type { ComputerClient } from "./client.js";
 /**
@@ -6,7 +6,7 @@ import type { ComputerClient } from "./client.js";
  *
  * Think's `read`, `write`, `edit` and `delete` run against whatever an agent's
  * workspace is, and the computer tools replace only the ones they name. So an
- * agent with a container and Think's default workspace would run `bash` in the
+ * agent with a container and Think's default workspace would run `exec` in the
  * container and `write` in its own SQLite, and nothing would say so. An agent
  * that installs the tools sets its workspace to `computerWorkspace`
  * (`./sandbox.ts`), and the plugin refuses to start without it — and reaches
@@ -28,4 +28,11 @@ export interface WorkspaceRoute {
 /** The route of a workspace {@link routedWorkspace} built, or `undefined`. */
 export declare function workspaceRoute(workspace: unknown): WorkspaceRoute | undefined;
 /** Think's file tools over `route`, carrying it for the computer tools to find. */
-export declare function routedWorkspace(route: WorkspaceRoute, cwd: string): WorkspaceLike;
+/**
+ * `root` is the sandbox's served root and never a working directory. The
+ * directories Think writes its own files into are fixed under that root, so
+ * anchoring their exclusions anywhere else both hides a checkout's own
+ * `attachments/` and leaves Think's in a search of the root: see
+ * {@link file://./paths.ts walkSkips}.
+ */
+export declare function routedWorkspace(route: WorkspaceRoute, root: string): ThinkWorkspace;