@bli-cockpit/mcp 0.1.1 → 0.1.3

package/dist/settings-tools.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `settings_*` / `team_*` / `model_show` MCP tools (BLI-3756) — the settings
+ * surface read by an agent, over the same `/api/settings/*` and `/api/team/*`
+ * doors `cockpit settings`, `cockpit team` and `cockpit model` call with the
+ * same device token.
+ *
+ * One file because the dashboard has one owner for all of it (`lib/settings/`
+ * behind `settings-gate.ts`, which the team directory and the model shorthand
+ * both sit behind), and because the reads share the rule below.
+ *
+ * **"Admin only" is not an error.** A 403 on a section is the system working;
+ * `settings_show` renders it as one line saying so and keeps every other
+ * section, exactly as the CLI does. Returning `isError` for the whole call
+ * would teach an agent that the surface is broken when in fact it is simply
+ * not this caller's to see.
+ *
+ * **A secret never comes back.** `settings_list` lists env-blob NAMES, sizes
+ * and stamps — the server cannot return a value and nothing here asks for one.
+ * Writing content is stdin-only by rule and stays in batch 2.
+ */
+import { type ToolDeps } from "./tool-result.js";
+export type SettingsDeps = ToolDeps;
+/** The sections `cockpit settings [section]` reads, plus the all-at-once view. */
+export declare const SETTINGS_SECTIONS: readonly ["overview", "personal", "switches", "models", "cli-floor"];
+export declare function registerSettingsTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: SettingsDeps): void;
+/** `provider:model`, or `unset`. The same rendering `cockpit model show` prints. */
+export declare function modelKeyOf(value: unknown): string;

package/dist/settings-tools.js

