@dynamicagents/plugins 0.11.0 → 0.12.0

package/dist/repo/tools-review.js

@@ -0,0 +1,373 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { FORGE_PAGE_SIZE } from "./context.js";
+/** A review as a conversation: whether it landed, what it said, and answering it. */
+/**
+ * How many pages of review threads one `repo_pr_threads` call will walk.
+ *
+ * A bound rather than a full walk, for the reason {@link FORGE_PAGE_SIZE} is one
+ * — but unlike the single page everything else here takes, threads genuinely
+ * have to page: a review long enough to spill one puts its newest threads on the
+ * last page, and those are exactly the ones an agent was sent to answer. So this
+ * is high enough that a real review never reaches it and low enough that a
+ * pathological pull request cannot turn one tool call into an unbounded number of
+ * round trips.
+ */
+const MAX_THREAD_PAGES = 10;
+/**
+ * How much of one thread's conversation is read back.
+ *
+ * Both ends, because the two uses pull opposite ways: what the reviewer asked for
+ * is at the top, and whether a reply landed is at the bottom. A thread shorter
+ * than this is returned whole and the two selections are the same comments, which
+ * is why the render de-duplicates on the count rather than on the text.
+ */
+const MAX_THREAD_COMMENTS = 6;
+/**
+ * The review threads on one pull request.
+ *
+ * `isResolved` is the field the whole workflow turns on and REST does not expose
+ * at all — which is why these three operations are GraphQL while everything else
+ * in this file is REST. Both ends of each thread are selected; see
+ * {@link MAX_THREAD_COMMENTS} for why one end is not enough.
+ */
+const REVIEW_THREADS_QUERY = `
+  query($owner:String!,$repo:String!,$number:Int!,$after:String){
+    repository(owner:$owner,name:$repo){
+      pullRequest(number:$number){
+        reviewThreads(first:${FORGE_PAGE_SIZE},after:$after){
+          pageInfo{hasNextPage endCursor}
+          nodes{
+            id isResolved isOutdated path line
+            opening: comments(first:1){nodes{author{login} body}}
+            latest: comments(last:${MAX_THREAD_COMMENTS}){totalCount nodes{author{login} body}}
+          }
+        }
+      }
+    }
+  }`;
+/**
+ * Who is currently *asked* to review, apps included.
+ *
+ * REST's `pulls/{n}/requested_reviewers` carries `users` and `teams` and no
+ * third key, so a Bot reviewer — Copilot is one — is absent from a request that
+ * is live, and its answer for "Copilot is working on it right now" is byte for
+ * byte its answer for "nobody was ever asked". GraphQL types the requested
+ * reviewer as a union with `Bot` in it, which is what makes the two
+ * distinguishable at all.
+ */
+const REVIEW_REQUESTS_QUERY = `
+  query($owner:String!,$repo:String!,$number:Int!){
+    repository(owner:$owner,name:$repo){
+      pullRequest(number:$number){
+        reviewRequests(first:${FORGE_PAGE_SIZE}){
+          nodes{
+            requestedReviewer{
+              ... on User{login}
+              ... on Bot{login}
+              ... on Team{slug}
+            }
+          }
+        }
+      }
+    }
+  }`;
+/** Which pull request, in which repository, a thread id names. */
+const THREAD_OWNER_QUERY = `
+  query($id:ID!){
+    node(id:$id){
+      ... on PullRequestReviewThread {
+        pullRequest{number repository{nameWithOwner}}
+      }
+    }
+  }`;
+const THREAD_REPLY_MUTATION = `
+  mutation($id:ID!,$body:String!){
+    addPullRequestReviewThreadReply(input:{pullRequestReviewThreadId:$id,body:$body}){
+      comment{url}
+    }
+  }`;
+const THREAD_RESOLVE_MUTATION = `
+  mutation($id:ID!){
+    resolveReviewThread(input:{threadId:$id}){thread{isResolved}}
+  }`;
+/** One thread, as the model reads it: where it is, its id, and the conversation. */
+function renderThread(t) {
+    const where = t.path
+        ? `${t.path}${typeof t.line === "number" ? `:${t.line}` : ""}`
+        : "(no file)";
+    const total = t.latest?.totalCount ?? 0;
+    const tail = t.latest?.nodes ?? [];
+    // Whole when it fits, and both ends with the middle named when it does not.
+    // The opening comment is the reviewer's actual point and the tail is where a
+    // reply this plugin sent would be, so neither end can be the one dropped.
+    const conversation = total > tail.length
+        ? [
+            ...(t.opening?.nodes ?? []),
+            {
+                author: { login: "…" },
+                body: `(${total - tail.length - 1} earlier replies not shown)`
+            },
+            ...tail
+        ]
+        : tail;
+    return [
+        `--- ${where}${t.isResolved ? " [resolved]" : ""}${t.isOutdated ? " [outdated]" : ""}`,
+        `id: ${t.id}`,
+        ...conversation.map((c) => `${c.author?.login ?? "unknown"}: ${c.body ?? ""}`)
+    ].join("\n");
+}
+/**
+ * The owner and repository as their own names, rather than as REST path segments.
+ *
+ * {@link file://./context.ts forgeRepo} percent-encodes both, because that is
+ * what makes a path safe. A GraphQL *variable* is not a path — it is compared
+ * against the repository's actual name — so an encoded one would silently stop
+ * matching the moment a name contains a character worth encoding.
+ */
+function decoded(target) {
+    return {
+        owner: decodeURIComponent(target.owner),
+        repo: decodeURIComponent(target.repo)
+    };
+}
+/**
+ * The review bot's logins, which GitHub does not spell the same way twice.
+ *
+ * One account arrives as `Copilot` from the issue timeline, as
+ * `copilot-pull-request-reviewer` from GraphQL, and as
+ * `copilot-pull-request-reviewer[bot]` from `pulls/{n}/reviews`. Compared
+ * exactly against the login a caller names, the request matches and the review
+ * never does, so `repo_pr_review_status` reports "none pending — waiting will
+ * not change it" at the moment the review lands. That is the one answer a
+ * polling caller stops on, so the mismatch does not degrade the tool, it
+ * inverts it.
+ *
+ * An alternation of the spellings that account answers to, and deliberately not
+ * a `copilot-` prefix: `copilot-swe-agent` is a **different** account, one that
+ * opens pull requests rather than reviewing them, so a prefix would let its
+ * request or its authorship answer a question asked about the reviewer.
+ */
+const COPILOT_LOGIN = /^copilot(-pull-request-reviewer)?$/;
+/**
+ * Whether a login from the API is the reviewer the caller asked about.
+ *
+ * `[bot]` is a suffix REST appends to an app's login and GraphQL does not, so it
+ * is never part of the identity — stripping it is what lets a caller name any
+ * app reviewer the way GitHub's UI shows it.
+ */
+function sameReviewer(a, b) {
+    const bare = (login) => login.toLowerCase().replace(/\[bot\]$/, "");
+    const [x, y] = [bare(a), bare(b)];
+    return COPILOT_LOGIN.test(x) && COPILOT_LOGIN.test(y) ? true : x === y;
+}
+export function reviewTools(ctx) {
+    const { bounded, forge, forgeGraphql, forgeRepo } = ctx;
+    return {
+        repo_pr_review_status: tool({
+            description: "Say whether a reviewer has finished reviewing a pull request in the repository you have checked out. Use it before reading review comments: a review that has not landed has left no comments, and an empty thread list means nothing yet.",
+            inputSchema: z.object({
+                dir: z.string().describe("The checkout directory"),
+                number: z.number().int().positive().describe("Pull request number"),
+                reviewer: z
+                    .string()
+                    .optional()
+                    .describe('The reviewer to ask about, as their login. Defaults to "Copilot".')
+            }),
+            execute: async ({ dir, number, reviewer }) => {
+                const target = await forgeRepo(dir);
+                if ("refusal" in target)
+                    return target.refusal;
+                const { owner, repo } = target;
+                const who = reviewer ?? "Copilot";
+                // A *pending* request outranks any review already on the pull request,
+                // and that ordering is the whole logic here. GitHub clears the request
+                // when a review is submitted and writes a new one when a re-review is
+                // asked for, so "still requested" is true now and "has reviewed" is
+                // about the past. Reading them the other way round reports a re-review
+                // as finished the moment it is asked for.
+                const requested = await forgeGraphql("repo_pr_review_status", REVIEW_REQUESTS_QUERY, { owner, repo, number });
+                if (!requested.ok)
+                    return bounded(requested.message);
+                const waiting = requested.data.repository?.pullRequest?.reviewRequests;
+                if (!waiting)
+                    return `#${number} is not a pull request in ${owner}/${repo}`;
+                const pending = (waiting.nodes ?? []).some((n) => {
+                    const name = n?.requestedReviewer?.login ?? n?.requestedReviewer?.slug;
+                    return !!name && sameReviewer(name, who);
+                });
+                if (pending)
+                    return `${who} has been asked to review #${number} and has not finished.`;
+                const reviews = await forge("repo_pr_review_status", `/repos/${owner}/${repo}/pulls/${number}/reviews?per_page=${FORGE_PAGE_SIZE}`);
+                if (!reviews.ok)
+                    return bounded(reviews.message);
+                const all = reviews.data;
+                const submitted = all.filter((r) => !!r.user?.login &&
+                    sameReviewer(r.user.login, who) &&
+                    // A `PENDING` review is a draft its author has not sent, and it is
+                    // visible to whoever holds the token that wrote it. Counting one as
+                    // finished reports a review nobody has read, which is the answer a
+                    // poll loop acts on by stopping.
+                    (r.state ?? "").toUpperCase() !== "PENDING");
+                const theirs = submitted.at(-1);
+                if (!theirs) {
+                    // The endpoint pages oldest-first, so a match beyond the first page is
+                    // **newer** than everything read — which is to say it is exactly the
+                    // review being waited for. So a truncated read cannot answer the
+                    // question at all, and must not answer it with "waiting will not help":
+                    // that is the one reply a caller ends its polling on.
+                    if (all.length >= FORGE_PAGE_SIZE)
+                        return bounded(`#${number} has at least ${FORGE_PAGE_SIZE} reviews and only the oldest were read, ` +
+                            `so whether ${who} has reviewed it is unknown. Read the pull request itself with repo_pr_view, ` +
+                            `or look for threads with repo_pr_threads.`);
+                    return bounded(`#${number} has no review from ${who}, and none is pending. ` +
+                        `Nobody asked them, or the request was withdrawn — waiting will not change it.`);
+                }
+                return bounded(`${who} reviewed #${number}${theirs.submitted_at ? ` at ${theirs.submitted_at}` : ""}` +
+                    `${theirs.state ? ` (${theirs.state.toLowerCase()})` : ""}. ` +
+                    `Read what it said with repo_pr_threads — a review can finish having left no comments.`);
+            }
+        }),
+        repo_pr_threads: tool({
+            description: "Read the review threads on a pull request in the repository you have checked out — the inline comments a reviewer left on specific lines, which are not on the conversation timeline repo_issue_view reads. Unresolved ones only, unless you ask for all.",
+            inputSchema: z.object({
+                dir: z.string().describe("The checkout directory"),
+                number: z.number().int().positive().describe("Pull request number"),
+                includeResolved: z
+                    .boolean()
+                    .optional()
+                    .describe("Include threads already resolved. Defaults to false.")
+            }),
+            execute: async ({ dir, number, includeResolved }) => {
+                const target = await forgeRepo(dir);
+                if ("refusal" in target)
+                    return target.refusal;
+                const { owner, repo } = decoded(target);
+                const threads = [];
+                let after = null;
+                let truncated = false;
+                // Paged, and that is not an optimisation. A review long enough to spill a
+                // page puts its newest threads on the last one — exactly the threads the
+                // model was sent to answer — so a single page can report a busy review as
+                // clean. The page cap is what stops a pathological pull request becoming
+                // an unbounded number of round trips.
+                for (let page = 0;; page++) {
+                    if (page >= MAX_THREAD_PAGES) {
+                        truncated = true;
+                        break;
+                    }
+                    const answered = await forgeGraphql("repo_pr_threads", REVIEW_THREADS_QUERY, {
+                        owner,
+                        repo,
+                        number,
+                        after
+                    });
+                    if (!answered.ok)
+                        return bounded(answered.message);
+                    const page_ = answered.data.repository?.pullRequest?.reviewThreads;
+                    if (!page_)
+                        return `#${number} is not a pull request in ${owner}/${repo}`;
+                    threads.push(...(page_.nodes ?? []));
+                    if (!page_.pageInfo?.hasNextPage)
+                        break;
+                    after = page_.pageInfo.endCursor ?? null;
+                    if (!after)
+                        break;
+                }
+                // Said once, and said on **every** exit including the empty one. A run
+                // that stopped early and found nothing open in what it did read must not
+                // answer "nothing to do": the unread pages are exactly where the newest
+                // threads are, which is the false-clean result the paging exists to
+                // prevent — reintroduced at the one exit that skipped the warning.
+                const unread = truncated
+                    ? `\n\n(stopped after ${MAX_THREAD_PAGES} pages, so this is not the whole review — there are more threads than were read)`
+                    : "";
+                const shown = includeResolved
+                    ? threads
+                    : threads.filter((t) => !t.isResolved);
+                if (shown.length === 0)
+                    return bounded((includeResolved
+                        ? `#${number} has no review threads.`
+                        : `#${number} has no unresolved review threads.` +
+                            (threads.length > 0
+                                ? ` (${threads.length} resolved — pass includeResolved to read them.)`
+                                : "")) + unread);
+                const rendered = shown.map((t) => renderThread(t)).join("\n\n");
+                return bounded(rendered + unread);
+            }
+        }),
+        repo_pr_thread_reply: tool({
+            description: "Answer one review thread on a pull request in the repository you have checked out, and resolve it. Reply with what you changed and where, or with why you did not — either way the thread ends resolved unless you say otherwise.",
+            inputSchema: z.object({
+                dir: z.string().describe("The checkout directory"),
+                number: z.number().int().positive().describe("Pull request number"),
+                threadId: z
+                    .string()
+                    .describe("The thread's id, exactly as repo_pr_threads printed it"),
+                body: z
+                    .string()
+                    .optional()
+                    .describe("The reply, as markdown. Leave it out to resolve a thread you have already replied to."),
+                resolve: z
+                    .boolean()
+                    .optional()
+                    .describe("Resolve the thread after replying. Defaults to true.")
+            }),
+            execute: async ({ dir, number, threadId, body, resolve }) => {
+                const target = await forgeRepo(dir);
+                if ("refusal" in target)
+                    return target.refusal;
+                const { owner, repo } = decoded(target);
+                // A thread id is a global node id, so unlike every other tool here this
+                // one takes something that can name a pull request in a repository
+                // nobody checked out — the reach `forgeRepo` exists to prevent. Checked
+                // rather than trusted: the id came from a tool result the model read,
+                // and a model that misremembers one must not write into a stranger's
+                // review.
+                const belongs = await forgeGraphql("repo_pr_thread_reply", THREAD_OWNER_QUERY, { id: threadId });
+                if (!belongs.ok)
+                    return bounded(belongs.message);
+                const node = belongs.data.node;
+                if (!node?.pullRequest)
+                    return `${threadId} is not a review thread — read the ids with repo_pr_threads`;
+                const at = node.pullRequest.repository?.nameWithOwner ?? "";
+                if (at.toLowerCase() !== `${owner}/${repo}`.toLowerCase() ||
+                    node.pullRequest.number !== number)
+                    return (`${threadId} belongs to ${at}#${node.pullRequest.number}, not ${owner}/${repo}#${number}. ` +
+                        `Read the ids for this pull request with repo_pr_threads.`);
+                // Resolve-only. The reply and the resolve are two calls, so they fail
+                // independently — and the tool that tells a caller "the reply landed,
+                // resolve it alone" has to give it a way to do that. Without this the
+                // only route back is a second reply the reviewer has already read.
+                if (body === undefined) {
+                    if (resolve === false)
+                        return "nothing to do: give a body to reply, or leave resolve unset to resolve the thread";
+                    const only = await forgeGraphql("repo_pr_thread_reply", THREAD_RESOLVE_MUTATION, { id: threadId });
+                    return only.ok
+                        ? `resolved ${threadId}`
+                        : bounded(`resolving the thread failed: ${only.message}`);
+                }
+                const replied = await forgeGraphql("repo_pr_thread_reply", THREAD_REPLY_MUTATION, { id: threadId, body });
+                if (!replied.ok)
+                    // The hazard `repo_pr_comment` names, and worse here: a reply that
+                    // landed and an answer that did not arrive look identical, and the
+                    // retry leaves the reviewer two of them.
+                    return bounded(`${replied.message}\nIf this was a timeout rather than a rejection the ` +
+                        `reply may exist anyway — read the thread back with repo_pr_threads before retrying.`);
+                const url = replied.data.addPullRequestReviewThreadReply?.comment?.url ?? "(no url)";
+                if (resolve === false)
+                    return `replied: ${url} (left unresolved)`;
+                // Reported separately, never folded into the reply's own failure: a
+                // thread that was answered and not resolved needs resolving, and one
+                // that was never answered needs answering. Saying "it failed" covers
+                // both and tells the model to do the wrong one.
+                const resolved = await forgeGraphql("repo_pr_thread_reply", THREAD_RESOLVE_MUTATION, { id: threadId });
+                if (!resolved.ok)
+                    return bounded(`replied: ${url}\nbut resolving the thread failed: ${resolved.message}\n` +
+                        `The reply has landed — do not send it again. Call repo_pr_thread_reply on the same ` +
+                        `threadId with no body to resolve it on its own.`);
+                return `replied and resolved: ${url}`;
+            }
+        })
+    };
+}

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

