@dynamicagents/plugins 0.16.1 → 0.18.0

package/README.md

@@ -38,7 +38,7 @@ export class Coder extends StepAgent<Env> {
 
   override getPlugins() {
     return [
-      browser({ binding: this.env.BROWSER }),
+      browser({ binding: this.env.BROWSER, loader: this.env.LOADER }),
       computer({ shell: "bash" }),
       repo(repoConfig(this.env))
     ];
@@ -66,9 +66,9 @@ plugin to the tools an install names.
 
 | Subpath                            | What it adds                                                                                              | Needs                                              |
 | ---------------------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
-| [`/browser`](src/browser/)         | Read web pages via Browser Rendering Quick Actions                                                        | `BROWSER` (paid plan)                              |
+| [`/browser`](src/browser/)         | Drive a persistent browser by writing code, over Browser Run                                              | `BROWSER` (paid plan), `LOADER`                    |
 | [`/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/browser/index.d.ts

@@ -1,28 +1,25 @@
 import type { AgentPlugin } from "@dynamicagents/core";
-import type { QuickActionToolName } from "agents/browser/ai";
-import type { QuickActionBinding, QuickActionCommonOptions } from "agents/browser";
+import type { BrowserBinding, BrowserRunOptions } from "agents/browser";
 export interface BrowserConfig {
     /**
      * The `BROWSER` binding. Browser Rendering is a **paid-plan** feature, and
      * `wrangler dev` needs `remote: true` to reach it.
      */
-    binding: QuickActionBinding;
+    binding: BrowserBinding;
     /**
-     * Character ceiling per result. Defaults to 20,000 — well under the SDK's own
-     * 50,000, because a page that fills a small chat model's context window costs
-     * it the conversation it was reading the page for.
+     * The `LOADER` binding, declared as `"worker_loaders": [{ "binding":
+     * "LOADER" }]`. Each call gets a fresh Dynamic Worker to run the model's
+     * code in, with no network access of its own.
      */
-    maxChars?: number;
+    loader: WorkerLoader;
+    /** How long one call may take, in milliseconds. The SDK defaults to 60,000. */
+    timeoutMs?: number;
     /**
-     * Which tools to expose. Defaults to the SDK's text-returning set; `content`
-     * (raw HTML) stays opt-in because it is large and rarely what a model wants.
+     * Browser Run launch options: how long an idle browser lives, hostname
+     * guardrails, session recording, internal hostnames. Fixed when the browser
+     * starts rather than per call, and host-supplied, so the model never sees or
+     * chooses any of it.
      */
-    actions?: QuickActionToolName[];
-    /**
-     * Browser Rendering options merged into every request — cookies, auth headers,
-     * viewport. Host-supplied and never exposed to the model, which only ever
-     * chooses the page and the action-specific fields.
-     */
-    options?: QuickActionCommonOptions;
+    provider?: BrowserRunOptions;
 }
 export declare function browser(config: BrowserConfig): AgentPlugin;

package/dist/browser/index.js

@@ -1,42 +1,104 @@
 import { definePlugin } from "@dynamicagents/core";
-import { createQuickActionTools } from "agents/browser/ai";
+import { Browser, DurableBrowserSessionStore, browserRun } from "agents/browser";
+import { browserTool } from "agents/browser/ai-sdk";
 /**
- * `@dynamicagents/plugins/browser` — read the web, via Cloudflare Browser Rendering
- * Quick Actions.
+ * `@dynamicagents/plugins/browser` — drive a real browser, via Cloudflare
+ * Browser Run.
  *
- * Four tools (`browser_markdown`, `browser_extract`, `browser_links`,
- * `browser_scrape`), the same for whichever agent installs the plugin: a parent
- * reads a page to answer a question directly, and a research sub-agent reads a
- * dozen of them.
+ * One tool, `browser`: the model writes JavaScript that drives a persistent
+ * browser over CDP, and that code runs in a Dynamic Worker with no network of
+ * its own. The browser outlives each call, so tabs, cookies and logins carry
+ * over between them, and the model never starts, closes or resets it.
  *
- * The binding is closed over at instantiation, so it is never model input.
+ * The binding and the loader are closed over at instantiation, so neither is
+ * ever model input.
+ */
+/**
+ * The browser's name in its own store. Two `Browser` objects on one Durable
+ * Object need different names, so this says which one is the plugin's rather
+ * than taking the SDK's default and colliding with a host that also built one.
+ */
+const BROWSER_NAME = "browser";
+/**
+ * What the model is told about the domain. Deliberately *not* the `browser.*`
+ * function reference: `browserTool` puts that in the tool's own description and
+ * keeps it in step with the SDK, and a copy here would be a second home for
+ * someone else's text. What is left is what this plugin knows and the SDK
+ * cannot: when reaching for a browser is the right move at all.
  */
-/** How many characters of a page result the model is allowed to see. */
-const DEFAULT_MAX_CHARS = 20_000;
 const CONTEXT = [
-    "You can read web pages directly:",
-    "- `browser_markdown` fetches a page and returns it as Markdown. This is the default — use it first.",
-    "- `browser_extract` pulls structured fields out of a page when you know what you are looking for.",
-    "- `browser_links` lists a page's links, for following a trail.",
-    "- `browser_scrape` returns the text of specific CSS selectors.",
-    "Results are truncated to protect your context window, so prefer a specific page over a search-results page, and extract rather than reading in full when you already know the fields you need."
+    "You can drive a real browser by writing JavaScript, with the `browser` tool. The tool's own description carries the API; what matters in choosing it:",
+    "- The browser is **persistent**. A later call lands on the same page, logged in, with the same cookies. Navigate in one call and read in the next rather than rebuilding state each time.",
+    "- Because it is persistent, read the page before acting on it. A call that submits a form or clicks through a checkout may be a repeat of one that already succeeded, and the page in front of you is the evidence of which.",
+    "- Prefer one call that does several steps over several calls that each do one: every call pays a round trip to the browser, and the page is still there either way.",
+    "- Return the part of the page you need rather than its whole text or markup. The tool's rules say where the ceiling is.",
+    "- A plain HTTP fetch is cheaper than a browser. Reach for this when a page needs rendering, a session, or interaction."
 ].join("\n");
 export function browser(config) {
-    const { binding, maxChars = DEFAULT_MAX_CHARS, actions, options } = config;
+    const { binding, loader, timeoutMs, provider } = config;
+    /**
+     * One `Browser` per installing object, and the lock is why.
+     *
+     * `browserTool` opens every run as a locking session, so runs in one scope
+     * wait for each other rather than driving one tab at once. But the SDK keeps
+     * its lock queues in a `WeakMap` keyed by the **`Browser` object itself**, so
+     * two instances over the same stored session hold two unrelated locks and
+     * serialise nothing. `getTools()` runs per turn, so a fresh `Browser` each
+     * time would leave overlapping turns in one object free to navigate each
+     * other's page.
+     *
+     * Keyed on the installing object's storage, which is the same granularity the
+     * SDK's locks have ("per isolate, which is per Durable Object"), and weak so
+     * an evicted object's browser handle goes with it. A `WeakMap` rather than one
+     * slot because nothing stops a host from hoisting this plugin to module scope
+     * and sharing it between objects in one isolate.
+     */
+    const browsers = new WeakMap();
+    const browserFor = (storage) => {
+        const known = browsers.get(storage);
+        if (known !== undefined)
+            return known;
+        const made = new Browser({
+            name: BROWSER_NAME,
+            provider: browserRun(binding, provider),
+            // **The store is what keeps this out of the host's Lifecycle.** A
+            // `Browser` with no store defaults to one over the host object's storage
+            // and requires `Lifecycle.use()` to install it, which a plugin has no way
+            // to ask for: the contract offers tools, actions, context and `requires`
+            // and nothing else. Passing the store explicitly is the SDK's own answer,
+            // and it is what lets this capability stay whole inside the plugin.
+            store: new DurableBrowserSessionStore(storage)
+        });
+        browsers.set(storage, made);
+        return made;
+    };
     return definePlugin({
         name: "browser",
-        // Built per call: the SDK returns a fresh ToolSet each time, and a tool
-        // object is not obviously safe to share across two concurrent executions.
-        tools: () => createQuickActionTools({
-            browser: binding,
-            maxChars,
-            ...(actions ? { actions } : {}),
-            ...(options ? { options } : {})
+        // **No `scope`.** A scope separates callers sharing one browser, and there
+        // is only ever one here: the record lives in the installing object's own
+        // storage, a parent object is keyed by its caller, and a sub-agent runs in
+        // its own facet with storage of its own. Naming a scope would imply an
+        // isolation the store already provides, and the default one still locks.
+        //
+        // **Nothing truncates here**, and the tool is handed over as the SDK built
+        // it. `browserTool` bounds its own output in two places: `execute` cuts the
+        // result and the error *structurally*, leaving valid JSON of the original
+        // shape with the largest values cut first and markers where content went,
+        // and `toModelOutput` then redacts base64 payloads, renders a screenshot as
+        // a note, and bounds the logs the same way. Wrapping either to add a flat
+        // ceiling of our own would collapse that JSON into a string, which is
+        // strictly worse than the bound it would be enforcing.
+        tools: (ctx) => ({
+            browser: browserTool({
+                browser: browserFor(ctx.storage),
+                loader,
+                ...(timeoutMs === undefined ? {} : { timeoutMs })
+            })
         }),
         context: [{ provider: { get: async () => CONTEXT } }],
-        // A plugin cannot add its own wrangler binding, so declaring it turns a
+        // A plugin cannot add its own wrangler binding, so declaring them turns a
         // missing one into a startup error naming this plugin, rather than a failed
         // tool call inside a request someone is waiting on.
-        requires: { bindings: ["BROWSER"] }
+        requires: { bindings: ["BROWSER", "LOADER"] }
     });
 }

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.317";

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.317";

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) } }]
     });
 }