@bli-cockpit/mcp 0.1.2 → 0.1.4

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

@@ -0,0 +1,34 @@
+/**
+ * `notes_upload` / `notes_paste` / `notes_share` / `notes_unshare` /
+ * `notes_move` MCP tools (BLI-3756 batch 2) — putting a meeting note in,
+ * sharing it, taking it back and moving it to another shelf, over the same
+ * `/api/notes/**` doors `cockpit notes` calls with the same device token.
+ *
+ * Reads live in `notes-tools.ts`. Three rules this half keeps.
+ *
+ * **The local screen runs before the network, on the name first.** A path is
+ * refused for a secret-shaped NAME without its bytes ever being read, then for
+ * being missing, unreadable, empty or over 20 MB — the same four checks and
+ * the same sentences as `commands/notes-file.ts`, because the server's own
+ * guard is the authority and this only avoids spending a round trip on a file
+ * it is certain to refuse. If the two ever disagree, the server wins.
+ *
+ * **Sharing is deliberate.** `cockpit notes share` asks before it acts unless
+ * `--yes` is passed; a client has no keyboard, so `confirm: true` is the whole
+ * of that gate here and a share without it is refused in the CLI's own words.
+ * Taking a note BACK narrows who can read it, and nobody needs to be talked
+ * out of that — `notes_unshare` asks for nothing, exactly as the CLI does not.
+ *
+ * **A slow door is named, not hidden.** `/api/notes/upload` reads the whole
+ * note with one model call and is budgeted to 300 seconds server-side; this
+ * waits slightly longer so the server's named failure wins the race whenever
+ * it manages to send one. An MCP client's own deadline may still be shorter —
+ * the description says so rather than letting a cut call read as a refusal.
+ */
+import { type ToolDeps } from "./tool-result.js";
+export type NotesWriteDeps = ToolDeps;
+/** Mirrors `UPLOADED_NOTE_MAX_BYTES`; a courtesy check, not a second authority. */
+export declare const NOTE_FILE_MAX_BYTES: number;
+export declare function registerNotesWriteTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: NotesWriteDeps): void;

package/dist/notes-write-tools.js

