@bli-cockpit/mcp 0.1.2 → 0.1.4

package/README.md

@@ -25,6 +25,96 @@ dead"). `src/verb-census.test.ts` is that rule as a test — it reads the CLI's
 own decision tables and fails when a verb is in neither the twin map, the
 terminal-only list, nor the written follow-up queue.
 
+## Every Tower verb, and the tool that does the same thing
+
+The three tables below are GENERATED from `src/verb-census.ts` by
+`npm run mcp:readme` — do not hand-edit them. They are the same three lists
+`src/verb-census.test.ts` polices, so this page and that suite cannot disagree
+about what an agent can reach.
+
+<!-- BEGIN GENERATED verb census — `npm run mcp:readme` -->
+
+**56 of 57 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
+three tables below.
+
+| CLI verb | MCP tool | Door |
+| --- | --- | --- |
+| `cockpit brief history` | `brief_history` | `GET /api/jarvis/brief?history=1` |
+| `cockpit brief read` | `brief_read` | `GET /api/jarvis/brief` |
+| `cockpit brief rewrite` | `brief_rewrite` | `POST /api/jarvis/recompile` |
+| `cockpit brief status` | `brief_status` | `GET /api/ops/brief-status` |
+| `cockpit correct` | `brief_correct` | `POST /api/jarvis/corrections` |
+| `cockpit docs create` | `docs_create` | `POST /api/docs/documents` |
+| `cockpit docs list` | `docs_list` | `GET /api/docs/documents` |
+| `cockpit docs read` | `docs_read` | `GET /api/docs/documents/[id]` |
+| `cockpit docs tree` | `docs_tree` | `GET /api/docs/tree` |
+| `cockpit docs update` | `docs_update` | `PATCH /api/docs/documents/[id]` |
+| `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` |
+| `cockpit issue list` | `work_list_issues` | `GET /api/work/issues` |
+| `cockpit issue move` | `work_move_issue` | `POST /api/work/issues/[id]/state` |
+| `cockpit issue show` | `work_get_issue` | `GET /api/work/issues/[id]` |
+| `cockpit issue update` | `work_update_issue` | `PATCH /api/work/issues/[id]` |
+| `cockpit jarvis` | `jarvis_ask` | `POST /api/jarvis/cli` |
+| `cockpit jarvis --trace` | `jarvis_trace` | `GET /api/ops/trace/[id]` |
+| `cockpit model set` | `model_set` | `POST /api/settings/jarvis-model` |
+| `cockpit model show` | `model_show` | `GET /api/settings/jarvis-model` |
+| `cockpit msg channels` | `msg_channels` | `GET /api/msg/channels` |
+| `cockpit msg create` | `msg_create_channel` | `POST /api/msg/channels` |
+| `cockpit msg dm` | `msg_dm` | `POST /api/msg/channels (dm)` |
+| `cockpit msg read` | `msg_read` | `GET /api/msg/channels/[id]/messages` |
+| `cockpit msg send` | `msg_send` | `POST /api/msg/channels/[id]/messages` |
+| `cockpit msg thread` | `msg_thread` | `GET /api/msg/channels/[id]/messages?thread_parent_id=` |
+| `cockpit notes list` | `notes_list` | `GET /api/notes/library` |
+| `cockpit notes move` | `notes_move` | `POST /api/notes/move` |
+| `cockpit notes paste` | `notes_paste` | `POST /api/notes/upload (text)` |
+| `cockpit notes share` | `notes_share` | `POST /api/notes/share` |
+| `cockpit notes shelf` | `notes_shelf` | `GET /api/notes/shelf` |
+| `cockpit notes shelves` | `notes_shelves` | `GET /api/notes/library` |
+| `cockpit notes show` | `notes_show` | `GET /api/notes/library/[id]` |
+| `cockpit notes unshare` | `notes_unshare` | `POST /api/notes/share (share=false)` |
+| `cockpit notes upload` | `notes_upload` | `POST /api/notes/upload` |
+| `cockpit ops recompile` | `ops_recompile` | `POST /api/ops/recompile` |
+| `cockpit ops status` | `ops_status` | `GET /api/ops/status` |
+| `cockpit project list` | `work_list_projects` | `GET /api/work/projects` |
+| `cockpit scout board` | `scout_board` | `GET /api/cockpit/scout` |
+| `cockpit scout dismiss` | `scout_dismiss` | `POST /api/cockpit/scout (dismiss)` |
+| `cockpit scout start` | `scout_start` | `POST /api/cockpit/scout (start)` |
+| `cockpit scout undo` | `scout_undo` | `POST /api/cockpit/scout (undo_dismiss)` |
+| `cockpit search` | `tower_search` | `GET /api/search` |
+| `cockpit settings delete` | `settings_delete` | `DELETE /api/settings/env-blobs` |
+| `cockpit settings list` | `settings_list` | `GET /api/settings/env-blobs` |
+| `cockpit settings set` | `settings_set` | `POST /api/settings/{jarvis-model,switches,model-routing,env-blobs} + PUT /api/settings/cli-floor` |
+| `cockpit settings show` | `settings_show` | `GET /api/settings/* + /api/team/members` |
+| `cockpit slack coverage` | `slack_coverage` | `GET /api/ops/slack/coverage` |
+| `cockpit slack read` | `slack_read` | `POST /api/ops/slack/read` |
+| `cockpit team device-list` | `team_device_list` | `GET /api/team/devices` |
+| `cockpit team device-revoke` | `team_device_revoke` | `POST /api/ambient/devices/[deviceId]/revoke` |
+| `cockpit team invite` | `team_invite` | `POST /api/team/invite` |
+| `cockpit team members` | `team_members` | `GET /api/team/members` |
+| `cockpit team role` | `team_role` | `PATCH /api/team/members/[userId]/role` |
+| `cockpit workbook` | `workbook_read` | `GET /api/cockpit/workbook` |
+
+### Owed a twin
+
+This table should only ever shrink.
+
+_Nothing. Every Tower verb an agent could want has a door (BLI-3756)._
+
+### Terminal-only
+
+A claim about the verb's nature, not a backlog.
+
+| CLI verb | Why it can never have a twin |
+| --- | --- |
+| `cockpit brief edit` | opens the person's own $EDITOR on this machine and files what they changed; an agent has no editor to open (commands/editor.ts) |
+
+<!-- END GENERATED verb census -->
+
 ## `jarvis_*` tools (BLI-3732)
 
 JARVIS itself — the same assistant Tower web chat, the Slack DM and
