Inline comments

A pull request comment that asks for a review now posts a real review, not a plain comment: the review file decides, the event no longer does.

Verified with deno fmt, lint and check.

Reviewed-on: #9
Co-authored-by: bot <temeddix@gmail.com>
Co-committed-by: bot <temeddix@gmail.com>

action.yml

@@ -20,10 +20,20 @@ inputs:
   bot-token:
     description: API key or token for the selected bot
     required: false
+  model:
+    description: >-
+      Model for the selected bot. Defaults to `claude-sonnet-5` or
+      `gpt-5.6-terra`, the mid tiers, which cover reviews and fixes.
+    required: false
 
 runs:
   using: composite
   steps:
+    # The agent works on the event's commit with full history, as the author.
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+        token: ${{ inputs.author-token }}
     # This step assumes this is `node:24-bookworm` container.
     - name: Install dependencies
       shell: bash
@@ -35,6 +45,7 @@ runs:
         ACTION_PATH: ${{ gitea.action_path }}
         BOT_TYPE: ${{ inputs.bot-type }}
         BOT_TOKEN: ${{ inputs.bot-token }}
+        MODEL: ${{ inputs.model }}
         GITEA_API_URL: ${{ gitea.api_url }}
         GITEA_REPOSITORY: ${{ gitea.repository }}
         GITEA_TOKEN: ${{ inputs.author-token }}

prompt.md

@@ -13,15 +13,50 @@ response ends, so background monitors, scheduled wake-ups, and queued tasks
 never resume. Never promise future action and never claim to be waiting on a
 notification.
 
-For a `pull_request` event, review the PR without changing code. Your final
+The repository is checked out in the working directory at the event's commit,
-response is posted as a pull request review from the bot account: it requests
+the head of the pull request when there is one, with full history and the
-changes when it mentions `@bot` and approves otherwise. So include `@bot` with
+author's push credentials. Read the code there, run its checks and tests when
-instructions to fix the findings exactly when changes are needed, and never
+they bear on the task, and push from there.
-mention `@bot` when the PR is ready. For UI changes, check that the result is
+
-aligned, clean, and pixel-perfect, and that included screenshots prove the
+For a `pull_request` event, and for a comment on a pull request that asks you to
-intended result was achieved. Also check the whole repository, not only the
+review it, review the PR without changing code, using the
-diff, against the code rules at the end of this prompt, and request changes for
+`requesting-code-review` skill from superpowers: run its code reviewer template
-every violation you find even when the diff did not cause it.
+against the PR's base and head. Run the project's checks on the head and treat a
+failure as at least Important. Check the whole repository against the code rules
+at the end of this prompt, not only the diff; a violation is at least Important
+even when the diff did not cause it. Write the complete review, and nothing
+else, to the file `${REVIEW_PATH}`: it is posted verbatim as a pull request
+review from the bot account, and your final response is not posted at all. The
+file's first line must be exactly the verdict and nothing else: `Approved` when
+the template's answer is yes, `Changes requested` otherwise. The mark in front
+of it is added when posting, so write the words alone; any other first line is
+posted as a plain comment, which wastes the run. Minor issues alone never block,
+and neither does a finding the author has answered in the comment history below
+as intended or a false alarm, once the code or docs make that clear. When the
+verdict is `Changes requested`, the second line names what must change in one
+line, addressed to the author; the author's own agent picks the fixes up, so
+never ask `@bot` to make them. For UI changes, check that the result is aligned,
+clean, and pixel-perfect, and that included screenshots prove the intended
+result was achieved.
+
+Every finding that belongs to one line of the diff goes on that line instead of
+into the body. Write those to `${ANCHORS_PATH}` as a JSON array, each entry
+`{"path": "<path from the repository root>", "line": <number>, "side": "new" |
+"old", "body": "<the finding>"}`.
+`side` is `new` for a line in the head file and `old` for one only in the base
+file; `line` is that file's own line number, and it must be a line the diff
+touches, or Gitea refuses the anchor. Write the file only when there is
+something to anchor, and keep each body to the what, the why, and the how, with
+no `file:line` prefix; the line carries that.
+
+The review body must read at a glance: everything outside `<details>` blocks
+totals under 512 bytes. Only core information stays visible: the verdict, the
+summary line, and the section headings. Anything verbose goes into a `<details>`
+block whose `<summary>` is a few words, such as the title of an issue with the
+what, why, and how inside; the same for each strength, each recommendation, the
+reasoning, and any compliance notes. A finding you anchored belongs there only
+as its title, since its detail is on the line. Details blocks are top-level,
+never inside a list item, because Gitea breaks them there.
 
 For an `issue_comment` or `pull_request_review_comment` event, treat the `body`
 in the triggering comment payload below as the user's exact instruction.

run.ts