@@ -0,0 +1,211 @@
+/**
+ * `notes_upload` / `notes_paste` / `notes_share` / `notes_unshare` /
+ * `notes_move` MCP tools (BLI-3756 batch 2) — putting a meeting note in,
+ * sharing it, taking it back and moving it to another shelf, over the same
+ * `/api/notes/**` doors `cockpit notes` calls with the same device token.
+ *
+ * Reads live in `notes-tools.ts`. Three rules this half keeps.
+ *
+ * **The local screen runs before the network, on the name first.** A path is
+ * refused for a secret-shaped NAME without its bytes ever being read, then for
+ * being missing, unreadable, empty or over 20 MB — the same four checks and
+ * the same sentences as `commands/notes-file.ts`, because the server's own
+ * guard is the authority and this only avoids spending a round trip on a file
+ * it is certain to refuse. If the two ever disagree, the server wins.
+ *
+ * **Sharing is deliberate.** `cockpit notes share` asks before it acts unless
+ * `--yes` is passed; a client has no keyboard, so `confirm: true` is the whole
+ * of that gate here and a share without it is refused in the CLI's own words.
+ * Taking a note BACK narrows who can read it, and nobody needs to be talked
+ * out of that — `notes_unshare` asks for nothing, exactly as the CLI does not.
+ *
+ * **A slow door is named, not hidden.** `/api/notes/upload` reads the whole
+ * note with one model call and is budgeted to 300 seconds server-side; this
+ * waits slightly longer so the server's named failure wins the race whenever
+ * it manages to send one. An MCP client's own deadline may still be shorter —
+ * the description says so rather than letting a cut call read as a refusal.
+ */
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { isSecretLikePathSegment } from "@bli-cockpit/telemetry-core";
+import { z } from "zod";
+import { callAgentDoor } from "./agent-door.js";
+import { CONFIRM_INPUT, doorFailureText, errorResult, registrarFor, textResult, unconfirmed, withSession, } from "./tool-result.js";
+/** Mirrors `UPLOADED_NOTE_MAX_BYTES`; a courtesy check, not a second authority. */
+export const NOTE_FILE_MAX_BYTES = 20 * 1024 * 1024;
+/** The route's own ceiling is 300 s. Wait past it so its sentence wins. */
+const UPLOAD_DEADLINE_MS = 305_000;
+const WRITE_DEADLINE_MS = 60_000;
+const PASTE_MAX_CHARS = 2_000_000;
+/** The sentence the CLI prints for a refusal caught locally, kept word for word. */
+function refusalSentence(refusal, filePath) {
+    switch (refusal) {
+        case "file_not_found":
+            return `I could not find that file: ${filePath}`;
+        case "file_unreadable":
+            return `I could not read that file: ${filePath}`;
+        case "file_empty":
+            return `There is nothing in that file: ${filePath}`;
+        case "file_too_big":
+            return "That file is too big to put in as a note — keep it under 20 MB.";
+        case "looks_like_a_key_file":
+            // The same rule the server's gate applies, said the same way: the name
+            // is all it takes to decide, and looking inside to be sure would already
+            // be the thing the rule forbids.
+            return `That name looks like a key or credential file, so I did not open it: ${filePath}`;
+    }
+}
+/** Reads and locally screens one note file. Never throws. */
+async function readNoteFile(filePath) {
+    const fileName = path.basename(filePath);
+    const refuse = (refusal) => ({
+        ok: false,
+        refusal,
+        sentence: refusalSentence(refusal, filePath),
+    });
+    if (isSecretLikePathSegment(fileName))
+        return refuse("looks_like_a_key_file");
+    let size;
+    try {
+        const info = await stat(filePath);
+        if (!info.isFile())
+            return refuse("file_unreadable");
+        size = info.size;
+    }
+    catch (error) {
+        return refuse(error.code === "ENOENT" ? "file_not_found" : "file_unreadable");
+    }
+    if (size === 0)
+        return refuse("file_empty");
+    if (size > NOTE_FILE_MAX_BYTES)
+        return refuse("file_too_big");
+    try {
+        return { ok: true, bytes: await readFile(filePath), fileName };
+    }
+    catch {
+        return refuse("file_unreadable");
+    }
+}
+/** The route's own words for what happened. Never rephrased here. */
+function saidByTower(body) {
+    const said = [body.headline ?? "Tower answered without a sentence.", ...(body.lines ?? [])];
+    if (body.noteId)
+        said.push(`Note id: ${body.noteId}`);
+    return said.join("\n");
+}
+async function postForm(deps, session, tool, form) {
+    const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/notes/upload", form, UPLOAD_DEADLINE_MS);
+    if (!response.ok)
+        return errorResult(doorFailureText(tool, response));
+    const body = response.body;
+    const text = saidByTower(body);
+    // `stored: false` is the door saying it did not keep the note. That is a
+    // refusal with a reason, not a success with a caveat.
+    return body.stored === true
+        ? textResult(text, { ok: true, noteId: body.noteId ?? null, scope: body.scope ?? null })
+        : errorResult(text);
+}
+export function registerNotesWriteTools(server, deps) {
+    const register = registrarFor(server);
+    register("notes_upload", {
+        title: "Put a local file in as a Tower meeting note",
+        description: "Uploads a transcript or note file from THIS machine's disk — the same door `cockpit notes upload` uses. "
+            + "A name that looks like a key or credential file is refused without being opened; so is a missing, empty or "
+            + "over-20-MB file. Tower reads the whole note with one model call, so a large file can take a couple of "
+            + "minutes and your client may give up first — the upload keeps going; notes_list will show it.",
+        inputSchema: {
+            path: z.string().min(1).max(4096).describe("An absolute path on this machine."),
+            exclude: z
+                .string()
+                .min(1)
+                .max(2000)
+                .optional()
+                .describe("Anything in the note to leave out, in plain words — forwarded to the reader verbatim."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const filePath = String(args.path ?? "");
+        const read = await readNoteFile(filePath);
+        if (!read.ok)
+            return errorResult(`Refused (${read.refusal}): ${read.sentence} Nothing was sent.`);
+        const form = new FormData();
+        form.set("file", new File([new Uint8Array(read.bytes)], read.fileName));
+        if (args.exclude)
+            form.set("exclusions", String(args.exclude));
+        return postForm(deps, session, "notes_upload", form);
+    }));
+    register("notes_paste", {
+        title: "Put text in as a Tower meeting note",
+        description: "Stores text you already have as a meeting note — the same door as notes_upload, which is what "
+            + "`cockpit notes paste` posts to. The CLI takes the body on stdin; here it is an argument, so the text "
+            + "travels in the request and is never echoed back to you.",
+        inputSchema: {
+            text: z.string().min(1).max(PASTE_MAX_CHARS).describe("The note itself."),
+            name: z.string().min(1).max(300).optional().describe("What to call it. Tower names it by date if you do not."),
+            exclude: z.string().min(1).max(2000).optional().describe("Anything to leave out, in plain words."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const text = String(args.text ?? "");
+        if (text.trim() === "") {
+            return errorResult("Refused (empty_paste): there was nothing to paste. Nothing was sent.");
+        }
+        const form = new FormData();
+        form.set("text", text);
+        if (args.name)
+            form.set("name", String(args.name));
+        if (args.exclude)
+            form.set("exclusions", String(args.exclude));
+        return postForm(deps, session, "notes_paste", form);
+    }));
+    register("notes_share", {
+        title: "Share a Tower meeting note with the team",
+        description: "Lets everyone signed in read one note. Deliberate: refused without `confirm: true`, the same rule as the "
+            + "CLI's --yes. Use notes_unshare to take it back.",
+        inputSchema: {
+            note_id: z.string().min(1).max(200).describe("A note id, as notes_list or notes_shelf reports it."),
+            confirm: CONFIRM_INPUT,
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const refusal = unconfirmed(args, "Sharing a note lets everyone signed in read it. Pass confirm: true to do it without being asked.");
+        if (refusal)
+            return refusal;
+        return shareCall(deps, session, args, true);
+    }));
+    register("notes_unshare", {
+        title: "Take a shared Tower note back",
+        description: "Makes one note yours again. No confirmation: taking a note back narrows who can read it, and nobody needs "
+            + "to be talked out of that — the same asymmetry `cockpit notes unshare` has.",
+        inputSchema: { note_id: z.string().min(1).max(200).describe("A note id.") },
+    }, async (args) => withSession(deps, async (session) => shareCall(deps, session, args, false)));
+    register("notes_move", {
+        title: "Move a Tower meeting note to another shelf",
+        description: "Puts one note on a different shelf, or clears its shelf with `clear: true` — the empty string the browser's "
+            + "own move box sends. A shelf is free text; notes_shelves lists the ones in use.",
+        inputSchema: {
+            note_id: z.string().min(1).max(200).describe("A note id."),
+            to: z.string().min(1).max(200).optional().describe("The shelf to move it to."),
+            clear: z.boolean().optional().describe("Take it off every shelf instead."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const clearing = args.clear === true;
+        if (!clearing && !args.to) {
+            return errorResult("Refused (no_destination): say which shelf with `to`, or pass `clear: true`. Nothing was moved.");
+        }
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/notes/move", { note_id: String(args.note_id ?? ""), category: clearing ? "" : String(args.to) }, WRITE_DEADLINE_MS);
+        if (!response.ok)
+            return errorResult(doorFailureText("notes_move", response));
+        const body = response.body;
+        const text = [body.headline ?? "Tower answered without a sentence.", ...(body.lines ?? [])].join("\n");
+        return body.ok === true
+            ? textResult(text, { ok: true, shelf: body.shelf ?? null })
+            : errorResult(text);
+    }));
+}
+/** Share and unshare are one door and one body; only the boolean differs. */
+async function shareCall(deps, session, args, share) {
+    const tool = share ? "notes_share" : "notes_unshare";
+    const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/notes/share", { note_id: String(args.note_id ?? ""), share }, WRITE_DEADLINE_MS);
+    if (!response.ok)
+        return errorResult(doorFailureText(tool, response));
+    const body = response.body;
+    return textResult(saidByTower(body), { ok: true, shared: share, noteId: body.noteId ?? null });
+}

package/dist/ops-tools.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `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` (BLI-3756 batch 2) is the one write here: it spends a model
+ * call, so it is the only tool in this file that can cost money, and the only
+ * one whose failure can leave the effect UNKNOWN rather than known.
+ */
+import { type ToolDeps } from "./tool-result.js";
+export type OpsDeps = ToolDeps;
+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,212 @@
+/**
+ * `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` (BLI-3756 batch 2) is the one write here: it spends a model
+ * call, so it is the only tool in this file that can cost money, and the only
+ * one whose failure can leave the effect UNKNOWN rather than known.
+ */
+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.
+ */
+/**
+ * A whole compile, plus a little. `maxDuration` on `/api/ops/recompile` is 800
+ * seconds; waiting slightly past it is what lets this tool tell "Tower gave up"
+ * from "the network did", instead of hanging up first and blaming the wrong
+ * one. A client with a shorter deadline of its own will cut the call first —
+ * the description says so.
+ */
+const RECOMPILE_DEADLINE_MS = 830_000;
+const TOWER_RECOMPILE_CEILING_SECONDS = 800;
+export const UNHEALTHY_VERDICTS = new Set([
+    "stale",
+    "never_produced",
+    "unreadable",
+    "failing",
+    // BLI-3762: a job that wrote less than it owed is not healthy. Amber counts.
+    "degraded",
+]);
+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,
+        });
+    }));
+    register("ops_recompile", {
+        title: "Write one person's Tower page again",
+        description: "Compiles a daily page on demand — `cockpit ops recompile`, same door. It SPENDS A MODEL CALL and takes "
+            + "several minutes; pass `dry_run: true` to resolve the person and see which page is being served without "
+            + "compiling anything. Your own page always; anybody else's is admin only, decided on the server. Tower's own "
+            + "budget is 800 seconds — if that runs out the effect is UNKNOWN, not failed, and this says so.",
+        inputSchema: {
+            person: z.string().min(1).max(200).describe("An email, a display name, or a person id."),
+            dry_run: z.boolean().optional().describe("Resolve the person and read the current page; compile nothing."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const dryRun = args.dry_run === true;
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/ops/recompile", { person: String(args.person ?? ""), dryRun }, RECOMPILE_DEADLINE_MS);
+        if (!response.ok) {
+            // The ceiling is its own outcome, and its effect is UNKNOWN rather
+            // than failed: the compile may well have finished after the
+            // connection was cut. Said in the CLI's own words, because a caller
+            // told "it failed" would reasonably ask for it again and pay twice.
+            if (response.transportError) {
+                return errorResult(`Refused (recompile_ceiling_exceeded): Tower's ${TOWER_RECOMPILE_CEILING_SECONDS}-second budget for one `
+                    + "recompile ran out before it answered. That is not the same as the compile failing: it may have "
+                    + "finished after the connection was cut. Call brief_read for that person to see which page is being "
+                    + "served now.");
+            }
+            return errorResult(doorFailureText("ops_recompile", response));
+        }
+        const body = response.body;
+        const status = typeof body["status"] === "string" ? body["status"] : "compiled";
+        const displayName = typeof body["displayName"] === "string" ? body["displayName"] : String(args.person ?? "");
+        const pageId = typeof body["pageId"] === "string" ? body["pageId"] : null;
+        if (status === "dry_run") {
+            const latest = typeof body["latestPageId"] === "string" ? body["latestPageId"] : null;
+            return textResult(`${displayName} is on the roster.\n`
+                + (latest
+                    ? `The page being served for them right now is ${latest}.`
+                    : "Nothing has ever been written for them.")
+                + "\nNothing was compiled — this was a dry run.", body);
+        }
+        return textResult(`Wrote ${displayName}'s page again: ${pageId ?? "(no id returned)"}\n`
+            + (body["isNowLive"] === true
+                ? "It is the page being served now."
+                : "It is NOT the page being served: a scheduled compile is stamped for a later delivery window, so that "
+                    + "one still wins. Nothing was lost — this is a new version alongside it."), body);
+    }));
+}

package/dist/pages-tools.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `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 (`scout_start`/`scout_dismiss`/`scout_undo`, BLI-3756
+ * batch 2) is super_admin server-side, so those three RELAY a decision rather
+ * than making one — and each reads the board first, so an id is matched
+ * exactly against cards that exist and a refusal still hands back the read.
+ */
+import { type ToolDeps } from "./tool-result.js";
+export type PagesDeps = ToolDeps;
+export declare function registerPagesTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: PagesDeps): void;
+/** The three verbs `cockpit scout` has beyond reading the board. */
+export declare const SCOUT_ACTIONS: readonly ["start", "dismiss", "undo"];