@@ -74,16 +164,92 @@ terminal, because nothing on the wire can tell a person-relayed code from one
 the model lifted out of the previous answer; `src/jarvis-tools.ts` says so in
 full at the top of the file.
 
+## The read tools (BLI-3756 batch 1)
+
+Every Tower READ the CLI already had. Doors and tool names are in the
+generated table above; what is worth knowing before you call one:
+
+- **`brief_read` / `brief_history` / `brief_status`** — the TODAY page as
+  finished text, the days a person has a page for, and why a brief was or was
+  not delivered. `subject` changes WHOSE page is asked for, never who is
+  asking. A delivery reason other than `delivered` (`not_monday`,
+  `no_slack_identity`, …) is a real answer and is NOT returned as an error.
+- **`notes_list` / `notes_show` / `notes_shelf` / `notes_shelves`** — the
+  meeting-notes library. A device token has no signed-in browser session, so
+  these reads are routinely NARROWER than a person's; every one of them
+  appends the door's own `scope`/`degradedBecause` reason rather than letting
+  an agent conclude a note was never taken.
+- **`ops_status` / `slack_coverage` / `slack_read`** — the pipeline board
+  (each job judged against its own expected interval, server-side), Slack
+  collection health, and the collected messages themselves. `slack_read` has a
+  narrower audience than `slack_coverage`, and says so on a 403.
+- **`settings_show` / `settings_list` / `model_show` / `team_members` /
+  `team_device_list`** — settings as this caller may see them. A section you
+  may not see comes back as `admin only`, not as an error; `settings_list`
+  returns env-file names, sizes and stamps and can never return a value.
+- **`scout_board` / `workbook_read`** — the Scout board (with the page's own
+  standing sentences, and a truncated read saying so) and the per-project
+  document library, rendered by the same walker the page uses.
+
+## The write tools (BLI-3756 batch 2)
+
+The seventeen things a person can DO from `cockpit` and could not do from an
+agent. Same doors, same device token, same refusal words — plus one rule the
+reads never needed:
+
+**An act that cannot be undone is refused without `confirm: true`.** The CLI's
+gate is `--yes` or a person at a keyboard; a client has no keyboard, so the
+explicit flag is the whole of it here, and the reason label is the CLI's own
+`confirmation_required`. It guards `notes_share` (sharing lets everyone signed
+in read the note), `settings_delete`, `team_role` and `team_device_revoke`.
+Taking a share BACK asks for nothing — nobody needs to be talked out of
+narrowing who can read something.
+
+- **`brief_rewrite` / `brief_correct`** — ask for a page to be written again,
+  and say that one line on it is wrong. `brief_rewrite` QUEUES and returns the
+  request id immediately; it does not wait, because an 800-second compile
+  outlives any client deadline and "the tool timed out" would be
+  indistinguishable from "the compile failed". `brief_correct` refuses a claim
+  id the page does not carry BEFORE writing, and Tower's push-back ("the record
+  disagrees") is a normal result — the correction is filed either way.
+- **`notes_upload` / `notes_paste` / `notes_share` / `notes_unshare` /
+  `notes_move`** — put a note in from this machine's disk or from text, share
+  it, take it back, move it to another shelf. A path whose NAME looks like a
+  key or credential file is refused without being opened; so is a missing,
+  empty or over-20-MB file. A large note is one model call server-side and can
+  take minutes — your client may give up first, and the upload keeps going.
+- **`ops_recompile`** — write one person's page again. It spends a model call;
+  `dry_run: true` resolves the person and reads the current page without
+  compiling. If Tower's own 800-second budget runs out the effect is UNKNOWN,
+  not failed, and it says so rather than inviting you to pay twice.
+- **`scout_start` / `scout_dismiss` / `scout_undo`** — move one card. Each
+  reads the board first, matches the id EXACTLY (no prefixes on this surface —
+  a near-miss would settle a card nobody decided on), and a 403 names the gate
+  without costing you the read.
+- **`settings_set` / `settings_delete` / `model_set`** — write one settings
+  section, delete an env file, or just change which model answers you. Env
+  content is an argument here rather than stdin (a tool call has no argv, no
+  shell history and no process list), and the rule that survives is the one
+  that mattered: it is **never echoed back** — not in the answer, not in the
+  structured payload, not in a log.
+- **`team_invite` / `team_role` / `team_device_revoke`** — invite somebody,
+  change a role, end a machine's pairing. All three relay a super_admin
+  decision made on the server. `team_device_revoke` looks the device up and
+  names it back to you first; without `confirm: true` that naming IS the
+  answer and nothing is revoked.
+
 ## `docs_*` / `msg_*` tools (BLI-3706)
 
 | Tool | Wraps | Notes |
 | --- | --- | --- |
 | `docs_list` | `GET /api/docs/documents` | Every document you may read: id, slug, title, visibility. Never a body. |