@@ -0,0 +1,151 @@
+/**
+ * `settings_*` / `team_*` / `model_show` MCP tools (BLI-3756) — the settings
+ * surface read by an agent, over the same `/api/settings/*` and `/api/team/*`
+ * doors `cockpit settings`, `cockpit team` and `cockpit model` call with the
+ * same device token.
+ *
+ * One file because the dashboard has one owner for all of it (`lib/settings/`
+ * behind `settings-gate.ts`, which the team directory and the model shorthand
+ * both sit behind), and because the reads share the rule below.
+ *
+ * **"Admin only" is not an error.** A 403 on a section is the system working;
+ * `settings_show` renders it as one line saying so and keeps every other
+ * section, exactly as the CLI does. Returning `isError` for the whole call
+ * would teach an agent that the surface is broken when in fact it is simply
+ * not this caller's to see.
+ *
+ * **A secret never comes back.** `settings_list` lists env-blob NAMES, sizes
+ * and stamps — the server cannot return a value and nothing here asks for one.
+ * Writing content is stdin-only by rule and stays in batch 2.
+ */
+import { z } from "zod";
+import { callAgentDoor } from "./agent-door.js";
+import { doorFailureText, errorResult, registrarFor, textResult, withSession, } from "./tool-result.js";
+/** The sections `cockpit settings [section]` reads, plus the all-at-once view. */
+export const SETTINGS_SECTIONS = ["overview", "personal", "switches", "models", "cli-floor"];
+/** Which door each section is behind. The overview reads all of them at once. */
+const SECTION_DOORS = {
+    personal: "/api/settings/personal",
+    switches: "/api/settings/switches",
+    models: "/api/settings/model-routing",
+    "cli-floor": "/api/settings/cli-floor",
+    env: "/api/settings/env-blobs",
+    team: "/api/team/members",
+};
+/**
+ * A section's answer, or the reason it is absent. `admin_only` is deliberately
+ * its own label and not an error — see the header.
+ */
+function sectionPayload(response, door) {
+    if (response.ok)
+        return response.body;
+    if (response.status === 403)
+        return { visible: false, reason: "admin_only" };
+    return { visible: false, reason: doorFailureText(door, response) };
+}
+function sectionWord(response) {
+    if (response.ok)
+        return "ok";
+    return response.status === 403 ? "admin only" : "unavailable";
+}
+async function readSection(deps, session, path) {
+    return callAgentDoor(session, deps.fetchImpl, "GET", path);
+}
+async function oneSection(deps, session, tool, path) {
+    const response = await readSection(deps, session, path);
+    if (!response.ok)
+        return errorResult(doorFailureText(tool, response));
+    return textResult(JSON.stringify(response.body, null, 2), response.body);
+}
+export function registerSettingsTools(server, deps) {
+    const register = registrarFor(server);
+    register("settings_show", {
+        title: "Read Tower settings",
+        description: "Settings as this caller may see them. `overview` (the default) reads all six sections at once and names any "
+            + "you may not see as \"admin only\" rather than failing; a named section reads just that one. Never a secret's "
+            + "value — settings_list lists env files by name only.",
+        inputSchema: {
+            section: z.enum(SETTINGS_SECTIONS).optional().describe("Defaults to overview — everything at once."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const section = String(args.section ?? "overview");
+        if (section !== "overview") {
+            const path = SECTION_DOORS[section];
+            if (!path)
+                return errorResult(`settings_show has no section "${section}".`);
+            return oneSection(deps, session, "settings_show", path);
+        }
+        // The six reads go out together: they are independent, and six
+        // sequential round trips would read as a hang.
+        const keys = ["personal", "team", "switches", "models", "env", "cli-floor"];
+        const responses = await Promise.all(keys.map((key) => readSection(deps, session, SECTION_DOORS[key])));
+        const byKey = Object.fromEntries(keys.map((key, index) => [key, responses[index]]));
+        // The one read every signed-in person is entitled to. If THAT is
+        // refused for any reason other than permission, nothing else here is
+        // going to work either, so say so once and stop.
+        const personal = byKey.personal;
+        if (!personal.ok && personal.status !== 403) {
+            return errorResult(doorFailureText("settings_show", personal));
+        }
+        const lines = keys
+            .map((key) => `${key.padEnd(10)}  ${sectionWord(byKey[key])}`)
+            .join("\n");
+        const payload = Object.fromEntries(keys.map((key) => [key, sectionPayload(byKey[key], `settings ${key}`)]));
+        return textResult(`TOWER SETTINGS\n${lines}\n\n${JSON.stringify(payload, null, 2)}`, payload);
+    }));
+    register("settings_list", {
+        title: "List Tower env files",
+        description: "The env files Tower holds: name, size and when each was last written. The server cannot return a value and "
+            + "this tool has no way to ask for one — content is write-only, on stdin, through the CLI.",
+        inputSchema: {},
+    }, async () => withSession(deps, async (session) => oneSection(deps, session, "settings_list", SECTION_DOORS.env)));
+    register("model_show", {
+        title: "Which model is answering",
+        description: "The chat and brief models in force for this account — the short way to read `settings personal`, because "
+            + "\"which model am I talking to?\" is the question people actually ask.",
+        inputSchema: {},
+    }, async () => withSession(deps, async (session) => {
+        const response = await readSection(deps, session, "/api/settings/jarvis-model");
+        if (!response.ok)
+            return errorResult(doorFailureText("model_show", response));
+        return textResult(`chat model:  ${modelKeyOf(response.body.chatModel)}\nbrief model: ${modelKeyOf(response.body.briefModel)}`, response.body);
+    }));
+    register("team_members", {
+        title: "Read the Tower team directory",
+        description: "Who is on this team, their roles, and any invitations still open.",
+        inputSchema: {},
+    }, async () => withSession(deps, async (session) => {
+        const response = await readSection(deps, session, "/api/team/members");
+        if (!response.ok)
+            return errorResult(doorFailureText("team_members", response));
+        const members = (Array.isArray(response.body.members) ? response.body.members : []);
+        const lines = members
+            .map((member) => `${String(member.role ?? "?").padEnd(12)}  ${String(member.email ?? member.userId ?? "?")}`)
+            .join("\n");
+        return textResult(`${members.length} member(s).${lines ? `\n${lines}` : ""}`, response.body);
+    }));
+    register("team_device_list", {
+        title: "List the collector devices Tower knows",
+        description: "Every paired collector device: id, name, owner, version and when it last checked in. Read only — revoking "
+            + "one is irreversible for that token and stays a deliberate act.",
+        inputSchema: {},
+    }, async () => withSession(deps, async (session) => {
+        const response = await readSection(deps, session, "/api/team/devices");
+        if (!response.ok)
+            return errorResult(doorFailureText("team_device_list", response));
+        const devices = (Array.isArray(response.body.devices) ? response.body.devices : []);
+        const lines = devices
+            .map((device) => `${String(device.device_id ?? "?")}  ${String(device.device_name ?? "?")}  `
+            + `${String(device.cli_version ?? "?")}  last seen ${String(device.last_seen_at ?? "never")}`)
+            .join("\n");
+        return textResult(`${devices.length} device(s).${lines ? `\n${lines}` : ""}`, response.body);
+    }));
+}
+/** `provider:model`, or `unset`. The same rendering `cockpit model show` prints. */
+export function modelKeyOf(value) {
+    const pair = value && typeof value === "object" ? value : {};
+    if (typeof pair.provider === "string" && typeof pair.model === "string") {
+        return `${pair.provider}:${pair.model}`;
+    }
+    return "unset";
+}

package/dist/tool-result.d.ts

@@ -0,0 +1,70 @@
+/**
+ * What every agent-door tool on this server needs, written once (BLI-3756).
+ *
+ * `docs-msg-tools.ts` and `work-tools.ts` each carried their own copy of these
+ * four helpers. Batch 1 of the MCP twin build added five more surfaces, and
+ * seven copies of "what does a refused door say?" is seven places for the
+ * answer to drift — so the copies became this module and nothing else decides
+ * how a tool names a refusal.
+ *
+ * The one rule worth stating out loud: **a refusal keeps the DOOR's own
+ * words.** The reason label and the sentence are both computed on the server,
+ * where the outcome is known, and relayed here verbatim. A second wording in
+ * this package would be a second thing to keep in step, and the agent reading
+ * it would have no way to tell which one was true.
+ */
+import { loadAgentDoorSession } from "./agent-door-session.js";
+import type { AgentDoorResponse, FetchImpl } from "./agent-door.js";
+/** Everything a tool family needs to reach Tower. Injectable for the suites. */
+export interface ToolDeps {
+    fetchImpl: FetchImpl;
+    /** Injectable for tests; defaults to reading `~/.config/bli-cockpit/session.json`. */
+    loadSession?: typeof loadAgentDoorSession;
+}
+/** What an MCP tool hands back. Narrower than the SDK's type, on purpose. */
+export interface ToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+}
+export interface DoorSession {
+    dashboardUrl: string;
+    deviceToken: string;
+}
+export declare function textResult(text: string, structured?: Record<string, unknown>): ToolResult;
+export declare function errorResult(text: string): ToolResult;
+/**
+ * The session is loaded fresh per call (a cheap file read) rather than once at
+ * server startup: this package still serves the legacy event-stream tools on a
+ * machine with no collector pairing at all, so a missing session must fail the
+ * ONE call that needed it, by name, and never the whole process.
+ */
+export declare function withSession(deps: ToolDeps, run: (session: DoorSession) => Promise<ToolResult>): Promise<ToolResult>;
+/**
+ * The door's own reason label and its own sentence.
+ *
+ * Two answer shapes are read because two exist on the server and both are
+ * deliberate: the ingest-style routes answer `{reason, message}`, while every
+ * `/api/notes/**` door answers in the shape the BROWSER renders — a `headline`
+ * plus `lines` — because the page and the terminal read the same body
+ * (`commands/notes-door.ts` says why). Reading both here rather than
+ * rephrasing either keeps one meaning per field.
+ */
+export declare function doorFailureText(door: string, response: AgentDoorResponse): string;
+/** The label a script should branch on. `unknown_error` only when the door named none. */
+export declare function doorReason(body: Record<string, unknown>): string;
+/** The `registerTool` signature this package's tools actually use. */
+export type RegisterTool = (name: string, config: {
+    title: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}, handler: (args: Record<string, unknown>) => Promise<ToolResult>) => unknown;
+/** The one cast, so no tool family repeats it. */
+export declare function registrarFor(server: {
+    registerTool: (...args: never[]) => unknown;
+}): RegisterTool;
+/** `?a=1&b=2`, or "" when nothing was asked for. Never a bare `?`. */
+export declare function queryString(params: URLSearchParams): string;