@@ -20,6 +20,13 @@ const EVENT = env("EVENT_NAME");
 const AUTHOR_TOKEN = env("GITEA_TOKEN");
 const REVIEWER_TOKEN = env("REVIEWER_TOKEN");
 const RULES_PATH = "repos/commons/code-rules/raw/README.md";
+// The mid tiers: a run follows a fixed template and the project's checks.
+const DEFAULT_MODELS: Record<string, string> = {
+  claude: "claude-sonnet-5",
+  codex: "gpt-5.6-terra",
+};
+const model = (bot: string): string =>
+  Deno.env.get("MODEL") || DEFAULT_MODELS[bot];
 
 // The reviewer token is withheld so the agent cannot approve as the bot.
 const { REVIEWER_TOKEN: _, ...agentEnv } = Deno.env.toObject();
@@ -52,32 +59,113 @@ async function postComment(body: string): Promise<void> {
   });
 }
 
-// A pull request event is a review request, so the response becomes a review:
+// A review is posted whenever the agent wrote one, whether a review request or
-// changes are requested when the agent asked @bot to fix something, a failed
+// a comment asked for it. It comes through a file, because a final chat message
-// run only comments, and anything else approves.
+// picks up narration while a file's first line is written on purpose. That line
-async function postResult(body: string): Promise<void> {
+// is the verdict, matched whole; anything unexpected only comments, never
-  if (EVENT !== "pull_request") return postComment(body);
+// approves. The mark in front is added here, so it is never part of the match.
-  const event = body.includes("@bot")
+const REVIEW_DIR = await Deno.makeTempDir();
-    ? "REQUEST_CHANGES"
+const REVIEW_PATH = `${REVIEW_DIR}/review.md`;
-    : body.startsWith("Bot failed:")
+const VERDICTS: Record<string, [event: string, mark: string]> = {
-    ? "COMMENT"
+  Approved: ["APPROVED", "✅"],
-    : "APPROVED";
+  "Changes requested": ["REQUEST_CHANGES", "🛑"],
-  await gitea(REVIEWER_TOKEN, `repos/${REPO}/pulls/${INDEX}/reviews`, {
+};
-    body: stripAnsi(body),
+
-    event,
+// A finding about one line is posted on that line of the diff rather than as
+// `file:line` prose in the body. Those anchors come as JSON, so the file and
+// line are structured instead of parsed back out of English; a malformed entry
+// fails the run, because a silently dropped finding is worse than a red run.
+const ANCHORS_PATH = `${REVIEW_DIR}/anchors.json`;
+type Anchor = { path: string; line: number; side: "new" | "old"; body: string };
+
+function parseAnchors(text: string): Anchor[] {
+  const entries: unknown = JSON.parse(text);
+  if (!Array.isArray(entries)) throw new Error(`${ANCHORS_PATH}: not an array`);
+  return entries.map((entry: unknown, index) => {
+    const at = `${ANCHORS_PATH}[${index}]`;
+    if (typeof entry !== "object" || entry === null) {
+      throw new Error(`${at}: not an object`);
+    }
+    const { path, line, side = "new", body } = entry as Record<string, unknown>;
+    if (typeof path !== "string" || path === "") {
+      throw new Error(`${at}.path: expected a repository path`);
+    }
+    if (typeof line !== "number" || !Number.isInteger(line) || line < 1) {
+      throw new Error(`${at}.line: expected a line number`);
+    }
+    if (side !== "new" && side !== "old") {
+      throw new Error(`${at}.side: expected "new" or "old"`);
+    }
+    if (typeof body !== "string" || body.trim() === "") {
+      throw new Error(`${at}.body: expected the finding`);
+    }
+    return { path, line, side, body };
   });
 }
 
+async function readAnchors(): Promise<Anchor[]> {
+  const written = await Deno.readTextFile(ANCHORS_PATH).catch(() => null);
+  return written === null ? [] : parseAnchors(written);
+}
+
+async function postResult(body: string): Promise<void> {
+  const review = await Deno.readTextFile(REVIEW_PATH).catch(() => null);
+  if (review === null) {
+    if (EVENT === "pull_request") {
+      throw new Error(`no review was written to ${REVIEW_PATH}`);
+    }
+    return postComment(body);
+  }
+  const [verdict, ...rest] = review.split("\n");
+  const [event, mark] = VERDICTS[verdict.trim()] ?? ["COMMENT", "💬"];
+  const post = (anchors: Anchor[]) =>
+    gitea(REVIEWER_TOKEN, `repos/${REPO}/pulls/${INDEX}/reviews`, {
+      body: stripAnsi([`${mark} ${verdict.trim()}`, ...rest].join("\n")),
+      event,
+      comments: anchors.map(({ path, line, side, body }) => ({
+        path,
+        body: stripAnsi(body),
+        new_position: side === "new" ? line : 0,
+        old_position: side === "old" ? line : 0,
+      })),
+    });
+  const anchors = await readAnchors();
+  // Gitea rejects the whole review when an anchor names a line outside the
+  // diff, and a verdict that never lands blocks the pull request, so the body
+  // goes up alone rather than not at all.
+  await post(anchors).catch(async (error: Error) => {
+    if (anchors.length === 0) throw error;
+    console.error(`inline comments rejected: ${error.message}`);
+    await post([]);
+  });
+}
+
+async function run(command: string, args: string[]): Promise<void> {
+  const { success, code } = await new Deno.Command(command, { args }).output();
+  if (!success) throw new Error(`${command} ${args[0]} exited with ${code}`);
+}
+
 // Commits belong to the same account as the pull request they end up in.
 async function configureGitAuthor(): Promise<void> {
   const user: GiteaUser = await (await gitea(AUTHOR_TOKEN, "user")).json();
   for (const [key, value] of [["name", user.login], ["email", user.email]]) {
-    await new Deno.Command("git", {
+    await run("git", ["config", "--global", `user.${key}`, value]);
-      args: ["config", "--global", `user.${key}`, value],
-    }).output();
   }
 }
 
+// The superpowers plugin gives the agent its skills, including the code review
+// one that the prompt asks for. Both installs are idempotent on the persisted
+// home.
+async function installSuperpowers(bot: string): Promise<void> {
+  const commands = bot === "claude"
+    ? [
+      ["plugin", "marketplace", "add", "obra/superpowers-marketplace"],
+      ["plugin", "install", "-y", "superpowers@superpowers-marketplace"],
+    ]
+    : [["plugin", "add", "superpowers@openai-curated-remote"]];
+  for (const args of commands) await run(bot, args);
+}
+
 async function renderPrompt(): Promise<string> {
   const comments: GiteaComment[] = await (await gitea(
     REVIEWER_TOKEN,
@@ -93,6 +181,8 @@ async function renderPrompt(): Promise<string> {
     GITEA_API_URL: API,
     GITEA_REPOSITORY: REPO,
     ISSUE_INDEX: INDEX,
+    REVIEW_PATH,
+    ANCHORS_PATH,
   };
   const template = await Deno.readTextFile(
     new URL("prompt.md", import.meta.url),
@@ -106,17 +196,17 @@ async function renderPrompt(): Promise<string> {
 async function runClaude(prompt: string): Promise<string> {
   const token = Deno.env.get("BOT_TOKEN");
   if (!token) {
-    await postComment(
+    throw new Error(
       "Run `claude setup-token` locally and set the `bot-token` action input.",
     );
-    Deno.exit(1);
   }
+  await installSuperpowers("claude");
   const claude = new Deno.Command("claude", {
     args: [
       "--print",
       "--dangerously-skip-permissions",
       "--model",
-      "claude-fable-5",
+      model("claude"),
       "--output-format",
       "stream-json",
       "--verbose",
@@ -127,7 +217,7 @@ async function runClaude(prompt: string): Promise<string> {
     clearEnv: true,
     stdout: "piped",
   }).spawn();
-  let result = "Bot failed: no result";
+  let result: { result?: string; subtype: string } | undefined;
   // Print events as they stream so the runner does not kill the job as a zombie.
   const lines = claude.stdout
     .pipeThrough(new TextDecoderStream())
@@ -139,12 +229,13 @@ async function runClaude(prompt: string): Promise<string> {
       const text = part.thinking ?? part.text ?? part.name;
       if (text) console.log(text);
     }
-    if (event.type === "result") {
+    if (event.type === "result") result = event;
-      result = event.result ?? `Bot failed: ${event.subtype}`;
-    }
   }
   await claude.status;
-  return result;
+  if (result?.result === undefined) {
+    throw new Error(`claude ended with ${result?.subtype ?? "no result"}`);
+  }
+  return result.result;
 }
 
 // Posts the device code so a human can finish the login on the persisted home.
@@ -174,12 +265,13 @@ async function runCodex(prompt: string): Promise<string> {
   })
     .output();
   if (!loggedIn.success) await codexDeviceLogin();
+  await installSuperpowers("codex");
   const file = await Deno.makeTempFile();
   const status = await new Deno.Command("codex", {
     args: [
       "exec",
       "--model",
-      "gpt-5.5",
+      model("codex"),
       "--dangerously-bypass-approvals-and-sandbox",
       "--output-last-message",
       file,
@@ -194,9 +286,14 @@ async function runCodex(prompt: string): Promise<string> {
   return await Deno.readTextFile(file);
 }
 
-await configureGitAuthor();
+try {
-const prompt = await renderPrompt();
+  await configureGitAuthor();
-const result = env("BOT_TYPE") === "claude"
+  const prompt = await renderPrompt();
+  const result = env("BOT_TYPE") === "claude"
     ? await runClaude(prompt)
     : await runCodex(prompt);
-await postResult(result);
+  await postResult(result);
+} catch (error) {
+  await postComment(`Bot failed: ${error}`);
+  throw error;
+}