@bli-cockpit/mcp 0.1.83 → 0.1.85

package/README.md

@@ -109,7 +109,7 @@ about what an agent can reach.
 
 <!-- BEGIN GENERATED verb census — `npm run mcp:readme` -->
 
-**123 of 128 Tower verbs have an MCP twin.**
+**124 of 129 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
@@ -172,6 +172,7 @@ three tables below.
 | `cockpit mail accounts` | `mail_accounts` | `GET /api/mail/accounts` |
 | `cockpit mail attachment` | `mail_attachment` | `GET /api/mail/attachments/[id]?meta=1` |
 | `cockpit mail detach` | `mail_detach` | `DELETE /api/mail/accounts` |
+| `cockpit mail draft` | `mail_draft` | `POST /api/mail/drafts` |
 | `cockpit mail inbox` | `mail_inbox` | `GET /api/mail/inbox` |
 | `cockpit mail read` | `mail_read` | `GET /api/mail/threads/[id]` |
 | `cockpit mail search` | `mail_search` | `GET /api/mail/search` |

package/dist/mail-tools.d.ts

@@ -6,7 +6,9 @@
  * The point, in one sentence: an agent working on somebody's behalf should be
  * able to READ the mail that explains a ticket — the invoice, the vendor's
  * reply, the bank notice — and send a reply, without a browser and without a
- * second copy of anybody's credentials.
+ * second copy of anybody's credentials. Or, when the person should be the one
+ * to press send, save the reply as a DRAFT in their own mailbox (`mail_draft`,
+ * BLI-12530): it reaches nobody, so unlike `mail_send` it needs no `confirm`.
  *
  * TWO DELIBERATE ASYMMETRIES with the CLI, both recorded in `verb-census.ts`:
  *

package/dist/mail-tools.js

@@ -6,7 +6,9 @@
  * The point, in one sentence: an agent working on somebody's behalf should be
  * able to READ the mail that explains a ticket — the invoice, the vendor's
  * reply, the bank notice — and send a reply, without a browser and without a
- * second copy of anybody's credentials.
+ * second copy of anybody's credentials. Or, when the person should be the one
+ * to press send, save the reply as a DRAFT in their own mailbox (`mail_draft`,
+ * BLI-12530): it reaches nobody, so unlike `mail_send` it needs no `confirm`.
  *
  * TWO DELIBERATE ASYMMETRIES with the CLI, both recorded in `verb-census.ts`:
  *
@@ -32,6 +34,23 @@ function messageLine(message) {
     return `${message.is_unread ? "*" : " "} ${message.internal_date.slice(0, 16)}  ${from}  ${message.subject ?? "(no subject)"}  [thread ${message.thread_id ?? "?"}]`;
 }
 const ADDRESS = EMAIL_INPUT.describe("An email address.");
+/**
+ * The JSON `mail_send` and `mail_draft` post. One shape, because the two doors
+ * take the same fields: a message that can be sent can be saved unsent, and a
+ * field added to one cannot be forgotten by the other.
+ */
+function composedBody(args) {
+    return {
+        account_id: args.account_id,
+        to: args.to.map((address) => ({ address })),
+        ...(Array.isArray(args.cc) && args.cc.length > 0
+            ? { cc: args.cc.map((address) => ({ address })) }
+            : {}),
+        subject: args.subject ?? "",
+        text: args.text,
+        ...(args.in_reply_to_message_id ? { in_reply_to_message_id: args.in_reply_to_message_id } : {}),
+    };
+}
 export function registerMailTools(server, deps) {
     const register = registrarFor(server);
     register("mail_accounts", {
@@ -186,21 +205,42 @@ export function registerMailTools(server, deps) {
         const refusal = unconfirmed(args, "Sending mail reaches real people and cannot be recalled.");
         if (refusal)
             return refusal;
-        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/mail/send", {
-            account_id: args.account_id,
-            to: args.to.map((address) => ({ address })),
-            ...(Array.isArray(args.cc) && args.cc.length > 0
-                ? { cc: args.cc.map((address) => ({ address })) }
-                : {}),
-            subject: args.subject ?? "",
-            text: args.text,
-            ...(args.in_reply_to_message_id ? { in_reply_to_message_id: args.in_reply_to_message_id } : {}),
-        });
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/mail/send", composedBody(args));
         if (!response.ok)
             return errorResult(doorFailureText("mail_send", response));
         const sent = response.body.sent;
         return textResult(`Sent from ${sent?.address ?? "that mailbox"} to ${args.to.join(", ")}${sent?.threaded ? " (as a reply)" : ""}.`, { sent });
     }));
