@bli-cockpit/mcp 0.1.2 → 0.1.4

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/settings-write-tools.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `settings_set` / `settings_delete` / `model_set` MCP tools (BLI-3756 batch
+ * 2) — changing a setting from an agent, over the same `/api/settings/*` doors
+ * `cockpit settings` and `cockpit model` call with the same device token.
+ *
+ * Reads live in `settings-tools.ts`. Nothing here decides policy: every
+ * allowlist, every super_admin check, the belt pre-flight on a chat model and
+ * every audit line lives on the server, so this surface cannot drift into
+ * permitting something the browser refuses. What it owns is the shape of the
+ * ask and the words of a refusal.
+ *
+ * **The env content rule, restated for this surface.** In the terminal an env
+ * blob's content is stdin-only *by rule* — there is no flag that takes a
+ * value, so it never reaches an argument vector, a shell history or a process
+ * list. A tool call has none of those: the arguments travel inside the MCP
+ * transport the same way a request body does. So `settings_set` takes the
+ * content as an argument, and the rule that survives is the one that mattered
+ * — **it is never echoed**: not in the answer, not in the structured payload,
+ * not in a log line. The server cannot return a value either, and
+ * `settings_list` lists names, sizes and stamps only.
+ *
+ * **A delete is deliberate.** `confirm: true` or nothing happens, in the CLI's
+ * own `confirmation_required` words.
+ */
+import { type ToolDeps } from "./tool-result.js";
+export type SettingsWriteDeps = ToolDeps;
+/** The sections `cockpit settings <section> set` can write. */
+export declare const SETTINGS_WRITE_SECTIONS: readonly ["personal", "switches", "models", "cli-floor", "env"];
+/**
+ * `provider:model` → the pair every model door takes. The same parse
+ * `commands/tower-command.ts` does, and the same refusal: a key without a
+ * separator is a typo, and forwarding it would make the SERVER answer a
+ * question about a model nobody named.
+ */
+export declare function parseModelKey(key: string): {
+    ok: true;
+    value: {
+        provider: string;
+        model: string;
+    };
+} | {
+    ok: false;
+    sentence: string;
+};
+export declare function registerSettingsWriteTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: SettingsWriteDeps): void;

package/dist/settings-write-tools.js

