@dynamicagents/plugins 0.12.0 → 0.13.0

package/dist/repo/context.js

@@ -1,7 +1,7 @@
 import { DEFAULT_ALLOWED_HOSTS, parseRepo, repoLocation } from "./url.js";
 /**
  * The machinery every repo tool closes over: the resolved config, the git
- * runners, and the forge client.
+ * runners, and the GitHub client.
  */
 const DEFAULT_WORKDIR = "/workspace";
 const DEFAULT_API_BASE = "https://api.github.com";
@@ -11,15 +11,15 @@ const DEFAULT_AUTHOR = {
 };
 const DEFAULT_MAX_OUTPUT_CHARS = 16_000;
 /**
- * Ceiling on every call this plugin makes to the forge's API.
+ * Ceiling on every call this plugin makes to GitHub's API.
  *
  * Not configurable, because it is not a tuning knob: it exists so an API that
- * stops answering costs a round rather than the task. These are single small
+ * stops answering costs a tool call rather than the task. These are single small
  * requests, and thirty seconds is already generous for one.
  */
-const FORGE_TIMEOUT_MS = 30_000;
+const GITHUB_TIMEOUT_MS = 30_000;
 /**
- * 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
@@ -28,7 +28,7 @@ const FORGE_TIMEOUT_MS = 30_000;
  * 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 const FORGE_PAGE_SIZE = 100;
+export const GITHUB_PAGE_SIZE = 100;
 /**
  * Where GraphQL lives, given where REST does.
  *
@@ -47,10 +47,10 @@ export function graphqlEndpoint(apiBase) {
 /**
  * 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.
@@ -74,7 +74,7 @@ export function truncateOutput(text, max) {
  * A sibling of the computer plugin's `execLostNote` rather than an import, for
  * the same reason {@link truncateOutput} is a copy: `verify:exports` fails any
  * subpath whose module graph reaches a sibling's, and installing `repo` must
- * not drag `computer` in behind it. The wording differs anyway, and the
+ * not drag `/computer` in behind it. The wording differs anyway, and the
  * difference is the point — that plugin cannot know the lost command was git,
  * and this one does. What a model needs after a lost `git push` is not "re-run
  * it" but whether re-running it is *safe*.
@@ -85,7 +85,7 @@ function unreachableNote(err) {
             "is known to have finished. This is infrastructure — not git, and not what " +
             "you asked for. The checkout is durable and is exactly as you left it. " +
             "Retry, and read what the retry says rather than assuming it starts from " +
-            "nothing: a command that had already reached the forge may have taken " +
+            "nothing: a command that had already reached GitHub may have taken " +
             "effect. Retrying is safe either way — these commands push one branch to " +
             "the branch of the same name, and never force.");
     }
@@ -102,13 +102,13 @@ function unreachableNote(err) {
  * than waiting if it is already held. A model may emit several tool calls in one
  * turn and the SDK runs them concurrently, so unserialised a `repo_commit` and a
  * `repo_push` race: the commit fails, the push succeeds against the previous
- * state, and the round reports work that never landed.
+ * state, and the turn reports work that never landed.
  *
  * Held here rather than in {@link repoContext}'s closure, because that closure
- * is too short-lived to be the boundary. Core rebuilds `mainAgentTools` every
- * turn and gives each subagent execution its own tool family, so a per-call queue
- * leaves a subagent racing its parent over one checkout — the same collision, one
- * level up. The config object is the plugin instance, and a `WeakMap` means a
+ * is too short-lived to be the boundary. The tools are built for every turn, and
+ * a sub-agent builds its own from the same config, so a per-call queue leaves a
+ * sub-agent racing its parent over one checkout — the same collision, one level
+ * up. The config object is the plugin instance, and a `WeakMap` means a
  * discarded agent takes its queue with it.
  *
  * A promise chain rather than a lock, because that is all the scope needs: one
@@ -145,11 +145,10 @@ const gitQueues = new WeakMap();
  *
  * A command whose container or host never answers — a workspace object that
  * reset under it — would otherwise hold every git command behind it for the life
- * of the isolate, each abandoned in turn at core's per-call limit. Past this the
- * command is reported unreachable and the queue moves on. It may still be
- * running; a later command that meets its `index.lock` fails fast and says so.
- * Under that per-call limit, so the tool answers for itself rather than being
- * abandoned, and far longer than any git command here takes.
+ * of the isolate. Past this the command is reported unreachable and the queue
+ * moves on. It may still be running; a later command that meets its
+ * `index.lock` fails fast and says so. Far longer than any git command here
+ * takes.
  */
 const GIT_SLOT_MS = 8 * 60_000;
 /** `work`, rejected once {@link GIT_SLOT_MS} passes without it settling. */
