dsh-desktop-kit 2.2.1 → 2.7.3

package/plugins/dsh-github-review/index.js

@@ -0,0 +1,536 @@
+/**
+ * dsh-github-review — Host half.
+ *
+ * One model tool, `github_review`, over the official `gh` CLI:
+ *  - read-only by default: status, pr, checks, comments, diff;
+ *  - one opt-in mutation: comment, only with `confirm: true`, an explicit PR
+ *    number and a non-empty body;
+ *  - merge / close / reopen / force-push are deliberately not implemented and
+ *    explicitly refused.
+ *
+ * All `gh` calls are argv arrays (no shell), time-bounded and scrubbed of
+ * tokens before anything reaches the model. The plugin never reads token
+ * files itself: authentication belongs to `gh auth login`.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  LIMITS,
+  clampDiffBytes,
+  formatBytes,
+  normalizeChecks,
+  normalizeConversationComments,
+  normalizePullRequest,
+  normalizeReviewComments,
+  parsePrNumber,
+  summarizeReviews,
+  truncateDiff,
+} from "./lib/normalize.js";
+import {
+  detectRepo,
+  fetchChecks,
+  fetchComments,
+  fetchDiff,
+  fetchPrView,
+  postComment,
+  probeStatus,
+  resolvePrNumber,
+} from "./lib/gh.js";
+
+export const inject = ["tools"];
+
+const TOOL_ACTIONS = new Set(["status", "pr", "checks", "comments", "diff", "comment"]);
+const UNSUPPORTED_ACTIONS = new Set([
+  "merge",
+  "close",
+  "reopen",
+  "approve",
+  "request-changes",
+  "request_changes",
+  "push",
+  "force-push",
+  "force_push",
+  "rebase",
+  "edit",
+  "delete",
+  "ready",
+]);
+const RENDER_CHARS = 24_000;
+const DIFF_RENDER_CHARS = 48_000;
+
+const FAILURE_HINTS = {
+  "gh-missing": "gh CLI не найден. Установите GitHub CLI (https://cli.github.com) и выполните `gh auth login`.",
+  "not-authenticated": "gh не авторизован — выполните `gh auth login` (или задайте GH_TOKEN с доступом к репозиторию).",
+  "no-pr": "PR для текущей ветки не найден — укажите точный номер: pr=<номер>.",
+  "pr-not-found": "PR с таким номером не найден или нет доступа (проверьте номер и права токена).",
+  "repo-not-found": "Репозиторий не найден или нет доступа. Проверьте repo=owner/name и права токена.",
+  "rate-limited": "Сработал лимит GitHub API — повторите позже или проверьте токен.",
+  timeout: "gh не ответил за отведённое время (сеть или аутентификация).",
+  "bad-pr": "Некорректный номер PR: нужно целое положительное число.",
+  "bad-repo": "Некорректный repo: нужен owner/name или host/owner/name.",
+  "bad-cwd": "Рабочий каталог не найден.",
+  "bad-body": "Комментарий не отправлен: body нарушает лимит длины.",
+  "bad-json": "gh вернул неожиданный ответ — проверьте версию gh и авторизацию.",
+  "gh-failed": "gh завершился с ошибкой.",
+  internal: "Внутренняя ошибка плагина.",
+};
+
+/* ------------------------------------------------------------------ */
+/* Session/argument helpers                                           */
+/* ------------------------------------------------------------------ */
+
+function rootOf(args, exec) {
+  const explicit = typeof args?.cwd === "string" ? args.cwd.trim() : "";
+  const cwd = exec?.agent?.session?.header?.cwd;
+  return path.resolve(explicit || cwd || process.cwd());
+}
+
+function truncate(text, max) {
+  const value = typeof text === "string" ? text : String(text ?? "");
+  return value.length <= max ? value : `${value.slice(0, Math.max(0, max - 1))}…`;
+}
+
+function repoLabel(spec) {
+  if (!spec) return "";
+  return spec.host === "github.com" ? spec.slug : `${spec.host}/${spec.slug}`;
+}
+
+function failureText(failure) {
+  const hint = FAILURE_HINTS[failure?.code] ?? FAILURE_HINTS["gh-failed"];
+  const detail = typeof failure?.detail === "string" && failure.detail.trim().length > 0
+    ? `\n${truncate(failure.detail.trim(), 800)}`
+    : "";
+  return `${hint}${detail}`;
+}
+
+function failureResult(action, failure) {
+  return {
+    ok: false,
+    action,
+    code: failure?.code ?? "gh-failed",
+    error: failureText(failure),
+    text: `github_review ${action}: ${failureText(failure)}`,
+  };
+}
+
+/** Resolve cwd + optional repo override + optional explicit PR number. */
+function prepareTarget({ args, cwd }) {
+  const detected = detectRepo({ cwd, repo: args?.repo });
+  if (detected.error) {
+    const code = /некорректный repo/iu.test(detected.error) ? "bad-repo" : "bad-cwd";
+    return { ok: false, failure: { code, detail: detected.error } };
+  }
+  const raw = args?.pr;
+  const provided = raw !== undefined && raw !== null && raw !== "";
+  const number = parsePrNumber(raw);
+  if (provided && number === undefined) {
+    return { ok: false, failure: { code: "bad-pr", detail: `pr=«${String(raw)}» не является номером PR` } };
+  }
+  return {
+    ok: true,
+    cwd,
+    repo: detected.repo ?? undefined,
+    detected,
+    number,
+  };
+}
+
+/** Explicit number wins; otherwise ask gh for the current branch PR. */
+function ensureNumber(target) {
+  if (target.number !== undefined) return { ok: true, number: target.number };
+  return resolvePrNumber({ cwd: target.cwd, repo: target.repo, branch: target.detected?.branch });
+}
+
+/**
+ * `no-pr` for an explicit number means "that PR is missing", not "no PR for
+ * the current branch" — keep the hint truthful.
+ */
+function targetFailure(failure, target) {
+  if (failure?.code === "no-pr" && target?.number !== undefined) return { ...failure, code: "pr-not-found" };
+  return failure;
+}
+
+/* ------------------------------------------------------------------ */
+/* status                                                             */
+/* ------------------------------------------------------------------ */
+
+function statusAction(cwd, args) {
+  const status = probeStatus({ cwd, repo: args?.repo });
+  const { gh, auth } = status;
+  const detected = status.repo;
+  const lines = [];
+  lines.push(gh.installed ? `gh: установлен${gh.version ? ` (v${gh.version})` : ""}` : "gh: не установлен");
+  if (gh.installed) {
+    if (auth.authenticated) {
+      const active = auth.active;
+      const scopes = Array.isArray(active?.scopes) && active.scopes.length > 0 ? ` · scopes: ${active.scopes.join(", ")}` : "";
+      lines.push(`Авторизация: да — ${active?.login || "аккаунт"}${active?.host ? ` @ ${active.host}` : ""}${scopes}`);
+      if (auth.accounts.length > 1) lines.push(`Аккаунтов в gh: ${auth.accounts.length} (активен ${active?.login || "?"})`);
+    } else {
+      lines.push("Авторизация: нет — выполните `gh auth login`");
+    }
+    if (auth.detail && !auth.authenticated) lines.push(`Детали: ${truncate(auth.detail, 400)}`);
+  } else {
+    lines.push("Установите GitHub CLI: https://cli.github.com — затем `gh auth login`.");
+    if (gh.detail) lines.push(`Детали: ${truncate(gh.detail, 400)}`);
+  }
+  if (detected.error) {
+    lines.push(`Репозиторий: ${detected.error}`);
+  } else if (detected.repo) {
+    lines.push(`Репозиторий: ${repoLabel(detected.repo)}${detected.branch ? ` · ветка ${detected.branch}` : ""}${detected.source === "explicit" ? " · из repo=" : " · из git remote"}`);
+  } else {
+    lines.push("Репозиторий: не определён — cwd не git-репозиторий или у origin нет GitHub-remote. Укажите repo=owner/name.");
+  }
+  if (detected.root) lines.push(`Корень: ${detected.root}`);
+  if (!detected.gitInstalled) lines.push("git: не найден в PATH — определение репозитория по remote недоступно.");
+  if (gh.installed && auth.authenticated) lines.push("Дальше: action=pr | checks | comments | diff (pr=<номер> опционально), action=comment (только с confirm: true).");
+  return {
+    ok: gh.installed && auth.authenticated && !detected.error,
+    action: "status",
+    cwd,
+    gh: { installed: gh.installed, version: gh.version },
+    auth: {
+      authenticated: auth.authenticated,
+      notLoggedIn: auth.notLoggedIn,
+      host: auth.host,
+      accounts: auth.accounts,
+      active: auth.active,
+      scopes: auth.scopes,
+    },
+    repository: detected.repo
+      ? {
+        slug: detected.repo.slug,
+        host: detected.repo.host,
+        url: detected.repo.webUrl,
+        source: detected.source,
+        branch: detected.branch ?? null,
+        root: detected.root ?? null,
+      }
+      : null,
+    text: lines.join("\n"),
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* pr / checks / comments / diff renderers                            */
+/* ------------------------------------------------------------------ */
+
+function renderPr(pr) {
+  const lines = [];
+  const flags = [pr.state.toLowerCase() || "state?", pr.isDraft ? "draft" : ""].filter(Boolean);
+  lines.push(`PR #${pr.number ?? "?"} · ${flags.join(" · ")} · «${pr.title || "(без заголовка)"}»`);
+  if (pr.url) lines.push(`URL: ${pr.url}`);
+  lines.push(`Автор: ${pr.author || "неизвестен"}${pr.createdAt ? ` · создан ${pr.createdAt}` : ""}${pr.updatedAt ? ` · обновлён ${pr.updatedAt}` : ""}`);
+  lines.push(`Ветки: ${pr.base.branch || "?"} ← ${pr.head.branch || "?"}`);
+  lines.push(`Изменения: ${pr.changedFiles} файлов, +${pr.additions} −${pr.deletions}, коммитов ${pr.commits.total}`);
+  const meta = [];
+  if (pr.reviewDecision) meta.push(`review: ${pr.reviewDecision}`);
+  if (pr.mergeable) meta.push(`mergeable: ${pr.mergeable}`);
+  if (pr.labels.length > 0) meta.push(`labels: ${pr.labels.map((label) => label.name).join(", ")}`);
+  if (meta.length > 0) lines.push(meta.join(" · "));
+  if (pr.files.total > 0) {
+    lines.push(`Файлы (${pr.files.total}${pr.files.truncated ? `, показаны ${pr.files.items.length}` : ""}):`);
+    for (const file of pr.files.items) {
+      const type = file.changeType ? ` [${file.changeType}]` : "";
+      const diff = file.additions || file.deletions ? ` (+${file.additions} −${file.deletions})` : "";
+      lines.push(`- ${file.path || "(без пути)"}${type}${diff}`);
+    }
+    if (pr.files.truncated) lines.push(`- … ещё ${pr.files.total - pr.files.items.length} файлов`);
+  }
+  if (pr.commits.total > 0) {
+    lines.push(`Коммиты (${pr.commits.total}${pr.commits.truncated ? `, показаны ${pr.commits.items.length}` : ""}):`);
+    for (const commit of pr.commits.items) {
+      lines.push(`- ${commit.shortOid || "?"} ${commit.messageHeadline || "(без сообщения)"}${commit.author ? ` — ${commit.author}` : ""}${commit.committedDate ? ` · ${commit.committedDate}` : ""}`);
+    }
+    if (pr.commits.truncated) lines.push(`- … ещё ${pr.commits.total - pr.commits.items.length} коммитов`);
+  }
+  if (!pr.body.empty) {
+    lines.push("Body:");
+    lines.push(pr.body.text.trim());
+    if (pr.body.truncated) lines.push(`… body обрезан (${pr.body.chars} символов)`);
+  }
+  return lines.join("\n");
+}
+
+function renderChecks(number, checks, format) {
+  const { summary } = checks;
+  const lines = [];
+  lines.push(`Checks PR #${number}: ${checks.total} проверок${checks.truncated ? ` (показаны ${checks.items.length})` : ""}${format === "text" ? " · формат: текст (gh без --json)" : ""}`);
+  lines.push(`pass ${summary.pass} · fail ${summary.fail} · pending ${summary.pending} · skipping ${summary.skipping} · cancel ${summary.cancel}${summary.unknown ? ` · unknown ${summary.unknown}` : ""}`);
+  if (checks.failed.length > 0) {
+    lines.push("Провалено:");
+    for (const item of checks.failed) {
+      const workflow = item.workflow ? ` (${item.workflow})` : "";
+      const description = item.description ? `: ${item.description}` : "";
+      const link = item.link ? ` → ${item.link}` : "";
+      lines.push(`- ${item.name}${workflow} — ${item.state || "FAIL"}${description}${link}`);
+    }
+  }
+  if (checks.pending.length > 0) {
+    lines.push("В процессе:");
+    for (const item of checks.pending) {
+      const link = item.link ? ` → ${item.link}` : "";
+      lines.push(`- ${item.name} — ${item.state || "PENDING"}${link}`);
+    }
+  }
+  const rest = checks.items.filter((item) => item.bucket !== "fail" && item.bucket !== "pending");
+  if (rest.length > 0) {
+    const shown = rest.slice(0, 15);
+    lines.push(`Остальные (${rest.length}): ${shown.map((item) => `${item.name}${item.state ? ` [${item.state}]` : ""}`).join(", ")}${rest.length > shown.length ? ", …" : ""}`);
+  }
+  if (checks.total === 0) lines.push("Проверки не найдены (возможно, CI не настроен или PR без workflow).");
+  return lines.join("\n");
+}
+
+function renderComments(number, viewJson, reviews, conversation, threads, inline) {
+  const title = viewJson && typeof viewJson.title === "string" ? viewJson.title : "";
+  const lines = [];
+  lines.push(`Комментарии PR #${number}${title ? ` · «${title}»` : ""}`);
+  lines.push(
+    `Review: ${reviews.total} · approved ${reviews.byState.APPROVED} · changes requested ${reviews.byState.CHANGES_REQUESTED} · commented ${reviews.byState.COMMENTED} · dismissed ${reviews.byState.DISMISSED}${reviews.byState.OTHER ? ` · other ${reviews.byState.OTHER}` : ""}`,
+  );
+  if (reviews.blocking.length > 0) {
+    lines.push("Запрошены изменения:");
+    for (const review of reviews.blocking) {
+      lines.push(`- @${review.author || "?"}${review.submittedAt ? ` (${review.submittedAt})` : ""}: ${review.body || "(без текста)"}`);
+    }
+  }
+  if (conversation.total > 0) {
+    lines.push(`Обсуждение: ${conversation.total} комментариев${conversation.truncated ? ` (показаны ${conversation.items.length})` : ""}`);
+    for (const item of conversation.items.slice(0, 10)) {
+      lines.push(`- @${item.author || "?"}${item.createdAt ? ` (${item.createdAt})` : ""}: ${item.body || "(пусто)"}`);
+    }
+  }
+  const replyNote = threads.replies > 0 ? ` · ответов ${threads.replies}` : "";
+  const truncatedNote = threads.truncated ? ` (показаны ${threads.threads.length})` : "";
+  lines.push(`Inline threads: ${threads.threadCount}${threads.total > 0 ? ` · комментариев ${threads.total}` : ""}${replyNote}${truncatedNote}`);
+  if (!inline.ok) lines.push(`Inline-комментарии недоступны: ${inline.failure?.detail || inline.failure?.code || "ошибка API"}`);
+  if (threads.byFile.length > 0) {
+    lines.push(`Файлы с замечаниями: ${threads.byFile.map((entry) => `${entry.path} (${entry.count})`).join(", ")}`);
+  }
+  for (const thread of threads.threads) {
+    const location = thread.path ? `${thread.path}${thread.line ? `:${thread.line}` : ""}` : "(без файла)";
+    const replies = thread.replies.length > 0 ? ` · ответов: ${thread.replies.length}` : "";
+    lines.push(`- ${location} · @${thread.author || "?"}: ${thread.body || "(пусто)"}${replies}`);
+  }
+  if (threads.resolvedKnown === false && threads.threadCount > 0) {
+    lines.push("Примечание: resolved/outdated у inline-тредов REST API не отдаёт — состояние не показано.");
+  }
+  if (threads.total >= LIMITS.inlineComments) {
+    lines.push(`Примечание: inline-комментариев ≥ ${LIMITS.inlineComments} — показаны не все (REST-лимит плагина).`);
+  }
+  return lines.join("\n");
+}
+
+function renderDiff(number, diff) {
+  const lines = [];
+  const size = diff.truncated
+    ? `diff больше лимита ${formatBytes(diff.limit)} · показано ${formatBytes(diff.shownBytes)}`
+    : `Размер: ${formatBytes(diff.bytes)}`;
+  lines.push(`Diff PR #${number} — ${size}`);
+  lines.push("");
+  if (diff.text.length === 0) lines.push("(diff пуст — изменений нет)");
+  else lines.push(diff.text);
+  if (diff.truncated) {
+    lines.push("");
+    lines.push("… diff обрезан по байтовому лимиту. Увеличьте maxBytes или смотрите отдельные файлы PR.");
+  }
+  return lines.join("\n");
+}
+
+/* ------------------------------------------------------------------ */
+/* Actions                                                            */
+/* ------------------------------------------------------------------ */
+
+function prAction(target) {
+  const resolved = ensureNumber(target);
+  if (!resolved.ok) return failureResult("pr", resolved.failure);
+  const view = fetchPrView({ cwd: target.cwd, repo: target.repo, number: resolved.number });
+  if (!view.ok) return failureResult("pr", targetFailure(view.failure, target));
+  const pr = normalizePullRequest(view.json);
+  return {
+    ok: true,
+    action: "pr",
+    number: pr.number ?? resolved.number,
+    pr,
+    text: renderPr(pr),
+  };
+}
+
+function checksAction(target) {
+  const resolved = ensureNumber(target);
+  if (!resolved.ok) return failureResult("checks", resolved.failure);
+  const fetched = fetchChecks({ cwd: target.cwd, repo: target.repo, number: resolved.number });
+  if (!fetched.ok) return failureResult("checks", targetFailure(fetched.failure, target));
+  const checks = normalizeChecks(fetched.rows);
+  return {
+    ok: true,
+    action: "checks",
+    number: resolved.number,
+    format: fetched.format,
+    checks,
+    failed: checks.failed.length,
+    text: renderChecks(resolved.number, checks, fetched.format),
+  };
+}
+
+function commentsAction(target) {
+  const resolved = ensureNumber(target);
+  if (!resolved.ok) return failureResult("comments", resolved.failure);
+  const fetched = fetchComments({ cwd: target.cwd, repo: target.repo, number: resolved.number });
+  if (!fetched.ok) return failureResult("comments", targetFailure(fetched.failure, target));
+  const reviews = summarizeReviews(fetched.json?.reviews);
+  const conversation = normalizeConversationComments(fetched.json?.comments);
+  const threads = normalizeReviewComments(fetched.inline.rows);
+  return {
+    ok: true,
+    action: "comments",
+    number: resolved.number,
+    reviews,
+    conversation,
+    threads,
+    inline: { ok: fetched.inline.ok, failure: fetched.inline.failure },
+    text: renderComments(resolved.number, fetched.json, reviews, conversation, threads, fetched.inline),
+  };
+}
+
+async function diffAction(target, args) {
+  const resolved = ensureNumber(target);
+  if (!resolved.ok) return failureResult("diff", resolved.failure);
+  const limit = clampDiffBytes(args?.maxBytes);
+  const fetched = await fetchDiff({ cwd: target.cwd, repo: target.repo, number: resolved.number, maxBytes: limit });
+  if (!fetched.ok) return failureResult("diff", targetFailure(fetched.failure, target));
+  const capped = truncateDiff(fetched.text, limit);
+  const diff = {
+    text: capped.text,
+    bytes: capped.bytes,
+    shownBytes: capped.shownBytes,
+    truncated: capped.truncated || fetched.truncated === true,
+    limit,
+  };
+  return {
+    ok: true,
+    action: "diff",
+    number: resolved.number,
+    bytes: diff.bytes,
+    shownBytes: diff.shownBytes,
+    truncated: diff.truncated,
+    limit,
+    patch: diff.text,
+    text: renderDiff(resolved.number, diff),
+  };
+}
+
+function commentRefusal(action, reason) {
+  return {
+    ok: false,
+    action,
+    code: "confirmation-required",
+    text: `github_review comment: отказ — ${reason}. Мутация не выполнена. Нужны одновременно confirm: true, точный целочисленный pr=<номер> и непустой body.`,
+  };
+}
+
+function commentAction(cwd, args) {
+  if (args?.confirm !== true) return commentRefusal("comment", "нет явного подтверждения confirm: true");
+  const number = parsePrNumber(args?.pr);
+  if (number === undefined) return commentRefusal("comment", "не указан точный номер PR (pr)");
+  if (typeof args?.body !== "string" || args.body.trim().length === 0) return commentRefusal("comment", "пустой body комментария");
+  const body = args.body.trim();
+  if (body.length > LIMITS.maxCommentChars) {
+    return failureResult("comment", { code: "bad-body", detail: `body ${body.length} символов > ${LIMITS.maxCommentChars}` });
+  }
+  const target = prepareTarget({ args, cwd });
+  if (!target.ok) return failureResult("comment", target.failure);
+  const posted = postComment({ cwd: target.cwd, repo: target.repo, number, body });
+  if (!posted.ok) return failureResult("comment", targetFailure(posted.failure, { number }));
+  return {
+    ok: true,
+    action: "comment",
+    number,
+    url: posted.url || null,
+    repo: target.repo ? repoLabel(target.repo) : null,
+    text: `Комментарий отправлен в PR #${number}${target.repo ? ` (${repoLabel(target.repo)})` : ""}${posted.url ? `: ${posted.url}` : ""}.`,
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* Tool registration                                                  */
+/* ------------------------------------------------------------------ */
+
+const TOOL_PARAMETERS = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    action: {
+      type: "string",
+      enum: ["status", "pr", "checks", "comments", "diff", "comment"],
+      description: "status | pr | checks | comments | diff | comment",
+    },
+    pr: { type: "integer", description: "PR number. Read actions default to the PR of the current branch; comment requires an explicit number." },
+    repo: { type: "string", description: "Repository override: owner/name or host/owner/name; defaults to the git origin remote of cwd." },
+    cwd: { type: "string", description: "Repository working directory; defaults to the current Session cwd." },
+    body: { type: "string", description: "Comment body for action=comment (Markdown, max 60000 characters)." },
+    confirm: { type: "boolean", description: "Explicit confirmation required by action=comment; without true the mutation is refused." },
+    maxBytes: { type: "integer", description: "Diff byte cap for action=diff (4096..2097152, default 204800)." },
+  },
+  required: ["action"],
+};
+
+async function runTool(args, exec) {
+  const action = typeof args?.action === "string" ? args.action.trim().toLowerCase() : "status";
+  const cwd = rootOf(args, exec);
+  try {
+    if (!fs.existsSync(cwd)) return failureResult(action, { code: "bad-cwd", detail: cwd });
+    if (action === "status") return statusAction(cwd, args);
+    if (action === "comment") return commentAction(cwd, args);
+    if (UNSUPPORTED_ACTIONS.has(action)) {
+      return {
+        ok: false,
+        action,
+        code: "unsupported-action",
+        text: `github_review: действие «${action}» не поддерживается. Плагин read-only по умолчанию и не делает merge/close/push — доступны status, pr, checks, comments, diff и подтверждённый comment.`,
+      };
+    }
+    if (!TOOL_ACTIONS.has(action)) {
+      return {
+        ok: false,
+        action,
+        code: "unknown-action",
+        text: `github_review: неизвестное действие «${action}». Доступно: status, pr, checks, comments, diff, comment.`,
+      };
+    }
+    const target = prepareTarget({ args, cwd });
+    if (!target.ok) return failureResult(action, target.failure);
+    if (action === "pr") return prAction(target);
+    if (action === "checks") return checksAction(target);
+    if (action === "comments") return commentsAction(target);
+    return await diffAction(target, args);
+  } catch (error) {
+    return failureResult(action, {
+      code: "internal",
+      detail: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+export function apply(ctx) {
+  const tool = {
+    name: "github_review",
+    description:
+      "Review a GitHub pull request through the authenticated `gh` CLI: status (gh install/auth, repo detection), PR overview, CI checks, review comment threads and a byte-capped diff. Read-only by default; the single mutation `comment` runs only with confirm: true plus an explicit PR number and body. Never merges, closes or force-pushes.",
+    parameters: TOOL_PARAMETERS,
+    timeoutMs: 60_000,
+    output: {
+      schema: { type: "object", additionalProperties: true },
+      render(_args, value) {
+        const text = typeof value?.text === "string" ? value.text : JSON.stringify(value);
+        return [{ type: "text", text: truncate(text, value?.action === "diff" ? DIFF_RENDER_CHARS : RENDER_CHARS) }];
+      },
+    },
+    execute: runTool,
+  };
+  ctx.tools.register(tool);
+  ctx.logger?.info?.("[github-review] tool ready");
+}