@bli-cockpit/mcp 0.1.2 → 0.1.3

package/dist/notes-tools.js

@@ -0,0 +1,143 @@
+/**
+ * `notes_*` MCP tools (BLI-3756) — the meeting-notes library, read by an
+ * agent, over the same `/api/notes/**` doors `cockpit notes` calls with the
+ * same device token.
+ *
+ * **The narrowing is always said out loud.** `lib/notes/api-doors.ts` gives a
+ * caller with no signed-in browser session a NARROWER read and names it in the
+ * answer's own `scope`/`degradedBecause` — a device token is exactly such a
+ * caller, so an agent reading this library is routinely seeing less than a
+ * person would in a browser. Every tool here appends that reason to its text.
+ * Swallowing it would let an agent conclude a note was never taken when in
+ * fact it simply was not this caller's to read, which is a fact invented out
+ * of a permission.
+ *
+ * Reads only. `notes move|share|unshare|paste|upload` are batch 2 — sharing is
+ * a deliberate act and the paste door takes a body on stdin by rule.
+ */
+import { z } from "zod";
+import { callAgentDoor } from "./agent-door.js";
+import { doorFailureText, errorResult, registrarFor, textResult, queryString, withSession, } from "./tool-result.js";
+/**
+ * The door's own words for "this answer is narrower than the browser's", or
+ * "" when it was not narrowed. Never rephrased here.
+ */
+export function narrowingNote(body) {
+    if (!body.degradedBecause)
+        return "";
+    return `\n\n(scope: ${body.scope ?? "unknown"} — ${body.degradedBecause}. `
+        + `${body.degradedNote ?? "This answer is narrower than the browser's."})`;
+}
+function libraryQuery(args) {
+    const params = new URLSearchParams();
+    if (args.shelf)
+        params.set("series", String(args.shelf));
+    if (args.kind)
+        params.set("kind", String(args.kind));
+    if (args.since)
+        params.set("since", String(args.since));
+    if (args.until)
+        params.set("until", String(args.until));
+    if (typeof args.limit === "number")
+        params.set("limit", String(args.limit));
+    return params;
+}
+const LIBRARY_FILTERS = {
+    shelf: z.string().min(1).max(200).optional().describe("Only this shelf (the library calls it a series)."),
+    kind: z.string().min(1).max(100).optional().describe("Only this meeting kind."),
+    since: z.string().min(1).max(20).optional().describe("YYYY-MM-DD — meetings on or after this date."),
+    until: z.string().min(1).max(20).optional().describe("YYYY-MM-DD — meetings on or before this date."),
+    limit: z.number().int().min(1).max(500).optional(),
+};
+export function registerNotesTools(server, deps) {
+    const register = registrarFor(server);
+    register("notes_list", {
+        title: "List Tower meeting notes",
+        description: "The meeting-notes library you may read, grouped by shelf: id, date, kind, participants and file name. "
+            + "Never a note's text — call notes_show for one. Says when the answer is narrower than a browser's.",
+        inputSchema: LIBRARY_FILTERS,
+    }, async (args) => withSession(deps, async (session) => {
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/notes/library${queryString(libraryQuery(args))}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("notes_list", response));
+        const body = response.body;
+        const series = body.series ?? [];
+        const lines = series
+            .map((shelf) => {
+            const notes = shelf.notes
+                .map((note) => {
+                const who = note.participants.length > 0 ? ` — ${note.participants.join(", ")}` : "";
+                return `  ${note.meetingDate}  ${note.id}  ${note.fileName}${who}`;
+            })
+                .join("\n");
+            return `${shelf.heading} (${shelf.notes.length})\n${notes}`;
+        })
+            .join("\n\n");
+        return textResult(`${body.count ?? 0} note(s)${body.more ? ", and more exist beyond the limit" : ""}.`
+            + `${lines ? `\n\n${lines}` : ""}${narrowingNote(body)}`, { scope: body.scope ?? null, count: body.count ?? 0, more: body.more ?? false, series });
+    }));
+    register("notes_show", {
+        title: "Read one Tower meeting note",
+        description: "One note's title, date, shelf, participants and full text, by its id (notes_list returns ids).",
+        inputSchema: { id: z.string().min(1).max(200).describe("A note id.") },
+    }, async (args) => withSession(deps, async (session) => {
+        const ref = String(args.id ?? "");
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/notes/library/${encodeURIComponent(ref)}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("notes_show", response));
+        const body = response.body;
+        const note = body.note;
+        if (!note) {
+            return errorResult(`Tower answered notes_show without a note for "${ref}".${narrowingNote(body)}`);
+        }
+        const room = note.participants.length > 0 ? `\nIn the room: ${note.participants.join(", ")}` : "";
+        return textResult(`${note.title}\n${note.meetingDate}  ·  ${note.shelf}  ·  ${note.fileName}  ·  ${note.lineCount} lines`
+            + `${room}\n${note.visibility}\n\n${note.content}${narrowingNote(body)}`, { scope: body.scope ?? null, note });
+    }));
+    register("notes_shelf", {
+        title: "Your own Tower notes shelf",
+        description: "The notes THIS machine's owner put in, with the per-note counts (statements, open to the team, kept back) "
+            + "when the server knows them. Says so when it does not, rather than printing zeros.",
+        inputSchema: { limit: z.number().int().min(1).max(500).optional() },
+    }, async (args) => withSession(deps, async (session) => {
+        const params = new URLSearchParams();
+        if (typeof args.limit === "number")
+            params.set("limit", String(args.limit));
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/notes/shelf${queryString(params)}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("notes_shelf", response));
+        const body = response.body;
+        const notes = body.notes ?? [];
+        const lines = notes
+            .map((note) => {
+            const counts = note.countsKnown
+                ? `${note.statements} statements, ${note.openToTheTeam} open to the team, ${note.keptBack} kept back`
+                : "counts unknown on this server";
+            return `${note.meetingDate}  ${note.id}  ${note.shared ? "shared" : "yours"}  ${note.name}\n    ${counts}`;
+        })
+            .join("\n");
+        return textResult(`${notes.length} note(s) on your shelf.${lines ? `\n${lines}` : ""}${narrowingNote(body)}`, { scope: body.scope ?? null, notes });
+    }));
+    register("notes_shelves", {
+        title: "List Tower note shelves",
+        description: "The shelves the library is grouped into and how many notes are on each — a shelf somebody typed is marked "
+            + "as such, one implied by the meeting kind is not. Pass a heading to notes_list's `shelf`.",
+        inputSchema: LIBRARY_FILTERS,
+    }, async (args) => withSession(deps, async (session) => {
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/notes/library${queryString(libraryQuery(args))}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("notes_shelves", response));
+        const body = response.body;
+        // The same derivation `commands/notes-reads.ts` does, kept identical on
+        // purpose: a shelf is free text, so only the typed ones are marked.
+        const shelves = (body.series ?? []).map((one) => ({
+            shelf: one.heading,
+            notes: one.notes.length,
+            custom: (body.categories ?? []).includes(one.heading),
+        }));
+        const lines = shelves
+            .map((shelf) => `${String(shelf.notes).padStart(4)}  ${shelf.shelf}${shelf.custom ? "" : "  (from the meeting kind)"}`)
+            .join("\n");
+        return textResult(`${shelves.length} shelf/shelves.${lines ? `\n${lines}` : ""}${narrowingNote(body)}`, { scope: body.scope ?? null, shelves });
+    }));
+}

