@dynamicagents/plugins 0.12.0 → 0.13.0

package/dist/computer/proxy.d.ts

@@ -0,0 +1,45 @@
+import type { WorkspaceLike } from "@cloudflare/think";
+import type { WorkspaceHost } from "../workspace/open.js";
+import type { ComputerConfig } from "./index.js";
+/**
+ * The container's workspace, 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
+ * 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
+ * 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.
+ */
+export interface WorkspaceRoute {
+    /** The workspace the running turn names. Read per call. */
+    name(): string;
+    host(name: string): DurableObjectStub<WorkspaceHost>;
+}
+/** The route of a workspace {@link computerWorkspace} 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;

package/dist/computer/proxy.js

@@ -0,0 +1,234 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { 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
+ * module in one bundle still recognises the first's workspaces.
+ */
+const ROUTE = Symbol.for("@dynamicagents/plugins/computer:workspace");
+/**
+ * The most one `glob` returns. Its caller is Think's `find`, which shows 200
+ * and says when there were more — so one past that is all it can use, and
+ * 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`. */
+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.
+ */
+function isMissing(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const { code, message } = err;
+    if (code === "ENOENT")
+        return true;
+    return typeof message === "string" && /ENOENT|no such/i.test(message);
+}
+/** `null` for a path that is not there, which is what Think's tools expect. */
+async function orNull(read) {
+    try {
+        return await read;
+    }
+    catch (err) {
+        if (isMissing(err))
+            return null;
+        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());
+}
+function fileInfo(entry) {
+    const type = entry.isDirectory ? "directory" : "file";
+    return {
+        path: entry.path,
+        name: entry.path.slice(entry.path.lastIndexOf("/") + 1),
+        type,
+        // Generic on purpose: Think's `read` sniffs a generic type from the bytes,
+        // and an extension is not evidence of what a file holds.
+        mimeType: type === "directory" ? "inode/directory" : "application/octet-stream",
+        size: entry.size ?? 0,
+        createdAt: entry.mtime ?? 0,
+        updatedAt: entry.mtime ?? 0
+    };
+}
+/** The directory a glob walks from, and the pattern relative to it. */
+function splitGlob(pattern, cwd) {
+    const absolute = pattern.startsWith("/") ? pattern : `${cwd}/${pattern}`;
+    const wildcard = absolute.search(/[*?[{]/);
+    const cut = wildcard === -1
+        ? absolute.lastIndexOf("/")
+        : absolute.lastIndexOf("/", wildcard);
+    return {
+        dir: cut <= 0 ? "/" : absolute.slice(0, cut),
+        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`.
+     */
+    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);
+            return await body(ws.fs, name);
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    };
+    /**
+     * A write, refused while the workspace cannot keep it. Thrown rather than
+     * returned: Think's tools report a thrown error to the model, and a write
+     * that returned would read as one that landed.
+     */
+    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()
+            .then(writeGate, () => undefined);
+        if (lost)
+            throw new Error(lost);
+        return body(fs, name);
+    });
+    const workspace = {
+        readFile: (path) => 
+        // Whole, never truncated: Think's `edit` writes back what it read.
+        withFs(path, "read", (fs) => orNull(fs.readFile(path, "utf8"))),
+        readFileBytes: (path) => withFs(path, "read", async (fs) => {
+            const stream = await orNull(fs.readFile(path));
+            return stream === null ? null : drain(stream);
+        }),
+        stat: (path) => withFs(path, "read", async (fs) => {
+            const stat = await statOrNull(fs, 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({
+            ...entry,
+            path: dir === "/" ? `/${entry.name}` : `${dir}/${entry.name}`
+        }))),
+        // Pruned rather than filtered: at a repository root either skipped
+        // directory outnumbers everything else.
+        glob: (pattern) => {
+            const { dir, rest } = splitGlob(pattern, cwd);
+            return withFs(dir, "find", async (fs) => (await fs.find(dir, rest, {
+                limit: GLOB_LIMIT,
+                exclude: WALK_SKIPS.map((segment) => `**/${segment}`)
+            })).map((entry) => fileInfo({ path: entry.path, isDirectory: entry.type === "dir" })));
+        },
+        // Locked per file, so a write never lands inside the `edit` tool's read and
+        // write of the same file — see `./file-lock.ts`.
+        writeFile: (path, content) => withWritableFs(path, "write", (fs, name) => withFileLock(name, path, () => fs.writeFile(path, content))),
+        mkdir: (path, opts) => withWritableFs(path, "write", (fs) => fs.mkdir(path, opts)),
+        // Locked too: a delete landing between an edit's read and its write would
+        // be undone by the write, and both would report success.
+        rm: (path, opts) => withWritableFs(path, "delete", (fs, name) => withFileLock(name, path, () => fs.rm(path, opts)))
+        // No `writeFileBytes`. Think writes through it on its own account —
+        // 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,28 +1,10 @@
 import type { WorkspaceClient, WorkspaceRuntimeStatus } from "@cloudflare/computer";
-/**
- * Middle-out truncation, so both the first error and the final summary survive.
- *
- * The guard is not defensive padding. Without it a `max` at or below the marker's
- * own length makes `half` zero or negative, and `slice(-0)` is `slice(0)` — the
- * *whole* string — so the function returns more than it was given: 500 characters
- * in, 543 out at `max: 80`. A silent inversion of the one thing it does,
- * reachable from a public config field.
- */
-export declare function truncateOutput(text: string, max: number): string;
-/**
- * A byte count in the form a model can act on.
- *
- * A listing that says a file is 4.2 MB tells the model the read it is about to do
- * comes back with a hole in the middle — the one thing it cannot infer from the
- * truncated result itself.
- */
-export declare function humanBytes(bytes: number): string;
 /**
  * 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 — the same structural approach {@link readBounded} takes to `fs`.
+ * by construction.
  */
 type GrepMatch = Awaited<ReturnType<WorkspaceClient["fs"]["grep"]>>[number];
 /**
@@ -70,8 +52,6 @@ export declare function renderGrepMatches(matches: GrepMatch[], maxChars: number
     shown: number;
     capped: boolean;
 };
-/** Elapsed time in the shape a sentence wants. */
-export declare function humanMs(ms: number): string;
 /**
  * Render a completed command the way a terminal would, minus the noise.
  *
@@ -129,23 +109,4 @@ export declare function renderResult(result: {
 export declare function syncPendingNote(sync: {
     status: "complete" | "pending";
 } | undefined): string | undefined;
-/**
- * Why a command has nothing to show for itself.
- *
- * {@link renderResult} states a non-`completed` status on its verdict line;
- * {@link computerExec} has no verdict line, only the four fields its caller
- * branches on. A *killed* process writes nothing, so without this a `git clone`
- * that hit the ten-minute ceiling reaches the model through
- * `@dynamicagents/plugins/repo` as `clone failed:` with an empty reason — which reads
- * like a bug in the plugin rather than a limit it can work within.
- *
- * Only `cancelled`. A `failed` status is an ordinary non-zero exit, where the
- * command's own stderr is the better explanation and this would be noise on top
- * of it.
- *
- * Both plausible causes are named because the exit code cannot separate them:
- * 137 is SIGKILL, which is what the timeout sends *and* what the kernel sends a
- * container that ran out of memory.
- */
-export declare function cancelledNote(status: WorkspaceRuntimeStatus | undefined, exitCode: number, timeoutMs: number): string | undefined;
 export {};

package/dist/computer/render.js

@@ -1,3 +1,4 @@
+import { truncateOutput } from "../workspace/format.js";
 /**
  * Turning a result into the text a model reads.
  *
@@ -15,43 +16,9 @@
  * A grep match carries the whole line, and a minified bundle is one line of
  * megabytes — a single match in `dist/` would otherwise be the entire result. The
  * head is kept because a match's file and line number are what the model acts on;
- * it reads the region with `sb_read` next.
+ * it reads the region with `read` next.
  */
 const MAX_MATCH_LINE_CHARS = 200;
-/**
- * Middle-out truncation, so both the first error and the final summary survive.
- *
- * The guard is not defensive padding. Without it a `max` at or below the marker's
- * own length makes `half` zero or negative, and `slice(-0)` is `slice(0)` — the
- * *whole* string — so the function returns more than it was given: 500 characters
- * in, 543 out at `max: 80`. A silent inversion of the one thing it does,
- * reachable from a public config field.
- */
-export function truncateOutput(text, max) {
-    if (text.length <= max)
-        return text;
-    const marker = (dropped) => `\n\n… [${dropped} characters omitted from the middle] …\n\n`;
-    // No budget for two halves plus the marker: keep the head, which is where the
-    // first error is, and say nothing clever.
-    const half = Math.floor((max - marker(text.length).length) / 2);
-    if (half < 1)
-        return text.slice(0, Math.max(0, max));
-    return (text.slice(0, half) + marker(text.length - half * 2) + text.slice(-half));
-}
-/**
- * A byte count in the form a model can act on.
- *
- * A listing that says a file is 4.2 MB tells the model the read it is about to do
- * comes back with a hole in the middle — the one thing it cannot infer from the
- * truncated result itself.
- */
-export function humanBytes(bytes) {
-    if (bytes < 1024)
-        return `${bytes} B`;
-    if (bytes < 1024 * 1024)
-        return `${(bytes / 1024).toFixed(1)} KB`;
-    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-}
 /** One matching line, bounded — see {@link MAX_MATCH_LINE_CHARS}. */
 function capLine(text) {
     // A CRLF file leaves the carriage return on every line, since the reader splits
@@ -135,13 +102,6 @@ export function renderGrepMatches(matches, maxChars) {
     // Only a line that actually made it out is worth explaining.
     return { body, shown, capped: hasLongLine.slice(0, shown).includes(true) };
 }
-/** Elapsed time in the shape a sentence wants. */
-export function humanMs(ms) {
-    const s = Math.round(ms / 1000);
-    return s < 60
-        ? `${s}s`
-        : `${Math.floor(s / 60)}m${String(s % 60).padStart(2, "0")}s`;
-}
 /**
  * Render a completed command the way a terminal would, minus the noise.
  *
@@ -212,29 +172,3 @@ export function syncPendingNote(sync) {
         "in a moment, and if the workspace still disagrees with what the command " +
         "wrote, say so in your result rather than working around it.)");
 }
-/**
- * Why a command has nothing to show for itself.
- *
- * {@link renderResult} states a non-`completed` status on its verdict line;
- * {@link computerExec} has no verdict line, only the four fields its caller
- * branches on. A *killed* process writes nothing, so without this a `git clone`
- * that hit the ten-minute ceiling reaches the model through
- * `@dynamicagents/plugins/repo` as `clone failed:` with an empty reason — which reads
- * like a bug in the plugin rather than a limit it can work within.
- *
- * Only `cancelled`. A `failed` status is an ordinary non-zero exit, where the
- * command's own stderr is the better explanation and this would be noise on top
- * of it.
- *
- * Both plausible causes are named because the exit code cannot separate them:
- * 137 is SIGKILL, which is what the timeout sends *and* what the kernel sends a
- * container that ran out of memory.
- */
-export function cancelledNote(status, exitCode, timeoutMs) {
-    if (status !== "cancelled")
-        return undefined;
-    return (`the command was killed rather than exiting on its own (exit ${exitCode}), so ` +
-        `anything it had not yet written is gone. The two usual causes are the ` +
-        `per-command time limit — ${humanMs(timeoutMs)} here — and the container ` +
-        `running out of memory.`);
-}

package/dist/computer/tools-exec.js

@@ -55,7 +55,7 @@ import { z } from "zod";
 import { withAbort } from "@dynamicagents/core";
 import { renderResult } from "./render.js";
 import { execLostNote } from "./gate.js";
-import { withShellTranscript } from "./shell.js";
+import { withShellTranscript } from "../workspace/shell.js";
 /** Running one command in the container. */
 /**
  * Wait for a disposable resource without outliving `signal`.
@@ -85,7 +85,7 @@ async function killLate(handle) {
 export function execTools(ctx) {
     const { config, cwd, timeoutMs, maxChars, workspace, awaitAdvisories, definedEnv } = ctx;
     return {
-        sb_exec: tool({
+        bash: tool({
             /**
              * States what the tool guarantees, rather than what it might withhold.
              *
@@ -131,7 +131,7 @@ export function execTools(ctx) {
                  * held, how long the command took, what it exited with — answer it
                  * directly.
                  *
-                 * Timed around the gate as well as the command, since a subagent blocked
+                 * Timed around the gate as well as the command, since an agent blocked
                  * waiting for `npm ci` and one running a slow test suite are
                  * indistinguishable from the outside and want opposite fixes.
                  */
@@ -143,15 +143,14 @@ export function execTools(ctx) {
                  * where the call stopped. A command that outran the limit once will again;
                  * one that never started because the workspace did not answer may not.
                  *
-                 * `sb_exec` reads its call's signal rather than leaving the wait to core,
-                 * and this is why: core's abandonment can say only that the command may
-                 * still be running. Core's `TOOL_CALL_GRACE_MS` is the window this answer
-                 * has to arrive in, and it covers sending the kill below.
+                 * `bash` reads its call's signal rather than leaving the wait to Think,
+                 * and this is why: an abandoned wait can say only that the command may
+                 * still be running, and the kill below is what stops it.
                  */
                 const stopped = (gateMs, started) => {
                     const timedOut = abortSignal?.reason?.name ===
                         "TimeoutError";
-                    console.info("[computer] sb_exec stopped", {
+                    console.info("[computer] bash stopped", {
                         command,
                         gateMs,
                         durationMs: Date.now() - startedAtMs - gateMs,
@@ -164,9 +163,9 @@ export function execTools(ctx) {
                         ? "the command was stopped: it ran past this call's time limit. Anything it changed before then is still changed. Try something narrower."
                         : "the command did not run: this call reached its time limit while the workspace was still getting ready, so nothing was changed. Try again; if it happens again, the workspace is not responding.";
                 };
-                // Only `sb_exec` waits on an install. The file tools read and write
+                // Only `bash` waits on an install. The file tools read and write
                 // source, which is in the workspace and unaffected by an install in
-                // flight — blocking them would stop the subagent doing the reading it
+                // flight — blocking them would stop the agent doing the reading it
                 // could usefully do while it waits. They do consult `writeGate`, which
                 // is a different question: not "is the tree ready" but "does a write
                 // survive at all".
@@ -182,7 +181,7 @@ export function execTools(ctx) {
                 }
                 const gateMsWaited = Date.now() - startedAtMs;
                 if (gate.block) {
-                    console.info("[computer] sb_exec blocked by a workspace advisory", {
+                    console.info("[computer] bash blocked by a workspace advisory", {
                         command,
                         gateMs: gateMsWaited
                     });
@@ -224,7 +223,7 @@ export function execTools(ctx) {
                         // process are two acts. Disposing the handle is neither — it releases
                         // this side's attachment and leaves the command running.
                         const result = await withAbort(abortSignal, handle.result(), () => handle.kill("SIGTERM"));
-                        console.info("[computer] sb_exec", {
+                        console.info("[computer] bash", {
                             command,
                             exitCode: result.exitCode,
                             // Split so a slow command and a slow *wait* never look alike.
@@ -248,7 +247,7 @@ export function execTools(ctx) {
                     if (abortSignal?.aborted)
                         return note(stopped(gateMsWaited, started));
                     const lost = execLostNote(err);
-                    console.warn("[computer] sb_exec failed", {
+                    console.warn("[computer] bash failed", {
                         command,
                         gateMs: gateMsWaited,
                         durationMs: Date.now() - startedAtMs - gateMsWaited,

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

@@ -1,4 +1,12 @@
 import type { ToolSet } from "ai";
 import type { ComputerContext } from "./context.js";
-/** One file at a time: reading it, replacing it, editing it in place. */
+/**
+ * Editing a file in place — the one file tool this plugin keeps. Think's
+ * `read`, `write` and `delete` reach the workspace through the agent's own
+ * `this.workspace`, which is `computerWorkspace` (`./proxy.ts`).
+ *
+ * Not Think's `edit`, because that one is two calls through the workspace — a
+ * `readFile`, then a `writeFile` — and a lock inside the workspace cannot span
+ * the pair. See `./file-lock.ts`.
+ */
 export declare function fileTools(ctx: ComputerContext): ToolSet;