@dynamicagents/plugins 0.16.1 → 0.17.0

package/dist/computer/proxy.js

@@ -52,78 +52,31 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
 });
 import { withFileLock } from "./file-lock.js";
 import { writeGate } from "./gate.js";
-import { guardPath, WALK_SKIPS } from "./paths.js";
+import { guardPath, walkSkips } 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 routedWorkspace} built, or `undefined`. */
 export function workspaceRoute(workspace) {
     if (typeof workspace !== "object" || workspace === null)
         return undefined;
     return workspace[ROUTE];
 }
-/**
- * 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;
-    }
-}
+/** The bytes of a stream, for a host RPC that takes a value rather than one. */
 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)
-    };
-}
 /** Think's file tools over `route`, carrying it for the computer tools to find. */
-export function routedWorkspace(route, cwd) {
+/**
+ * `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 function routedWorkspace(route, root) {
     /** One call, against the workspace this turn names. */
     const withFs = async (path, verb, body) => {
         const env_1 = { stack: [], error: void 0, hasError: false };
@@ -158,42 +111,79 @@ export function routedWorkspace(route, cwd) {
             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 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({
+    /**
+     * Read whole or ranged, and as text or as bytes, in the one overloaded
+     * method Computer's filesystem declares. The options go through untouched:
+     * an `edit` reads text and writes back what it read, and a `read` of an
+     * evicted image asks for the bytes.
+     *
+     * **A host's `readFile` has to materialise what it answers**, because the
+     * client is released when this call returns and a stream that outlived it
+     * would be read against a disposed one. `/sandbox`'s does: it awaits the
+     * bytes and hands back a stream over them.
+     */
+    const readFile = (path, options) => withFs(path, "read", (fs) => options === undefined
+        ? fs.readFile(path)
+        : fs.readFile(path, options));
+    const fs = {
+        readFile: readFile,
+        stat: (path) => withFs(path, "read", async (fs) => ({
+            ...(await fs.stat(path)),
+            // The container has one, and the sandbox does not report it. Nothing
+            // downstream reads it: Computer's tools take `size`, `mtime`, `mode`
+            // and the three kind flags, and a number is all the type needs.
+            inode: 0
+        })),
+        readdir: (path, options) => withFs(path, "list", async (fs) => (await fs.readdir(path, options)).map((entry) => ({
             ...entry,
-            path: dir === "/" ? `/${entry.name}` : `${dir}/${entry.name}`
+            // The directory this listing was read from, which is what a caller
+            // joins a name onto. The sandbox lists names and kinds, so the size
+            // and the time are the entry's own where it has them and zero where
+            // it does not: `ls` shows both to the model, and a second round trip
+            // per entry to fill them in would cost a directory's worth of RPCs.
+            parentPath: path,
+            size: entry.size ?? 0,
+            mtime: entry.mtime ?? 0,
+            isSymbolicLink: entry.isSymbolicLink ?? false
         }))),
         // 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)),
+        // directory outnumbers everything else. No limit of this layer's own —
+        // `./sandbox.ts` caps a walk that arrives without one.
+        find: (directory, pattern, options) => withFs(directory, "find", (fs) => fs.find(directory, pattern, {
+            ...options,
+            exclude: [...walkSkips(directory, root), ...(options?.exclude ?? [])]
+        })),
+        grep: (pattern, path, options) => withFs(path, "search", (fs) => fs.grep(pattern, path, {
+            ...options,
+            exclude: [
+                ...walkSkips(path, root),
+                ...(options?.exclude ?? [])
+            ]
+        })),
+        /**
+         * Locked per file, so a write never lands inside the `edit` tool's read and
+         * write of the same file — see `./file-lock.ts`.
+         *
+         * A stream is drained here because the sandbox RPC takes a value. The
+         * `mode` a caller may send is dropped: the sandbox's write has nowhere to
+         * put one, so a mode this cannot set is not one it can claim to preserve.
+         */
+        writeFile: (path, content) => withWritableFs(path, "write", async (fs, name) => {
+            const body = content instanceof ReadableStream ? await drain(content) : content;
+            return withFileLock(name, path, () => fs.writeFile(path, body));
+        }),
+        mkdir: (path, options) => withWritableFs(path, "write", (fs) => fs.mkdir(path, options)),
         // 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.
+        rm: (path, options) => withWritableFs(path, "delete", (fs, name) => withFileLock(name, path, () => fs.rm(path, options)))
     };
+    /**
+     * `fs` alone. Computer's exec tool is offered only for a workspace carrying a
+     * `runtime`, so withholding one is how this keeps Think from building a
+     * second shell over the same container — `./tools-exec.ts` is the one the
+     * model gets, and it is this package's.
+     */
+    const workspace = { fs };
     Object.defineProperty(workspace, ROUTE, { value: route });
     return workspace;
 }

package/dist/computer/render.d.ts

@@ -1,13 +1,13 @@
-import type { CommandResult, GrepMatch } from "./client.js";
+import type { GrepMatch } from "./client.js";
 /**
  * Emit whole items until the byte budget is spent, and report exactly how many.
  *
- * {@link truncateOutput} is wrong for every list this module produces, and is
+ * Core's `truncateOutput` is wrong for every list this module produces, and is
  * deliberately not used by them. It keeps both ends and drops the middle, which is
- * right for a build log — first error, final summary — and destructive for a match
- * list or a directory listing, where the middle is a whole file's worth of hits or a
- * whole subtree that silently vanishes. So the budget is spent item by item, in
- * order, and the caller learns where it stopped.
+ * right for a build log and destructive for a match list or a directory listing,
+ * where the middle is a whole file's worth of hits or a whole subtree that silently
+ * vanishes. So the budget is spent item by item, in order, and the caller learns
+ * where it stopped.
  *
  * `shown` is the load-bearing return value: it is what makes the next page's offset
  * exact rather than a guess. A block is committed whole or not at all, because half
@@ -44,32 +44,3 @@ export declare function renderGrepMatches(matches: GrepMatch[], maxChars: number
     shown: number;
     capped: boolean;
 };
-/**
- * Render a completed command the way a terminal would, minus the noise.
- *
- * ## Every command ends with its verdict, including the successful ones
- *
- * Printing the exit code only when it is non-zero looks like saving noise and is
- * not: a model with no verdict appends `; echo "EXIT_CODE=$?"` itself, and
- * reaches for `${PIPESTATUS[0]}` to read a piped one — which dash does not
- * implement, so the whole line fails after the command it wrapped has run.
- *
- * ## `status` is not the exit code
- *
- * 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
- * other than `completed` is stated.
- *
- * ## One budget, applied once
- *
- * Truncating per stream makes `maxOutputChars` mean "up to twice this". The bound
- * is on the rendered transcript, which is what reaches the context window.
- */
-export declare function renderResult(result: {
-    exitCode: number;
-    stdout: string;
-    stderr: string;
-    status?: CommandResult["status"];
-}, maxChars: number): string;

package/dist/computer/render.js

@@ -1,4 +1,3 @@
-import { truncateOutput } from "@dynamicagents/core";
 /**
  * Turning a result into the text a model reads.
  *
@@ -31,12 +30,12 @@ function capLine(text) {
 /**
  * Emit whole items until the byte budget is spent, and report exactly how many.
  *
- * {@link truncateOutput} is wrong for every list this module produces, and is
+ * Core's `truncateOutput` is wrong for every list this module produces, and is
  * deliberately not used by them. It keeps both ends and drops the middle, which is
- * right for a build log — first error, final summary — and destructive for a match
- * list or a directory listing, where the middle is a whole file's worth of hits or a
- * whole subtree that silently vanishes. So the budget is spent item by item, in
- * order, and the caller learns where it stopped.
+ * right for a build log and destructive for a match list or a directory listing,
+ * where the middle is a whole file's worth of hits or a whole subtree that silently
+ * vanishes. So the budget is spent item by item, in order, and the caller learns
+ * where it stopped.
  *
  * `shown` is the load-bearing return value: it is what makes the next page's offset
  * exact rather than a guess. A block is committed whole or not at all, because half
@@ -102,40 +101,3 @@ 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) };
 }
-/**
- * Render a completed command the way a terminal would, minus the noise.
- *
- * ## Every command ends with its verdict, including the successful ones
- *
- * Printing the exit code only when it is non-zero looks like saving noise and is
- * not: a model with no verdict appends `; echo "EXIT_CODE=$?"` itself, and
- * reaches for `${PIPESTATUS[0]}` to read a piped one — which dash does not
- * implement, so the whole line fails after the command it wrapped has run.
- *
- * ## `status` is not the exit code
- *
- * 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
- * other than `completed` is stated.
- *
- * ## One budget, applied once
- *
- * Truncating per stream makes `maxOutputChars` mean "up to twice this". The bound
- * is on the rendered transcript, which is what reaches the context window.
- */
-export function renderResult(result, maxChars) {
-    const parts = [];
-    if (result.stdout)
-        parts.push(result.stdout);
-    // Empty whenever the host configured a `shell`, which merges the streams at the
-    // source so the transcript keeps its causal order. Kept for hosts that did not:
-    // two labelled blocks beat silently dropping half the output.
-    if (result.stderr)
-        parts.push(`--- stderr ---\n${result.stderr}`);
-    const body = truncateOutput(parts.join("\n"), maxChars);
-    const state = result.status && result.status !== "completed" ? ` (${result.status})` : "";
-    const verdict = `--- exit ${result.exitCode}${state} ---`;
-    return body ? `${body}\n${verdict}` : `(no output)\n${verdict}`;
-}

package/dist/computer/sandbox.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";
 /**
@@ -27,11 +27,12 @@ export interface SandboxComputerHost extends Rpc.DurableObjectBranded {
         stderr: string;
     }>;
     readFile(path: string): Promise<Uint8Array | null>;
-    writeFile(path: string, content: string): Promise<void>;
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
     stat(path: string): Promise<{
         type: string;
         size: number;
         modifiedAt: number;
+        mode: number;
     } | null>;
     readDir(path: string): Promise<{
         name: string;
@@ -50,6 +51,6 @@ export interface SandboxComputerConfig {
     sandboxName: () => string;
     cwd?: string;
 }
-export declare function computerWorkspace(config: SandboxComputerConfig, runtime?: () => unknown): WorkspaceLike;
+export declare function computerWorkspace(config: SandboxComputerConfig, runtime?: () => unknown): ThinkWorkspace;
 /** The computer tools' client over one sandbox. */
 export declare function sandboxClient(host: SandboxComputerHost): ComputerClient;

package/dist/computer/sandbox.js

@@ -1,4 +1,5 @@
 import { RUN_DIR } from "../sandbox/constants.js";
+import { SANDBOX_ROOT } from "../sandbox/header.js";
 import { sandboxNameFromRuntime } from "../sandbox/name.js";
 import { routedWorkspace } from "./proxy.js";
 /** After `timeout`'s TERM, how long before its KILL. */
@@ -39,7 +40,10 @@ export function computerWorkspace(config, runtime) {
         name: () => sandboxNameFromRuntime(runtime?.()) ?? config.sandboxName(),
         open: async (name) => sandboxClient(host(name)),
         advisories: (name) => host(name).advisories()
-    }, config.cwd ?? "/workspace");
+    }, 
+    // The served root, not `config.cwd`: a host may point the tools at a
+    // checkout, and Think's own directories stay where Think puts them.
+    SANDBOX_ROOT);
 }
 function missing(path) {
     return Object.assign(new Error(`ENOENT: no such file or directory, ${path}`), { code: "ENOENT" });
@@ -61,8 +65,10 @@ export function sandboxClient(host) {
             if (!stat)
                 throw missing(path);
             return {
+                name: path.slice(path.lastIndexOf("/") + 1),
                 size: stat.size,
                 mtime: stat.modifiedAt,
+                mode: stat.mode,
                 isFile: stat.type === "file",
                 isDirectory: stat.type === "directory",
                 isSymbolicLink: stat.type === "symlink"
@@ -75,7 +81,8 @@ export function sandboxClient(host) {
                 .map((entry) => ({
                 name: entry.name,
                 isFile: entry.type === "file",
-                isDirectory: entry.type === "directory"
+                isDirectory: entry.type === "directory",
+                isSymbolicLink: entry.type === "symlink"
             }));
         },
         find: (directory, pattern, options = {}) => find(host, directory, pattern, options),

package/dist/computer/shell.d.ts

@@ -3,7 +3,8 @@
  * two output streams merged into one transcript, in the order they were
  * written, or hand it back untouched when no shell is configured.
  *
- * `bash`'s consumer is **a model reading output**. A project's check is a chain
+ * The shell tool's consumer is **a model reading output**. A project's check is a
+ * chain
  * — `wrangler types && prettier && eslint && tsc` — and *which tool spoke last*
  * is how you know which one failed. A stdout block and a separate stderr block
  * destroy that ordering, and a model that wants it back re-runs the whole gate
@@ -25,12 +26,12 @@
  *
  * The trade is worth stating. `pipefail` surfaces SIGPIPE too, so
  * `ls big-dir | head -1` reports 141 rather than 0 — noisy, but *visible*. The
- * tool description tells the model not to pipe into `head`/`tail` at all, since
- * output is already truncated with both ends kept. It needs a shell that
- * implements it — `bash`, `zsh`, `ksh`, not `sh`/dash.
+ * tool's description is Computer's and says nothing about either, so the
+ * plugin's own context block in {@link file://./index.ts} is where the model is
+ * told not to pipe into `head`/`tail`. It needs a shell that implements it —
+ * `bash`, `zsh`, `ksh`, not `sh`/dash.
  *
- * With no shell configured the two streams arrive separate, and
- * {@link file://./render.ts renderResult} renders them as a labelled
- * `--- stderr ---` block.
+ * With no shell configured the two streams arrive separate, and the tool reports
+ * them as the `stdout` and `stderr` of its result.
  */
 export declare function withShellTranscript(command: string, shell: string | undefined): string;

package/dist/computer/shell.js

@@ -4,7 +4,8 @@ import { shellQuote } from "../sandbox/agent-exec.js";
  * two output streams merged into one transcript, in the order they were
  * written, or hand it back untouched when no shell is configured.
  *
- * `bash`'s consumer is **a model reading output**. A project's check is a chain
+ * The shell tool's consumer is **a model reading output**. A project's check is a
+ * chain
  * — `wrangler types && prettier && eslint && tsc` — and *which tool spoke last*
  * is how you know which one failed. A stdout block and a separate stderr block
  * destroy that ordering, and a model that wants it back re-runs the whole gate
@@ -26,13 +27,13 @@ import { shellQuote } from "../sandbox/agent-exec.js";
  *
  * The trade is worth stating. `pipefail` surfaces SIGPIPE too, so
  * `ls big-dir | head -1` reports 141 rather than 0 — noisy, but *visible*. The
- * tool description tells the model not to pipe into `head`/`tail` at all, since
- * output is already truncated with both ends kept. It needs a shell that
- * implements it — `bash`, `zsh`, `ksh`, not `sh`/dash.
+ * tool's description is Computer's and says nothing about either, so the
+ * plugin's own context block in {@link file://./index.ts} is where the model is
+ * told not to pipe into `head`/`tail`. It needs a shell that implements it —
+ * `bash`, `zsh`, `ksh`, not `sh`/dash.
  *
- * With no shell configured the two streams arrive separate, and
- * {@link file://./render.ts renderResult} renders them as a labelled
- * `--- stderr ---` block.
+ * With no shell configured the two streams arrive separate, and the tool reports
+ * them as the `stdout` and `stderr` of its result.
  */
 export function withShellTranscript(command, shell) {
     return shell

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

@@ -1,3 +1,42 @@
 import type { ToolSet } from "ai";
 import type { ComputerContext } from "./context.js";
+/**
+ * The container's shell, as Computer's `exec` tool.
+ *
+ * **The tool is upstream's, and deliberately not wrapped past the advisory
+ * gate.** Its schema, its description, its truncation and its result shape are
+ * `@cloudflare/computer`'s, so the model sees the same `exec` everywhere that
+ * package's tools are installed and this plugin has no second dialect to keep in
+ * step. What that costs, each of it accepted rather than overlooked:
+ *
+ * - **Truncation keeps the tail, not both ends.** Upstream cuts each stream to
+ *   its last lines, so a failure printed early in a long build is gone from what
+ *   the model reads. The exit code still reports it, and the model's recourse is
+ *   a narrower command.
+ * - **The description promises a file this workspace does not write.** Upstream
+ *   tells the model that truncated output is saved where `read` and `grep` can
+ *   open it. That holds for a Workspace whose runtime saves it; this one reports
+ *   no saved path, so the reply names none and the sentence is unfulfilled.
+ *   Nothing can be set to turn it off: the sentence is built into the generated
+ *   description.
+ * - **A command stopped at the time limit or cancelled reads as a plain
+ *   failure.** Upstream's result has somewhere for an exit code and somewhere
+ *   for an error, and nowhere for the difference between a command that outran
+ *   its limit, one whose call was cancelled, and one that simply failed.
+ *   {@link file://./client.ts CommandResult.status} still carries it for the log
+ *   line below, which is the only place it is read.
+ *
+ * What stays this plugin's, because neither belongs to a tool:
+ *
+ * - **The advisory gate**, below: a command waits out a running install, is
+ *   refused while something transient makes it pointless, and carries a note
+ *   about anything permanent. {@link file://./gate.ts ExecGate} is the contract.
+ * - **How the container runs a command**, in
+ *   {@link file://./sandbox.ts sandboxClient}: the launch-and-cancel handshake,
+ *   the time limit, and the shell transcript. A configured shell merges the two
+ *   streams onto one of them, so `stderr` arrives empty and the whole transcript
+ *   is in `stdout` — see {@link file://./shell.ts withShellTranscript} for why a
+ *   model reading output wants that, and why the plugin's context block rather
+ *   than the tool description is where the model is told.
+ */
 export declare function execTools(ctx: ComputerContext): ToolSet;