package/dist/ops-tools.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `ops_status` / `slack_*` MCP tools (BLI-3756) — the `/api/ops/**` board an
+ * agent can open, over the same doors `cockpit ops` and `cockpit slack` call
+ * with the same device token.
+ *
+ * These three share a file because they share a door family and a gate, not
+ * because they share a noun. `lib/ops/pipeline-status.ts` is the one place
+ * that knows a job's EXPECTED INTERVAL — written next to its reader, so a
+ * once-daily job quiet for 18 hours reads healthy (BLI-3276) — and no verdict
+ * is computed here. This surface reports the server's verdicts and counts the
+ * unhealthy ones so an agent does not have to know the vocabulary to notice a
+ * red board.
+ *
+ * `ops recompile` stays out: it spends a model call and wants its own gate on
+ * this surface (batch 2).
+ */
+import { type ToolDeps } from "./tool-result.js";
+export type OpsDeps = ToolDeps;
+/**
+ * The verdicts that mean something is wrong, verbatim from `commands/ops.ts`.
+ * `failing` is its own word and not a shade of `stale` (BLI-3723): a failing
+ * reader's input is CURRENT and its answer is bad.
+ */
+export declare const UNHEALTHY_VERDICTS: Set<string>;
+export declare function registerOpsTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: OpsDeps): void;

