@bli-cockpit/mcp 0.1.80 → 0.1.82

package/README.md

@@ -103,7 +103,7 @@ about what an agent can reach.
 
 <!-- BEGIN GENERATED verb census — `npm run mcp:readme` -->
 
-**119 of 124 Tower verbs have an MCP twin.**
+**123 of 128 Tower verbs have an MCP twin.**
 Each tool goes through the SAME door its CLI verb calls, with the same
 collector device token — never a second route and never a service-role
 reader. `src/verb-census.test.ts` fails when a verb is in none of the
@@ -150,6 +150,10 @@ three tables below.
 | `cockpit docs sync-status` | `docs_sync_status` | `GET /api/docs/notion-sync` |
 | `cockpit docs tree` | `docs_tree` | `GET /api/docs/tree` |
 | `cockpit docs update` | `docs_update` | `PATCH /api/docs/documents/[id]` |
+| `cockpit github merge` | `github_merge` | `POST /api/github/pull-request (merge)` |
+| `cockpit github pr` | `github_pr` | `POST /api/github/pull-request (read)` |
+| `cockpit github rerun` | `github_rerun` | `POST /api/github/pull-request (rerun)` |
+| `cockpit github retitle` | `github_retitle` | `POST /api/github/pull-request (retitle)` |
 | `cockpit issue comment` | `work_comment_issue` | `POST /api/work/issues/[id]/comments` |
 | `cockpit issue create` | `work_create_issue` | `POST /api/work/issues` |
 | `cockpit issue history` | `work_issue_history` | `GET /api/work/issues/[id]/history` |

package/dist/github-tools.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `github_pr` / `github_merge` / `github_retitle` / `github_rerun` (BLI-12385):
+ * the MCP twins of `cockpit github pr|merge|retitle|rerun`, over the same door
+ * (`POST /api/github/pull-request`) with the same device token.
+ *
+ * The door runs JARVIS's own GitHub implementations, so the lock is the same:
+ * the caller's OWN GitHub login (on the roster) must hold write, maintain or
+ * admin on the repo, and a change is TWO STEPS. The first call (no `confirm`)
+ * changes nothing and returns what would happen plus an eight-character code;
+ * the second carries `confirm`. The code is signed to the caller, repo, pull
+ * request and exact change. An agent must pass a code only after the PERSON has
+ * sent it back: whether to merge is theirs, and the descriptions say so.
+ * A refusal keeps the door's reason label and sentence verbatim.
+ */
+import { type ToolDeps } from "./tool-result.js";
+export declare function registerGithubTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: ToolDeps): void;

package/dist/github-tools.js