+| `docs_tree` | `GET /api/docs/tree` | The library as its nesting rather than a flat list. Never a body. |
 | `docs_read` | `GET /api/docs/documents/[id]` | One document's title and full body, by id or slug (resolved against `docs_list` first). |
 | `docs_create` | `POST /api/docs/documents` | Creates a document. Omitting `body_markdown` creates an empty one. |
-| `docs_update` | `PATCH /api/docs/documents/[id]` | Updates title/body/visibility/parent (a parent change IS a move). |
+| `docs_update` | `PATCH /api/docs/documents/[id]` | Updates title/body/visibility/parent (a parent change IS a move). Emptying a document that holds text needs `allow_empty: true` (BLI-3757's guard). |
 | `msg_channels` | `GET /api/msg/channels` | Every channel you are a member of. |
-| `msg_read` | `GET /api/msg/channels/[id]/messages` | Recent messages of one channel, or one thread's replies. `channel` is an id or a `#name`. |
+| `msg_read` | `GET /api/msg/channels/[id]/messages` | Recent messages of one channel, newest first. `channel` is an id or a `#name`. |
+| `msg_thread` | `GET /api/msg/channels/[id]/messages?thread_parent_id=` | One thread's replies, oldest first, so it reads as a conversation. |
 | `msg_send` | `POST /api/msg/channels/[id]/messages` | Posts a message. |
 
 **Auth: this machine's collector device token, not `BLI_OPERATOR_TOKEN`.**

package/dist/agent-door.d.ts

@@ -12,4 +12,11 @@ export interface AgentDoorResponse {
     /** Set only when no JSON answer was produced at all — DNS, TLS, timeout, non-JSON body. */
     transportError: string | null;
 }
-export declare function callAgentDoor(session: AgentDoorSession, fetchImpl: FetchImpl, method: "GET" | "POST" | "PATCH", path: string, body?: unknown, timeoutMs?: number): Promise<AgentDoorResponse>;
+/**
+ * The four verbs Tower's agent doors answer to. `PUT` is the CLI floor
+ * (`PUT /api/settings/cli-floor`) and `DELETE` is an env blob — both arrived
+ * with BLI-3756 batch 2, and both are the door's own choice of verb, not this
+ * package's.
+ */
+export type AgentDoorMethod = "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+export declare function callAgentDoor(session: AgentDoorSession, fetchImpl: FetchImpl, method: AgentDoorMethod, path: string, body?: unknown, timeoutMs?: number): Promise<AgentDoorResponse>;

package/dist/agent-door.js

@@ -9,16 +9,21 @@ export async function callAgentDoor(session, fetchImpl, method, path, body, time
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     timer.unref?.();
+    // A note goes in as multipart, exactly as `cockpit notes upload` sends it,
+    // so `content-type` must be left to fetch: it is the only thing that knows
+    // the boundary it just generated, and a hand-set JSON header would make the
+    // route read an empty form.
+    const multipart = typeof FormData !== "undefined" && body instanceof FormData;
     let response;
     try {
         response = await fetchImpl(url, {
             method,
             headers: {
                 authorization: `Bearer ${session.deviceToken}`,
-                "content-type": "application/json",
+                ...(multipart ? {} : { "content-type": "application/json" }),
                 accept: "application/json",
             },
-            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            ...(body === undefined ? {} : { body: multipart ? body : JSON.stringify(body) }),
             signal: controller.signal,
         });
     }

package/dist/brief-tools.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `brief_*` MCP tools (BLI-3756) — the TODAY page, read by an agent, over the
+ * same doors `cockpit brief` calls with the same device token.
+ *
+ * Nothing here renders a page. `GET /api/jarvis/brief` hands back finished
+ * text (the serializer's terminal flavour, the same one the CLI prints), and
+ * `GET /api/ops/brief-status` hands back the delivery reason computed by the
+ * code the Slack DM cron delivers with. A second renderer in this package
+ * would let the agent and the browser drift into describing two different
+ * days.
+ *
+ * `subject` changes WHOSE page is asked for, never who is asking — the same
+ * rule `cockpit brief --for` and `cockpit jarvis --as` follow. The server owns
+ * whether this caller may see that person at all, and says so in its own words.
+ *
+ * One judgement call worth naming: `brief_status` answers `not_monday` or
+ * `no_slack_identity` as a normal RESULT, not as an `isError`. The CLI exits 1
+ * on anything but `delivered` because a shell script needs a branch; a tool
+ * that reported "error" for a successful read of a true fact would teach an
+ * agent that the surface is broken.
+ */
+import { type ToolDeps } from "./tool-result.js";
+export type BriefDeps = ToolDeps;
+export declare function registerBriefTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: BriefDeps): void;

package/dist/brief-tools.js

@@ -0,0 +1,160 @@
+/**
+ * `brief_*` MCP tools (BLI-3756) — the TODAY page, read by an agent, over the
+ * same doors `cockpit brief` calls with the same device token.
+ *
+ * Nothing here renders a page. `GET /api/jarvis/brief` hands back finished
+ * text (the serializer's terminal flavour, the same one the CLI prints), and
+ * `GET /api/ops/brief-status` hands back the delivery reason computed by the
+ * code the Slack DM cron delivers with. A second renderer in this package
+ * would let the agent and the browser drift into describing two different
+ * days.
+ *
+ * `subject` changes WHOSE page is asked for, never who is asking — the same
+ * rule `cockpit brief --for` and `cockpit jarvis --as` follow. The server owns
+ * whether this caller may see that person at all, and says so in its own words.
+ *
+ * One judgement call worth naming: `brief_status` answers `not_monday` or
+ * `no_slack_identity` as a normal RESULT, not as an `isError`. The CLI exits 1
+ * on anything but `delivered` because a shell script needs a branch; a tool
+ * that reported "error" for a successful read of a true fact would teach an
+ * agent that the surface is broken.
+ */
+import { z } from "zod";
+import { callAgentDoor } from "./agent-door.js";
+import { doorFailureText, errorResult, registrarFor, textResult, queryString, withSession, } from "./tool-result.js";
+const SUBJECT = z
+    .string()
+    .min(1)
+    .max(200)
+    .optional()
+    .describe("Whose page — a name, email or person id. Omit for your own. Changes the SUBJECT, never who is asking.");
+export function registerBriefTools(server, deps) {
+    const register = registrarFor(server);
+    register("brief_read", {
+        title: "Read a Tower daily page",
+        description: "The TODAY page as text — the same page the website and `cockpit brief` show. Optionally one pinned version, "
+            + "one of the subject's own past days, the TLDR only, the claim ids you would file a correction against, or "
+            + "what changed since the day before.",
+        inputSchema: {
+            subject: SUBJECT,
+            date: z
+                .string()
+                .min(1)
+                .max(20)
+                .optional()
+                .describe('YYYY-MM-DD, "today" or "yesterday" — sent verbatim; the server owns where a day starts.'),
+            version: z.string().min(1).max(100).optional().describe("One exact stored page id instead of the newest."),
+            tldr: z.boolean().optional().describe("Just the TLDR."),
+            versions: z.boolean().optional().describe("Also list the earlier stored versions."),
+            claims: z.boolean().optional().describe("Also list claim ids — what `cockpit correct --claim` takes."),
+            delta: z.boolean().optional().describe("Also say what changed since the previous day."),
+            against: z.string().min(1).max(20).optional().describe("Compare against this date instead of the previous day."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const params = new URLSearchParams();
+        if (args.subject)
+            params.set("p", String(args.subject));
+        if (args.version)
+            params.set("v", String(args.version));
+        if (args.date)
+            params.set("d", String(args.date));
+        if (args.tldr)
+            params.set("tldr", "1");
+        if (args.versions)
+            params.set("versions", "1");
+        if (args.claims)
+            params.set("claims", "1");
+        if (args.delta) {
+            params.set("delta", "1");
+            if (args.against)
+                params.set("against", String(args.against));
+        }
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/jarvis/brief${queryString(params)}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("brief_read", response));
+        const body = response.body;
+        if (!body.ok || typeof body.text !== "string") {
+            // The route's own plain-words notice ("Nothing has been written for
+            // you yet.") is an answer, not a stack trace — relayed as it stands.
+            return errorResult(`Tower returned no page for brief_read (${body.error ?? "no_page"}): `
+                + (body.reply ?? "Tower answered without a page."));
+        }
+        const whose = body.page?.displayName ? `${body.page.displayName}'s page` : "This page";
+        const day = body.day?.date ? ` · ${body.day.date}${body.day.zone ? ` ${body.day.zone}` : ""}` : "";
+        const pinned = body.page?.olderVersionLabel ? ` · version from ${body.page.olderVersionLabel}` : "";
+        // A missing delta is SAID, never left as an empty space: an agent that
+        // asked what changed and got silence would report that nothing did.
+        const deltaText = args.delta
+            ? `\n\n--- what changed ---\n${body.delta?.headline ?? `No delta (${body.deltaReason ?? "no reason given"}).`}`
+            : "";
+        const claimText = body.claims?.length
+            ? `\n\n--- claim ids ---\n${body.claims.map((claim) => `[${claim.claimId}] ${claim.text ?? ""}`).join("\n")}`
+            : "";
+        const versionText = body.versions
+            ? body.versions.length === 0
+                ? `\n\n(earlier versions could not be listed: ${body.versionsReason ?? "no reason given"})`
+                : `\n\n--- versions ---\n${body.versions.map((v) => `${v.version}/${v.of}  ${v.pageId}  ${v.asOf}`).join("\n")}`
+            : "";
+        return textResult(`${whose}${pinned}${day}\n\n${body.text}${deltaText}${claimText}${versionText}`, {
+            text: body.text,
+            page: body.page ?? null,
+            day: body.day ?? null,
+            visibleBecause: body.visibleBecause ?? null,
+            ...(body.claims ? { claims: body.claims } : {}),
+            ...(body.versions ? { versions: body.versions, versionsReason: body.versionsReason ?? null } : {}),
+            ...(args.delta ? { delta: body.delta ?? null, deltaReason: body.deltaReason ?? null } : {}),
+        });
+    }));
+    register("brief_history", {
+        title: "List a subject's daily pages",
+        description: "Which days a person has a page for, newest first — dates and page ids, no page text. Pass a page id to "
+            + "brief_read's `version` to open one.",
+        inputSchema: {
+            subject: SUBJECT,
+            days: z.number().int().min(1).max(365).optional().describe("How many days back to list."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const params = new URLSearchParams({ history: "1" });
+        if (args.subject)
+            params.set("p", String(args.subject));
+        if (typeof args.days === "number")
+            params.set("days", String(args.days));
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/jarvis/brief${queryString(params)}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("brief_history", response));
+        const body = response.body;
+        const history = body.history ?? [];
+        const lines = history
+            .map((row) => `${row.date ?? "?"}  ${row.pageId ?? "?"}  ${row.versionCount ?? 1}v  ${row.heading ?? ""}`.trimEnd())
+            .join("\n");
+        return textResult(`${history.length} day(s)${body.historyTruncated ? ", and more beyond the window" : ""}.${lines ? `\n${lines}` : ""}`, { history, historyTruncated: body.historyTruncated ?? false });
+    }));
+    register("brief_status", {
+        title: "Why a Tower brief was or was not delivered",
+        description: "The delivery reason for one person's brief, from the closed set the Slack DM cron itself computes "
+            + "(`delivered`, `not_monday`, `no_slack_identity`, …). A reason other than `delivered` is a real answer, "
+            + "not a failure. `render` also returns the TLDR the DM would have carried.",
+        inputSchema: {
+            subject: SUBJECT,
+            render: z.boolean().optional().describe("Also return the text the DM would have carried."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const params = new URLSearchParams();
+        if (args.subject)
+            params.set("who", String(args.subject));
+        if (args.render)
+            params.set("render", "1");
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/ops/brief-status${queryString(params)}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("brief_status", response));
+        const body = response.body;
+        const status = body.status ?? {};
+        const reason = status.reason ?? "unknown";
+        const detail = status.detail ? `\n${status.detail}` : "";
+        const slack = status.slack?.hasIdentity === false ? "\nNo Slack identity is on file for them." : "";
+        const readError = status.readError ? `\n(one source could not be read: ${status.readError})` : "";
+        const rendered = body.render?.text ? `\n\n--- the DM would have said ---\n${body.render.text}` : "";
+        return textResult(`${status.displayName ?? "This person"} — ${reason}${detail}${slack}${readError}`
+            + `\n${status.owningCadence ?? "?"} owns this morning${status.timeZone ? ` (${status.timeZone})` : ""}${rendered}`, { status, ...(body.render ? { render: body.render } : {}) });
+    }));
+}

package/dist/brief-write-tools.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `brief_rewrite` / `brief_correct` MCP tools (BLI-3756 batch 2) — the two
+ * things a person can DO to the daily page, over the same doors
+ * `cockpit brief rewrite` and `cockpit correct` call with the same device
+ * token.
+ *
+ * Reads live in `brief-tools.ts`; these two write, and each carries one
+ * judgement the read side never has to make.
+ *
+ * **`brief_rewrite` asks and does not wait.** The CLI queues the compile and
+ * then watches the page for up to fifteen minutes, because a terminal can sit
+ * there. A tool call cannot: the client's own deadline would cut the call
+ * long before an 800-second compile finished, and "the tool timed out" is
+ * indistinguishable from "the compile failed" — the exact confusion this repo
+ * keeps paying for. So this tool sends `mode: "queue"`, reports the request id
+ * the moment it exists, and says in its own answer that the page is not
+ * written yet and `brief_read` is how to find out. That is the CLI's
+ * `--no-wait` shape, chosen deliberately and named out loud rather than
+ * silently.
+ *
+ * **`brief_correct` treats push-back as the answer, not an error.** The
+ * corrections door checks the claim against the live record BEFORE writing and
+ * can answer that the record disagrees. That sentence is what the caller came
+ * for: the correction WAS filed, with its outcome recorded, so it comes back
+ * as a normal result. Only a failure to file at all is an error.
+ *
+ * A claim id the page does not carry is refused HERE, before any write, in the
+ * CLI's own words — filing it anyway would land a correction on a clause
+ * nobody can find, which is how a ledger fills with rows that mean nothing.
+ */
+import { type ToolDeps } from "./tool-result.js";
+export type BriefWriteDeps = ToolDeps;
+/** The same ceiling `cockpit correct` enforces before it sends anything. */
+export declare const MAX_CORRECTION_LENGTH = 4000;
+export declare function registerBriefWriteTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: BriefWriteDeps): void;

package/dist/brief-write-tools.js

@@ -0,0 +1,178 @@
+/**
+ * `brief_rewrite` / `brief_correct` MCP tools (BLI-3756 batch 2) — the two
+ * things a person can DO to the daily page, over the same doors
+ * `cockpit brief rewrite` and `cockpit correct` call with the same device
+ * token.
+ *
+ * Reads live in `brief-tools.ts`; these two write, and each carries one
+ * judgement the read side never has to make.
+ *
+ * **`brief_rewrite` asks and does not wait.** The CLI queues the compile and
+ * then watches the page for up to fifteen minutes, because a terminal can sit
+ * there. A tool call cannot: the client's own deadline would cut the call
+ * long before an 800-second compile finished, and "the tool timed out" is
+ * indistinguishable from "the compile failed" — the exact confusion this repo
+ * keeps paying for. So this tool sends `mode: "queue"`, reports the request id
+ * the moment it exists, and says in its own answer that the page is not
+ * written yet and `brief_read` is how to find out. That is the CLI's
+ * `--no-wait` shape, chosen deliberately and named out loud rather than
+ * silently.
+ *
+ * **`brief_correct` treats push-back as the answer, not an error.** The
+ * corrections door checks the claim against the live record BEFORE writing and
+ * can answer that the record disagrees. That sentence is what the caller came
+ * for: the correction WAS filed, with its outcome recorded, so it comes back
+ * as a normal result. Only a failure to file at all is an error.
+ *
+ * A claim id the page does not carry is refused HERE, before any write, in the
+ * CLI's own words — filing it anyway would land a correction on a clause
+ * nobody can find, which is how a ledger fills with rows that mean nothing.
+ */
+import { z } from "zod";
+import { callAgentDoor } from "./agent-door.js";
+import { doorFailureText, errorResult, registrarFor, textResult, withSession, } from "./tool-result.js";
+/** The same ceiling `cockpit correct` enforces before it sends anything. */
+export const MAX_CORRECTION_LENGTH = 4000;
+/** A rewrite queues in seconds; the compile it queues takes minutes. */
+const QUEUE_DEADLINE_MS = 60_000;
+const SUBJECT = z
+    .string()
+    .min(1)
+    .max(200)
+    .optional()
+    .describe("Whose page — a name, email or person id. Omit for your own. Changes the SUBJECT, never who is asking.");
+/**
+ * Which page, and whose. The same read both verbs open with, and the only way
+ * either learns the person id the write doors need.
+ */
+async function readPage(deps, session, params) {
+    const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/jarvis/brief?${params.toString()}`, undefined, QUEUE_DEADLINE_MS);
+    if (!response.ok)
+        return { ok: false, text: doorFailureText("brief", response) };
+    const body = response.body;
+    if (!body.ok || !body.page?.personId) {
+        return {
+            ok: false,
+            text: body.reply ?? "There is no page here to work on yet. The first one is compiled by the daily job.",
+        };
+    }
+    return { ok: true, body };
+}
+export function registerBriefWriteTools(server, deps) {
+    const register = registrarFor(server);
+    register("brief_rewrite", {
+        title: "Ask for a Tower daily page to be written again",
+        description: "Queues a recompile of the TODAY page — the website's button and `cockpit brief rewrite`, same door. It spends "
+            + "a model call and takes several minutes, so this tool ASKS and returns the request id immediately; it does "
+            + "not wait. Read the result later with brief_read. An admin may ask about anybody; everyone else about their "
+            + "own page, decided on the server.",
+        inputSchema: { subject: SUBJECT },
+    }, async (args) => withSession(deps, async (session) => {
+        const params = new URLSearchParams({ tldr: "1" });
+        if (args.subject)
+            params.set("p", String(args.subject));
+        const page = await readPage(deps, session, params);
+        if (!page.ok)
+            return errorResult(page.text);
+        const personId = page.body.page?.personId;
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/jarvis/recompile", { personIds: [personId], mode: "queue" }, QUEUE_DEADLINE_MS);
+        if (!response.ok)
+            return errorResult(doorFailureText("brief_rewrite", response));
+        const answer = response.body;
+        const request = (answer.queued ?? [])[0];
+        if (!answer.ok || !request?.requestId) {
+            return errorResult(answer.reply ?? "Tower did not accept that ask.");
+        }
+        const whose = request.name ?? page.body.page?.displayName ?? "that page";
+        const scheduled = answer.compileScheduled !== false;
+        // Queue-only, said as queue-only. The ask is a real row; what is
+        // missing is somebody to run it in the next minute, and pretending
+        // otherwise would leave a caller watching a page that was never going
+        // to change.
+        const sentence = scheduled
+            ? `Asked. ${whose} is being written again — this takes a few minutes. Call brief_read then; nothing here waits for it.`
+            : `${whose} is on the list to be written again, but this Tower could not start the work now `
+                + `(${answer.compileReason ?? "no reason given"}). The daily compile will reach it. Nothing is lost.`;
+        return textResult(sentence, {
+            ok: true,
+            outcome: scheduled ? "queued" : "queued_only",
+            requestId: request.requestId,
+            personId,
+            compileScheduled: scheduled,
+            compileReason: answer.compileReason ?? null,
+        });
+    }));
+    register("brief_correct", {
+        title: "Say that one line on a Tower page is wrong",
+        description: "Files a correction against ONE claim on the daily page — `cockpit correct`, same door and same ledger. Get "
+            + "claim ids from brief_read with `claims: true`. Tower checks the claim against the live record before "
+            + "writing and may answer that the record disagrees; that push-back is the RESULT, not a failure — the "
+            + "correction is filed either way, with its outcome recorded.",
+        inputSchema: {
+            claim_id: z.string().min(1).max(200).describe("A claim id from brief_read({claims: true})."),
+            text: z
+                .string()
+                .min(1)
+                .max(MAX_CORRECTION_LENGTH)
+                .describe("What is wrong, and what is true instead."),
+            subject: SUBJECT,
+            version: z.string().min(1).max(100).optional().describe("Correct one exact stored page id instead of the newest."),
+            supersedes: z
+                .string()
+                .min(1)
+                .max(200)
+                .optional()
+                .describe("A correction on the same clause that this one takes back."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const claimId = String(args.claim_id ?? "");
+        const params = new URLSearchParams({ claims: "1" });
+        if (args.subject)
+            params.set("p", String(args.subject));
+        if (args.version)
+            params.set("v", String(args.version));
+        const page = await readPage(deps, session, params);
+        if (!page.ok)
+            return errorResult(page.text);
+        const claim = (page.body.claims ?? []).find((candidate) => candidate.claimId === claimId);
+        if (!claim) {
+            return errorResult(`Refused (unknown_claim): that page has no line called “${claimId}”. `
+                + "Call brief_read with `claims: true` to see the ids. Nothing was filed.");
+        }
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/jarvis/corrections", {
+            personId: page.body.page?.personId,
+            pageId: page.body.page?.pageId ?? null,
+            claimId,
+            // The line as it reads now, so the ledger records what was
+            // disputed and the live check has the sentence to work from.
+            quotedText: claim.text ?? null,
+            correctionText: String(args.text ?? ""),
+            contextLinks: claim.links ?? [],
+            clauseOnPage: true,
+            clauseIsObserved: Boolean(claim.observed),
+            ...(args.supersedes ? { supersedes: String(args.supersedes) } : {}),
+        }, QUEUE_DEADLINE_MS);
+        if (!response.ok)
+            return errorResult(doorFailureText("brief_correct", response));
+        const filed = response.body;
+        if (!filed.correctionId) {
+            return errorResult(filed.error ?? "Tower did not record that correction.");
+        }
+        const said = [
+            filed.reply ?? "Filed.",
+            filed.finding ? `The record says: ${filed.finding}` : "",
+            filed.link ?? "",
+        ]
+            .filter(Boolean)
+            .join("\n");
+        return textResult(said, {
+            ok: true,
+            correctionId: filed.correctionId,
+            tier: filed.tier ?? null,
+            outcome: filed.outcome ?? null,
+            pushBack: filed.pushBack ?? null,
+            finding: filed.finding ?? null,
+            link: filed.link ?? null,
+        });
+    }));
+}