package/dist/ops-tools.js

@@ -0,0 +1,151 @@
+/**
+ * `ops_status` / `slack_*` MCP tools (BLI-3756) — the `/api/ops/**` board an
+ * agent can open, over the same doors `cockpit ops` and `cockpit slack` call
+ * with the same device token.
+ *
+ * These three share a file because they share a door family and a gate, not
+ * because they share a noun. `lib/ops/pipeline-status.ts` is the one place
+ * that knows a job's EXPECTED INTERVAL — written next to its reader, so a
+ * once-daily job quiet for 18 hours reads healthy (BLI-3276) — and no verdict
+ * is computed here. This surface reports the server's verdicts and counts the
+ * unhealthy ones so an agent does not have to know the vocabulary to notice a
+ * red board.
+ *
+ * `ops recompile` stays out: it spends a model call and wants its own gate on
+ * this surface (batch 2).
+ */
+import { z } from "zod";
+import { callAgentDoor } from "./agent-door.js";
+import { doorFailureText, errorResult, registrarFor, textResult, queryString, withSession, } from "./tool-result.js";
+/**
+ * The verdicts that mean something is wrong, verbatim from `commands/ops.ts`.
+ * `failing` is its own word and not a shade of `stale` (BLI-3723): a failing
+ * reader's input is CURRENT and its answer is bad.
+ */
+export const UNHEALTHY_VERDICTS = new Set(["stale", "never_produced", "unreadable", "failing"]);
+function numberOf(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+export function registerOpsTools(server, deps) {
+    const register = registrarFor(server);
+    register("ops_status", {
+        title: "Read the Tower pipeline board",
+        description: "Every scheduled job's verdict against its own expected interval, plus the collector fleet and collection "
+            + "coverage. A job's `detail` is the server's sentence for why — relayed as it stands. Status only: nothing "
+            + "here fires a job.",
+        inputSchema: {
+            job: z.string().min(1).max(100).optional().describe("One pipeline id instead of the whole board."),
+            skips: z.boolean().optional().describe("Also return the open ingest-skip ledgers."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const params = new URLSearchParams();
+        if (args.job)
+            params.set("job", String(args.job));
+        if (args.skips)
+            params.set("skips", "1");
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/ops/status${queryString(params)}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("ops_status", response));
+        const body = response.body;
+        const rows = (Array.isArray(body.pipelines) ? body.pipelines : []);
+        const unhealthy = rows.filter((row) => UNHEALTHY_VERDICTS.has(row.verdict ?? ""));
+        const lines = rows
+            .map((row) => `${(row.verdict ?? "?").padEnd(14)}  ${row.id ?? "?"}  ${row.detail ?? row.label ?? ""}`.trimEnd())
+            .join("\n");
+        // Both branches say something. A board that is entirely green and
+        // reports nothing cannot answer "did anybody look today?".
+        return textResult(`${rows.length} pipeline(s), ${unhealthy.length} unhealthy`
+            + `${unhealthy.length > 0 ? `: ${unhealthy.map((row) => row.id ?? "?").join(", ")}` : "."}`
+            + `${lines ? `\n${lines}` : ""}`, {
+            pipelines: rows,
+            unhealthy: unhealthy.map((row) => row.id ?? "?"),
+            ...(body.fleet ? { fleet: body.fleet } : {}),
+            ...(body.coverage ? { coverage: body.coverage } : {}),
+            ...(body.skips ? { skips: body.skips } : {}),
+        });
+    }));
+    register("slack_coverage", {
+        title: "Read Tower's Slack collection coverage",
+        description: "Which Slack channels the bot can actually read, per workspace, and which are stale beyond the server's own "
+            + "threshold. Open to everyone — this is collection health, not message content.",
+        inputSchema: {
+            workspace: z.string().min(1).max(100).optional().describe("One workspace key instead of all of them."),
+            stale_only: z.boolean().optional().describe("Report only the stale channels, not the whole breakdown."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const params = new URLSearchParams();
+        if (args.workspace)
+            params.set("workspace", String(args.workspace));
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/ops/slack/coverage${queryString(params)}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("slack_coverage", response));
+        const coverage = asRecord(response.body["coverage"]);
+        const workspaces = (Array.isArray(coverage["workspaces"]) ? coverage["workspaces"] : []);
+        const staleAfter = numberOf(coverage["staleAfterHours"]);
+        const staleTotal = workspaces.reduce((sum, row) => sum + numberOf(row["staleChannelsTotal"]), 0);
+        const lines = workspaces
+            .map((workspace) => {
+            const key = String(workspace["workspace"] ?? "?").toUpperCase();
+            const head = `${key}  ${numberOf(workspace["covered"])} of ${numberOf(workspace["channelsKnown"])} channels readable`;
+            const stale = numberOf(workspace["staleChannelsTotal"]);
+            const staleLine = stale === 0
+                ? `  no channel is over ${staleAfter}h since its last sync`
+                : `  ${stale} channel(s) over ${staleAfter}h since last sync`;
+            const cursor = args.stale_only ? "" : `\n  newest cursor: ${String(workspace["newestCursorIso"] ?? "never")}`;
+            return `${head}\n${staleLine}${cursor}`;
+        })
+            .join("\n\n");
+        return textResult(`${workspaces.length} workspace(s), ${staleTotal} stale channel(s).${lines ? `\n\n${lines}` : ""}`
+            + (typeof coverage["note"] === "string" ? `\n\n${coverage["note"]}` : ""), { coverage });
+    }));
+    register("slack_read", {
+        title: "Read Tower-collected Slack messages",
+        description: "Messages the Slack collector holds, filtered by person, channel, text and date. A narrower audience than "
+            + "slack_coverage: the server decides who may read message content, and refuses in its own words.",
+        inputSchema: {
+            person: z.string().min(1).max(200).optional().describe("A person — name, email or Slack member id."),
+            channel: z.string().min(1).max(200).optional().describe("One channel name."),
+            query: z.string().min(1).max(500).optional().describe("Text to look for."),
+            since: z.string().min(1).max(30).optional().describe("YYYY-MM-DD or ISO-8601."),
+            until: z.string().min(1).max(30).optional().describe("YYYY-MM-DD or ISO-8601."),
+            limit: z.number().int().min(1).max(500).optional(),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const body = {};
+        for (const key of ["person", "channel", "query", "since", "until"]) {
+            if (args[key])
+                body[key] = String(args[key]);
+        }
+        if (typeof args.limit === "number")
+            body["limit"] = args.limit;
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/ops/slack/read", body);
+        if (!response.ok) {
+            // The CLI names the open door beside the closed one on a 403; an
+            // agent told only "forbidden" would stop, when the coverage read it
+            // is entitled to may well answer the question it was asking.
+            const hint = response.status === 403
+                ? " slack_coverage is open to everyone and answers what the bot can see."
+                : "";
+            return errorResult(`${doorFailureText("slack_read", response)}${hint}`);
+        }
+        const read = asRecord(response.body["result"]);
+        const messages = (Array.isArray(read["messages"]) ? read["messages"] : []);
+        const lines = messages
+            .map((message) => `#${String(message["channel"] ?? "?")}  ${String(message["author"] ?? "?")}  ${String(message["messageTs"] ?? "?")}`
+            + `\n  ${String(message["text"] ?? "")}`)
+            .join("\n");
+        // The server's own summary first and verbatim: it is the sentence that
+        // keeps an empty answer from reading as "nobody said anything".
+        const summary = typeof read["summary"] === "string" ? read["summary"] : `${messages.length} message(s).`;
+        const note = typeof read["note"] === "string" && read["note"] ? `\n\n${read["note"]}` : "";
+        return textResult(`${summary}${lines ? `\n\n${lines}` : ""}${note}`, {
+            status: read["status"] ?? null,
+            reason: read["reason"] ?? null,
+            messages,
+            coverage: read["coverage"] ?? null,
+        });
+    }));
+}

package/dist/pages-tools.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `scout_board` / `workbook_read` MCP tools (BLI-3756) — the two read-only
+ * `/api/cockpit/**` pages, over the same doors `cockpit scout` and
+ * `cockpit workbook` call with the same device token.
+ *
+ * **The sentences belong to the page, not to this file.** Both doors return
+ * the finished words the browser renders — Scout's standing lines come from
+ * `lib/cockpit/scout-lines.ts`, and the workbook's markdown comes from
+ * `lib/workbook/to-markdown.ts` walking the same static elements the page
+ * renders. A tool that reworded either would eventually disagree with the page
+ * about what happened, and an agent would have no way to tell which was right.
+ *
+ * **A bounded read says so.** The Scout door returns at most 8 cards and 12
+ * signals and reports the totals in `coverage`; a truncated board and a quiet
+ * board must never read alike.
+ *
+ * Moving a Scout card (`start`/`dismiss`/`undo`) is super_admin server-side and
+ * stays in batch 2.
+ */
+import { type ToolDeps } from "./tool-result.js";
+export type PagesDeps = ToolDeps;
+export declare function registerPagesTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: PagesDeps): void;

