@dynamicagents/plugins 0.14.0 → 0.16.0

package/dist/computer/paths.d.ts

@@ -4,9 +4,8 @@
  * Each refused directory is also skipped by every walk, though the walk steps
  * over more than it refuses — see {@link WALK_SKIPS}. `.git` is refused as
  * policy: a model that edits `.git/HEAD` corrupts a checkout in a way that
- * surfaces much later. `node_modules` is refused as a fact: it lives on the
- * container's disk (see `../workspace/container-deps.ts`), so these tools, which read
- * the workspace, would find it empty.
+ * surfaces much later. `node_modules` is refused because it is installed
+ * output, not source: one walk into it is most of a checkout's files.
  *
  * 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.
@@ -21,33 +20,12 @@
  * `.github/` are untouched.
  */
 export declare function isGitInternal(path: string): boolean;
-/**
- * Where a session's own state lives inside a workspace, as a directory name.
- *
- * Every Claude Code session keeps its `CLAUDE_CONFIG_DIR` in a directory of
- * this name at the workspace root — the Durable Object's storage, so a
- * conversation outlives its container and a later session can continue it. See
- * {@link file://../claude-code/run.ts SESSION_CONFIG_DIR}.
- *
- * **Spelled here as well as in the plugin that sets the variable**, because the
- * module that has to step over it is the walk below, and neither may import the
- * other: `/computer` reaching into `/claude-code` would pull a whole plugin into
- * every agent that installs the file tools, and `/claude-code` reaches no other
- * subpath — `verify:exports` refuses both. A spec in `/claude-code` holds the
- * two spellings to one.
- */
-export declare const SESSION_STATE_DIR = ".claude-sessions";
 /**
  * What every walk steps over, as directory names. Both the workspace's `glob`
- * and the `grep` tool hand these to the store as `**\/<name>` exclusions, which
- * prunes them: no directory named here is descended into, so none costs a read.
- *
- * {@link SESSION_STATE_DIR} is here for a reason the refused directories do not
- * share: a transcript is a verbatim record of everything a session read, so a
- * walk that descended into it would answer a `grep` for a line of source with
- * the session that quoted it.
+ * 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", ".claude-sessions"];
+export declare const WALK_SKIPS: readonly [".git", "node_modules"];
 /**
  * The path check every file tool and every workspace call makes, before it
  * opens anything.

package/dist/computer/paths.js

@@ -4,9 +4,8 @@
  * Each refused directory is also skipped by every walk, though the walk steps
  * over more than it refuses — see {@link WALK_SKIPS}. `.git` is refused as
  * policy: a model that edits `.git/HEAD` corrupts a checkout in a way that
- * surfaces much later. `node_modules` is refused as a fact: it lives on the
- * container's disk (see `../workspace/container-deps.ts`), so these tools, which read
- * the workspace, would find it empty.
+ * surfaces much later. `node_modules` is refused because it is installed
+ * output, not source: one walk into it is most of a checkout's files.
  *
  * 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.
@@ -27,38 +26,16 @@ function hasSegment(path, segment) {
 export function isGitInternal(path) {
     return hasSegment(path, ".git");
 }
-/**
- * Where a session's own state lives inside a workspace, as a directory name.
- *
- * Every Claude Code session keeps its `CLAUDE_CONFIG_DIR` in a directory of
- * this name at the workspace root — the Durable Object's storage, so a
- * conversation outlives its container and a later session can continue it. See
- * {@link file://../claude-code/run.ts SESSION_CONFIG_DIR}.
- *
- * **Spelled here as well as in the plugin that sets the variable**, because the
- * module that has to step over it is the walk below, and neither may import the
- * other: `/computer` reaching into `/claude-code` would pull a whole plugin into
- * every agent that installs the file tools, and `/claude-code` reaches no other
- * subpath — `verify:exports` refuses both. A spec in `/claude-code` holds the
- * two spellings to one.
- */
-export const SESSION_STATE_DIR = ".claude-sessions";
 /**
  * What every walk steps over, as directory names. Both the workspace's `glob`
- * and the `grep` tool hand these to the store as `**\/<name>` exclusions, which
- * prunes them: no directory named here is descended into, so none costs a read.
- *
- * {@link SESSION_STATE_DIR} is here for a reason the refused directories do not
- * share: a transcript is a verbatim record of everything a session read, so a
- * walk that descended into it would answer a `grep` for a line of source with
- * the session that quoted it.
+ * 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", SESSION_STATE_DIR];
+export const WALK_SKIPS = [".git", "node_modules"];
 /** The sentence a `node_modules` path gets. */
 function dependencyTreeNote(path, verb) {
-    return (`${path} is inside node_modules, which lives on the container's disk rather ` +
-        `than in the workspace ${verb} works on. Use bash there — ` +
-        `\`cat\`, \`ls\`, \`rg\`.`);
+    return (`${path} is inside node_modules, which ${verb} leaves out: it is installed ` +
+        `output, not source. Use bash there — \`cat\`, \`ls\`, \`rg\`.`);
 }
 /**
  * The sentence a `.git` path gets.

package/dist/computer/proxy.d.ts

@@ -1,45 +1,31 @@
 import type { WorkspaceLike } from "@cloudflare/think";
-import type { WorkspaceHost } from "../workspace/open.js";
-import type { ComputerConfig } from "./index.js";
+import type { SandboxAdvisory } from "../sandbox/advisory.js";
+import type { ComputerClient } from "./client.js";
 /**
- * The container's workspace, as the agent's own `this.workspace`.
+ * The container's checkout, as the agent's own `this.workspace`.
  *
  * Think's `read`, `write`, `edit` and `delete` run against whatever an agent's
- * workspace is, and `computer()`'s tools replace only the ones it names. So an
+ * 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
  * container and `write` in its own SQLite, and nothing would say so. An agent
- * that installs `computer` sets this instead:
- *
- * ```ts
- * override workspace = computerWorkspace(config, () => this.pluginContext().runtime());
- * ```
- *
- * and `computer(config).tools(ctx)` refuses to start without it — and reaches
- * the workspace through it, so the tools and Think's file tools cannot resolve
+ * that installs the tools sets its workspace to `computerWorkspace`
+ * (`./sandbox.ts`), and the plugin refuses to start without it — and reaches
+ * the container through it, so the tools and Think's file tools cannot resolve
  * two different ones.
- *
- * Built on the workspace's own filesystem, not on `@cloudflare/computer`'s
- * Think adapter: that one's `glob` and `readDir` read every entry, and its
- * `writeFile` knows nothing of the paths and the states this plugin refuses.
  */
 /**
- * Where a {@link computerWorkspace} sends each call, carried on it under
- * {@link ROUTE}. `computer()`'s tools route through this rather than through
- * their own config, which is what makes a workspace built from another config,
- * or without its runtime, a wrong workspace for both rather than a split.
+ * Where a workspace sends each call, carried on it under {@link ROUTE}. The
+ * tools route through this rather than through their own config, which is
+ * what makes a workspace built from another config, or without its runtime, a
+ * wrong workspace for both rather than a split.
  */
 export interface WorkspaceRoute {
-    /** The workspace the running turn names. Read per call. */
+    /** The sandbox the running turn names. Read per call. */
     name(): string;
-    host(name: string): DurableObjectStub<WorkspaceHost>;
+    open(name: string): Promise<ComputerClient>;
+    advisories(name: string): Promise<readonly SandboxAdvisory[]>;
 }
