@dynamicagents/plugins 0.12.0 → 0.13.0

package/dist/computer/tools-file.js

@@ -2,97 +2,37 @@ import { tool } from "ai";
 import { z } from "zod";
 import { guardPath } from "./paths.js";
 import { withFileLock } from "./file-lock.js";
-import { readBounded, readWindow } from "./read.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 function fileTools(ctx) {
-    const { maxChars, inWorkspace, refuseWrite, scope } = ctx;
+    const { inWorkspace, refuseWrite, scope } = ctx;
     return {
-        sb_read: tool({
-            description: "Read a file from the workspace. Returns the file's text, or a note if it does not exist. " +
-                "A large file comes back with its middle removed and a marker giving the `offset` that reaches the missing part. " +
-                "Pass `offset` (and optionally `length`) to read a specific byte window instead — the result states the window it returned and how many bytes follow, so you can page through a file. Byte offsets, not lines: to see the lines around a match, use sb_grep with `context`. " +
-                "Files under node_modules are not in the workspace — read them with sb_exec.",
-            inputSchema: z.object({
-                path: z
-                    .string()
-                    .describe("Absolute path, e.g. '/workspace/repo/src/a.ts'"),
-                offset: z
-                    .number()
-                    .int()
-                    .min(0)
-                    .optional()
-                    .describe("Byte offset to start reading from"),
-                length: z
-                    .number()
-                    .int()
-                    .min(1)
-                    .optional()
-                    .describe("Maximum bytes to return from `offset`")
-            }),
-            execute: async ({ path, offset, length }) => {
-                const refusal = guardPath(path, "sb_read");
-                if (refusal)
-                    return refusal;
-                return inWorkspace("reading", path, async (fs) => {
-                    // Either knob means the model chose a region; only an unqualified read
-                    // gets the middle-out guess.
-                    return offset === undefined && length === undefined
-                        ? await readBounded(fs, path, maxChars)
-                        : await readWindow(fs, path, offset ?? 0, length ?? maxChars, maxChars);
-                });
-            }
-        }),
-        sb_write: tool({
-            description: "Create or overwrite a file in the workspace. Parent directories are created for you. For a small change to a large file prefer sb_edit, which does not require sending the whole file back.",
-            inputSchema: z.object({
-                path: z.string().describe("Absolute path"),
-                content: z
-                    .string()
-                    .describe("Full file content (overwrites any existing file)")
-            }),
-            execute: async ({ path, content }) => {
-                const refusal = guardPath(path, "sb_write");
-                if (refusal)
-                    return refusal;
-                // Before the write, not after: the point is to not report a success that
-                // did not happen.
-                const lost = await refuseWrite();
-                if (lost)
-                    return lost;
-                return inWorkspace("writing", path, (fs) => withFileLock(scope(), path, async () => {
-                    const dir = path.slice(0, path.lastIndexOf("/"));
-                    if (dir)
-                        await fs.mkdir(dir, { recursive: true });
-                    await fs.writeFile(path, content);
-                    // Characters, not bytes. `String.length` counts UTF-16 code units — the
-                    // distinction `readBounded` documents at length — so calling them bytes
-                    // was simply wrong for anything outside ASCII. The exact byte count
-                    // would cost a `TextEncoder` pass over the whole content for a number
-                    // nobody does arithmetic with, and "characters" is already this module's
-                    // word for the same count in `truncateOutput`'s omission marker.
-                    const written = content.length;
-                    return `wrote ${path} (${written} character${written === 1 ? "" : "s"})`;
-                }));
-            }
-        }),
-        sb_edit: tool({
-            description: "Replace an exact string in a file. The string must be non-empty and must appear exactly once — if it appears zero times or more than once the edit is refused, so include enough surrounding context to make it unique.",
+        edit: tool({
+            description: "Replace an exact string in a file. old_string must be non-empty and must appear exactly once — if it appears zero times or more than once the edit is refused, so include enough surrounding context to make it unique. To create a file, use write.",
             inputSchema: z.object({
                 path: z.string().describe("Absolute path"),
-                find: z
+                old_string: z
                     .string()
                     // Empty is refused at the schema rather than in the body, because
                     // `split("")` does not count empty-string occurrences: on a file of
                     // one character it reports none, on a longer one it reports one per
                     // character, and on an *empty* file it reports -1 — which slips past
-                    // both guards below and writes `replace` into the file as if an edit
-                    // had been found. A write tool must not write what nobody asked for.
+                    // both guards below and writes `new_string` into the file as if an
+                    // edit had been found. A write tool must not write what nobody asked
+                    // for.
                     .min(1)
                     .describe("Exact text to replace, unique within the file"),
-                replace: z.string().describe("Replacement text")
+                new_string: z.string().describe("Replacement text")
             }),
-            execute: async ({ path, find, replace }) => {
-                const refusal = guardPath(path, "sb_edit");
+            execute: async ({ path, old_string, new_string }) => {
+                const refusal = guardPath(path, "edit");
                 if (refusal)
                     return refusal;
                 const lost = await refuseWrite();
@@ -100,9 +40,9 @@ export function fileTools(ctx) {
                     return lost;
                 return inWorkspace("editing", path, (fs) => withFileLock(scope(), path, async () => {
                     const content = await fs.readFile(path, "utf8");
-                    const occurrences = content.split(find).length - 1;
+                    const occurrences = content.split(old_string).length - 1;
                     // Refusing an ambiguous edit is the whole value of this tool over
-                    // sb_write: a silent first-match replace corrupts the file in a way
+                    // `write`: a silent first-match replace corrupts the file in a way
                     // that surfaces much later, usually as a confusing test failure.
                     if (occurrences === 0)
                         return `no match for that text in ${path}`;
@@ -115,7 +55,7 @@ export function fileTools(ctx) {
                     // in everything before the match. Those two are not exotic — `$$`
                     // escapes a dollar in a Makefile and reads a PID in shell, and `$'…'`
                     // is bash ANSI-C quoting. A function's return value is used verbatim.
-                    await fs.writeFile(path, content.replace(find, () => replace));
+                    await fs.writeFile(path, content.replace(old_string, () => new_string));
                     return `edited ${path}`;
                 }));
             }

package/dist/computer/{tools-find.d.ts → tools-grep.d.ts}

@@ -1,3 +1,3 @@
 import type { ToolSet } from "ai";
 import type { ComputerContext } from "./context.js";
-export declare function findTools(ctx: ComputerContext): ToolSet;
+export declare function grepTools(ctx: ComputerContext): ToolSet;

package/dist/computer/tools-grep.js

@@ -0,0 +1,129 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { guardPath, WALK_SKIPS } from "./paths.js";
+import { renderGrepMatches } from "./render.js";
+/**
+ * Searching file contents, under Think's name so it replaces Think's `grep` —
+ * which lists every file under the root and reads each one through the
+ * workspace, one round trip per file. Think's `find` and `list` stay Think's:
+ * over `computerWorkspace` they walk with `.git` and `node_modules` pruned.
+ */
+/**
+ * How many matches one `grep` returns.
+ *
+ * Bounded at the source: without a `limit`, `fs.grep` reads *every* file under
+ * the path looking for more, so an unbounded search of `/workspace` answers only
+ * after streaming the whole tree through the isolate. The limit stops that walk
+ * early; `exclude` keeps it out of `.git` and the dependency tree entirely.
+ */
+const DEFAULT_MAX_MATCHES = 200;
+/**
+ * The most `context` lines one `grep` shows around each match.
+ *
+ * Clamped rather than refused, since a refusal costs the model a step to retry.
+ * The bound is {@link file://./render.ts packBlocks}: it ships the first match's
+ * block whole, so a block has to stay well inside the output budget.
+ */
+const MAX_CONTEXT_LINES = 10;
+export function grepTools(ctx) {
+    const { cwd, maxChars, inWorkspace } = ctx;
+    return {
+        /**
+         * Search, without the container.
+         *
+         * The alternative is `bash("grep -rn …")`, and the case for a native one is
+         * not that shelling out fails — it is where the search runs. `fs.grep` reads
+         * the Durable Object's SQLite, so it answers while the container is being
+         * replaced or an install is still running, which is exactly the window the
+         * install gate leaves an agent with nothing to do. It is also why this tool
+         * is not gated: see {@link file://./context.ts awaitAdvisories}.
+         *
+         * And not Think's `grep`, which globs every file under the root and reads
+         * each one through the workspace.
+         *
+         * Two lesser reasons that still matter. The query arrives as a value rather
+         * than through `shellQuote` and a shell that would re-parse it. And the result
+         * is bounded by a `limit` at the source instead of being middle-truncated
+         * afterwards, which for a match list means losing whole files silently.
+         */
+        grep: tool({
+            description: "Search file contents across the workspace. Returns matching lines grouped by file, each with its line number. " +
+                "The query is matched literally — set `regex` to interpret it as a regular expression. " +
+                "Pass `include` to limit which files are searched, e.g. '**/*.ts' — without it every file under `path` is read, which is slower and rarely what you meant. " +
+                "A cut result reports the `offset` that continues it. Use `context` to see the lines around a match. " +
+                "Results from `.git` and `node_modules` are left out — search node_modules with bash.",
+            inputSchema: z.object({
+                query: z.string().describe("Text to find, e.g. 'buildComputerTools'"),
+                path: z
+                    .string()
+                    .optional()
+                    .describe(`Absolute file or directory to search (default: ${cwd})`),
+                include: z
+                    .string()
+                    .optional()
+                    .describe("Glob relative to path limiting which files are searched, e.g. '**/*.ts'"),
+                regex: z
+                    .boolean()
+                    .optional()
+                    .describe("Interpret query as a regular expression"),
+                ignoreCase: z.boolean().optional().describe("Ignore letter case"),
+                context: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .optional()
+                    .describe(`Lines of surrounding context to include with each match, at most ${MAX_CONTEXT_LINES}`),
+                offset: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .optional()
+                    .describe("Matches to skip — use the offset a cut result reports")
+            }),
+            execute: async ({ query, path, include, regex, ignoreCase, context, offset }) => {
+                const target = path ?? cwd;
+                const refusal = guardPath(target, "grep");
+                if (refusal)
+                    return refusal;
+                const from = offset ?? 0;
+                const around = context === undefined
+                    ? undefined
+                    : Math.min(context, MAX_CONTEXT_LINES);
+                return inWorkspace("searching", target, async (fs) => {
+                    // Pruned in the store, not filtered here: an excluded directory is
+                    // never descended into, so `node_modules` costs nothing to skip and
+                    // `offset` counts only matches the model can actually be shown. A
+                    // filter on this side could not do either — it pages blind, so a
+                    // crowded page could hide every real match behind skipped ones.
+                    const matches = await fs.grep(query, target, {
+                        include,
+                        regex,
+                        ignoreCase,
+                        context: around,
+                        limit: DEFAULT_MAX_MATCHES + 1,
+                        offset: from,
+                        exclude: WALK_SKIPS.map((segment) => `**/${segment}`)
+                    });
+                    if (matches.length === 0)
+                        return `no matches for ${JSON.stringify(query)} in ${target}${include ? ` (${include})` : ""}${from > 0 ? ` past offset ${from}` : ""}`;
+                    const { body, shown, capped } = renderGrepMatches(matches.slice(0, DEFAULT_MAX_MATCHES), maxChars);
+                    return (body +
+                        // `shown` falls short of what came back either because the page was
+                        // capped or because the render budget ran out; both continue here.
+                        (shown < matches.length
+                            ? `\n\n… showed ${shown} matches; there are more. Continue with ` +
+                                `\`offset: ${from + shown}\`, or narrow with \`include\` — ` +
+                                `narrowing is cheaper, since an offset still walks everything ` +
+                                `it skips.`
+                            : "") +
+                        (capped
+                            ? `\n(Some lines were shortened. Read one in full with \`read\`, passing its line number as \`offset\`.)`
+                            : "") +
+                        (around !== context
+                            ? `\n(\`context\` is at most ${MAX_CONTEXT_LINES}, so ${context} was clamped to ${MAX_CONTEXT_LINES}. Read a wider region with \`read\`.)`
+                            : ""));
+                });
+            }
+        })
+    };
+}

package/dist/repo/checkout.d.ts

@@ -77,9 +77,8 @@ export declare function resolveDefaultBranch(plain: GitRunners["plain"], dir: st
  * on the commit itself, which is the one layer a stale config cannot outrank.
  * Underneath, a repository this plugin never cloned falls back to whatever the
  * shell's own git is configured with — which is an identity rather than nothing
- * only where `exec` is backed by the computer plugin, whose workspace writes one
- * per container; see
- * {@link file://../computer/host/git-identity.ts}. `exec` is an arbitrary
+ * only where `exec` is backed by `/workspace`, whose object writes one per
+ * container; see {@link file://../workspace/git-identity.ts}. `exec` is an arbitrary
  * runner, so that is a property of a deployment, not of this plugin.
  *
  * Unchecked, like the config pins at the clone: git's identity is needed by the
@@ -95,13 +94,13 @@ export declare function writeGitIdentity(plain: GitRunners["plain"], dir: string
  *
  * The workspace outlives the task, so a clone target may already hold one —
  * where `git clone` fails with "destination path already exists and is not an
- * empty directory" and the round has to improvise from an error that reads like
+ * empty directory" and the model has to improvise from an error that reads like
  * a bug.
  *
  * The refusal on a dirty tree is the important half. Uncommitted changes there
  * are a *previous task's work* — possibly the thing a human is waiting on — and
  * silently `reset --hard`ing them away to make a fresh clone look clean is the
- * one outcome nobody could recover from. Refusing costs a round; discarding
+ * one outcome nobody could recover from. Refusing costs a tool call; discarding
  * costs the work.
  */
 export declare function refreshCheckout({ dir, url, branch, author, plain, fetchOrigin }: GitRunners & {

package/dist/repo/checkout.js

@@ -34,9 +34,8 @@ export async function resolveDefaultBranch(plain, dir) {
  * on the commit itself, which is the one layer a stale config cannot outrank.
  * Underneath, a repository this plugin never cloned falls back to whatever the
  * shell's own git is configured with — which is an identity rather than nothing
- * only where `exec` is backed by the computer plugin, whose workspace writes one
- * per container; see
- * {@link file://../computer/host/git-identity.ts}. `exec` is an arbitrary
+ * only where `exec` is backed by `/workspace`, whose object writes one per
+ * container; see {@link file://../workspace/git-identity.ts}. `exec` is an arbitrary
  * runner, so that is a property of a deployment, not of this plugin.
  *
  * Unchecked, like the config pins at the clone: git's identity is needed by the
@@ -56,13 +55,13 @@ export async function writeGitIdentity(plain, dir, author) {
  *
  * The workspace outlives the task, so a clone target may already hold one —
  * where `git clone` fails with "destination path already exists and is not an
- * empty directory" and the round has to improvise from an error that reads like
+ * empty directory" and the model has to improvise from an error that reads like
  * a bug.
  *
  * The refusal on a dirty tree is the important half. Uncommitted changes there
  * are a *previous task's work* — possibly the thing a human is waiting on — and
  * silently `reset --hard`ing them away to make a fresh clone look clean is the
- * one outcome nobody could recover from. Refusing costs a round; discarding
+ * one outcome nobody could recover from. Refusing costs a tool call; discarding
  * costs the work.
  */
 export async function refreshCheckout({ dir, url, branch, author, plain, fetchOrigin }) {
@@ -99,7 +98,14 @@ export async function refreshCheckout({ dir, url, branch, author, plain, fetchOr
     // and `reset --hard`. Conflating the two lets a permissions error or a
     // half-written index discard a tree nobody established was clean, which is the
     // one loss in this file that cannot be undone.
-    const dirty = await plain("status --porcelain", dir);
+    //
+    // Submodules are left out of the question. Neither `checkout` nor
+    // `reset --hard` below touches a submodule's tree without
+    // `--recurse-submodules`, so a submodule that has moved past its pin — which
+    // is what a superproject looks like after its own sync — is not work this
+    // refresh could lose. Counted as dirty, it would refuse every refresh of such
+    // a checkout, and a host's `afterCheckout` would never learn it is there.
+    const dirty = await plain("status --porcelain --ignore-submodules=all", dir);
     if (!dirty.success) {
         return {
             message: `could not read the state of the checkout at ${dir}: ` +
@@ -121,9 +127,26 @@ export async function refreshCheckout({ dir, url, branch, author, plain, fetchOr
                 `Nothing was fetched or reset.`
         };
     }
+    /**
+     * A failed fetch leaves a checkout that is still there, still clean and still
+     * on its branch — only not updated. So it is still reported, on the branch it
+     * is on: a host that records checkouts would otherwise lose sight of one that
+     * exists because its remote could not be reached, and a clone taken from the
+     * recorded url goes to the remote itself. Nothing below — no checkout, no
+     * reset — runs against a tree whose remote state is unknown.
+     */
     const fetched = await fetchOrigin(dir, url);
-    if (!fetched.success)
-        return { message: `fetch failed: ${fetched.stderr || fetched.stdout}` };
+    if (!fetched.success) {
+        const failure = `fetch failed: ${fetched.stderr || fetched.stdout}`;
+        const current = await plain("symbolic-ref --quiet --short HEAD", dir);
+        const on = current.success ? current.stdout.trim() : "";
+        if (!on)
+            return { message: failure };
+        return {
+            message: `${failure}\nThe checkout was left on ${on}, clean but not updated from the remote.`,
+            branch: on
+        };
+    }
     // The branch to land on: the one asked for, else the remote's own default.
     let target = branch;
     if (!target) {

package/dist/repo/context.d.ts

@@ -1,6 +1,7 @@
+import type { ActionContext } from "@cloudflare/think";
 import type { RepoCheckout, RepoConfig, RepoExec, RepoGitResult } from "./index.js";
 /**
- * How many items one forge list call asks for. GitHub's maximum, and its default
+ * How many items one GitHub list call asks for. GitHub's maximum, and its default
  * without this is 30.
  *
  * One page, never a Link-header walk: an unbounded fetch loop does not belong
@@ -9,7 +10,7 @@ import type { RepoCheckout, RepoConfig, RepoExec, RepoGitResult } from "./index.
  * presented as the whole answer — a pull request's newest review comments are on
  * the last page, and those are exactly the ones an agent was sent to act on.
  */
-export declare const FORGE_PAGE_SIZE = 100;
+export declare const GITHUB_PAGE_SIZE = 100;
 /**
  * Where GraphQL lives, given where REST does.
  *
@@ -24,10 +25,10 @@ export declare function graphqlEndpoint(apiBase: string): string;
 /**
  * Middle-out truncation, so both the head of a diff and its tail survive.
  *
- * Deliberately a **copy** of the computer plugin's function of the same name,
- * not an import. `npm run verify:exports` fails any subpath whose module graph
+ * Deliberately a **copy** of `/workspace`'s function of the same name, not an
+ * import. `npm run verify:exports` fails any subpath whose module graph
  * reaches a sibling's directory, and its own advice for a shared helper is to
- * duplicate it — installing `repo` must not drag `computer` (and therefore
+ * duplicate it — installing `repo` must not drag `/workspace` (and therefore
  * `@cloudflare/computer`) into a consumer's bundle. Fifteen lines is a cheaper
  * price than that coupling, and it is the same reason `exec` is injected here
  * rather than imported.
@@ -82,7 +83,7 @@ export interface RepoContext {
         };
         unreachable?: string;
     }>;
-    forge: (tool: string, path: string, init?: {
+    github: (tool: string, path: string, init?: {
         method: string;
         body: unknown;
     }) => Promise<{
@@ -92,18 +93,43 @@ export interface RepoContext {
         ok: false;
         message: string;
     }>;
-    forgeGraphql: (tool: string, query: string, variables: Record<string, unknown>) => Promise<{
+    githubGraphql: (tool: string, query: string, variables: Record<string, unknown>) => Promise<{
         ok: true;
         data: unknown;
     } | {
         ok: false;
         message: string;
     }>;
-    forgeRepo: (dir: string) => Promise<{
+    githubRepo: (dir: string) => Promise<{
         owner: string;
         repo: string;
     } | {
         refusal: string;
     }>;
 }
-export declare function repoContext(config: RepoConfig, runtime?: unknown): RepoContext;
+/**
+ * How long an action that calls GitHub may run before Think gives up on it.
+ *
+ * An action's default is thirty seconds, which is {@link GITHUB_TIMEOUT_MS}
+ * alone — and a thread reply is three GitHub calls, after an `origin` read that
+ * waits its turn in the git queue.
+ */
+export declare const GITHUB_ACTION_TIMEOUT_MS = 120000;
+/**
+ * The task an action runs for, which leads its idempotency key.
+ *
+ * Think replays a settled key for as long as it keeps the row
+ * (`actionLedgerRetention`), so a key without the task would replay, not post,
+ * the same comment in a later task. Every turn core runs carries a task id, so
+ * a missing one is a wiring fault — and keying without it would be the silent
+ * version of that fault.
+ */
+export declare function actionTask(ctx: ActionContext): string;
+/** A hex SHA-256, so a key names a body without carrying it. */
+export declare function sha256(text: string): Promise<string>;
+export declare function repoContext(config: RepoConfig, 
+/**
+ * The running sub-agent's `runtime()`, read per command. Forwarded to every
+ * `exec`; see {@link RepoExec}'s `runtime` option.
+ */
+runtime?: () => unknown): RepoContext;