package/dist/tool-result.js

@@ -0,0 +1,79 @@
+/**
+ * What every agent-door tool on this server needs, written once (BLI-3756).
+ *
+ * `docs-msg-tools.ts` and `work-tools.ts` each carried their own copy of these
+ * four helpers. Batch 1 of the MCP twin build added five more surfaces, and
+ * seven copies of "what does a refused door say?" is seven places for the
+ * answer to drift — so the copies became this module and nothing else decides
+ * how a tool names a refusal.
+ *
+ * The one rule worth stating out loud: **a refusal keeps the DOOR's own
+ * words.** The reason label and the sentence are both computed on the server,
+ * where the outcome is known, and relayed here verbatim. A second wording in
+ * this package would be a second thing to keep in step, and the agent reading
+ * it would have no way to tell which one was true.
+ */
+import { loadAgentDoorSession } from "./agent-door-session.js";
+export function textResult(text, structured) {
+    return { content: [{ type: "text", text }], ...(structured ? { structuredContent: structured } : {}) };
+}
+export function errorResult(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+/**
+ * The session is loaded fresh per call (a cheap file read) rather than once at
+ * server startup: this package still serves the legacy event-stream tools on a
+ * machine with no collector pairing at all, so a missing session must fail the
+ * ONE call that needed it, by name, and never the whole process.
+ */
+export async function withSession(deps, run) {
+    const loadSession = deps.loadSession ?? loadAgentDoorSession;
+    const loaded = loadSession();
+    if (!loaded.ok) {
+        return errorResult(`This machine is not paired with Tower (${loaded.reason}). ${loaded.message}`);
+    }
+    return run(loaded.session);
+}
+/**
+ * The door's own reason label and its own sentence.
+ *
+ * Two answer shapes are read because two exist on the server and both are
+ * deliberate: the ingest-style routes answer `{reason, message}`, while every
+ * `/api/notes/**` door answers in the shape the BROWSER renders — a `headline`
+ * plus `lines` — because the page and the terminal read the same body
+ * (`commands/notes-door.ts` says why). Reading both here rather than
+ * rephrasing either keeps one meaning per field.
+ */
+export function doorFailureText(door, response) {
+    if (response.transportError) {
+        return `Tower could not be reached for ${door} (${response.transportError}). Nothing was read or written.`;
+    }
+    return `Tower refused ${door} (${doorReason(response.body)}): ${doorSentence(response.body, response.status)}`;
+}
+/** The label a script should branch on. `unknown_error` only when the door named none. */
+export function doorReason(body) {
+    for (const key of ["reason", "error", "code"]) {
+        const value = body[key];
+        if (typeof value === "string" && value.trim() !== "")
+            return value;
+    }
+    return "unknown_error";
+}
+function doorSentence(body, status) {
+    const headline = typeof body["headline"] === "string" ? body["headline"] : null;
+    const message = typeof body["message"] === "string" ? body["message"] : null;
+    const lines = Array.isArray(body["lines"])
+        ? body["lines"].filter((line) => typeof line === "string")
+        : [];
+    const said = [headline ?? message, ...lines].filter(Boolean);
+    return said.length > 0 ? said.join(" ") : `Tower answered ${status}.`;
+}
+/** The one cast, so no tool family repeats it. */
+export function registrarFor(server) {
+    return server.registerTool.bind(server);
+}
+/** `?a=1&b=2`, or "" when nothing was asked for. Never a bare `?`. */
+export function queryString(params) {
+    const rendered = params.toString();
+    return rendered === "" ? "" : `?${rendered}`;
+}

package/dist/verb-census.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Every `cockpit <noun> <verb>` that talks to Tower, read off the collector's
+ * own decision tables (BLI-3732).
+ *
+ * This is a test helper with no runtime consumer, kept out of the suite file
+ * so the census itself — the three lists a person actually reviews — reads as
+ * a list and not as a parser. It reads SOURCE TEXT rather than importing the
+ * collector, because this package declares no dependency on it (the same
+ * reason `agent-door-session.ts` copies a session reader instead of importing
+ * one).
+ *
+ * ## Where each half comes from
+ *
+ * - The NOUNS are the `parse<Noun>Args` functions `local-args-tower.ts`
+ *   re-exports. That file is the authoritative "these are the commands that
+ *   talk to Tower" table — its siblings are a filing decision, not a contract.
+ * - The VERBS are each noun's `action:` union in `LocalCommand`
+ *   (`local-args.ts`), with an `XAction` alias resolved from whichever
+ *   `local-args-tower-*.ts` declares it. A noun with no `action` field is one
+ *   verb wearing the noun's own name (`jarvis`, `correct`, `workbook`).
+ *
+ * ## What it deliberately does NOT see
+ *
+ * Mode FLAGS. `cockpit jarvis --trace`, `--threads` and `--history` are three
+ * different acts behind one noun, and no decision table calls them verbs, so
+ * the mechanical rule cannot find them. They are covered by hand in the
+ * census's own twin map (`jarvis --trace` → `jarvis_trace`); a flag that grows
+ * into a verb will show up here the moment it becomes an `action`.
+ */
+export declare const COLLECTOR_COMMANDS_DIR: string;
+export interface TowerVerb {
+    noun: string;
+    /** The action word, or "" for a noun that is its own single verb. */
+    action: string;
+    /** How a person types it: `docs read`, or just `jarvis`. */
+    spelling: string;
+}
+/** `parseJarvisArgs` → `jarvis`. The re-export table IS the noun list. */
+export declare function towerNouns(): string[];
+/** Every Tower verb a person may type today. */
+export declare function towerVerbs(): TowerVerb[];
+export interface McpTwin {
+    /** The MCP tool name. Must actually be registered — the suite checks. */
+    tool: string;
+    /** The API door it goes through: the SAME one the CLI verb calls. */
+    door: string;
+}
+/** A CLI verb and the MCP tool that does the same thing, over the same door. */
+export declare const MCP_TWINS: Record<string, McpTwin>;
+/** Verbs that can never have an MCP twin, and why. A claim, not a backlog. */
+export declare const TERMINAL_ONLY: Record<string, string>;
+/** Verbs owed a twin, with who owes it. This list should only ever shrink. */
+export declare const AWAITING_TWIN: Record<string, string>;

package/dist/verb-census.js

@@ -0,0 +1,201 @@
+/**
+ * Every `cockpit <noun> <verb>` that talks to Tower, read off the collector's
+ * own decision tables (BLI-3732).
+ *
+ * This is a test helper with no runtime consumer, kept out of the suite file
+ * so the census itself — the three lists a person actually reviews — reads as
+ * a list and not as a parser. It reads SOURCE TEXT rather than importing the
+ * collector, because this package declares no dependency on it (the same
+ * reason `agent-door-session.ts` copies a session reader instead of importing
+ * one).
+ *
+ * ## Where each half comes from
+ *
+ * - The NOUNS are the `parse<Noun>Args` functions `local-args-tower.ts`
+ *   re-exports. That file is the authoritative "these are the commands that
+ *   talk to Tower" table — its siblings are a filing decision, not a contract.
+ * - The VERBS are each noun's `action:` union in `LocalCommand`
+ *   (`local-args.ts`), with an `XAction` alias resolved from whichever
+ *   `local-args-tower-*.ts` declares it. A noun with no `action` field is one
+ *   verb wearing the noun's own name (`jarvis`, `correct`, `workbook`).
+ *
+ * ## What it deliberately does NOT see
+ *
+ * Mode FLAGS. `cockpit jarvis --trace`, `--threads` and `--history` are three
+ * different acts behind one noun, and no decision table calls them verbs, so
+ * the mechanical rule cannot find them. They are covered by hand in the
+ * census's own twin map (`jarvis --trace` → `jarvis_trace`); a flag that grows
+ * into a verb will show up here the moment it becomes an `action`.
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const COLLECTOR_COMMANDS_DIR = resolve(HERE, "../../cockpit-local-collector/src/commands");
+function read(file) {
+    return readFileSync(join(COLLECTOR_COMMANDS_DIR, file), "utf8");
+}
+/** Every `local-args-tower*.ts` in the collector, so a new sibling is read too. */
+function towerFiles() {
+    return readdirSync(COLLECTOR_COMMANDS_DIR).filter((name) => name.startsWith("local-args-tower") && name.endsWith(".ts") && !name.includes(".test."));
+}
+/** `parseJarvisArgs` → `jarvis`. The re-export table IS the noun list. */
+export function towerNouns() {
+    const source = read("local-args-tower.ts");
+    const nouns = new Set();
+    for (const match of source.matchAll(/\bparse([A-Z][A-Za-z]*)Args\b/g)) {
+        nouns.add(match[1].replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase());
+    }
+    return [...nouns].sort();
+}
+/** `export type NotesAction = "list" | "show" | …` across every tower sibling. */
+function actionAliases() {
+    const aliases = new Map();
+    for (const file of towerFiles()) {
+        const source = read(file);
+        for (const match of source.matchAll(/export type (\w+Action)\s*=\s*([\s\S]*?);/g)) {
+            aliases.set(match[1], [...match[2].matchAll(/"([a-z-]+)"/g)].map((m) => m[1]));
+        }
+    }
+    return aliases;
+}
+/**
+ * The `LocalCommand` variants, split the way the union is written: one chunk
+ * per `  | {` at the top level of the type.
+ */
+/**
+ * The `LocalCommand` union, wherever it currently lives.
+ *
+ * It moved from `local-args.ts` to `local-command-shapes.ts` in BLI-3728, when
+ * `local-args.ts` crossed the 700-line readability ceiling and was split into
+ * "which parser does this argv go to" (there) and "what does a parsed command
+ * look like" (the sibling). Both files are read rather than one, because a
+ * census that silently finds fewer verbs than exist is worse than no census —
+ * this function throwing when it can find the union in NEITHER file is the
+ * whole point, and hardcoding one filename is how it would stop throwing while
+ * being wrong.
+ */
+function commandVariants() {
+    for (const file of ["local-command-shapes.ts", "local-args.ts"]) {
+        let source;
+        try {
+            source = readFileSync(join(COLLECTOR_COMMANDS_DIR, file), "utf8");
+        }
+        catch {
+            continue;
+        }
+        const start = source.indexOf("export type LocalCommand =");
+        if (start < 0)
+            continue;
+        const end = source.indexOf("\nexport ", start + 10);
+        return source.slice(start, end < 0 ? undefined : end).split(/\n\s{2}\|\s/);
+    }
+    throw new Error("LocalCommand union not found in local-command-shapes.ts or local-args.ts");
+}
+/** Every Tower verb a person may type today. */
+export function towerVerbs() {
+    const nouns = new Set(towerNouns());
+    const aliases = actionAliases();
+    const verbs = [];
+    const seenNouns = new Set();
+    for (const variant of commandVariants()) {
+        const kind = /kind:\s*"([a-z-]+)"/.exec(variant)?.[1];
+        if (!kind || !nouns.has(kind) || seenNouns.has(kind))
+            continue;
+        seenNouns.add(kind);
+        const action = /\n\s*action:\s*([^;]+);/.exec(variant)?.[1]?.trim();
+        if (!action) {
+            verbs.push({ noun: kind, action: "", spelling: kind });
+            continue;
+        }
+        const words = action.endsWith("Action")
+            ? (aliases.get(action) ?? [])
+            : [...action.matchAll(/"([a-z-]+)"/g)].map((m) => m[1]);
+        if (words.length === 0) {
+            throw new Error(`No action vocabulary found for cockpit ${kind} (read "${action}")`);
+        }
+        for (const word of words) {
+            verbs.push({ noun: kind, action: word, spelling: `${kind} ${word}` });
+        }
+    }
+    const missing = [...nouns].filter((noun) => !seenNouns.has(noun));
+    if (missing.length > 0) {
+        // A parser with no `LocalCommand` variant means the extraction has drifted
+        // from the source, and a census that quietly reads fewer verbs than exist
+        // is worse than no census at all.
+        throw new Error(`Tower nouns with no LocalCommand variant: ${missing.join(", ")}`);
+    }
+    return verbs.sort((a, b) => a.spelling.localeCompare(b.spelling));
+}
+/** A CLI verb and the MCP tool that does the same thing, over the same door. */
+export const MCP_TWINS = {
+    "docs list": { tool: "docs_list", door: "GET /api/docs/documents" },
+    "docs tree": { tool: "docs_tree", door: "GET /api/docs/tree" },
+    "docs read": { tool: "docs_read", door: "GET /api/docs/documents/[id]" },
+    "docs create": { tool: "docs_create", door: "POST /api/docs/documents" },
+    "docs update": { tool: "docs_update", door: "PATCH /api/docs/documents/[id]" },
+    "msg channels": { tool: "msg_channels", door: "GET /api/msg/channels" },
+    "msg create": { tool: "msg_create_channel", door: "POST /api/msg/channels" },
+    "msg dm": { tool: "msg_dm", door: "POST /api/msg/channels (dm)" },
+    "msg read": { tool: "msg_read", door: "GET /api/msg/channels/[id]/messages" },
+    "msg thread": { tool: "msg_thread", door: "GET /api/msg/channels/[id]/messages?thread_parent_id=" },
+    "msg send": { tool: "msg_send", door: "POST /api/msg/channels/[id]/messages" },
+    "issue list": { tool: "work_list_issues", door: "GET /api/work/issues" },
+    "issue show": { tool: "work_get_issue", door: "GET /api/work/issues/[id]" },
+    "issue create": { tool: "work_create_issue", door: "POST /api/work/issues" },
+    "issue update": { tool: "work_update_issue", door: "PATCH /api/work/issues/[id]" },
+    "issue move": { tool: "work_move_issue", door: "POST /api/work/issues/[id]/state" },
+    "issue comment": { tool: "work_comment_issue", door: "POST /api/work/issues/[id]/comments" },
+    "issue history": { tool: "work_issue_history", door: "GET /api/work/issues/[id]/history" },
+    "project list": { tool: "work_list_projects", door: "GET /api/work/projects" },
+    "brief read": { tool: "brief_read", door: "GET /api/jarvis/brief" },
+    "brief history": { tool: "brief_history", door: "GET /api/jarvis/brief?history=1" },
+    "brief status": { tool: "brief_status", door: "GET /api/ops/brief-status" },
+    "notes list": { tool: "notes_list", door: "GET /api/notes/library" },
+    "notes show": { tool: "notes_show", door: "GET /api/notes/library/[id]" },
+    "notes shelf": { tool: "notes_shelf", door: "GET /api/notes/shelf" },
+    "notes shelves": { tool: "notes_shelves", door: "GET /api/notes/library" },
+    "ops status": { tool: "ops_status", door: "GET /api/ops/status" },
+    "slack coverage": { tool: "slack_coverage", door: "GET /api/ops/slack/coverage" },
+    "slack read": { tool: "slack_read", door: "POST /api/ops/slack/read" },
+    "settings show": { tool: "settings_show", door: "GET /api/settings/* + /api/team/members" },
+    "settings list": { tool: "settings_list", door: "GET /api/settings/env-blobs" },
+    "team members": { tool: "team_members", door: "GET /api/team/members" },
+    "team device-list": { tool: "team_device_list", door: "GET /api/team/devices" },
+    "model show": { tool: "model_show", door: "GET /api/settings/jarvis-model" },
+    "scout board": { tool: "scout_board", door: "GET /api/cockpit/scout" },
+    workbook: { tool: "workbook_read", door: "GET /api/cockpit/workbook" },
+    // BLI-3728: one search over documents, messages, issues, meeting notes and
+    // memory. `cockpit search` takes no action word — the whole verb is the noun
+    // — so it is keyed on the noun alone, the same way `jarvis` and `workbook`
+    // are.
+    search: { tool: "tower_search", door: "GET /api/search" },
+    jarvis: { tool: "jarvis_ask", door: "POST /api/jarvis/cli" },
+    // Entered by hand: a mode flag, not an `action` the parser names (see the
+    // header of this file).
+    "jarvis --trace": { tool: "jarvis_trace", door: "GET /api/ops/trace/[id]" },
+};
+/** Verbs that can never have an MCP twin, and why. A claim, not a backlog. */
+export const TERMINAL_ONLY = {
+    "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)",
+};
+/** Verbs owed a twin, with who owes it. This list should only ever shrink. */
+export const AWAITING_TWIN = {
+    "brief rewrite": "BLI-3756 batch 2 — spends a model call; wants its own gate on this surface",
+    correct: "BLI-3756 batch 2 — filing a correction against a claim has no tool",
+    "notes move": "BLI-3756 batch 2 — needs a signed-in session server-side; reachable, just unwritten",
+    "notes share": "BLI-3756 batch 2 — a deliberate act; wants an explicit confirmation on this surface",
+    "notes unshare": "BLI-3756 batch 2 — same gate as notes share",
+    "notes paste": "BLI-3756 batch 2 — the CLI takes the body on stdin; a tool would take it as an argument",
+    "notes upload": "BLI-3756 batch 2 — takes local file paths, which an MCP server on the same machine can also read",
+    "ops recompile": "BLI-3756 batch 2 — spends a model call; wants its own gate on this surface",
+    "scout start": "BLI-3756 batch 2 — super_admin server-side; a tool would relay, not decide",
+    "scout dismiss": "BLI-3756 batch 2 — super_admin server-side; a tool would relay, not decide",
+    "scout undo": "BLI-3756 batch 2 — super_admin server-side; a tool would relay, not decide",
+    "settings set": "BLI-3756 batch 2 — mostly reachable, but env CONTENT is stdin-only by rule; a tool must keep that",
+    "settings delete": "BLI-3756 batch 2 — destructive; wants an explicit confirmation on this surface",
+    "team invite": "BLI-3756 batch 2 — super_admin; a tool would relay, not decide",
+    "team role": "BLI-3756 batch 2 — super_admin; a tool would relay, not decide",
+    "team device-revoke": "BLI-3756 batch 2 — destructive; wants an explicit confirmation on this surface",
+    "model set": "BLI-3756 batch 2 — a shorthand over settings personal; follows settings",
+};

package/dist/work-tools.d.ts

@@ -14,13 +14,8 @@
  * per call, so a machine with no `cockpit login` pairing still serves this
  * server's other tools and only a `work_` call fails, by name.
  */
-import { loadAgentDoorSession } from "./agent-door-session.js";
-import { type FetchImpl } from "./agent-door.js";
-export interface WorkDeps {
-    fetchImpl: FetchImpl;
-    /** Injectable for tests; defaults to reading `~/.config/bli-cockpit/session.json`. */
-    loadSession?: typeof loadAgentDoorSession;
-}
+import { type ToolDeps } from "./tool-result.js";
+export type WorkDeps = ToolDeps;
 /** The closed state vocabulary, verbatim from `lib/work/api-doors.ts` `WORK_ISSUE_STATES`. */
 export declare const WORK_ISSUE_STATES: readonly ["backlog", "todo", "in_progress", "in_review", "done", "canceled"];
 export declare function registerWorkTools(server: {