@@ -0,0 +1,116 @@
+/**
+ * `github_pr` / `github_merge` / `github_retitle` / `github_rerun` (BLI-12385):
+ * the MCP twins of `cockpit github pr|merge|retitle|rerun`, over the same door
+ * (`POST /api/github/pull-request`) with the same device token.
+ *
+ * The door runs JARVIS's own GitHub implementations, so the lock is the same:
+ * the caller's OWN GitHub login (on the roster) must hold write, maintain or
+ * admin on the repo, and a change is TWO STEPS. The first call (no `confirm`)
+ * changes nothing and returns what would happen plus an eight-character code;
+ * the second carries `confirm`. The code is signed to the caller, repo, pull
+ * request and exact change. An agent must pass a code only after the PERSON has
+ * sent it back: whether to merge is theirs, and the descriptions say so.
+ * A refusal keeps the door's reason label and sentence verbatim.
+ */
+import { z } from "zod";
+import { callAgentDoor } from "./agent-door.js";
+import { dataResult, doorFailureText, errorResult, registrarFor, textResult, withSession, } from "./tool-result.js";
+const PATH = "/api/github/pull-request";
+const TWO_STEPS = "TWO STEPS: call it WITHOUT confirm first. That changes nothing and returns what would happen plus an "
+    + "eight-character confirmation code; show the person exactly that and ask them to send the code back. Only then "
+    + "call again with the SAME arguments plus confirm set to the code THE PERSON gave you. Never invent a code, "
+    + "never reuse one the person did not send, and never change the arguments between the two calls (the code is "
+    + "signed to the exact change). It runs only if the person's OWN GitHub login has write, maintain or admin on the "
+    + "repo; otherwise it refuses with github_login_unknown or github_permission_insufficient: relay that as written. "
+    + "Only BLI-INC repositories.";
+const repoField = z.string().min(1).max(100).describe("`owner/repo` or a bare repo name in BLI-INC, e.g. bli-cockpit.");
+const numberField = z.number().int().min(1).describe("The pull request number.");
+const confirmField = z
+    .string()
+    .min(1)
+    .max(64)
+    .optional()
+    .describe("The code the preview returned, which the PERSON sent back. Omit on the first call.");
+export function registerGithubTools(server, deps) {
+    const register = registrarFor(server);
+    async function press(tool, session, body) {
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", PATH, body);
+        if (!response.ok)
+            return errorResult(doorFailureText(tool, response));
+        const result = (response.body["result"] ?? {});
+        if (result["status"] === "needs_confirmation") {
+            return textResult(`Nothing has been changed. Would ${String(result["preview"] ?? "make this change")} `
+                + `To go ahead, the person must send back the code ${String(result["confirmationCode"] ?? "")}; `
+                + `then call ${tool} again with the same arguments and confirm set to that code.`, result);
+        }
+        if (result["status"] === "done")
+            return textResult(String(result["sayThis"] ?? "Done."), result);
+        return dataResult("GitHub pull request", result);
+    }
+    register("github_pr", {
+        title: "Read one pull request from GitHub",
+        description: "GitHub's own live record of ONE pull request in BLI-INC: merged (and by whom), open/closed, draft, mergeable, "
+            + "title and CI. GitHub is the source of truth: when somebody asserts a state, read it here. Pass `claim` "
+            + "(merged, open, closed, ci_green or mergeable) to get GitHub's verdict on that assertion with the correction "
+            + "sentence. `cockpit github pr`, same door.",
+        inputSchema: {
+            repo: repoField,
+            pull_number: numberField,
+            claim: z.enum(["merged", "open", "closed", "ci_green", "mergeable"]).optional().describe("The state somebody asserted."),
+        },
+    }, async (args) => withSession(deps, (session) => press("github_pr", session, {
+        action: "read",
+        repo: String(args.repo),
+        pullNumber: args.pull_number,
+        ...(args.claim ? { claim: args.claim } : {}),
+    })));
+    register("github_merge", {
+        title: "Merge a pull request (two steps, caller's own GitHub access)",
+        description: `Merge ONE pull request in BLI-INC, squash by default. \`cockpit github merge\`, same door. ${TWO_STEPS}`,
+        inputSchema: {
+            repo: repoField,
+            pull_number: numberField,
+            method: z.enum(["squash", "merge", "rebase"]).optional().describe("Defaults to squash."),
+            confirm: confirmField,
+        },
+    }, async (args) => withSession(deps, (session) => press("github_merge", session, {
+        action: "merge",
+        repo: String(args.repo),
+        pullNumber: args.pull_number,
+        ...(args.method ? { method: args.method } : {}),
+        ...(args.confirm ? { confirm: String(args.confirm) } : {}),
+    })));
+    register("github_retitle", {
+        title: "Retitle a pull request (two steps, caller's own GitHub access)",
+        description: `Change the title of ONE pull request in BLI-INC. \`cockpit github retitle\`, same door. ${TWO_STEPS}`,
+        inputSchema: {
+            repo: repoField,
+            pull_number: numberField,
+            title: z.string().min(1).max(256).describe("The new title."),
+            confirm: confirmField,
+        },
+    }, async (args) => withSession(deps, (session) => press("github_retitle", session, {
+        action: "retitle",
+        repo: String(args.repo),
+        pullNumber: args.pull_number,
+        title: String(args.title),
+        ...(args.confirm ? { confirm: String(args.confirm) } : {}),
+    })));
+    register("github_rerun", {
+        title: "Re-run failed workflow jobs (two steps, caller's own GitHub access)",
+        description: "Re-run the FAILED jobs of workflow runs in BLI-INC: pass pull_number for every failed workflow on that pull "
+            + `request's head commit, or run_id for one run (exactly one). \`cockpit github rerun\`, same door. ${TWO_STEPS}`,
+        inputSchema: {
+            repo: repoField,
+            pull_number: numberField.optional(),
+            run_id: z.number().int().min(1).optional().describe("One workflow run, instead of pull_number."),
+            confirm: confirmField,
+        },
+    }, async (args) => withSession(deps, (session) => press("github_rerun", session, {
+        action: "rerun",
+        repo: String(args.repo),
+        ...(args.pull_number ? { pullNumber: args.pull_number } : {}),
+        ...(args.run_id ? { runId: args.run_id } : {}),
+        ...(args.confirm ? { confirm: String(args.confirm) } : {}),
+    })));
+}

package/dist/ops-tools.js