package/dist/pages-tools.js

@@ -0,0 +1,123 @@
+/**
+ * `scout_board` / `workbook_read` MCP tools (BLI-3756) — the two read-only
+ * `/api/cockpit/**` pages, over the same doors `cockpit scout` and
+ * `cockpit workbook` call with the same device token.
+ *
+ * **The sentences belong to the page, not to this file.** Both doors return
+ * the finished words the browser renders — Scout's standing lines come from
+ * `lib/cockpit/scout-lines.ts`, and the workbook's markdown comes from
+ * `lib/workbook/to-markdown.ts` walking the same static elements the page
+ * renders. A tool that reworded either would eventually disagree with the page
+ * about what happened, and an agent would have no way to tell which was right.
+ *
+ * **A bounded read says so.** The Scout door returns at most 8 cards and 12
+ * signals and reports the totals in `coverage`; a truncated board and a quiet
+ * board must never read alike.
+ *
+ * Moving a Scout card (`start`/`dismiss`/`undo`) is super_admin server-side and
+ * stays in batch 2.
+ */
+import { z } from "zod";
+import { callAgentDoor } from "./agent-door.js";
+import { doorFailureText, errorResult, registrarFor, textResult, queryString, withSession, } from "./tool-result.js";
+/** "8 of 23 (truncated)" — never a bare count that hides what was left out. */
+function coverageWord(coverage, shown) {
+    if (!coverage)
+        return String(shown);
+    const total = coverage.total ?? null;
+    return `${coverage.returned ?? shown}${total === null ? "" : ` of ${total}`}${coverage.truncated ? " (truncated)" : ""}`;
+}
+export function registerPagesTools(server, deps) {
+    const register = registrarFor(server);
+    register("scout_board", {
+        title: "Read the Tower Scout board",
+        description: "The experiment cards Scout is proposing, the ones already settled, and the raw signals behind them — plus "
+            + "the page's own standing sentences. Read only; moving a card is not on this surface.",
+        inputSchema: {
+            days: z.number().int().min(1).max(365).optional().describe("How many days of signals to look back over."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const params = new URLSearchParams();
+        if (typeof args.days === "number")
+            params.set("days", String(args.days));
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/cockpit/scout${queryString(params)}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("scout_board", response));
+        const board = (response.body.board ?? {});
+        const lines = (response.body.lines ?? {});
+        const experiments = board.experiments ?? [];
+        const settled = board.settled ?? [];
+        const signals = board.signals ?? [];
+        const said = [lines.watch, lines.headline, lines.quiet].filter(Boolean).join("\n");
+        const cards = experiments
+            .map((card) => `  ${card.id ?? "?"}  ${card.status ?? "?"}  ${card.title ?? ""}\n    ${card.claimSummary ?? ""}`)
+            .join("\n");
+        const settledCards = settled.map((card) => `  ${card.id ?? "?"}  ${card.title ?? ""}`).join("\n");
+        const rawSignals = signals.map((signal) => `  ${signal.source ?? "?"}  ${signal.title ?? ""}`).join("\n");
+        return textResult(`${said}\n\n${lines.waitingLabel ?? "OPEN"} — ${coverageWord(board.coverage?.openExperiments, experiments.length)}`
+            + `${cards ? `\n${cards}` : ""}`
+            + `\n\n${lines.settledLabel ?? "SETTLED"} — ${coverageWord(board.coverage?.settledExperiments, settled.length)}`
+            + `${settledCards ? `\n${settledCards}` : ""}`
+            + `\n\n${lines.rawWatchLabel ?? "SIGNALS"} — ${coverageWord(board.coverage?.signals, signals.length)}`
+            + `${rawSignals ? `\n${rawSignals}` : `\n  ${lines.rawWatchEmpty ?? ""}`}`, {
+            audience: response.body.audience ?? null,
+            windowDays: response.body.windowDays ?? board.windowDays ?? null,
+            board,
+            lines,
+        });
+    }));
+    register("workbook_read", {
+        title: "Read the Tower workbook",
+        description: "The per-project document library. With no arguments: every project and the documents in it. With `project` "
+            + "and `doc`: that document as markdown, rendered by the same walker the page uses.",
+        inputSchema: {
+            project: z.string().min(1).max(200).optional().describe("A project slug, as workbook_read lists it."),
+            doc: z.string().min(1).max(200).optional().describe("A document slug within that project. Needs `project` too."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const wantsDoc = Boolean(args.doc);
+        if (wantsDoc && !args.project) {
+            return errorResult("workbook_read needs `project` beside `doc` — a document slug is only unique within its project.");
+        }
+        const params = new URLSearchParams();
+        if (wantsDoc) {
+            params.set("project", String(args.project));
+            params.set("doc", String(args.doc));
+        }
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/cockpit/workbook${queryString(params)}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("workbook_read", response));
+        if (wantsDoc) {
+            const markdown = typeof response.body.markdown === "string" ? response.body.markdown : "";
+            if (markdown === "") {
+                return errorResult(`Tower answered workbook_read without a document for ${String(args.project)}/${String(args.doc)}.`);
+            }
+            return textResult(markdown, {
+                project: response.body.project ?? null,
+                doc: response.body.doc ?? null,
+                markdown,
+                sections: response.body.sections ?? [],
+            });
+        }
+        const projects = (Array.isArray(response.body.projects) ? response.body.projects : []);
+        // A named project that is not there is a refusal with the list beside
+        // it: an agent that guessed a slug can fix the guess in one step.
+        if (args.project) {
+            const found = projects.find((project) => project.slug === args.project);
+            if (!found) {
+                const known = projects.map((project) => project.slug ?? "").filter(Boolean);
+                return errorResult(`No project "${String(args.project)}" in the workbook library (${known.join(", ") || "none"}).`);
+            }
+            const docs = (found.docs ?? []).map((doc) => `  ${doc.slug ?? "?"}  ${doc.title ?? ""}`).join("\n");
+            return textResult(`${found.title ?? found.slug ?? ""}\n${found.line ?? ""}${docs ? `\n${docs}` : ""}`, { project: found });
+        }
+        const docCount = projects.reduce((count, project) => count + (project.docs?.length ?? 0), 0);
+        const lines = projects
+            .map((project) => {
+            const docs = (project.docs ?? []).map((doc) => `  ${doc.slug ?? "?"}  ${doc.title ?? ""}`).join("\n");
+            return `${(project.title ?? project.slug ?? "").toUpperCase()} (${project.slug ?? "?"})${docs ? `\n${docs}` : ""}`;
+        })
+            .join("\n\n");
+        return textResult(`WORKBOOK · ${projects.length} project(s) · ${docCount} document(s).${lines ? `\n\n${lines}` : ""}`, { projects });
+    }));
+}