-/** The route of a workspace {@link computerWorkspace} built, or `undefined`. */
+/** The route of a workspace {@link routedWorkspace} built, or `undefined`. */
 export declare function workspaceRoute(workspace: unknown): WorkspaceRoute | undefined;
-/** Whether `workspace` is one {@link computerWorkspace} built. */
-export declare function isComputerWorkspace(workspace: unknown): boolean;
-/**
- * @param runtime The running sub-agent's `runtime()`, read per call — how a
- *   sub-agent's file tools reach the workspace its parent prepared. A parent's
- *   is `undefined`, and {@link ComputerConfig.workspaceName} names it.
- */
-export declare function computerWorkspace(config: ComputerConfig, runtime?: () => unknown): WorkspaceLike;
+/** Think's file tools over `route`, carrying it for the computer tools to find. */
+export declare function routedWorkspace(route: WorkspaceRoute, cwd: string): WorkspaceLike;

package/dist/computer/proxy.js

@@ -52,7 +52,6 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
 });
 import { withFileLock } from "./file-lock.js";
 import { writeGate } from "./gate.js";
-import { openWorkspaceFs, workspaceNameFromRuntime } from "../workspace/open.js";
 import { guardPath, WALK_SKIPS } from "./paths.js";
 /**
  * The key the route is carried under. `Symbol.for`, so a second copy of this
@@ -65,16 +64,12 @@ const ROUTE = Symbol.for("@dynamicagents/plugins/computer:workspace");
  * reading the rest of a large checkout into the object would buy nothing.
  */
 const GLOB_LIMIT = 201;