@@ -0,0 +1,4 @@
+import type { ToolSet } from "ai";
+import type { RepoContext } from "./context.js";
+/** Reading the working tree, committing it, and publishing the branch. */
+export declare function worktreeTools(ctx: RepoContext): ToolSet;

package/dist/repo/tools-worktree.js

@@ -0,0 +1,221 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { PROTECTED_BRANCHES, UNSAFE_BRANCH } from "./url.js";
+import { resolveDefaultBranch } from "./checkout.js";
+/** Reading the working tree, committing it, and publishing the branch. */
+export function worktreeTools(ctx) {
+    const { author, bounded, logFailure, plain, origin, pushBranch } = ctx;
+    return {
+        repo_status: tool({
+            description: "Show which files changed in the checkout.",
+            inputSchema: z.object({ dir: z.string().describe("Checkout directory") }),
+            execute: async ({ dir }) => {
+                const result = await plain("status --short", dir);
+                // "(no changes)" is a claim about the tree. A command that failed
+                // supports no claim about anything, and reporting one as the other sends
+                // the model on to commit against a repository it cannot read.
+                if (!result.success) {
+                    logFailure("repo_status", result);
+                    return bounded(`could not read the status of ${dir}: ${result.stderr || result.stdout}`);
+                }
+                return bounded(result.stdout.trim()) || "(no changes)";
+            }
+        }),
+        repo_diff: tool({
+            description: "Show the current diff. Read this before committing — it is the cheapest way to catch an edit that did more than you intended. Pass stat:true first on a large change to see which files moved and by how much, then read the full diff of what matters.",
+            inputSchema: z.object({
+                dir: z.string().describe("Checkout directory"),
+                staged: z.boolean().optional().describe("Show staged changes instead"),
+                stat: z
+                    .boolean()
+                    .optional()
+                    .describe("Summarise as a per-file changed-line count instead of the full patch")
+            }),
+            execute: async ({ dir, staged, stat }) => {
+                const flags = [staged ? "--staged" : "", stat ? "--stat" : ""]
+                    .filter(Boolean)
+                    .join(" ");
+                const result = await plain(`diff ${flags}`, dir);
+                // Same reasoning as `repo_status`: "(no diff)" and "the diff could not
+                // be read" are opposite answers, and this is the tool a reviewing agent
+                // trusts most.
+                if (!result.success) {
+                    logFailure("repo_diff", result);
+                    return bounded(`could not read the diff in ${dir}: ${result.stderr || result.stdout}`);
+                }
+                // Truncated from the middle rather than the end: the head of a diff and
+                // its tail are both informative, and the middle of a large one rarely
+                // is. A model that needs the part that was dropped can ask for `stat`
+                // and then read the file.
+                return bounded(result.stdout.trim()) || "(no diff)";
+            }
+        }),
+        repo_commit: tool({
+            description: "Stage everything and commit. Write the message for a reviewer reading it in the log a year from now: what changed and why, not how.",
+            inputSchema: z.object({
+                dir: z.string().describe("Checkout directory"),
+                message: z.string().describe("Commit message")
+            }),
+            execute: async ({ dir, message }) => {
+                // Checked rather than fired and forgotten. A failed `add` leaves the
+                // index holding less than the model believes, and the commit that
+                // follows still succeeds — so the round reports a commit that quietly
+                // does not contain the change.
+                const staged = await plain("add -A", dir);
+                if (!staged.success) {
+                    logFailure("repo_commit", staged);
+                    return bounded(`could not stage the changes in ${dir}: ${staged.stderr || staged.stdout}`);
+                }
+                // The message is model-authored free text — quotes, backticks, newlines,
+                // `$(…)`. Expanded from the environment inside the container, all of
+                // that is inert; interpolated into the command string, none of it is.
+                const result = await plain(`commit -m "$GIT_COMMIT_MESSAGE"`, dir, {
+                    GIT_COMMIT_MESSAGE: message,
+                    // On the commit as well as in the checkout's config, and this is
+                    // the copy that is current: config is written when a checkout is set
+                    // up, and the environment is read at the commit. A workspace that
+                    // outlived a change of identity commits under the new one.
+                    GIT_AUTHOR_NAME: author.name,
+                    GIT_AUTHOR_EMAIL: author.email,
+                    GIT_COMMITTER_NAME: author.name,
+                    GIT_COMMITTER_EMAIL: author.email
+                });
+                if (!result.success && /nothing to commit/i.test(result.stdout))
+                    return "nothing to commit — the working tree is clean";
+                if (!result.success) {
+                    logFailure("repo_commit", result);
+                    return bounded(`commit failed: ${result.stderr || result.stdout}`);
+                }
+                return bounded(result.stdout.trim());
+            }
+        }),
+        repo_push: tool({
+            description: "Push a branch to the remote. Refuses to push to a protected branch and refuses to force-push — open a pull request instead.",
+            inputSchema: z.object({
+                dir: z.string().describe("Checkout directory"),
+                branch: z
+                    .string()
+                    .describe("Branch name to create and push, e.g. 'coder/add-json-flag'")
+            }),
+            execute: async ({ dir, branch }) => {
+                // Enforced here rather than in the prompt: a guardrail a model can talk
+                // itself out of is not a guardrail.
+                //
+                // Shape first, then the name. `git push origin <name>` reads `<name>`
+                // as a refspec, so `+x:main` is a force push to main that the name
+                // check below would wave through — it only ever sees a literal string.
+                if (UNSAFE_BRANCH.test(branch))
+                    return `"${branch}" is not a plain branch name — use something like "coder/add-json-flag"`;
+                if (PROTECTED_BRANCHES.has(branch))
+                    return `refusing to push to "${branch}" — push a work branch and open a pull request`;
+                // The repository's *own* default, which is often none of the four names
+                // above: a repo whose trunk is `release` deserves the same protection.
+                // A command that never ran stops here rather than standing the guards
+                // down — the same rule as the two probes further down, and the reason
+                // {@link resolveDefaultBranch} reports the two separately.
+                const head = await resolveDefaultBranch(plain, dir);
+                if (head.unreachable)
+                    return bounded(`could not push "${branch}": ${head.unreachable}`);
+                const defaultBranch = head.branch;
+                if (defaultBranch && defaultBranch === branch)
+                    return `refusing to push to "${branch}" — it is this repository's default branch; push a work branch and open a pull request`;
+                const { remote, unreachable } = await origin(dir);
+                if (unreachable)
+                    return bounded(`could not push "${branch}": ${unreachable}`);
+                if (!remote)
+                    return `${dir} has no origin on an allowed host — clone it with repo_clone first`;
+                // Switch to the branch, or create it — but never *reset* it.
+                //
+                // `-b`, never `-B`: `-B` is create-or-reset, so on a branch that already
+                // holds the commit it force-moves it to wherever HEAD is now. The commit
+                // survives only as an unreferenced object, and what gets pushed is an
+                // empty branch with a pull request opened on it — a complete loss
+                // dressed up as success.
+                const exists = await plain(`rev-parse --verify --quiet "refs/heads/$REPO_BRANCH"`, dir, { REPO_BRANCH: branch });
+                // Same reasoning as the probe in `repo_clone`: `!success` means "no such
+                // branch, create it" only when git was there to say so.
+                if (exists.unreachable)
+                    return bounded(`could not push "${branch}": ${exists.stderr}`);
+                const checkout = await plain(exists.success
+                    ? `checkout "$REPO_BRANCH"`
+                    : `checkout -b "$REPO_BRANCH"`, dir, { REPO_BRANCH: branch });
+                if (!checkout.success) {
+                    logFailure("repo_push", checkout);
+                    return bounded(`could not switch to branch "${branch}": ${checkout.stderr || checkout.stdout}`);
+                }
+                // Nothing to push is a bug upstream of here, not a no-op.
+                //
+                // A branch level with the default branch means the commit went
+                // somewhere else, or was never made. Pushing it succeeds, `repo_open_pr`
+                // opens an empty pull request, and the round reports a URL as if the
+                // work had landed — the one outcome worse than an error.
+                //
+                // The guard is skipped only when there is no baseline to compare
+                // against: a repository with no `origin/HEAD` is unusual but legitimate,
+                // and guessing is worse than not guarding. Once there *is* one, a
+                // comparison that fails is an unanswered question rather than a pass —
+                // the same rule the three probes around this one follow.
+                if (defaultBranch) {
+                    const ahead = await plain(`rev-list --count "origin/$REPO_BASE..HEAD"`, dir, {
+                        REPO_BASE: defaultBranch
+                    });
+                    if (ahead.unreachable)
+                        return bounded(`could not push "${branch}": ${ahead.stderr}`);
+                    if (!ahead.success) {
+                        logFailure("repo_push", ahead);
+                        return bounded(`could not tell whether "${branch}" has anything to push: comparing it ` +
+                            `against origin/${defaultBranch} failed with ` +
+                            `${ahead.stderr || ahead.stdout || "no output"}\n` +
+                            `Nothing was pushed. Pushing without that answer risks an empty pull ` +
+                            `request reported as success, so check repo_status and repo_diff first.`);
+                    }
+                    if (ahead.stdout.trim() === "0") {
+                        return (`refusing to push "${branch}" — it has no commits that origin/${defaultBranch} ` +
+                            `does not already have, so the pull request would be empty. Check repo_status ` +
+                            `and repo_diff: either the change was never committed, or it was committed on ` +
+                            `a different branch.`);
+                    }
+                }
+                // A pre-flight check, not a value anyone downstream consumes: `push`
+                // takes the branch *name* and resolves it itself, against the same
+                // files. What this buys is the failure arriving here, where the sentence
+                // can name the branch and the checkout, instead of surfacing as a push
+                // that rejects a ref nobody can see.
+                const tip = await plain(`rev-parse --verify "refs/heads/$REPO_BRANCH"`, dir, { REPO_BRANCH: branch });
+                if (!tip.success || !tip.stdout.trim()) {
+                    logFailure("repo_push", tip);
+                    return bounded(`could not resolve "${branch}" to a commit: ${tip.stderr || tip.stdout}`);
+                }
+                const result = await pushBranch(dir, remote.url, branch);
+                if (!result.success) {
+                    logFailure("repo_push", result);
+                    return bounded(`push failed: ${result.stderr || result.stdout}`);
+                }
+                // What `--set-upstream` would do as a side effect of the push, written
+                // here because the push happens on the host's side: a subagent reaching
+                // for a bare `git push` in the shell should still find the branch
+                // tracking something.
+                //
+                // Checked, but *reported* rather than raised: this is the one place in
+                // the plugin where a failed command is not a failed operation. The push
+                // has landed, saying so is the important half, and all that is lost is
+                // the convenience these two keys buy.
+                const remoteSet = await plain(`config "branch.$REPO_BRANCH.remote" origin`, dir, { REPO_BRANCH: branch });
+                const mergeSet = await plain(`config "branch.$REPO_BRANCH.merge" "refs/heads/$REPO_BRANCH"`, dir, { REPO_BRANCH: branch });
+                const untracked = [remoteSet, mergeSet].find((r) => !r.success);
+                if (untracked) {
+                    // Named apart from the push, which succeeded — a log line reading
+                    // "repo_push failed" next to a branch that is on the remote is worse
+                    // than no log line.
+                    logFailure("repo_push (upstream tracking)", untracked);
+                    return bounded(`pushed ${branch}, but could not record what it tracks: ` +
+                        `${untracked.stderr || untracked.stdout}\n` +
+                        `The push itself landed. The only consequence is local: a bare ` +
+                        `\`git push\` from the shell will not know where to send this ` +
+                        `branch, and needs \`git push -u origin ${branch}\` once.`);
+                }
+                return `pushed ${branch}`;
+            }
+        })
+    };
+}

package/dist/triage/index.d.ts

@@ -1,7 +1,7 @@
 import type { LanguageModel } from "ai";
 import { z } from "zod";
-import type { SessionMessage } from "agents/experimental/memory/session";
 import type { AgentPlugin } from "@dynamicagents/core";
+import type { SessionMessage } from "@dynamicagents/core/agent";
 /**
  * The classifier's output. The booleans are **not** metadata for the caller —
  * only `should_reply` is ever read. They exist to shape the generation itself:
@@ -38,6 +38,11 @@ export interface TriageTuning {
      * in one gateway.
      */
     aiGatewayId?: string;
+    /**
+     * The `agent` key on the classifier's AI Gateway log rows. Pass the host's
+     * `PluginHost.agentName`, for the reason given on {@link aiGatewayId}.
+     */
+    agentName?: string;
     /** Workers-AI id for the classifier. Defaults to a small, fast model. */
     modelId?: string;
     /** Trailing messages the classifier sees. Defaults to 12. */