+    register("mail_draft", {
+        title: "Save a draft in one mailbox",
+        description: "Saves a message as a DRAFT in one of YOUR mailboxes, for a person to read, edit and send themselves. Use it "
+            + "when you are preparing mail on somebody's behalf and they should be the one to press send. NOTHING IS SENT and "
+            + "nobody is notified, so unlike mail_send there is no confirm flag. `account_id` is REQUIRED and is the mailbox the "
+            + "draft is saved in (mail_accounts) — with several attached, that is never something to guess. "
+            + "`in_reply_to_message_id` (a message id from mail_read) threads the draft into that conversation the way mail_send "
+            + "threads a reply; Gmail files it there only when the subject matches the original's, and the answer says whether it "
+            + "did (`threaded`). Only the mailbox's OWNER can draft into it, and only Gmail mailboxes can take one: an IMAP "
+            + "mailbox is refused as imap_drafts_unsupported. Answers the provider draft id, the thread id and the account id.",
+        inputSchema: {
+            account_id: z.string().uuid().describe("The mailbox the draft is saved in (mail_accounts). Never guessed."),
+            to: z.array(ADDRESS).min(1).max(50).describe("Recipient email addresses, so the draft is ready to send as it is."),
+            cc: z.array(ADDRESS).max(50).optional().describe("Copied email addresses."),
+            subject: z.string().max(998).describe("The subject line. For a reply, keep the original's subject or Gmail will not thread it."),
+            text: z.string().min(1).max(500_000).describe("The plain-text body."),
+            in_reply_to_message_id: z.string().uuid().optional().describe("A message id from mail_read: save this as a reply in that thread."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/mail/drafts", composedBody(args));
+        if (!response.ok)
+            return errorResult(doorFailureText("mail_draft", response));
+        const draft = response.body.draft;
+        // Both halves carry the ids (BLI-10432): a client that hands the model only
+        // `content`, or only `structuredContent`, must still learn where the draft is.
+        return textResult(`Saved a draft in ${draft?.address ?? "that mailbox"} for ${args.to.join(", ")}`
+            + `${draft?.threaded ? " (in the reply's thread)" : args.in_reply_to_message_id ? " (Gmail did NOT file it in that thread: its subject has to match the original's)" : ""}. `
+            + "Nothing was sent: it waits in Drafts for a person to read, edit and send. "
+            + `draft_id=${draft?.provider_draft_id ?? "(none returned)"} thread_id=${draft?.provider_thread_id ?? "(none)"} account_id=${draft?.account_id ?? String(args.account_id)}`, { draft });
+    }));
     register("mail_attachment", {
         title: "Describe an attachment",
         description: "The filename, mime type and size of one attachment. Attachments are POINTERS in Tower — nothing is stored — and "

package/dist/tool-catalog.d.ts

@@ -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", "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"];
+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_draft", "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

@@ -116,6 +116,8 @@ export const WRITE_TOOLS = [
     "github_retitle",
     "github_rerun",
     "mail_send",
+    // BLI-12530: writes into a mailbox (a draft), reaches nobody. Never smoked.
+    "mail_draft",
     "mail_sync",
     "mail_detach",
     "cal_create",

package/dist/usage-tools.d.ts

@@ -1,4 +1,39 @@
 import { type ToolDeps } from "./tool-result.js";
+/**
+ * BLI-12561: the sentences about the GitHub counts, worded exactly as the /usage
+ * page and `cockpit usage people` word them (`apps/dashboard/src/lib/usage/
+ * usage-github-words.ts` is the original; every copy has the same cases). This
+ * package does not import the dashboard, so the words are carried here.
+ */
+interface GithubCounts {
+    match: string;
+    pull_requests_opened: number | null;
+    pull_requests_merged: number | null;
+    commits: number | null;
+}
+interface GithubBlock {
+    status: "ok" | "unavailable";
+    reason?: string;
+    detail?: string;
+    counts_label?: string;
+    repositories?: unknown[];
+    oldest_pull_request_at?: string | null;
+    newest_pull_request_at?: string | null;
+    unattributed?: {
+        pull_requests_opened: number;
+        pull_requests_merged: number;
+        commits: number;
+    };
+}
+export declare function githubWords(github: GithubBlock, people: readonly {
+    github?: GithubCounts;
+}[]): {
+    lines: string[];
+    label: string;
+};
+/** The sentence appended to the text half, or the line that says a dashboard sent no GitHub block. */
+export declare function githubSentence(body: Record<string, unknown>): string;
 export declare function registerUsageTools(server: {
     registerTool: (...args: never[]) => unknown;
 }, deps: ToolDeps): void;
+export {};

package/dist/usage-tools.js

@@ -6,10 +6,43 @@ import { dataResult, doorFailureText, errorResult, registrarFor, withSession } f
 // half alone) could say how many sessions were counted and never whose they
 // were or what they cost (BLI-10432).
 const WINDOW_BOUND = "<n>d (1 to 365), <n>h (1 to 8760), or an ISO timestamp";
+const noun = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+const PLACED = new Set(["github_login", "counted_on_other_account"]);
+export function githubWords(github, people) {
+    const label = github.counts_label ?? "";
+    if (github.status === "unavailable") {
+        return { lines: [`GitHub counts are unavailable: ${github.reason ?? "unknown_reason"}${github.detail ? ` (${github.detail})` : ""}.`], label };
+    }
+    const sum = (field) => people.reduce((total, person) => total + (person.github?.[field] ?? 0), 0);
+    const range = github.oldest_pull_request_at && github.newest_pull_request_at
+        ? `; mirrored pull requests run from ${github.oldest_pull_request_at} to ${github.newest_pull_request_at}`
+        : "; the mirror holds no pull requests";
+    const lines = [
+        `GitHub: ${noun(sum("pull_requests_opened"), "pull request")} opened, ${sum("pull_requests_merged")} merged, ${noun(sum("commits"), "commit")}, ` +
+            `from ${noun((github.repositories ?? []).length, "mirrored repository", "mirrored repositories")}${range}.`,
+    ];
+    const unmatched = github.unattributed;
+    if (unmatched && unmatched.pull_requests_opened + unmatched.pull_requests_merged + unmatched.commits > 0) {
+        lines.push(`Not matched to a person: ${noun(unmatched.pull_requests_opened, "pull request")} opened, ${unmatched.pull_requests_merged} merged, ${noun(unmatched.commits, "commit")}.`);
+    }
+    const unplaced = people.filter((person) => person.github && !PLACED.has(person.github.match)).length;
+    if (unplaced > 0)
+        lines.push(`${noun(unplaced, "person cannot", "people cannot")} be matched to a GitHub login, so their GitHub counts are unknown, not zero.`);
+    return { lines, label };
+}
+/** The sentence appended to the text half, or the line that says a dashboard sent no GitHub block. */
+export function githubSentence(body) {
+    const github = body.github;
+    if (github === undefined)
+        return " GitHub counts: this dashboard sent none (it predates them).";
+    const people = Array.isArray(body.people) ? body.people : [];
+    const words = githubWords(github, people);
+    return ` ${[...words.lines, words.label].filter(Boolean).join(" ")}`;
+}
 export function registerUsageTools(server, deps) {
     registrarFor(server)("usage_people", {
         title: "Read usage by person",
-        description: "Per-person Claude Code and Codex token usage, list-price equivalent (not actual spend), and extraction coverage, over a window (default the last 30 days). groupBy adds a per-person breakdown; groupBy topic or ticket lists the labels usage_sessions takes as subject or task.",
+        description: "Per-person Claude Code and Codex token usage, list-price equivalent (not actual spend), and extraction coverage, over a window (default the last 30 days). Each person also carries GitHub pull requests opened, pull requests merged and commits from the pull requests Tower mirrors from GitHub (null means Tower cannot match that person to a GitHub login: unknown, not zero); the github block says which repositories the mirror holds and what matched nobody. groupBy adds a per-person breakdown; groupBy topic or ticket lists the labels usage_sessions takes as subject or task.",
         inputSchema: {
             minConfidence: z.enum(["high", "medium", "low"]).optional().describe("With groupBy task_type or topic: only labels at or above this confidence."),
             groupBy: z.enum(["repo", "task_type", "topic", "ticket"]).optional().describe("Break each person's usage down by repo, task type, topic or ticket."),
@@ -43,7 +76,11 @@ export function registerUsageTools(server, deps) {
         const priceLabel = typeof response.body.api_list_price_equivalent_label === "string"
             ? ` ${response.body.api_list_price_equivalent_label}.`
             : "";
-        return dataResult(`${coverage?.sessions_extracted ?? 0} of ${coverage?.sessions_observed ?? 0} sessions extracted.${why} ${coverage?.sessions_counted_at_upload ?? 0} of ${coverage?.sessions_observed ?? 0} sessions counted at upload, ${coverage?.sessions_counted_by_server ?? 0} by server backfill, ${coverage?.sessions_counted_by_ladder ?? 0} by the ladder.${args.groupBy === "task_type" ? ` ${coverage?.sessions_labelled ?? 0} of ${coverage?.sessions_observed ?? 0} sessions labelled by topic.` : ""}${priceLabel}`, response.body);
+        // BLI-12561: the same GitHub sentences the page and the CLI print, so an
+        // agent reading only the text half cannot quote a pull-request count without
+        // what it covers and who it left out.
+        const github = githubSentence(response.body);
+        return dataResult(`${coverage?.sessions_extracted ?? 0} of ${coverage?.sessions_observed ?? 0} sessions extracted.${why} ${coverage?.sessions_counted_at_upload ?? 0} of ${coverage?.sessions_observed ?? 0} sessions counted at upload, ${coverage?.sessions_counted_by_server ?? 0} by server backfill, ${coverage?.sessions_counted_by_ladder ?? 0} by the ladder.${args.groupBy === "task_type" ? ` ${coverage?.sessions_labelled ?? 0} of ${coverage?.sessions_observed ?? 0} sessions labelled by topic.` : ""}${priceLabel}${github}`, response.body);
     }));
     registrarFor(server)("usage_sessions", {
         title: "Read task or subject sessions",

package/dist/verb-census.js

@@ -268,6 +268,8 @@ export const MCP_TWINS = {
     "mail read": { tool: "mail_read", door: "GET /api/mail/threads/[id]" },
     "mail search": { tool: "mail_search", door: "GET /api/mail/search" },
     "mail send": { tool: "mail_send", door: "POST /api/mail/send" },
+    // BLI-12530: the same message, saved unsent in the owner's own mailbox.
+    "mail draft": { tool: "mail_draft", door: "POST /api/mail/drafts" },
     "mail attachment": { tool: "mail_attachment", door: "GET /api/mail/attachments/[id]?meta=1" },
     "mail sync": { tool: "mail_sync", door: "POST /api/mail/accounts/[id]/sync" },
     "mail sync-status": { tool: "mail_sync_status", door: "GET /api/mail/sync-status" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.83",
+  "version": "0.1.85",
   "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",