-/** The route of a workspace {@link computerWorkspace} built, or `undefined`. */
+/** The route of a workspace {@link routedWorkspace} built, or `undefined`. */
 export function workspaceRoute(workspace) {
     if (typeof workspace !== "object" || workspace === null)
         return undefined;
     return workspace[ROUTE];
 }
-/** Whether `workspace` is one {@link computerWorkspace} built. */
-export function isComputerWorkspace(workspace) {
-    return workspaceRoute(workspace) !== undefined;
-}
 /**
  * Missing, as the filesystem says it across the boundary. The code does not
  * always survive RPC, so the message is read too.
@@ -98,23 +93,6 @@ async function orNull(read) {
         throw err;
     }
 }
-/**
- * `stat`, with a missing path answered as `null`.
- *
- * Asked of the stub's own `statOrNull` where it has one, the way
- * {@link file://../workspace/read.ts pathExists} asks for `exists`: Think's
- * `read` stats before it reads, so a missing file is an ordinary answer here,
- * and a `stat` that throws across the boundary leaves the object an unhandled
- * rejection to log for it.
- */
-function statOrNull(fs, path) {
-    // Called as a method, never through `.call`: on an RPC stub `.call` is read
-    // as a remote method.
-    const remote = fs;
-    if (typeof remote.statOrNull === "function")
-        return remote.statOrNull(path);
-    return orNull(fs.stat(path));
-}
 async function drain(stream) {
     return new Uint8Array(await new Response(stream).arrayBuffer());
 }
@@ -144,29 +122,17 @@ function splitGlob(pattern, cwd) {
         rest: absolute.slice(cut + 1)
     };
 }