package/dist/readme-census.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The README's verb table, rendered from the census (BLI-3756).
+ *
+ * `npm run mcp:readme` writes the output of `renderCensusMarkdown()` between
+ * the two markers below, and `readme-census.test.ts` fails when the committed
+ * README no longer matches — so the table a stranger reads and the map the
+ * suite polices cannot disagree. A table typed by hand beside a list of tools
+ * is a table that goes stale on the next batch; this one cannot.
+ *
+ * Pure: it reads the census (which reads the collector's own decision tables)
+ * and returns a string. No file writing here — that is the script's job, so
+ * this can be asserted without touching a disk.
+ */
+export declare const CENSUS_BEGIN = "<!-- BEGIN GENERATED verb census \u2014 `npm run mcp:readme` -->";
+export declare const CENSUS_END = "<!-- END GENERATED verb census -->";
+export declare function renderCensusMarkdown(): string;
+/** The README with a fresh census block spliced in. Throws if the markers are gone. */
+export declare function spliceCensus(readme: string): string;

package/dist/readme-census.js

@@ -0,0 +1,77 @@
+/**
+ * The README's verb table, rendered from the census (BLI-3756).
+ *
+ * `npm run mcp:readme` writes the output of `renderCensusMarkdown()` between
+ * the two markers below, and `readme-census.test.ts` fails when the committed
+ * README no longer matches — so the table a stranger reads and the map the
+ * suite polices cannot disagree. A table typed by hand beside a list of tools
+ * is a table that goes stale on the next batch; this one cannot.
+ *
+ * Pure: it reads the census (which reads the collector's own decision tables)
+ * and returns a string. No file writing here — that is the script's job, so
+ * this can be asserted without touching a disk.
+ */
+import { AWAITING_TWIN, MCP_TWINS, TERMINAL_ONLY, towerVerbs } from "./verb-census.js";
+export const CENSUS_BEGIN = "<!-- BEGIN GENERATED verb census — `npm run mcp:readme` -->";
+export const CENSUS_END = "<!-- END GENERATED verb census -->";
+/** `cockpit docs read` → `` `cockpit docs read` ``; `jarvis --trace` keeps its flag. */
+function spell(verb) {
+    return `\`cockpit ${verb}\``;
+}
+export function renderCensusMarkdown() {
+    // Every verb the collector's own tables name, plus the one hand-entered mode
+    // flag — in the same order the census sorts them, so a diff is readable.
+    const verbs = [...new Set([...towerVerbs().map((verb) => verb.spelling), ...Object.keys(MCP_TWINS)])].sort();
+    const twinRows = verbs
+        .filter((verb) => MCP_TWINS[verb])
+        .map((verb) => {
+        const twin = MCP_TWINS[verb];
+        return `| ${spell(verb)} | \`${twin.tool}\` | \`${twin.door}\` |`;
+    });
+    const owedRows = verbs
+        .filter((verb) => AWAITING_TWIN[verb])
+        .map((verb) => `| ${spell(verb)} | ${AWAITING_TWIN[verb]} |`);
+    const terminalRows = verbs
+        .filter((verb) => TERMINAL_ONLY[verb])
+        .map((verb) => `| ${spell(verb)} | ${TERMINAL_ONLY[verb]} |`);
+    return [
+        CENSUS_BEGIN,
+        "",
+        `**${twinRows.length} of ${twinRows.length + owedRows.length + terminalRows.length} 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 |",
+        "| --- | --- | --- |",
+        ...twinRows,
+        "",
+        "### Owed a twin",
+        "",
+        "This table should only ever shrink.",
+        "",
+        "| CLI verb | Who owes it, and why it is not built yet |",
+        "| --- | --- |",
+        ...owedRows,
+        "",
+        "### Terminal-only",
+        "",
+        "A claim about the verb's nature, not a backlog.",
+        "",
+        "| CLI verb | Why it can never have a twin |",
+        "| --- | --- |",
+        ...terminalRows,
+        "",
+        CENSUS_END,
+    ].join("\n");
+}
+/** The README with a fresh census block spliced in. Throws if the markers are gone. */
+export function spliceCensus(readme) {
+    const start = readme.indexOf(CENSUS_BEGIN);
+    const end = readme.indexOf(CENSUS_END);
+    if (start < 0 || end < 0) {
+        throw new Error(`README.md has no census markers. Put ${CENSUS_BEGIN} and ${CENSUS_END} back, or the generated table has nowhere to go.`);
+    }
+    return readme.slice(0, start) + renderCensusMarkdown() + readme.slice(end + CENSUS_END.length);
+}

package/dist/search-tool.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `tower_search` — one bar over five corpora, as an MCP tool (BLI-3728).
+ *
+ * The same `GET /api/search` door the browser's search bar and `cockpit
+ * search` press, over this machine's device token
+ * (`agent-door-session.ts`/`agent-door.ts`). Nothing about ranking, scoping or
+ * snippets is decided here; this file turns one HTTP answer into one tool
+ * result.
+ *
+ * WHY IT IS ONE TOOL AND NOT FIVE
+ * -------------------------------
+ * `docs_list`, `msg_read` and the rest already exist and answer "show me this
+ * corpus". The question this tool answers is different and is the reason the
+ * ticket exists: "where in Tower is the thing I half-remember?" A model that
+ * has to pick a corpus before it can look has already been asked to know the
+ * answer. `kinds` narrows it when the model DOES know.
+ *
+ * Its result carries provenance, and that is not decoration: every hit says
+ * which corpus produced it, what its address is, and — for the corpora that
+ * could not answer — that they did not. A tool result that folds "messages
+ * failed" into "no messages matched" invites the model to report the record as
+ * silent when nobody asked it. That is the same rule the door, the CLI and the
+ * browser overlay all keep.
+ */
+import { loadAgentDoorSession } from "./agent-door-session.js";
+import { type FetchImpl } from "./agent-door.js";
+export interface SearchToolDeps {
+    fetchImpl: FetchImpl;
+    /** Injectable for tests; defaults to reading `~/.config/bli-cockpit/session.json`. */
+    loadSession?: typeof loadAgentDoorSession;
+}
+interface SearchHit {
+    kind: string;
+    id: string;
+    title: string;
+    snippet: string;
+    date: string | null;
+    author: string | null;
+    href: string | null;
+    score: number;
+    channels: string[];
+}
+export declare function registerSearchTool(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: SearchToolDeps): void;
+/**
+ * The sentence a model reads.
+ *
+ * Every line carries its own provenance — corpus, address, author, date — so a
+ * model quoting a result can cite it without a second call, and so a `Source:`
+ * line in its answer is copied rather than invented.
+ */
+export declare function renderHits(query: string, hits: readonly SearchHit[], failures: Record<string, string>): string;
+export {};