@@ -286,8 +286,15 @@ export function registerOpsTools(server, deps) {
         // anything" — and the messages/note print exactly once, not twice.
         const rawSummary = typeof read["summary"] === "string" ? read["summary"] : `${messages.length} message(s).`;
         const summary = rawSummary.split("\n")[0] ?? rawSummary;
-        const note = typeof read["note"] === "string" && read["note"] ? `\n\n${read["note"]}` : "";
-        return textResult(`${summary}${lines ? `\n\n${lines}` : ""}${note}`, {
+        // BLI-12381: a refusal's summary IS its note; print it once.
+        const noteText = typeof read["note"] === "string" && read["note"] && read["note"] !== summary ? read["note"] : null;
+        const note = noteText ? `\n\n${noteText}` : "";
+        // BLI-12381: an unknown, uncovered or empty read leads with its reason
+        // label, so a zero never reads as "nobody said anything".
+        const label = typeof read["status"] === "string" && (read["status"] !== "ok" || messages.length === 0)
+            ? `[slack_read status=${read["status"]} reason=${String(read["reason"] ?? "?")}] `
+            : "";
+        return textResult(`${label}${summary}${lines ? `\n\n${lines}` : ""}${note}`, {
             status: read["status"] ?? null,
             reason: read["reason"] ?? null,
             messages,

package/dist/server.js

@@ -23,6 +23,7 @@ import { registerMemoryExperienceTools } from "./memory-experience-tools.js";
 import { registerMemoryProfileTools } from "./memory-profile-tools.js";
 import { registerMemoryRequeueTools } from "./memory-requeue-tools.js";
 import { registerModelsTools } from "./models-tools.js";
+import { registerGithubTools } from "./github-tools.js";
 import { registerOpsTools } from "./ops-tools.js";
 import { registerPagesTools } from "./pages-tools.js";
 import { registerSearchTool } from "./search-tool.js";
@@ -429,6 +430,8 @@ export function createServer(deps) {
     // BLI-12378: the twins of `cockpit rename list|resolve`, the human's call on
     // whether a correction becomes a rule.
     registerRenameTools(server, deps);
+    // BLI-12385: GitHub PR read, and merge / retitle / re-run behind the two-step code.
+    registerGithubTools(server, deps);
     registerUsageTools(server, { fetchImpl: deps.fetchImpl });
     // BLI-3708: the mailboxes a person attached. Reads, a send and a sync over
     // the same /api/mail/** doors `cockpit mail` calls; `add-imap` deliberately

package/dist/tool-catalog.d.ts

@@ -10,7 +10,7 @@
  * from `src/` under Node's type stripping, so it may import nothing.
  */
 /** Tools that change nothing. The smoke calls every one. */
-export declare const READ_TOOLS: readonly ["get_ticket_timeline", "get_active_tickets", "docs_list", "docs_tree", "docs_read", "docs_sync_status", "msg_channels", "msg_read", "msg_thread", "work_list_issues", "work_get_issue", "work_issue_history", "work_list_projects", "careers_list", "careers_show", "careers_resume_url", "careers_takehome_show", "careers_settings_show", "rename_pending", "usage_people", "usage_sessions", "mail_accounts", "mail_inbox", "mail_read", "mail_search", "mail_attachment", "mail_sync_status", "cal_today", "cal_week", "cal_next", "cal_find", "cal_calendars", "cal_sync_status", "jarvis_ask", "jarvis_trace", "jarvis_check", "models_list", "models_card", "models_compare", "brief_read", "brief_history", "brief_status", "brief_missed", "notes_folders", "notes_list", "notes_show", "notes_shelf", "notes_shelves", "notes_place", "notes_accounts", "notes_sync_status", "notes_granola_status", "ops_status", "slack_coverage", "slack_read", "memory_profile", "memory_consolidation", "settings_show", "settings_list", "model_show", "team_members", "team_device_list", "scout_board", "workbook_read", "tower_search", "sources_check"];
+export declare const READ_TOOLS: readonly ["get_ticket_timeline", "get_active_tickets", "docs_list", "docs_tree", "docs_read", "docs_sync_status", "msg_channels", "msg_read", "msg_thread", "work_list_issues", "work_get_issue", "work_issue_history", "work_list_projects", "careers_list", "careers_show", "careers_resume_url", "careers_takehome_show", "careers_settings_show", "rename_pending", "github_pr", "usage_people", "usage_sessions", "mail_accounts", "mail_inbox", "mail_read", "mail_search", "mail_attachment", "mail_sync_status", "cal_today", "cal_week", "cal_next", "cal_find", "cal_calendars", "cal_sync_status", "jarvis_ask", "jarvis_trace", "jarvis_check", "models_list", "models_card", "models_compare", "brief_read", "brief_history", "brief_status", "brief_missed", "notes_folders", "notes_list", "notes_show", "notes_shelf", "notes_shelves", "notes_place", "notes_accounts", "notes_sync_status", "notes_granola_status", "ops_status", "slack_coverage", "slack_read", "memory_profile", "memory_consolidation", "settings_show", "settings_list", "model_show", "team_members", "team_device_list", "scout_board", "workbook_read", "tower_search", "sources_check"];
 /**
  * Tools that write, but answer a dry run that writes nothing. The smoke calls
  * each one ONLY with its dry-run flag set (`scripts/smoke.ts` says which).
@@ -21,7 +21,7 @@ export declare const DRY_RUN_TOOLS: readonly ["ops_recompile", "memory_requeue"]
  * candidates, share calendars. Never called by the smoke; covered by the unit
  * suites (`write-tools.test.ts` and each family's own).
  */
-export declare const WRITE_TOOLS: readonly ["emit_event", "docs_create", "docs_update", "docs_delete", "docs_link", "msg_create_channel", "msg_dm", "msg_send", "work_create_issue", "work_update_issue", "work_move_issue", "work_comment_issue", "careers_rescreen", "careers_send_takehome", "careers_invite", "careers_grade", "careers_decide", "careers_followup", "careers_interview", "careers_takehome_set", "careers_settings_set", "rename_resolve", "mail_send", "mail_sync", "mail_detach", "cal_create", "cal_share", "cal_sync", "cal_detach", "cal_delete", "jarvis_dispatch", "notes_mkdir", "notes_rmdir", "notes_rename", "notes_upload", "notes_paste", "notes_share", "notes_unshare", "notes_move", "notes_sync", "notes_detach", "memory_experience", "scout_start", "scout_dismiss", "scout_undo", "brief_rewrite", "brief_correct", "brief_done", "brief_undone", "settings_set", "settings_delete", "model_set", "team_invite", "team_role", "team_device_revoke"];
+export declare const WRITE_TOOLS: readonly ["emit_event", "docs_create", "docs_update", "docs_delete", "docs_link", "msg_create_channel", "msg_dm", "msg_send", "work_create_issue", "work_update_issue", "work_move_issue", "work_comment_issue", "careers_rescreen", "careers_send_takehome", "careers_invite", "careers_grade", "careers_decide", "careers_followup", "careers_interview", "careers_takehome_set", "careers_settings_set", "rename_resolve", "github_merge", "github_retitle", "github_rerun", "mail_send", "mail_sync", "mail_detach", "cal_create", "cal_share", "cal_sync", "cal_detach", "cal_delete", "jarvis_dispatch", "notes_mkdir", "notes_rmdir", "notes_rename", "notes_upload", "notes_paste", "notes_share", "notes_unshare", "notes_move", "notes_sync", "notes_detach", "memory_experience", "scout_start", "scout_dismiss", "scout_undo", "brief_rewrite", "brief_correct", "brief_done", "brief_undone", "settings_set", "settings_delete", "model_set", "team_invite", "team_role", "team_device_revoke"];
 /** Reads that spend a model turn. The smoke's `--no-model` leaves these out. */
 export declare const MODEL_SPENDING_TOOLS: readonly ["jarvis_ask", "jarvis_check"];
 /**

package/dist/tool-catalog.js

@@ -30,6 +30,7 @@ export const READ_TOOLS = [
     "careers_takehome_show",
     "careers_settings_show",
     "rename_pending",
+    "github_pr",
     "usage_people",
     "usage_sessions",
     "mail_accounts",
@@ -111,6 +112,9 @@ export const WRITE_TOOLS = [
     "careers_takehome_set",
     "careers_settings_set",
     "rename_resolve",
+    "github_merge",
+    "github_retitle",
+    "github_rerun",
     "mail_send",
     "mail_sync",
     "mail_detach",

package/dist/verb-census.js

@@ -234,6 +234,11 @@ export const MCP_TWINS = {
     // BLI-12378: the human's call on whether a correction becomes a rule.
     "rename list": { tool: "rename_pending", door: "GET /api/jarvis/rename-scope" },
     "rename resolve": { tool: "rename_resolve", door: "POST /api/jarvis/rename-scope" },
+    // BLI-12385: GitHub PR read and the two-step merge / retitle / re-run.
+    "github pr": { tool: "github_pr", door: "POST /api/github/pull-request (read)" },
+    "github merge": { tool: "github_merge", door: "POST /api/github/pull-request (merge)" },
+    "github retitle": { tool: "github_retitle", door: "POST /api/github/pull-request (retitle)" },
+    "github rerun": { tool: "github_rerun", door: "POST /api/github/pull-request (rerun)" },
     "usage sessions": { tool: "usage_sessions", door: "GET /api/usage/sessions" },
     "usage people": { tool: "usage_people", door: "GET /api/usage/people" },
     "docs list": { tool: "docs_list", door: "GET /api/docs/documents" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.80",
+  "version": "0.1.82",
   "private": false,
   "description": "bli-tower: an MCP server over BLI Cockpit's agent doors: JARVIS (jarvis_*), documents (docs_*), channels (msg_*), issues (work_*), the daily page (brief_*), meeting notes (notes_*), the ops board (ops_status/slack_*), settings/team/model, Scout and the workbook, plus the legacy event-stream tools (emit_event, get_ticket_timeline, get_active_tickets).",
   "type": "module",