@gaud_erp/paperclip-github-manager 0.3.0 → 0.4.0

package/README.md

@@ -8,6 +8,29 @@ Paperclip connector plugin for GitHub — repository listing, PR/issue sync, and
 - Sync open pull requests and issues (manual actions + scheduled job)
 - Register GitHub webhooks pointing at the Paperclip host inbound URL
 - Dashboard health widget and full **GitHub** page in the host UI
+- **Agent tools** for autonomous PR code review (diff, inline comments, review verdict, file read, repo list, issue search)
+
+## Agent reviewer workflow
+
+Tools are exposed to Paperclip agents as `cus.github-manager/github_*` (plugin-namespaced at runtime).
+
+1. **Collect** — `github_get_pull_request_diff` with `owner`, `repo`, `pr_number`
+2. **Analyze** — agent reads metadata + unified diff (truncated above ~120k chars with a changed-files index)
+3. **Context** (optional) — `github_read_file_content` when the diff is insufficient
+4. **Inline feedback** (optional) — `github_create_review_comment` per finding (`commit_id` = PR head SHA)
+5. **Verdict** — `github_submit_pr_review` with `APPROVE`, `REQUEST_CHANGES`, or `COMMENT`
+
+Supporting tools: `github_list_repositories`, `github_search_issues`.
+
+### Configuration
+
+| Variable | Purpose |
+|----------|---------|
+| `GITHUB_TOKEN` | Optional worker-level PAT fallback |
+| `GITHUB_DEFAULT_OWNER` | Default org/user when `owner` is omitted in list tools |
+| `GITHUB_API_URL` | API base (GitHub Enterprise), default `https://api.github.com` |
+
+Per-company PAT in **GitHub → Configurações** is preferred for multi-tenant installs.
 
 ## Requirements
 