@@ -0,0 +1,183 @@
+/**
+ * `settings_set` / `settings_delete` / `model_set` MCP tools (BLI-3756 batch
+ * 2) — changing a setting from an agent, over the same `/api/settings/*` doors
+ * `cockpit settings` and `cockpit model` call with the same device token.
+ *
+ * Reads live in `settings-tools.ts`. Nothing here decides policy: every
+ * allowlist, every super_admin check, the belt pre-flight on a chat model and
+ * every audit line lives on the server, so this surface cannot drift into
+ * permitting something the browser refuses. What it owns is the shape of the
+ * ask and the words of a refusal.
+ *
+ * **The env content rule, restated for this surface.** In the terminal an env
+ * blob's content is stdin-only *by rule* — there is no flag that takes a
+ * value, so it never reaches an argument vector, a shell history or a process
+ * list. A tool call has none of those: the arguments travel inside the MCP
+ * transport the same way a request body does. So `settings_set` takes the
+ * content as an argument, and the rule that survives is the one that mattered
+ * — **it is never echoed**: not in the answer, not in the structured payload,
+ * not in a log line. The server cannot return a value either, and
+ * `settings_list` lists names, sizes and stamps only.
+ *
+ * **A delete is deliberate.** `confirm: true` or nothing happens, in the CLI's
+ * own `confirmation_required` words.
+ */
+import { z } from "zod";
+import { callAgentDoor } from "./agent-door.js";
+import { CONFIRM_INPUT, doorFailureText, errorResult, registrarFor, textResult, unconfirmed, withSession, } from "./tool-result.js";
+import { modelKeyOf } from "./settings-tools.js";
+/** The sections `cockpit settings <section> set` can write. */
+export const SETTINGS_WRITE_SECTIONS = ["personal", "switches", "models", "cli-floor", "env"];
+const WRITE_DEADLINE_MS = 60_000;
+/**
+ * `provider:model` → the pair every model door takes. The same parse
+ * `commands/tower-command.ts` does, and the same refusal: a key without a
+ * separator is a typo, and forwarding it would make the SERVER answer a
+ * question about a model nobody named.
+ */
+export function parseModelKey(key) {
+    const separator = key.indexOf(":");
+    if (separator <= 0 || separator === key.length - 1) {
+        return {
+            ok: false,
+            sentence: `\`${key}\` is not a model key. Use provider:model, e.g. openai:gpt-5.6-terra.`,
+        };
+    }
+    return { ok: true, value: { provider: key.slice(0, separator), model: key.slice(separator + 1) } };
+}
+async function write(deps, session, tool, method, path, body, say) {
+    const response = await callAgentDoor(session, deps.fetchImpl, method, path, body, WRITE_DEADLINE_MS);
+    if (!response.ok)
+        return errorResult(doorFailureText(tool, response));
+    return textResult(say(response.body), response.body);
+}
+export function registerSettingsWriteTools(server, deps) {
+    const register = registrarFor(server);
+    register("settings_set", {
+        title: "Change one Tower setting",
+        description: "Writes one settings section — `cockpit settings <section> set`, same doors. `personal`: your own chat/brief "
+            + "model (provider:model). `switches`: an access or feature switch, admin only. `models`: the org-wide map, "
+            + "admin only, and the candidate is sent the REAL tool belt before it is saved — a provider that refuses the "
+            + "belt refuses the switch. `cli-floor`: the fleet forced-update floor, which only ever goes up. `env`: store "
+            + "an env file's content; the content is never echoed back, and no door can read one out again.",
+        inputSchema: {
+            section: z.enum(SETTINGS_WRITE_SECTIONS).describe("Which section to write."),
+            chat_model: z.string().min(3).max(200).optional().describe("personal/models: provider:model."),
+            brief_model: z.string().min(3).max(200).optional().describe("personal: provider:model."),
+            memory_model: z.string().min(1).max(200).optional().describe("models: the memory compiler's model id."),
+            key: z.string().min(1).max(200).optional().describe("switches: which switch."),
+            value: z.string().min(1).max(200).optional().describe("switches: its new value."),
+            version: z.string().min(1).max(50).optional().describe("cli-floor: the version every collector is pulled to."),
+            project: z.string().min(1).max(200).optional().describe("env: which project the file belongs to."),
+            // Deliberately no example filename: `scripts/assert-public-package-pack.mjs`
+            // bans an env-file literal in a published tarball, and this file ships.
+            file_name: z.string().min(1).max(200).optional().describe("env: the file's name, as settings_list shows it."),
+            content: z
+                .string()
+                .min(1)
+                .max(1_000_000)
+                .optional()
+                .describe("env: the file's contents. Sent to Tower and never echoed back — not here, not in a log."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const section = String(args.section ?? "");
+        switch (section) {
+            case "personal": {
+                const body = {};
+                for (const [field, key] of [["chat_model", "chatModel"], ["brief_model", "briefModel"]]) {
+                    if (!args[field])
+                        continue;
+                    const parsed = parseModelKey(String(args[field]));
+                    if (!parsed.ok)
+                        return errorResult(`Refused (bad_model_key): ${parsed.sentence}`);
+                    body[key] = parsed.value;
+                }
+                if (Object.keys(body).length === 0) {
+                    return errorResult("Refused (nothing_to_set): name chat_model or brief_model. Nothing was changed.");
+                }
+                return write(deps, session, "settings_set", "POST", "/api/settings/jarvis-model", body, (answer) => `Saved your model choices. chat: ${modelKeyOf(answer.chatModel)} · brief: ${modelKeyOf(answer.briefModel)}`);
+            }
+            case "switches": {
+                if (!args.key || !args.value) {
+                    return errorResult("Refused (nothing_to_set): a switch needs both `key` and `value`. Nothing was changed.");
+                }
+                return write(deps, session, "settings_set", "POST", "/api/settings/switches", { key: String(args.key), value: String(args.value) }, (answer) => `Switch ${String(answer.key)} is now ${String(answer.value)}.`);
+            }
+            case "models": {
+                const body = {};
+                if (args.chat_model) {
+                    const parsed = parseModelKey(String(args.chat_model));
+                    if (!parsed.ok)
+                        return errorResult(`Refused (bad_model_key): ${parsed.sentence}`);
+                    body.chatModel = parsed.value;
+                }
+                if (args.memory_model)
+                    body.memoryModel = String(args.memory_model);
+                if (Object.keys(body).length === 0) {
+                    return errorResult("Refused (nothing_to_set): name chat_model or memory_model. Nothing was changed.");
+                }
+                return write(deps, session, "settings_set", "POST", "/api/settings/model-routing", body, (answer) => {
+                    const saved = Array.isArray(answer.saved) ? answer.saved.join(", ") : "";
+                    // BLI-3481: the save succeeded but the belt pre-flight could not
+                    // reach the provider, so nobody has checked that the model just
+                    // chosen will accept Tower's tool belt. A bare "Saved." there
+                    // would be a silent success.
+                    const warning = typeof answer.warning === "string" && answer.warning ? `\n${answer.warning}` : "";
+                    return `Saved: ${saved || "nothing"}.${warning}`;
+                });
+            }
+            case "cli-floor": {
+                if (!args.version) {
+                    return errorResult("Refused (nothing_to_set): the floor needs a `version`. Nothing was changed.");
+                }
+                return write(deps, session, "settings_set", "PUT", "/api/settings/cli-floor", { version: String(args.version) }, (answer) => answer.changed === true
+                    ? `Fleet CLI floor raised ${String(answer.previous ?? "none")}→${String(answer.version)}.`
+                    : `Fleet CLI floor is already ${String(answer.version)}; nothing changed.`);
+            }
+            case "env": {
+                if (!args.project || !args.file_name || !args.content) {
+                    return errorResult("Refused (nothing_to_set): an env file needs `project`, `file_name` and `content`. Nothing was stored.");
+                }
+                const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/settings/env-blobs", { project: String(args.project), file_name: String(args.file_name), content: String(args.content) }, WRITE_DEADLINE_MS);
+                if (!response.ok)
+                    return errorResult(doorFailureText("settings_set", response));
+                // Deliberately narrow: the door's own answer carries no content
+                // field, and this hands back the file's identity and nothing else
+                // — never the bytes that just went in.
+                return textResult(`Stored ${String(args.file_name)} for ${String(args.project)}.`, {
+                    ok: true,
+                    blob: response.body.blob ?? null,
+                });
+            }
+            default:
+                return errorResult(`settings_set has no section "${section}".`);
+        }
+    }));
+    register("settings_delete", {
+        title: "Delete a Tower env file",
+        description: "Removes one stored env file by id — `cockpit settings env delete`, same door. Irreversible, so it is refused "
+            + "without `confirm: true`. Ids come from settings_list.",
+        inputSchema: {
+            id: z.string().min(1).max(200).describe("The env file's id, as settings_list reports it."),
+            confirm: CONFIRM_INPUT,
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const refusal = unconfirmed(args, "Deleting an env file cannot be undone. Call it again with confirm: true.");
+        if (refusal)
+            return refusal;
+        return write(deps, session, "settings_delete", "DELETE", "/api/settings/env-blobs", { id: String(args.id ?? "") }, (answer) => `Deleted env file ${String(answer.deleted_id ?? args.id)}.`);
+    }));
+    register("model_set", {
+        title: "Choose which model answers you",
+        description: "Sets YOUR chat model — the short way to say settings_set personal, because \"which model am I talking to?\" "
+            + "is the question people actually ask. Takes a provider:model key; the server owns which ones are allowed.",
+        inputSchema: {
+            model: z.string().min(3).max(200).describe("provider:model, e.g. openai:gpt-5.6-terra."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const parsed = parseModelKey(String(args.model ?? ""));
+        if (!parsed.ok)
+            return errorResult(`Refused (bad_model_key): ${parsed.sentence}`);
+        return write(deps, session, "model_set", "POST", "/api/settings/jarvis-model", { chatModel: parsed.value }, (answer) => `Chat model is now ${modelKeyOf(answer.chatModel)}.`);
+    }));
+}

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

@@ -0,0 +1,39 @@
+/**
+ * `team_invite` / `team_role` / `team_device_revoke` MCP tools (BLI-3756 batch
+ * 2) — the three things an admin does to the team, over the same `/api/team/*`
+ * and `/api/ambient/devices/*` doors `cockpit team` calls with the same device
+ * token.
+ *
+ * Reads live in `settings-tools.ts` (`team_members`, `team_device_list`). All
+ * three of these RELAY a decision rather than making one: the roster union,
+ * the super_admin gate, the self-role-change refusal and the audit line all
+ * live server-side, so a tool can be wrong about wording and never about
+ * permission.
+ *
+ * Two shapes worth naming.
+ *
+ * **The invite needs a team, and the obvious one is the caller's own.** So
+ * `team_id` is optional and the fallback is a real read of
+ * `/api/team/members` rather than a guess — a caller with no team is told
+ * that, which is true and fixable, instead of getting a uuid validation error
+ * from a body we assembled badly.
+ *
+ * **A revoke names the device before it asks.** `cockpit team device revoke`
+ * looks the device up, prints what it is about to end, and only then acts —
+ * the same "name it, then confirm" shape `dispatchCodingTask` uses, because a
+ * revoke is irreversible for that token. Here the naming happens in the
+ * refusal a caller gets without `confirm: true`, so the confirmation is spent
+ * on a device that has already been identified rather than on a string.
+ */
+import { type ToolDeps } from "./tool-result.js";
+export type TeamWriteDeps = ToolDeps;
+/**
+ * The same closed vocabulary `commands/team-device-reasons.ts` carries, which
+ * is itself a copy of the dashboard's `lib/settings/device-revoke-reasons.ts`
+ * (a CLI workspace cannot import app code, and this one cannot import the CLI).
+ * Three lists; keep them in step by eye if any changes.
+ */
+export declare const DEVICE_REVOKE_REASONS: readonly ["stale_test_pairing", "machine_retired", "person_left", "re_pairing", "other"];
+export declare function registerTeamWriteTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: TeamWriteDeps): void;

package/dist/team-write-tools.js

@@ -0,0 +1,141 @@
+/**
+ * `team_invite` / `team_role` / `team_device_revoke` MCP tools (BLI-3756 batch
+ * 2) — the three things an admin does to the team, over the same `/api/team/*`
+ * and `/api/ambient/devices/*` doors `cockpit team` calls with the same device
+ * token.
+ *
+ * Reads live in `settings-tools.ts` (`team_members`, `team_device_list`). All
+ * three of these RELAY a decision rather than making one: the roster union,
+ * the super_admin gate, the self-role-change refusal and the audit line all
+ * live server-side, so a tool can be wrong about wording and never about
+ * permission.
+ *
+ * Two shapes worth naming.
+ *
+ * **The invite needs a team, and the obvious one is the caller's own.** So
+ * `team_id` is optional and the fallback is a real read of
+ * `/api/team/members` rather than a guess — a caller with no team is told
+ * that, which is true and fixable, instead of getting a uuid validation error
+ * from a body we assembled badly.
+ *
+ * **A revoke names the device before it asks.** `cockpit team device revoke`
+ * looks the device up, prints what it is about to end, and only then acts —
+ * the same "name it, then confirm" shape `dispatchCodingTask` uses, because a
+ * revoke is irreversible for that token. Here the naming happens in the
+ * refusal a caller gets without `confirm: true`, so the confirmation is spent
+ * on a device that has already been identified rather than on a string.
+ */
+import { z } from "zod";
+import { callAgentDoor } from "./agent-door.js";
+import { CONFIRM_INPUT, doorFailureText, errorResult, registrarFor, textResult, unconfirmed, withSession, } from "./tool-result.js";
+const WRITE_DEADLINE_MS = 60_000;
+/**
+ * The same closed vocabulary `commands/team-device-reasons.ts` carries, which
+ * is itself a copy of the dashboard's `lib/settings/device-revoke-reasons.ts`
+ * (a CLI workspace cannot import app code, and this one cannot import the CLI).
+ * Three lists; keep them in step by eye if any changes.
+ */
+export const DEVICE_REVOKE_REASONS = [
+    "stale_test_pairing",
+    "machine_retired",
+    "person_left",
+    "re_pairing",
+    "other",
+];
+/** Exact device_id, or an unambiguous case-insensitive name — the CLI's rule. */
+function findDevice(devices, ref) {
+    const needle = ref.trim();
+    if (!needle)
+        return null;
+    const byId = devices.find((device) => device.device_id === needle);
+    if (byId)
+        return byId;
+    const lower = needle.toLowerCase();
+    const byName = devices.filter((device) => String(device.device_name ?? "").toLowerCase() === lower);
+    return byName.length === 1 ? (byName[0] ?? null) : null;
+}
+async function listDevices(deps, session) {
+    const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/team/devices");
+    if (!response.ok)
+        return { ok: false, text: doorFailureText("team_device_revoke", response) };
+    return { ok: true, devices: (Array.isArray(response.body.devices) ? response.body.devices : []) };
+}
+export function registerTeamWriteTools(server, deps) {
+    const register = registrarFor(server);
+    register("team_invite", {
+        title: "Invite somebody to Tower",
+        description: "Sends a sign-in link to an email address — `cockpit team invite`, same door. super_admin, decided on the "
+            + "server. The team defaults to yours; pass `team_id` to name another.",
+        inputSchema: {
+            email: z.string().min(3).max(320).describe("Who to invite."),
+            role: z.string().min(1).max(50).describe("The role to invite them as; the server owns the vocabulary."),
+            team_id: z.string().min(1).max(100).optional().describe("Defaults to your own team."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        let teamId = args.team_id ? String(args.team_id) : "";
+        if (!teamId) {
+            const directory = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/team/members");
+            if (!directory.ok)
+                return errorResult(doorFailureText("team_invite", directory));
+            const currentTeam = (directory.body.currentTeam ?? {});
+            if (typeof currentTeam.id !== "string") {
+                return errorResult("Refused (no_current_team): you do not belong to a team, so there is nowhere to invite them. "
+                    + "Pass team_id. Nobody was invited.");
+            }
+            teamId = currentTeam.id;
+        }
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/team/invite", { email: String(args.email ?? ""), role: String(args.role ?? ""), team_id: teamId }, WRITE_DEADLINE_MS);
+        if (!response.ok)
+            return errorResult(doorFailureText("team_invite", response));
+        return textResult(`Invited ${String(args.email)} as ${String(response.body.role ?? args.role)}. `
+            + "Tower emailed them a sign-in link.", response.body);
+    }));
+    register("team_role", {
+        title: "Change somebody's Tower role",
+        description: "Changes what one person may do — `cockpit team role`, same door. super_admin, and the server refuses a "
+            + "caller changing their OWN role. Deliberate: refused without `confirm: true`.",
+        inputSchema: {
+            user_id: z.string().min(1).max(100).describe("Whose role, as team_members reports it."),
+            role: z.string().min(1).max(50).describe("The role to give them; the server owns the vocabulary."),
+            confirm: CONFIRM_INPUT,
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const refusal = unconfirmed(args, `Changing ${String(args.user_id)} to ${String(args.role)} changes what they may do. `
+            + "Call it again with confirm: true.");
+        if (refusal)
+            return refusal;
+        const response = await callAgentDoor(session, deps.fetchImpl, "PATCH", `/api/team/members/${encodeURIComponent(String(args.user_id ?? ""))}/role`, { role: String(args.role ?? "") }, WRITE_DEADLINE_MS);
+        if (!response.ok)
+            return errorResult(doorFailureText("team_role", response));
+        return textResult(`${String(response.body.user_id ?? args.user_id)} is now ${String(response.body.role ?? args.role)}.`, response.body);
+    }));
+    register("team_device_revoke", {
+        title: "End a collector device's pairing",
+        description: "Revokes one paired machine's token — `cockpit team device revoke`, same door. Irreversible for that token "
+            + "and super_admin, decided on the server. The device is looked up FIRST and named back to you; without "
+            + "`confirm: true` that naming IS the answer and nothing is revoked.",
+        inputSchema: {
+            device: z.string().min(1).max(200).describe("A device id, or a device name that matches exactly one machine."),
+            reason: z.enum(DEVICE_REVOKE_REASONS).describe("Why, from the closed vocabulary the audit records."),
+            note: z.string().min(1).max(120).optional().describe("Optional free text, 120 characters, server-enforced."),
+            confirm: CONFIRM_INPUT,
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const listed = await listDevices(deps, session);
+        if (!listed.ok)
+            return errorResult(listed.text);
+        const device = findDevice(listed.devices, String(args.device ?? ""));
+        if (!device?.device_id) {
+            return errorResult(`Refused (device_not_found): no device matches "${String(args.device)}". `
+                + "Call team_device_list to see ids and names. Nothing was revoked.");
+        }
+        const named = `${String(device.device_name ?? device.device_id)} (${device.device_id})`;
+        const refusal = unconfirmed(args, `This would revoke ${named}, which cannot be undone. Call it again with confirm: true.`);
+        if (refusal)
+            return refusal;
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", `/api/ambient/devices/${encodeURIComponent(device.device_id)}/revoke`, { reason_label: String(args.reason ?? ""), ...(args.note ? { reason_note: String(args.note) } : {}) }, WRITE_DEADLINE_MS);
+        if (!response.ok)
+            return errorResult(doorFailureText("team_device_revoke", response));
+        return textResult(`Revoked ${named}.`, response.body);
+    }));
+}

package/dist/tool-result.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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 { z } from "zod";
+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;
+/**
+ * The `--yes` of this surface.
+ *
+ * `cockpit` refuses a share, a revoke, a role change or a delete that nobody
+ * confirmed: `--yes`, or a person at a keyboard, and nothing else
+ * (`commands/settings.ts` `confirmDestructive`). An MCP client has no
+ * keyboard, so the only half that survives is the explicit flag — and it must
+ * survive, or the surface a model reaches would be the one surface where a
+ * revoke needs no second thought. The reason label is the CLI's own,
+ * `confirmation_required`, so a script branching on it reads the same word
+ * from either door.
+ */
+export declare const CONFIRM_INPUT: z.ZodOptional<z.ZodBoolean>;
+/** `null` when the caller confirmed; the refusal itself when they did not. */
+export declare function unconfirmed(args: Record<string, unknown>, sentence: string): ToolResult | null;