@@ -162,7 +161,43 @@ function withinSlot(work) {
     work.catch(() => { });
     return Promise.race([work, expired]).finally(() => clearTimeout(timer));
 }
-export function repoContext(config, runtime) {
+/**
+ * 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 const GITHUB_ACTION_TIMEOUT_MS = 120_000;
+/**
+ * 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 function actionTask(ctx) {
+    const task = ctx.agent.activeTurnMetadata?.taskId;
+    if (typeof task !== "string")
+        throw new Error("this turn carries no task id, so a GitHub write cannot be keyed to it — " +
+            "the repo plugin's actions run only in turns core started for a task");
+    return task;
+}
+/** A hex SHA-256, so a key names a body without carrying it. */
+export async function sha256(text) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+    return [...new Uint8Array(digest)]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+}
+export function repoContext(config, 
+/**
+ * The running sub-agent's `runtime()`, read per command. Forwarded to every
+ * `exec`; see {@link RepoExec}'s `runtime` option.
+ */
+runtime = () => undefined) {
     const workdir = config.workdir ?? DEFAULT_WORKDIR;
     const apiBase = config.apiBase ?? DEFAULT_API_BASE;
     const graphqlUrl = graphqlEndpoint(apiBase);
@@ -194,7 +229,7 @@ export function repoContext(config, runtime) {
         }
     };
     /**
-     * The forge credential, or the reason there is none.
+     * The GitHub credential, or the reason there is none.
      *
      * `config.token` is the host's thunk, and an unresolvable secret throws at the
      * moment of use rather than at startup. Every caller here has a sentence to
@@ -208,7 +243,7 @@ export function repoContext(config, runtime) {
         }
         catch (err) {
             return {
-                failure: `the forge credential could not be read: ${String(err)}. That is the ` +
+                failure: `the GitHub credential could not be read: ${String(err)}. That is the ` +
                     `host's configuration rather than anything you passed — report it ` +
                     `rather than working around it.`
             };
@@ -229,8 +264,8 @@ export function repoContext(config, runtime) {
      * of an investigation and findable only by timestamp.
      *
      * The token is scrubbed rather than trusted. It has no route into a container
-     * command, and the one channel that could carry it is the forge API's error
-     * body, which {@link forge} logs through this same function. So stderr *should*
+     * command, and the one channel that could carry it is the GitHub API's error
+     * body, which {@link github} logs through this same function. So stderr *should*
      * be clean — but "should be" is not the standard for something that writes a
      * credential into a log that outlives the request, and the scrub costs a
      * `split`/`join` on a path that already failed.
@@ -308,7 +343,7 @@ export function repoContext(config, runtime) {
      */
     const shell = (script, cwd, vars = {}) => run(script, () => ({
         cwd,
-        runtime,
+        runtime: runtime(),
         env: { GIT_TERMINAL_PROMPT: "0", ...vars }
     }));
     const plain = (args, cwd, vars = {}) => shell(`git ${args}`, cwd, vars);