@@ -46,7 +69,7 @@ Cada **release no GitHub** (tag `v*`, ex. `v0.3.0`) dispara o workflow [publish-
 ## Production install (npm)
 
 ```bash
-paperclipai plugin install @gaud_erp/paperclip-github-manager@0.3.0 --api-base http://127.0.0.1:3100
+paperclipai plugin install @gaud_erp/paperclip-github-manager@0.4.0 --api-base http://127.0.0.1:3100
 paperclipai plugin inspect cus.github-manager --api-base http://127.0.0.1:3100
 ```
 

package/dist/manifest.js

@@ -9,7 +9,7 @@ var ROUTES = {
 var manifest = {
   id: "cus.github-manager",
   apiVersion: 1,
-  version: "0.3.0",
+  version: "0.4.0",
   displayName: "GitHub Manager",
   description: "Plugin Paperclip para gerenciar repositorios, PRs, issues e webhooks GitHub",
   author: "CUS",
@@ -20,6 +20,7 @@ var manifest = {
     "secrets.read-ref",
     "plugin.state.read",
     "plugin.state.write",
+    "agent.tools.register",
     "jobs.schedule",
     "webhooks.receive",
     "ui.sidebar.register",

package/dist/manifest.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/constants.ts", "../src/manifest.ts"],
-  "sourcesContent": ["/** Plugin page route segments (manifest `routePath` \u2014 single slug, no slashes). */\nexport const ROUTES = {\n  repos: \"github\",\n  settings: \"github-settings\",\n  pullRequests: \"github-pull-requests\"\n} as const;\n\n/** Host navigation paths (use with `linkProps`). */\nexport const PATHS = {\n  repos: \"/github\",\n  settings: \"/github-settings\",\n  pullRequests: \"/github-pull-requests\",\n  companySecrets: \"/company/settings\"\n} as const;\n\nexport const GITHUB_TOKEN_SECRET_KEY = \"github_token\";\n", "import type { PaperclipPluginManifestV1 } from \"@paperclipai/plugin-sdk\";\nimport { ROUTES } from \"./constants.js\";\n\nconst manifest: PaperclipPluginManifestV1 = {\n  id: \"cus.github-manager\",\n  apiVersion: 1,\n  version: \"0.3.0\",\n  displayName: \"GitHub Manager\",\n  description: \"Plugin Paperclip para gerenciar repositorios, PRs, issues e webhooks GitHub\",\n  author: \"CUS\",\n  categories: [\"connector\"],\n  capabilities: [\n    \"events.subscribe\",\n    \"http.outbound\",\n    \"secrets.read-ref\",\n    \"plugin.state.read\",\n    \"plugin.state.write\",\n    \"jobs.schedule\",\n    \"webhooks.receive\",\n    \"ui.sidebar.register\",\n    \"ui.dashboardWidget.register\",\n    \"ui.page.register\"\n  ],\n  jobs: [\n    {\n      jobKey: \"sync-github\",\n      displayName: \"Sync GitHub PRs and issues\",\n      description: \"Pulls open PRs and issues for tracked repositories\",\n      schedule: \"0 */6 * * *\"\n    }\n  ],\n  webhooks: [\n    {\n      endpointKey: \"github-events\",\n      displayName: \"GitHub repository events\",\n      description: \"Receives pull_request and issues events from configured repositories\"\n    }\n  ],\n  entrypoints: {\n    worker: \"./dist/worker.js\",\n    ui: \"./dist/ui\"\n  },\n  ui: {\n    slots: [\n      {\n        type: \"sidebarPanel\",\n        id: \"github-module\",\n        displayName: \"GitHub\",\n        exportName: \"GitHubSidebarModule\",\n        order: 45\n      },\n      {\n        type: \"routeSidebar\",\n        id: \"github-route-nav\",\n        displayName: \"GitHub\",\n        routePath: ROUTES.repos,\n        exportName: \"GitHubRouteSidebar\",\n        order: 45\n      },\n      {\n        type: \"routeSidebar\",\n        id: \"github-settings-route-nav\",\n        displayName: \"GitHub\",\n        routePath: ROUTES.settings,\n        exportName: \"GitHubRouteSidebar\",\n        order: 45\n      },\n      {\n        type: \"routeSidebar\",\n        id: \"github-prs-route-nav\",\n        displayName: \"GitHub\",\n        routePath: ROUTES.pullRequests,\n        exportName: \"GitHubRouteSidebar\",\n        order: 45\n      },\n      {\n        type: \"dashboardWidget\",\n        id: \"github-health\",\n        displayName: \"GitHub Manager Health\",\n        exportName: \"DashboardWidget\"\n      },\n      {\n        type: \"page\",\n        id: \"github-settings-page\",\n        displayName: \"GitHub \u2014 Configura\u00E7\u00F5es\",\n        routePath: ROUTES.settings,\n        exportName: \"GitHubSettingsPage\",\n        order: 45\n      },\n      {\n        type: \"page\",\n        id: \"github-repos-page\",\n        displayName: \"GitHub \u2014 Reposit\u00F3rios\",\n        routePath: ROUTES.repos,\n        exportName: \"GitHubReposPage\",\n        order: 45\n      },\n      {\n        type: \"page\",\n        id: \"github-prs-page\",\n        displayName: \"GitHub \u2014 Pull requests\",\n        routePath: ROUTES.pullRequests,\n        exportName: \"GitHubPullRequestsPage\",\n        order: 45\n      }\n    ]\n  }\n};\n\nexport default manifest;\n"],
-  "mappings": ";AACO,IAAM,SAAS;AAAA,EACpB,OAAO;AAAA,EACP,UAAU;AAAA,EACV,cAAc;AAChB;;;ACFA,IAAM,WAAsC;AAAA,EAC1C,IAAI;AAAA,EACJ,YAAY;AAAA,EACZ,SAAS;AAAA,EACT,aAAa;AAAA,EACb,aAAa;AAAA,EACb,QAAQ;AAAA,EACR,YAAY,CAAC,WAAW;AAAA,EACxB,cAAc;AAAA,IACZ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA,MAAM;AAAA,IACJ;AAAA,MACE,QAAQ;AAAA,MACR,aAAa;AAAA,MACb,aAAa;AAAA,MACb,UAAU;AAAA,IACZ;AAAA,EACF;AAAA,EACA,UAAU;AAAA,IACR;AAAA,MACE,aAAa;AAAA,MACb,aAAa;AAAA,MACb,aAAa;AAAA,IACf;AAAA,EACF;AAAA,EACA,aAAa;AAAA,IACX,QAAQ;AAAA,IACR,IAAI;AAAA,EACN;AAAA,EACA,IAAI;AAAA,IACF,OAAO;AAAA,MACL;AAAA,QACE,MAAM;AAAA,QACN,IAAI;AAAA,QACJ,aAAa;AAAA,QACb,YAAY;AAAA,QACZ,OAAO;AAAA,MACT;AAAA,MACA;AAAA,QACE,MAAM;AAAA,QACN,IAAI;AAAA,QACJ,aAAa;AAAA,QACb,WAAW,OAAO;AAAA,QAClB,YAAY;AAAA,QACZ,OAAO;AAAA,MACT;AAAA,MACA;AAAA,QACE,MAAM;AAAA,QACN,IAAI;AAAA,QACJ,aAAa;AAAA,QACb,WAAW,OAAO;AAAA,QAClB,YAAY;AAAA,QACZ,OAAO;AAAA,MACT;AAAA,MACA;AAAA,QACE,MAAM;AAAA,QACN,IAAI;AAAA,QACJ,aAAa;AAAA,QACb,WAAW,OAAO;AAAA,QAClB,YAAY;AAAA,QACZ,OAAO;AAAA,MACT;AAAA,MACA;AAAA,QACE,MAAM;AAAA,QACN,IAAI;AAAA,QACJ,aAAa;AAAA,QACb,YAAY;AAAA,MACd;AAAA,MACA;AAAA,QACE,MAAM;AAAA,QACN,IAAI;AAAA,QACJ,aAAa;AAAA,QACb,WAAW,OAAO;AAAA,QAClB,YAAY;AAAA,QACZ,OAAO;AAAA,MACT;AAAA,MACA;AAAA,QACE,MAAM;AAAA,QACN,IAAI;AAAA,QACJ,aAAa;AAAA,QACb,WAAW,OAAO;AAAA,QAClB,YAAY;AAAA,QACZ,OAAO;AAAA,MACT;AAAA,MACA;AAAA,QACE,MAAM;AAAA,QACN,IAAI;AAAA,QACJ,aAAa;AAAA,QACb,WAAW,OAAO;AAAA,QAClB,YAAY;AAAA,QACZ,OAAO;AAAA,MACT;AAAA,IACF;AAAA,EACF;AACF;AAEA,IAAO,mBAAQ;",
+  "sourcesContent": ["/** Plugin page route segments (manifest `routePath` \u2014 single slug, no slashes). */\nexport const ROUTES = {\n  repos: \"github\",\n  settings: \"github-settings\",\n  pullRequests: \"github-pull-requests\"\n} as const;\n\n/** Host navigation paths (use with `linkProps`). */\nexport const PATHS = {\n  repos: \"/github\",\n  settings: \"/github-settings\",\n  pullRequests: \"/github-pull-requests\",\n  companySecrets: \"/company/settings\"\n} as const;\n\nexport const GITHUB_TOKEN_SECRET_KEY = \"github_token\";\n", "import type { PaperclipPluginManifestV1 } from \"@paperclipai/plugin-sdk\";\nimport { ROUTES } from \"./constants.js\";\n\nconst manifest: PaperclipPluginManifestV1 = {\n  id: \"cus.github-manager\",\n  apiVersion: 1,\n  version: \"0.4.0\",\n  displayName: \"GitHub Manager\",\n  description: \"Plugin Paperclip para gerenciar repositorios, PRs, issues e webhooks GitHub\",\n  author: \"CUS\",\n  categories: [\"connector\"],\n  capabilities: [\n    \"events.subscribe\",\n    \"http.outbound\",\n    \"secrets.read-ref\",\n    \"plugin.state.read\",\n    \"plugin.state.write\",\n    \"agent.tools.register\",\n    \"jobs.schedule\",\n    \"webhooks.receive\",\n    \"ui.sidebar.register\",\n    \"ui.dashboardWidget.register\",\n    \"ui.page.register\"\n  ],\n  jobs: [\n    {\n      jobKey: \"sync-github\",\n      displayName: \"Sync GitHub PRs and issues\",\n      description: \"Pulls open PRs and issues for tracked repositories\",\n      schedule: \"0 */6 * * *\"\n    }\n  ],\n  webhooks: [\n    {\n      endpointKey: \"github-events\",\n      displayName: \"GitHub repository events\",\n      description: \"Receives pull_request and issues events from configured repositories\"\n    }\n  ],\n  entrypoints: {\n    worker: \"./dist/worker.js\",\n    ui: \"./dist/ui\"\n  },\n  ui: {\n    slots: [\n      {\n        type: \"sidebarPanel\",\n        id: \"github-module\",\n        displayName: \"GitHub\",\n        exportName: \"GitHubSidebarModule\",\n        order: 45\n      },\n      {\n        type: \"routeSidebar\",\n        id: \"github-route-nav\",\n        displayName: \"GitHub\",\n        routePath: ROUTES.repos,\n        exportName: \"GitHubRouteSidebar\",\n        order: 45\n      },\n      {\n        type: \"routeSidebar\",\n        id: \"github-settings-route-nav\",\n        displayName: \"GitHub\",\n        routePath: ROUTES.settings,\n        exportName: \"GitHubRouteSidebar\",\n        order: 45\n      },\n      {\n        type: \"routeSidebar\",\n        id: \"github-prs-route-nav\",\n        displayName: \"GitHub\",\n        routePath: ROUTES.pullRequests,\n        exportName: \"GitHubRouteSidebar\",\n        order: 45\n      },\n      {\n        type: \"dashboardWidget\",\n        id: \"github-health\",\n        displayName: \"GitHub Manager Health\",\n        exportName: \"DashboardWidget\"\n      },\n      {\n        type: \"page\",\n        id: \"github-settings-page\",\n        displayName: \"GitHub \u2014 Configura\u00E7\u00F5es\",\n        routePath: ROUTES.settings,\n        exportName: \"GitHubSettingsPage\",\n        order: 45\n      },\n      {\n        type: \"page\",\n        id: \"github-repos-page\",\n        displayName: \"GitHub \u2014 Reposit\u00F3rios\",\n        routePath: ROUTES.repos,\n        exportName: \"GitHubReposPage\",\n        order: 45\n      },\n      {\n        type: \"page\",\n        id: \"github-prs-page\",\n        displayName: \"GitHub \u2014 Pull requests\",\n        routePath: ROUTES.pullRequests,\n        exportName: \"GitHubPullRequestsPage\",\n        order: 45\n      }\n    ]\n  }\n};\n\nexport default manifest;\n"],
+  "mappings": ";AACO,IAAM,SAAS;AAAA,EACpB,OAAO;AAAA,EACP,UAAU;AAAA,EACV,cAAc;AAChB;;;ACFA,IAAM,WAAsC;AAAA,EAC1C,IAAI;AAAA,EACJ,YAAY;AAAA,EACZ,SAAS;AAAA,EACT,aAAa;AAAA,EACb,aAAa;AAAA,EACb,QAAQ;AAAA,EACR,YAAY,CAAC,WAAW;AAAA,EACxB,cAAc;AAAA,IACZ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAAA,EACA,MAAM;AAAA,IACJ;AAAA,MACE,QAAQ;AAAA,MACR,aAAa;AAAA,MACb,aAAa;AAAA,MACb,UAAU;AAAA,IACZ;AAAA,EACF;AAAA,EACA,UAAU;AAAA,IACR;AAAA,MACE,aAAa;AAAA,MACb,aAAa;AAAA,MACb,aAAa;AAAA,IACf;AAAA,EACF;AAAA,EACA,aAAa;AAAA,IACX,QAAQ;AAAA,IACR,IAAI;AAAA,EACN;AAAA,EACA,IAAI;AAAA,IACF,OAAO;AAAA,MACL;AAAA,QACE,MAAM;AAAA,QACN,IAAI;AAAA,QACJ,aAAa;AAAA,QACb,YAAY;AAAA,QACZ,OAAO;AAAA,MACT;AAAA,MACA;AAAA,QACE,MAAM;AAAA,QACN,IAAI;AAAA,QACJ,aAAa;AAAA,QACb,WAAW,OAAO;AAAA,QAClB,YAAY;AAAA,QACZ,OAAO;AAAA,MACT;AAAA,MACA;AAAA,QACE,MAAM;AAAA,QACN,IAAI;AAAA,QACJ,aAAa;AAAA,QACb,WAAW,OAAO;AAAA,QAClB,YAAY;AAAA,QACZ,OAAO;AAAA,MACT;AAAA,MACA;AAAA,QACE,MAAM;AAAA,QACN,IAAI;AAAA,QACJ,aAAa;AAAA,QACb,WAAW,OAAO;AAAA,QAClB,YAAY;AAAA,QACZ,OAAO;AAAA,MACT;AAAA,MACA;AAAA,QACE,MAAM;AAAA,QACN,IAAI;AAAA,QACJ,aAAa;AAAA,QACb,YAAY;AAAA,MACd;AAAA,MACA;AAAA,QACE,MAAM;AAAA,QACN,IAAI;AAAA,QACJ,aAAa;AAAA,QACb,WAAW,OAAO;AAAA,QAClB,YAAY;AAAA,QACZ,OAAO;AAAA,MACT;AAAA,MACA;AAAA,QACE,MAAM;AAAA,QACN,IAAI;AAAA,QACJ,aAAa;AAAA,QACb,WAAW,OAAO;AAAA,QAClB,YAAY;AAAA,QACZ,OAAO;AAAA,MACT;AAAA,MACA;AAAA,QACE,MAAM;AAAA,QACN,IAAI;AAAA,QACJ,aAAa;AAAA,QACb,WAAW,OAAO;AAAA,QAClB,YAAY;AAAA,QACZ,OAAO;AAAA,MACT;AAAA,IACF;AAAA,EACF;AACF;AAEA,IAAO,mBAAQ;",
   "names": []
 }

package/dist/worker.js

@@ -8981,11 +8981,21 @@ async function resolveGithubToken(ctx, companyId) {
   }
 }
 
+// src/github-env.ts
+function getGithubApiBase() {
+  const raw = process.env.GITHUB_API_URL?.trim();
+  return raw ? raw.replace(/\/+$/, "") : "https://api.github.com";
+}
+function getGithubDefaultOwner() {
+  const raw = process.env.GITHUB_DEFAULT_OWNER?.trim();
+  return raw && raw.length > 0 ? raw : null;
+}
+
 // src/github-api.ts
-var GITHUB_API = "https://api.github.com";
 var GITHUB_WEBHOOK_ENDPOINT = "github-events";
 async function githubFetch(ctx, token, path2, init) {
-  const url = path2.startsWith("http") ? path2 : `${GITHUB_API}${path2}`;
+  const apiBase = getGithubApiBase();
+  const url = path2.startsWith("http") ? path2 : `${apiBase}${path2}`;
   return ctx.http.fetch(url, {
     ...init,
     headers: {
@@ -9006,6 +9016,421 @@ function parseRepoFullName(fullName) {
 function buildInboundWebhookUrl(pluginId, baseUrl = "http://127.0.0.1:3100") {
   return `${baseUrl.replace(/\/+$/, "")}/api/plugins/${pluginId}/webhooks/${GITHUB_WEBHOOK_ENDPOINT}`;
 }
+function formatRateLimitMessage(res) {
+  const remaining = res.headers.get("x-ratelimit-remaining");
+  const reset = res.headers.get("x-ratelimit-reset");
+  if (res.status !== 403 || remaining !== "0") {
+    return null;
+  }
+  const resetAt = reset && Number.isFinite(Number(reset)) ? new Date(Number(reset) * 1e3).toISOString() : "unknown";
+  return `GitHub API rate limit exceeded. Retry after ${resetAt}.`;
+}
+async function assertGithubResponse(res, action) {
+  if (res.ok) {
+    return;
+  }
+  const rateLimit = formatRateLimitMessage(res);
+  const body = await res.text().catch(() => "");
+  const detail = body.length > 0 && body.length < 500 ? `: ${body}` : "";
+  throw new Error(rateLimit ?? `GitHub ${action} failed (HTTP ${res.status})${detail}`);
+}
+
+// src/github-review-tools.ts
+var MAX_DIFF_CHARS = 12e4;
+var MAX_FILE_PATCH_CHARS = 32e3;
+function requireString(value, field) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${field} is required`);
+  }
+  return value.trim();
+}
+function requireNumber(value, field) {
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(n) || n < 1) {
+    throw new Error(`${field} must be a positive number`);
+  }
+  return Math.floor(n);
+}
+function resolveOwnerRepo(params) {
+  const owner = requireString(params.owner, "owner");
+  const repo = requireString(params.repo, "repo");
+  return { owner, repo };
+}
+async function resolveTokenForRun(ctx, runCtx) {
+  const companyToken = await resolveGithubToken(ctx, runCtx.companyId);
+  if (companyToken) {
+    return companyToken;
+  }
+  const envToken = process.env.GITHUB_TOKEN?.trim();
+  if (envToken) {
+    return envToken;
+  }
+  throw new Error(
+    "GitHub token not configured \u2014 save a PAT in GitHub \u2192 Configura\xE7\xF5es or set GITHUB_TOKEN"
+  );
+}
+function toolJson(data, summary) {
+  return {
+    content: summary ?? JSON.stringify(data, null, 2),
+    data
+  };
+}
+function truncateDiff(diff) {
+  if (diff.length <= MAX_DIFF_CHARS) {
+    return { diff, truncated: false, originalLength: diff.length };
+  }
+  const head = diff.slice(0, MAX_DIFF_CHARS);
+  const notice = `
+
+\u2026 [diff truncated: ${diff.length} chars total, showing first ${MAX_DIFF_CHARS}] \u2026
+`;
+  return {
+    diff: head + notice,
+    truncated: true,
+    originalLength: diff.length
+  };
+}
+async function fetchPullRequestDiff(ctx, token, { owner, repo }, prNumber) {
+  const metaRes = await githubFetch(
+    ctx,
+    token,
+    `/repos/${owner}/${repo}/pulls/${prNumber}`
+  );
+  await assertGithubResponse(metaRes, "fetch pull request");
+  const pr = await metaRes.json();
+  const diffRes = await githubFetch(
+    ctx,
+    token,
+    `/repos/${owner}/${repo}/pulls/${prNumber}`,
+    { headers: { Accept: "application/vnd.github.diff" } }
+  );
+  await assertGithubResponse(diffRes, "fetch pull request diff");
+  let diffText = await diffRes.text();
+  const { diff, truncated, originalLength } = truncateDiff(diffText);
+  diffText = diff;
+  let files = [];
+  if (truncated) {
+    const filesRes = await githubFetch(
+      ctx,
+      token,
+      `/repos/${owner}/${repo}/pulls/${prNumber}/files?per_page=100`
+    );
+    if (filesRes.ok) {
+      const rows = await filesRes.json();
+      files = rows.map((f) => ({
+        filename: f.filename,
+        status: f.status,
+        additions: f.additions,
+        deletions: f.deletions
+      }));
+    }
+  }
+  const payload = {
+    pullRequest: {
+      number: pr.number,
+      title: pr.title,
+      state: pr.state,
+      htmlUrl: pr.html_url,
+      author: pr.user?.login ?? "unknown",
+      headSha: pr.head?.sha ?? null,
+      headRef: pr.head?.ref ?? null,
+      baseRef: pr.base?.ref ?? null,
+      draft: pr.draft ?? false,
+      mergedAt: pr.merged_at ?? null
+    },
+    diff: diffText,
+    truncated,
+    diffOriginalLength: originalLength,
+    changedFiles: files
+  };
+  return toolJson(
+    payload,
+    truncated ? `PR #${prNumber} "${pr.title}" \u2014 diff truncated (${originalLength} chars)` : `PR #${prNumber} "${pr.title}" \u2014 full diff (${originalLength} chars)`
+  );
+}
+async function createReviewComment(ctx, token, params) {
+  const { owner, repo } = resolveOwnerRepo(params);
+  const prNumber = requireNumber(params.pr_number, "pr_number");
+  const commitId = requireString(params.commit_id, "commit_id");
+  const path2 = requireString(params.path, "path");
+  const line = requireNumber(params.line, "line");
+  const body = requireString(params.body, "body");
+  const res = await githubFetch(
+    ctx,
+    token,
+    `/repos/${owner}/${repo}/pulls/${prNumber}/comments`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        body,
+        commit_id: commitId,
+        path: path2,
+        line,
+        side: "RIGHT"
+      })
+    }
+  );
+  await assertGithubResponse(res, "create review comment");
+  const comment = await res.json();
+  return toolJson(
+    { id: comment.id, htmlUrl: comment.html_url ?? null },
+    `Review comment created on ${path2}:${line}`
+  );
+}
+async function submitPrReview(ctx, token, params) {
+  const { owner, repo } = resolveOwnerRepo(params);
+  const prNumber = requireNumber(params.pr_number, "pr_number");
+  const event = requireString(params.event, "event").toUpperCase();
+  const body = requireString(params.body, "body");
+  if (!["APPROVE", "REQUEST_CHANGES", "COMMENT"].includes(event)) {
+    throw new Error("event must be APPROVE, REQUEST_CHANGES, or COMMENT");
+  }
+  const res = await githubFetch(
+    ctx,
+    token,
+    `/repos/${owner}/${repo}/pulls/${prNumber}/reviews`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ event, body })
+    }
+  );
+  await assertGithubResponse(res, "submit pull request review");
+  const review = await res.json();
+  return toolJson(
+    { id: review.id, state: review.state, htmlUrl: review.html_url ?? null },
+    `Review submitted: ${review.state}`
+  );
+}
+async function readFileContent(ctx, token, params) {
+  const { owner, repo } = resolveOwnerRepo(params);
+  const path2 = requireString(params.path, "path").replace(/^\/+/, "");
+  const ref = typeof params.ref === "string" && params.ref.trim().length > 0 ? params.ref.trim() : void 0;
+  const query = ref ? `?ref=${encodeURIComponent(ref)}` : "";
+  const res = await githubFetch(
+    ctx,
+    token,
+    `/repos/${owner}/${repo}/contents/${path2.split("/").map(encodeURIComponent).join("/")}${query}`
+  );
+  await assertGithubResponse(res, "read file content");
+  const file = await res.json();
+  if (file.type !== "file" || !file.content) {
+    throw new Error(`Path is not a file or is too large for API: ${path2}`);
+  }
+  const decoded = Buffer.from(file.content.replace(/\n/g, ""), "base64").toString("utf8");
+  if (decoded.length > MAX_FILE_PATCH_CHARS * 4) {
+    return toolJson(
+      {
+        path: path2,
+        ref: ref ?? "default",
+        truncated: true,
+        size: file.size ?? decoded.length,
+        content: decoded.slice(0, MAX_FILE_PATCH_CHARS * 4),
+        message: `File content truncated to ${MAX_FILE_PATCH_CHARS * 4} characters`
+      },
+      `File ${path2} (truncated)`
+    );
+  }
+  return toolJson(
+    { path: path2, ref: ref ?? "default", sha: file.sha ?? null, size: file.size ?? decoded.length, content: decoded },
+    `File ${path2} (${decoded.length} chars)`
+  );
+}
+async function listRepositories(ctx, token, params) {
+  const defaultOwner = getGithubDefaultOwner();
+  const owner = typeof params.owner === "string" && params.owner.trim().length > 0 ? params.owner.trim() : defaultOwner;
+  const perPage = Math.min(
+    100,
+    typeof params.per_page === "number" ? params.per_page : Number(params.per_page) || 30
+  );
+  let path2;
+  if (owner) {
+    const orgProbe = await githubFetch(ctx, token, `/orgs/${owner}`);
+    path2 = orgProbe.ok ? `/orgs/${owner}/repos?per_page=${perPage}&sort=updated` : `/users/${owner}/repos?per_page=${perPage}&sort=updated`;
+  } else {
+    path2 = `/user/repos?per_page=${perPage}&sort=updated&affiliation=owner,organization_member`;
+  }
+  const res = await githubFetch(ctx, token, path2);
+  await assertGithubResponse(res, "list repositories");
+  const rows = await res.json();
+  const repos = rows.map((r) => ({
+    id: r.id,
+    fullName: r.full_name,
+    private: r.private,
+    htmlUrl: r.html_url,
+    defaultBranch: r.default_branch,
+    updatedAt: r.updated_at
+  }));
+  return toolJson({ owner: owner ?? null, count: repos.length, repos });
+}
+async function searchIssues(ctx, token, params) {
+  const query = requireString(params.q ?? params.query, "q");
+  const perPage = Math.min(
+    100,
+    typeof params.per_page === "number" ? params.per_page : Number(params.per_page) || 20
+  );
+  const res = await githubFetch(
+    ctx,
+    token,
+    `/search/issues?q=${encodeURIComponent(query)}&per_page=${perPage}`
+  );
+  await assertGithubResponse(res, "search issues");
+  const body = await res.json();
+  const issues = body.items.map((item) => {
+    const repoMatch = item.repository_url.match(/repos\/([^/]+)\/([^/]+)$/);
+    const repoFullName = repoMatch && repoMatch[1] && repoMatch[2] ? `${repoMatch[1]}/${repoMatch[2]}` : null;
+    return {
+      id: item.id,
+      number: item.number,
+      title: item.title,
+      state: item.state,
+      htmlUrl: item.html_url,
+      repoFullName,
+      updatedAt: item.updated_at
+    };
+  });
+  return toolJson({
+    totalCount: body.total_count,
+    incompleteResults: body.incomplete_results ?? false,
+    count: issues.length,
+    issues
+  });
+}
+var ownerRepoSchema = {
+  type: "object",
+  properties: {
+    owner: { type: "string", description: "Repository owner (user or org)" },
+    repo: { type: "string", description: "Repository name" }
+  },
+  required: ["owner", "repo"]
+};
+function registerGithubReviewTools(ctx) {
+  const wrap = (name, declaration, handler) => {
+    ctx.tools.register(name, declaration, async (params, runCtx) => {
+      try {
+        const token = await resolveTokenForRun(ctx, runCtx);
+        return await handler(ctx, token, params ?? {});
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { error: message, content: message };
+      }
+    });
+  };
+  wrap(
+    "github_get_pull_request_diff",
+    {
+      displayName: "Get PR diff",
+      description: "Returns pull request metadata and unified diff. Large diffs are truncated with a file list.",
+      parametersSchema: {
+        ...ownerRepoSchema,
+        properties: {
+          ...ownerRepoSchema.properties,
+          pr_number: { type: "integer", description: "Pull request number" }
+        },
+        required: ["owner", "repo", "pr_number"]
+      }
+    },
+    async (ctx2, token, params) => {
+      const { owner, repo } = resolveOwnerRepo(params);
+      const prNumber = requireNumber(params.pr_number, "pr_number");
+      return fetchPullRequestDiff(ctx2, token, { owner, repo }, prNumber);
+    }
+  );
+  wrap(
+    "github_create_review_comment",
+    {
+      displayName: "Create PR review comment",
+      description: "Adds an inline review comment on a specific line in a pull request diff.",
+      parametersSchema: {
+        ...ownerRepoSchema,
+        properties: {
+          ...ownerRepoSchema.properties,
+          pr_number: { type: "integer" },
+          commit_id: { type: "string", description: "Head commit SHA" },
+          path: { type: "string", description: "File path in the repo" },
+          line: { type: "integer", description: "Line number in the modified file" },
+          body: { type: "string", description: "Comment text" }
+        },
+        required: ["owner", "repo", "pr_number", "commit_id", "path", "line", "body"]
+      }
+    },
+    async (ctx2, token, params) => createReviewComment(ctx2, token, params)
+  );
+  wrap(
+    "github_submit_pr_review",
+    {
+      displayName: "Submit PR review",
+      description: "Submits a pull request review with APPROVE, REQUEST_CHANGES, or COMMENT.",
+      parametersSchema: {
+        ...ownerRepoSchema,
+        properties: {
+          ...ownerRepoSchema.properties,
+          pr_number: { type: "integer" },
+          event: {
+            type: "string",
+            enum: ["APPROVE", "REQUEST_CHANGES", "COMMENT"],
+            description: "Review verdict"
+          },
+          body: { type: "string", description: "Summary comment for the review" }
+        },
+        required: ["owner", "repo", "pr_number", "event", "body"]
+      }
+    },
+    async (ctx2, token, params) => submitPrReview(ctx2, token, params)
+  );
+  wrap(
+    "github_read_file_content",
+    {
+      displayName: "Read repository file",
+      description: "Reads full file content from a repository at an optional ref (branch or SHA).",
+      parametersSchema: {
+        ...ownerRepoSchema,
+        properties: {
+          ...ownerRepoSchema.properties,
+          path: { type: "string", description: "Path to the file" },
+          ref: { type: "string", description: "Branch name or commit SHA (optional)" }
+        },
+        required: ["owner", "repo", "path"]
+      }
+    },
+    async (ctx2, token, params) => readFileContent(ctx2, token, params)
+  );
+  wrap(
+    "github_list_repositories",
+    {
+      displayName: "List GitHub repositories",
+      description: "Lists repositories for an owner/org, or the authenticated user when owner is omitted.",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          owner: {
+            type: "string",
+            description: "Org or user (defaults to GITHUB_DEFAULT_OWNER or authenticated user)"
+          },
+          per_page: { type: "integer", description: "Page size (max 100)" }
+        }
+      }
+    },
+    async (ctx2, token, params) => listRepositories(ctx2, token, params)
+  );
+  wrap(
+    "github_search_issues",
+    {
+      displayName: "Search GitHub issues",
+      description: "Searches issues using GitHub issue search syntax (q parameter).",
+      parametersSchema: {
+        type: "object",
+        properties: {
+          q: { type: "string", description: "GitHub search query" },
+          per_page: { type: "integer", description: "Results per page (max 100)" }
+        },
+        required: ["q"]
+      }
+    },
+    async (ctx2, token, params) => searchIssues(ctx2, token, params)
+  );
+}
 
 // src/worker.ts
 var SYNC_STATE_KEY = "github.sync.cache";
@@ -9276,6 +9701,7 @@ async function handleGithubWebhook(input) {
 var plugin = definePlugin({
   async setup(ctx) {
     workerCtx = ctx;
+    registerGithubReviewTools(ctx);
     ctx.events.on("issue.created", async (event) => {
       const issueId = event.entityId ?? "unknown";
       await ctx.state.set({ scopeKind: "issue", scopeId: issueId, stateKey: "seen" }, true);