-/**
- * @param runtime The running sub-agent's `runtime()`, read per call — how a
- *   sub-agent's file tools reach the workspace its parent prepared. A parent's
- *   is `undefined`, and {@link ComputerConfig.workspaceName} names it.
- */
-export function computerWorkspace(config, runtime) {
-    const cwd = config.cwd ?? "/workspace";
-    // Resolved per call, never memoized: the name belongs to the turn, and a
-    // stale one would route this caller's writes into another's files.
-    const named = () => workspaceNameFromRuntime(runtime?.()) ?? config.workspaceName();
-    const host = (name) => config.binding.get(config.binding.idFromName(name));
-    /**
-     * One call, against the workspace this turn names. Opened without starting a
-     * container — see `WorkspaceHost.__getWorkspaceFsStub`.
-     */
+/** Think's file tools over `route`, carrying it for the computer tools to find. */
+export function routedWorkspace(route, cwd) {
+    /** One call, against the workspace this turn names. */
     const withFs = async (path, verb, body) => {
         const env_1 = { stack: [], error: void 0, hasError: false };
         try {
             const refusal = guardPath(path, verb);
             if (refusal)
                 throw new Error(refusal);
-            const name = named();
-            const ws = __addDisposableResource(env_1, await openWorkspaceFs(host(name)), false);
+            const name = route.name();
+            const ws = __addDisposableResource(env_1, await route.open(name), false);
             return await body(ws.fs, name);
         }
         catch (e_1) {
@@ -185,8 +151,8 @@ export function computerWorkspace(config, runtime) {
     const withWritableFs = (path, verb, body) => withFs(path, verb, async (fs, name) => {
         // Fails open, for the reason the tools' own write gate does: a read of
         // another Durable Object's state must not take out a working tool.
-        const lost = await host(name)
-            .advisories()
+        const lost = await route
+            .advisories(name)
             .then(writeGate, () => undefined);
         if (lost)
             throw new Error(lost);
@@ -201,7 +167,7 @@ export function computerWorkspace(config, runtime) {
             return stream === null ? null : drain(stream);
         }),
         stat: (path) => withFs(path, "read", async (fs) => {
-            const stat = await statOrNull(fs, path);
+            const stat = await orNull(fs.stat(path));
             return stat === null ? null : fileInfo({ ...stat, path });
         }),
         readDir: (dir = cwd, opts) => withFs(dir, "list", async (fs) => (await fs.readdir(dir, opts)).map((entry) => fileInfo({
@@ -228,7 +194,6 @@ export function computerWorkspace(config, runtime) {
         // evicted media, projected skills — and none of that belongs in a
         // repository's checkout. Without it Think skips both, with a warning.
     };
-    const route = { name: named, host };
     Object.defineProperty(workspace, ROUTE, { value: route });
     return workspace;
 }

package/dist/computer/render.d.ts

@@ -1,12 +1,4 @@
-import type { WorkspaceClient, WorkspaceRuntimeStatus } from "@cloudflare/computer";
-/**
- * One `fs.grep` hit, derived from the client rather than imported.
- *
- * `@cloudflare/computer` declares `WorkspaceGrepMatch` but does not re-export it,
- * so there is no name to import. Reading it back off the method keeps this correct
- * by construction.
- */
-type GrepMatch = Awaited<ReturnType<WorkspaceClient["fs"]["grep"]>>[number];
+import type { CommandResult, GrepMatch } from "./client.js";
 /**
  * Emit whole items until the byte budget is spent, and report exactly how many.
  *
@@ -64,7 +56,7 @@ export declare function renderGrepMatches(matches: GrepMatch[], maxChars: number
  *
  * ## `status` is not the exit code
  *
- * `WorkspaceRuntimeStatus` is `completed | failed | cancelled`. Dropping it
+ * A `status` is `completed | failed | cancelled`. Dropping it
  * renders a command killed at the `timeoutMs` ceiling exactly like one that ran
  * to completion and failed — "your test suite was killed at ten minutes" and
  * "your test suite has a failing test", which want opposite responses. Anything
@@ -79,34 +71,5 @@ export declare function renderResult(result: {
     exitCode: number;
     stdout: string;
     stderr: string;
-    status?: WorkspaceRuntimeStatus;
-    sync?: {
-        status: "complete" | "pending";
-    };
+    status?: CommandResult["status"];
 }, maxChars: number): string;
-/**
- * The command ran; its changes have not landed in the workspace yet.
- *
- * Every command is bracketed by a sync, and the pull afterwards is what moves
- * what it wrote from the container into the Durable Object. That pull can fail
- * while the command itself succeeds — a transport that dropped, a container
- * replaced underneath — and the runtime reports it in `sync` rather than in the
- * exit code, because the command genuinely did run.
- *
- * Worth a sentence to the model because the *next* thing it does is usually read
- * what it just wrote, and the file tools read the workspace rather than the
- * container. Without this the file looks unchanged and the obvious conclusion is
- * that the command did not work, which is the one conclusion that is wrong.
- *
- * Recovery is deliberately not the model's, and is not automatic either: the
- * runtime schedules no retry of its own, so an outstanding pull lands when the
- * host drives one or when a later command's own bracket carries it. What the
- * model is told therefore stops short of "it will be there in a moment" — it is
- * told the read may be stale, that re-running the command is the wrong fix
- * because it would repeat the side effects, and to say so in its result if the
- * workspace still disagrees with what it wrote.
- */
-export declare function syncPendingNote(sync: {
-    status: "complete" | "pending";
-} | undefined): string | undefined;
-export {};

package/dist/computer/render.js

@@ -1,4 +1,4 @@
-import { truncateOutput } from "../workspace/format.js";
+import { truncateOutput } from "@dynamicagents/core";
 /**
  * Turning a result into the text a model reads.
  *
@@ -114,7 +114,7 @@ export function renderGrepMatches(matches, maxChars) {
  *
  * ## `status` is not the exit code
  *
- * `WorkspaceRuntimeStatus` is `completed | failed | cancelled`. Dropping it
+ * A `status` is `completed | failed | cancelled`. Dropping it
  * renders a command killed at the `timeoutMs` ceiling exactly like one that ran
  * to completion and failed — "your test suite was killed at ten minutes" and
  * "your test suite has a failing test", which want opposite responses. Anything
@@ -137,38 +137,5 @@ export function renderResult(result, maxChars) {
     const body = truncateOutput(parts.join("\n"), maxChars);
     const state = result.status && result.status !== "completed" ? ` (${result.status})` : "";
     const verdict = `--- exit ${result.exitCode}${state} ---`;
-    const pending = syncPendingNote(result.sync);
-    const transcript = body ? `${body}\n${verdict}` : `(no output)\n${verdict}`;
-    return pending ? `${transcript}\n${pending}` : transcript;
-}
-/**
- * The command ran; its changes have not landed in the workspace yet.
- *
- * Every command is bracketed by a sync, and the pull afterwards is what moves
- * what it wrote from the container into the Durable Object. That pull can fail
- * while the command itself succeeds — a transport that dropped, a container
- * replaced underneath — and the runtime reports it in `sync` rather than in the
- * exit code, because the command genuinely did run.
- *
- * Worth a sentence to the model because the *next* thing it does is usually read
- * what it just wrote, and the file tools read the workspace rather than the
- * container. Without this the file looks unchanged and the obvious conclusion is
- * that the command did not work, which is the one conclusion that is wrong.
- *
- * Recovery is deliberately not the model's, and is not automatic either: the
- * runtime schedules no retry of its own, so an outstanding pull lands when the
- * host drives one or when a later command's own bracket carries it. What the
- * model is told therefore stops short of "it will be there in a moment" — it is
- * told the read may be stale, that re-running the command is the wrong fix
- * because it would repeat the side effects, and to say so in its result if the
- * workspace still disagrees with what it wrote.
- */
-export function syncPendingNote(sync) {
-    if (sync?.status !== "pending")
-        return undefined;
-    return ("(The command finished, but what it wrote has not reached the workspace " +
-        "yet, so the file tools may still show the previous contents. Do not re-run " +
-        "the command to force it — that repeats whatever it already did. Read again " +
-        "in a moment, and if the workspace still disagrees with what the command " +
-        "wrote, say so in your result rather than working around it.)");
+    return body ? `${body}\n${verdict}` : `(no output)\n${verdict}`;
 }

package/dist/computer/sandbox.d.ts

@@ -0,0 +1,55 @@
+import type { WorkspaceLike } from "@cloudflare/think";
+import type { SandboxAdvisory } from "../sandbox/advisory.js";
+import type { ComputerClient } from "./client.js";
+/**
+ * The computer tools over a `/sandbox` object.
+ *
+ * The checkout is the container's own disk, so every call reaches the
+ * container: a file read wakes a stopped one (measured at about two seconds,
+ * once), and `grep` and `find` are `ripgrep` there. The sandbox's RPCs run as
+ * the agent and refuse anything outside `/workspace`.
+ *
+ * ```ts
+ * override workspace = computerWorkspace(config, () => this.pluginContext().runtime());
+ * ```
+ *
+ * `computer(config)`'s tools then find the sandbox through it.
+ */
+/** The sandbox RPCs this uses. A `/sandbox` object answers all of them. */
+export interface SandboxComputerHost extends Rpc.DurableObjectBranded {
+    exec(argv: string[], options?: {
+        cwd?: string;
+        env?: Record<string, string>;
+        timeoutMs?: number;
+    }): Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    }>;
+    readFile(path: string): Promise<Uint8Array | null>;
+    writeFile(path: string, content: string): Promise<void>;
+    stat(path: string): Promise<{
+        type: string;
+        size: number;
+        modifiedAt: number;
+    } | null>;
+    readDir(path: string): Promise<{
+        name: string;
+        type: string;
+    }[]>;
+    mkdir(path: string): Promise<void>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    advisories(): Promise<readonly SandboxAdvisory[]>;
+}
+export interface SandboxComputerConfig {
+    /** Addressed by name only: the sandbox's lifecycle needs it. */
+    binding: DurableObjectNamespace<SandboxComputerHost>;
+    /** The sandbox a parent's own turn works in. A sub-agent's comes from its `runtime()`. */
+    sandboxName: () => string;
+    cwd?: string;
+}
+export declare function computerWorkspace(config: SandboxComputerConfig, runtime?: () => unknown): WorkspaceLike;
+/** The computer tools' client over one sandbox. */
+export declare function sandboxClient(host: SandboxComputerHost): ComputerClient;