@@ -366,9 +401,9 @@ export function repoContext(config, runtime) {
     /** Push one branch to the same-named branch on the remote. Never forced. */
     const pushBranch = (dir, url, branch) => runGit(() => config.git.push({ url, dir, branch, allowedHosts }));
     /**
-     * One call to the forge's API, from the Worker.
+     * One call to GitHub's API, from the Worker.
      *
-     * Every tool here that talks to the forge goes through this, so the credential
+     * Every tool here that talks to GitHub goes through this, so the credential
      * stays on the Worker's side of the boundary and the bound, the header set and
      * the refusal to let an unreadable body replace an explanatory status are
      * written once.
@@ -377,14 +412,14 @@ export function repoContext(config, runtime) {
      * its own sentence to add: a POST whose answer never arrived may have been
      * received, which a GET has no reason to warn about.
      */
-    const forge = (tool, path, init) => forgeAt(tool, `${apiBase}${path}`, init);
+    const github = (tool, path, init) => githubAt(tool, `${apiBase}${path}`, init);
     /**
      * The same call, against a URL rather than a path under {@link apiBase}.
      *
      * GraphQL needs it: on Enterprise the REST base carries `/api/v3` and GraphQL
      * does not live under it — see {@link graphqlEndpoint}.
      */
-    const forgeAt = async (tool, url, init) => {
+    const githubAt = async (tool, url, init) => {
         const secret = credential();
         if ("failure" in secret) {
             logFailure(tool, { stderr: secret.failure });
@@ -401,7 +436,7 @@ export function repoContext(config, runtime) {
                     "user-agent": "da-coder"
                 },
                 ...(init ? { body: JSON.stringify(init.body) } : {}),
-                signal: AbortSignal.timeout(FORGE_TIMEOUT_MS)
+                signal: AbortSignal.timeout(GITHUB_TIMEOUT_MS)
             });
         }
         catch (err) {
@@ -419,7 +454,7 @@ export function repoContext(config, runtime) {
         return { ok: true, data: await response.json().catch(() => ({})) };
     };
     /**
-     * One GraphQL query or mutation, over {@link forge} so the credential, the
+     * One GraphQL query or mutation, over {@link github} so the credential, the
      * bound, the headers and the scrubbed failure log stay written once.
      *
      * **A failed GraphQL query answers `200`.** The errors are in the body, so
@@ -434,8 +469,8 @@ export function repoContext(config, runtime) {
      * `repo_issue_view` reads, and a review *request* naming an app is invisible to
      * REST — see {@link file://./tools-review.ts REVIEW_REQUESTS_QUERY}.
      */
-    const forgeGraphql = async (tool, query, variables) => {
-        const answered = await forgeAt(tool, graphqlUrl, {
+    const githubGraphql = async (tool, query, variables) => {
+        const answered = await githubAt(tool, graphqlUrl, {
             method: "POST",
             body: { query, variables }
         });
@@ -455,7 +490,7 @@ export function repoContext(config, runtime) {
         return { ok: true, data: body.data };
     };
     /**
-     * Which repository the tools that read the forge are talking about.
+     * Which repository the tools that read GitHub are talking about.
      *
      * The checkout's own origin, never a URL the model supplies. Three reasons, in
      * order of how much they matter: the origin has already been through the host
@@ -465,7 +500,7 @@ export function repoContext(config, runtime) {
      * "issue 42" almost always means the repository it is working in, so the extra
      * parameter would mostly be an extra way to be wrong.
      */
-    const forgeRepo = async (dir) => {
+    const githubRepo = async (dir) => {
         const { remote, unreachable } = await origin(dir);
         if (unreachable)
             return { refusal: bounded(unreachable) };
@@ -491,15 +526,32 @@ export function repoContext(config, runtime) {
      * `repo_clone` only ever writes after the allowlist has passed.
      */
     const origin = async (dir) => {
-        const result = await plain("remote get-url origin", dir);
-        // Two different nothings. `repo_push`'s answer to "no origin here" is to
-        // tell the model to clone the repository first — advice that is actively
-        // wrong when the truth is that no command ran at all.
-        if (result.unreachable)
-            return { unreachable: result.stderr };
-        if (!result.success)
-            return {};
-        const url = result.stdout.trim();
+        let url;
+        if (config.git.origin) {
+            let read;
+            try {
+                read = await config.git.origin(dir);
+            }
+            catch (err) {
+                return {
+                    unreachable: `the workspace could not be reached to read ${dir}'s origin: ${String(err)}`
+                };
+            }
+            if (!read)
+                return {};
+            url = read.trim();
+        }
+        else {
+            const result = await plain("remote get-url origin", dir);
+            // Two different nothings. `repo_push`'s answer to "no origin here" is to
+            // tell the model to clone the repository first — advice that is actively
+            // wrong when the truth is that no command ran at all.
+            if (result.unreachable)
+                return { unreachable: result.stderr };
+            if (!result.success)
+                return {};
+            url = result.stdout.trim();
+        }
         const location = repoLocation(url);
         if (!location || !allowedHosts.includes(location.host))
             return {};
@@ -523,8 +575,8 @@ export function repoContext(config, runtime) {
         fetchOrigin,
         pushBranch,
         origin,
-        forge,
-        forgeGraphql,
-        forgeRepo
+        github,
+        githubGraphql,
+        githubRepo
     };
 }

package/dist/repo/index.d.ts

@@ -1,4 +1,3 @@
-import type { ToolSet } from "ai";
 import type { AgentPlugin } from "@dynamicagents/core";
 /**
  * The URL parsing, re-exported from the one entry point.
@@ -13,8 +12,8 @@ export { graphqlEndpoint, truncateOutput } from "./context.js";
  * `@dynamicagents/plugins/repo` — clone, commit, push, open a pull request.
  *
  * Layered over a container rather than owning one: it needs a shell with `git`
- * on it, and `@dynamicagents/plugins/computer` provides exactly that through
- * `computerExec`. Passing `exec` in rather than importing that plugin keeps the
+ * on it, and `@dynamicagents/plugins/workspace` provides exactly that through
+ * `workspaceExec`. Passing `exec` in rather than importing that plugin keeps the
  * two independent — a host with its own container can use this against that
  * instead, and the tests here need no container at all.
  *
@@ -27,7 +26,7 @@ export { graphqlEndpoint, truncateOutput } from "./context.js";
  * none of it needs to authenticate.
  *
  * That split is the one thing to preserve when changing this file: if an
- * operation talks to the forge it does not belong on `exec`, and if it does not,
+ * operation talks to GitHub it does not belong on `exec`, and if it does not,
  * it has no business anywhere else.
  *
  * It is absolute rather than careful because a narrower version does not hold.
@@ -41,9 +40,9 @@ export { graphqlEndpoint, truncateOutput } from "./context.js";
  * the length of one command is readable at `/proc/<pid>/environ` by anything
  * else in the container.
  *
- * Two further rules, which are about the forge rather than the container:
+ * Two further rules, which are about GitHub rather than the container:
  *
- * 1. **The forge is an allowlist, checked before anything runs.** A clone URL is
+ * 1. **GitHub's hosts are an allowlist, checked before anything runs.** A clone URL is
  *    model input — a repository README, an issue body, or a page fetched by a
  *    co-installed browser plugin is enough to choose it — and a credential
  *    offered to a host of the model's choosing is the whole game. So the URL's
@@ -52,7 +51,7 @@ export { graphqlEndpoint, truncateOutput } from "./context.js";
  *    check to the moment the token would actually be handed over. `origin` is
  *    re-derived and re-checked on every push rather than remembered, because the
  *    checkout's `.git/config` is a file the container can rewrite.
- * 2. **The forge API is called from the Worker**, so the credential that can
+ * 2. **The GitHub API is called from the Worker**, so the credential that can
  *    write to a repository through the API never crosses the boundary either.
  *    Every tool that reads or writes through it resolves the repository from the
  *    checkout's own origin rather than from a parameter, so there is no way to
@@ -67,23 +66,20 @@ export { graphqlEndpoint, truncateOutput } from "./context.js";
  * repository. Whatever the token can reach, an agent talked into naming it can
  * reach. See the README — the token wants to be fine-grained.
  */
-/** This plugin's tool-family name, as a recipe's `toolFamilies` lists it. */
-export declare const REPO_FAMILY = "repo";
-/** Run one command in the host's container. Matches `computerExec`'s shape. */
+/** Run one command in the host's container. Matches `workspaceExec`'s shape. */
 export type RepoExec = (command: string, options?: {
     cwd?: string;
     env?: Record<string, string | undefined>;
     timeout?: number;
     /**
-     * The executing subtask's runtime state, forwarded **opaquely**.
+     * The running sub-agent's `runtime()`, forwarded **opaquely**.
      *
-     * This plugin never looks inside it. A delegated subtask has to reach the
-     * container its parent prepared, and the key for that lives in the runtime
-     * state the parent resolved — but decoding it is the container plugin's
+     * This plugin never looks inside it. A sub-agent has to reach the
+     * container its parent prepared, and the key for that lives in what the
+     * parent's `prepare` returned — but decoding it is the container plugin's
      * business, not git's. Passing it through untouched is what lets the two
-     * plugins compose
-     * without either importing the other, which is the whole reason `exec` is
-     * injected rather than imported.
+     * plugins compose without either importing the other, which is the whole
+     * reason `exec` is injected rather than imported.
      */
     runtime?: unknown;
 }) => Promise<{
@@ -93,7 +89,7 @@ export type RepoExec = (command: string, options?: {
     exitCode: number;
 }>;
 /**
- * The three git operations that need the forge token, run by the host.
+ * The three git operations that need the GitHub token, run by the host.
  *
  * Injected for the same reason {@link RepoExec} is — this plugin owns the
  * policy, not the plumbing — but the split between the two is not arbitrary. It
@@ -102,7 +98,7 @@ export type RepoExec = (command: string, options?: {
  * keeps its secret and never touches the container at all.
  *
  * That is why `clone`, `fetch` and `push` are the whole interface. They are
- * exactly the operations that talk to the forge. `status`, `diff`, `add`,
+ * exactly the operations that talk to GitHub. `status`, `diff`, `add`,
  * `commit` and `checkout` are local, need nothing to authenticate with, and stay
  * on `exec` where they are cheap and where the model can see them work.
  *
@@ -155,6 +151,14 @@ export interface RepoGit {
         branch: string;
         allowedHosts: string[];
     }): Promise<RepoGitResult>;
+    /**
+     * The checkout's `origin` URL, read on the host's side; `undefined` for none.
+     *
+     * Optional. Set, the GitHub tools resolve their repository without the
+     * container, so an agent polling a pull request does not keep one running.
+     * Unset, the origin is read through {@link RepoConfig.exec}.
+     */
+    origin?(dir: string): Promise<string | undefined>;
 }
 /** What a {@link RepoGit} operation reports. */
 export type RepoGitResult = {
@@ -169,14 +173,14 @@ export interface RepoConfig {
     /**
      * Runs commands in the container holding the checkout.
      *
-     * Uncredentialed, always. Nothing this runs is ever given the forge token —
+     * Uncredentialed, always. Nothing this runs is ever given the GitHub token —
      * see {@link RepoGit} for the operations that need one.
      */
     exec: RepoExec;
     /** Runs the three credentialed operations, on the host's side of the boundary. */
     git: RepoGit;
     /**
-     * A forge token with contents+pull-request write. A thunk so a rotated secret
+     * A GitHub token with contents+pull-request write. A thunk so a rotated secret
      * is picked up without rebuilding the plugin list.
      */
     token: () => string;
@@ -205,9 +209,9 @@ export interface RepoConfig {
      * 16,000 non-ASCII characters is three times that many UTF-8 bytes.
      *
      * `repo_diff` is the main input for an agent that
-     * reviews rather than writes — a delegating coder whose subagents hold the
-     * shell — and an unbounded diff on a large change is precisely the context
-     * blowup that design exists to prevent.
+     * reviews rather than writes — a coder whose sub-agents hold the shell — and
+     * an unbounded diff on a large change is precisely the context blowup that
+     * design exists to prevent.
      */
     maxOutputChars?: number;
     /**
@@ -228,7 +232,7 @@ export interface RepoConfig {
      * not — a host that stored the path alongside its install state found that a
      * repository the resolver had nothing to install in (no `package.json`) cloned
      * perfectly, reported itself correctly, and could never be worked in, because
-     * the one path its subagents needed was written on a branch that never ran.
+     * the one path its sub-agents needed was written on a branch that never ran.
      *
      * Awaited, so it can record intent durably, but it must **return quickly**:
      * it runs inside `repo_clone`, which runs inside a model turn. A host that
@@ -265,6 +269,50 @@ export interface RepoConfig {
         owner: string;
         repo: string;
     }) => void;
+    /**
+     * The worktrees a host keeps for its sub-agents' work, and the way between
+     * them.
+     *
+     * Set, the plugin offers `repo_worktrees` and `repo_worktree`. A switch moves
+     * the installing agent's own tools, so a host sets this on the parent's
+     * install and never on a sub-agent's. See {@link RepoWorktrees}.
+     */
+    worktrees?: RepoWorktrees;
+    /**
+     * The tools this install offers, and with them the lines of context that
+     * describe them. Unset, every tool. A selection rather than core's
+     * `restrictTools`, which drops a plugin's context whole: an agent that
+     * coordinates others' work reads about the tools it has and no others.
+     */
+    tools?: readonly RepoToolName[];
+}
+/** Every tool and action this plugin can offer, by the name the model sees. */
+export declare const REPO_TOOL_NAMES: readonly ["repo_clone", "repo_fetch", "repo_status", "repo_diff", "repo_commit", "repo_push", "repo_open_pr", "repo_issue_view", "repo_pr_view", "repo_pr_comment", "repo_pr_review_status", "repo_pr_threads", "repo_pr_thread_reply", "repo_pr_checks", "repo_worktrees", "repo_worktree"];
+export type RepoToolName = (typeof REPO_TOOL_NAMES)[number];
+/**
+ * Checkouts a host keeps apart from the main one — each holding a branch its
+ * writing sub-agents committed on — and the switch that points every repo tool
+ * at one of them.
+ *
+ * The host renders every answer: which worktrees exist, where their checkouts
+ * sit and what is safe to do in them are its facts, and a sentence is what the
+ * model reads.
+ */
+export interface RepoWorktrees {
+    /** Every worktree, with its branch and state. */
+    list(): Promise<string>;
+    /**
+     * Point every repo tool — and whatever else the host routes the same way — at
+     * the worktree holding `branch`, or back at the main checkout when it is absent.
+     * Answers what the model now has in front of it.
+     *
+     * The switch holds until the next one. This answer is what the model
+     * remembers, so a host that moves the tools on its own says so where the
+     * model reads it every turn.
+     */
+    use(branch?: string): Promise<string>;
+    /** Give up `branch`'s worktree, and the unpushed work in it. */
+    release(branch: string): Promise<string>;
 }
 /** What {@link RepoConfig.afterCheckout} is told about a checkout. */
 export interface RepoCheckout {
@@ -294,9 +342,6 @@ export interface RepoCheckout {
     /** True for a first clone, false when an existing tree was refreshed. */
     fresh: boolean;
 }
-export declare function buildRepoTools(config: RepoConfig, 
-/** Forwarded to every `exec`; see {@link RepoExec}'s `runtime` option. */
-runtime?: unknown): ToolSet;
 /**
  * No tool here is held for a person's approval — see this plugin's README for
  * why, and for what a fork that wants one does instead.