@bli-cockpit/mcp 0.1.2 → 0.1.3

package/README.md

@@ -25,6 +25,97 @@ dead"). `src/verb-census.test.ts` is that rule as a test — it reads the CLI's
 own decision tables and fails when a verb is in neither the twin map, the
 terminal-only list, nor the written follow-up queue.
 
+## Every Tower verb, and the tool that does the same thing
+
+The three tables below are GENERATED from `src/verb-census.ts` by
+`npm run mcp:readme` — do not hand-edit them. They are the same three lists
+`src/verb-census.test.ts` polices, so this page and that suite cannot disagree
+about what an agent can reach.
+
+<!-- BEGIN GENERATED verb census — `npm run mcp:readme` -->
+
+**39 of 57 Tower verbs have an MCP twin.**
+Each tool goes through the SAME door its CLI verb calls, with the same
+collector device token — never a second route and never a service-role
+reader. `src/verb-census.test.ts` fails when a verb is in none of the
+three tables below.
+
+| CLI verb | MCP tool | Door |
+| --- | --- | --- |
+| `cockpit brief history` | `brief_history` | `GET /api/jarvis/brief?history=1` |
+| `cockpit brief read` | `brief_read` | `GET /api/jarvis/brief` |
+| `cockpit brief status` | `brief_status` | `GET /api/ops/brief-status` |
+| `cockpit docs create` | `docs_create` | `POST /api/docs/documents` |
+| `cockpit docs list` | `docs_list` | `GET /api/docs/documents` |
+| `cockpit docs read` | `docs_read` | `GET /api/docs/documents/[id]` |
+| `cockpit docs tree` | `docs_tree` | `GET /api/docs/tree` |
+| `cockpit docs update` | `docs_update` | `PATCH /api/docs/documents/[id]` |
+| `cockpit issue comment` | `work_comment_issue` | `POST /api/work/issues/[id]/comments` |
+| `cockpit issue create` | `work_create_issue` | `POST /api/work/issues` |
+| `cockpit issue history` | `work_issue_history` | `GET /api/work/issues/[id]/history` |
+| `cockpit issue list` | `work_list_issues` | `GET /api/work/issues` |
+| `cockpit issue move` | `work_move_issue` | `POST /api/work/issues/[id]/state` |
+| `cockpit issue show` | `work_get_issue` | `GET /api/work/issues/[id]` |
+| `cockpit issue update` | `work_update_issue` | `PATCH /api/work/issues/[id]` |
+| `cockpit jarvis` | `jarvis_ask` | `POST /api/jarvis/cli` |
+| `cockpit jarvis --trace` | `jarvis_trace` | `GET /api/ops/trace/[id]` |
+| `cockpit model show` | `model_show` | `GET /api/settings/jarvis-model` |
+| `cockpit msg channels` | `msg_channels` | `GET /api/msg/channels` |
+| `cockpit msg create` | `msg_create_channel` | `POST /api/msg/channels` |
+| `cockpit msg dm` | `msg_dm` | `POST /api/msg/channels (dm)` |
+| `cockpit msg read` | `msg_read` | `GET /api/msg/channels/[id]/messages` |
+| `cockpit msg send` | `msg_send` | `POST /api/msg/channels/[id]/messages` |
+| `cockpit msg thread` | `msg_thread` | `GET /api/msg/channels/[id]/messages?thread_parent_id=` |
+| `cockpit notes list` | `notes_list` | `GET /api/notes/library` |
+| `cockpit notes shelf` | `notes_shelf` | `GET /api/notes/shelf` |
+| `cockpit notes shelves` | `notes_shelves` | `GET /api/notes/library` |
+| `cockpit notes show` | `notes_show` | `GET /api/notes/library/[id]` |
+| `cockpit ops status` | `ops_status` | `GET /api/ops/status` |
+| `cockpit project list` | `work_list_projects` | `GET /api/work/projects` |
+| `cockpit scout board` | `scout_board` | `GET /api/cockpit/scout` |
+| `cockpit search` | `tower_search` | `GET /api/search` |
+| `cockpit settings list` | `settings_list` | `GET /api/settings/env-blobs` |
+| `cockpit settings show` | `settings_show` | `GET /api/settings/* + /api/team/members` |
+| `cockpit slack coverage` | `slack_coverage` | `GET /api/ops/slack/coverage` |
+| `cockpit slack read` | `slack_read` | `POST /api/ops/slack/read` |
+| `cockpit team device-list` | `team_device_list` | `GET /api/team/devices` |
+| `cockpit team members` | `team_members` | `GET /api/team/members` |
+| `cockpit workbook` | `workbook_read` | `GET /api/cockpit/workbook` |
+
+### Owed a twin
+
+This table should only ever shrink.
+
+| CLI verb | Who owes it, and why it is not built yet |
+| --- | --- |
+| `cockpit brief rewrite` | BLI-3756 batch 2 — spends a model call; wants its own gate on this surface |
+| `cockpit correct` | BLI-3756 batch 2 — filing a correction against a claim has no tool |
+| `cockpit model set` | BLI-3756 batch 2 — a shorthand over settings personal; follows settings |
+| `cockpit notes move` | BLI-3756 batch 2 — needs a signed-in session server-side; reachable, just unwritten |
+| `cockpit notes paste` | BLI-3756 batch 2 — the CLI takes the body on stdin; a tool would take it as an argument |
+| `cockpit notes share` | BLI-3756 batch 2 — a deliberate act; wants an explicit confirmation on this surface |
+| `cockpit notes unshare` | BLI-3756 batch 2 — same gate as notes share |
+| `cockpit notes upload` | BLI-3756 batch 2 — takes local file paths, which an MCP server on the same machine can also read |
+| `cockpit ops recompile` | BLI-3756 batch 2 — spends a model call; wants its own gate on this surface |
+| `cockpit scout dismiss` | BLI-3756 batch 2 — super_admin server-side; a tool would relay, not decide |
+| `cockpit scout start` | BLI-3756 batch 2 — super_admin server-side; a tool would relay, not decide |
+| `cockpit scout undo` | BLI-3756 batch 2 — super_admin server-side; a tool would relay, not decide |
+| `cockpit settings delete` | BLI-3756 batch 2 — destructive; wants an explicit confirmation on this surface |
+| `cockpit settings set` | BLI-3756 batch 2 — mostly reachable, but env CONTENT is stdin-only by rule; a tool must keep that |
+| `cockpit team device-revoke` | BLI-3756 batch 2 — destructive; wants an explicit confirmation on this surface |
+| `cockpit team invite` | BLI-3756 batch 2 — super_admin; a tool would relay, not decide |
+| `cockpit team role` | BLI-3756 batch 2 — super_admin; a tool would relay, not decide |
+
+### Terminal-only
+
+A claim about the verb's nature, not a backlog.
+
+| CLI verb | Why it can never have a twin |
+| --- | --- |
+| `cockpit brief edit` | opens the person's own $EDITOR on this machine and files what they changed; an agent has no editor to open (commands/editor.ts) |
+
+<!-- END GENERATED verb census -->
+
 ## `jarvis_*` tools (BLI-3732)
 
 JARVIS itself — the same assistant Tower web chat, the Slack DM and
@@ -74,16 +165,50 @@ terminal, because nothing on the wire can tell a person-relayed code from one
 the model lifted out of the previous answer; `src/jarvis-tools.ts` says so in
 full at the top of the file.
 
+## The read tools (BLI-3756 batch 1)
+
+Every Tower READ the CLI already had. Doors and tool names are in the
+generated table above; what is worth knowing before you call one:
+
+- **`brief_read` / `brief_history` / `brief_status`** — the TODAY page as
+  finished text, the days a person has a page for, and why a brief was or was
+  not delivered. `subject` changes WHOSE page is asked for, never who is
+  asking. A delivery reason other than `delivered` (`not_monday`,
+  `no_slack_identity`, …) is a real answer and is NOT returned as an error.
+- **`notes_list` / `notes_show` / `notes_shelf` / `notes_shelves`** — the
+  meeting-notes library. A device token has no signed-in browser session, so
+  these reads are routinely NARROWER than a person's; every one of them
+  appends the door's own `scope`/`degradedBecause` reason rather than letting
+  an agent conclude a note was never taken.
+- **`ops_status` / `slack_coverage` / `slack_read`** — the pipeline board
+  (each job judged against its own expected interval, server-side), Slack
+  collection health, and the collected messages themselves. `slack_read` has a
+  narrower audience than `slack_coverage`, and says so on a 403.
+- **`settings_show` / `settings_list` / `model_show` / `team_members` /
+  `team_device_list`** — settings as this caller may see them. A section you
+  may not see comes back as `admin only`, not as an error; `settings_list`
+  returns env-file names, sizes and stamps and can never return a value.
+- **`scout_board` / `workbook_read`** — the Scout board (with the page's own
+  standing sentences, and a truncated read saying so) and the per-project
+  document library, rendered by the same walker the page uses.
+
+Writes — `brief rewrite`, `correct`, `notes move|share|unshare|paste|upload`,
+`ops recompile`, `scout start|dismiss|undo`, `settings set|delete`,
+`team invite|role|device-revoke`, `model set` — are batch 2, each with the
+reason it waited in the generated "Owed a twin" table.
+
 ## `docs_*` / `msg_*` tools (BLI-3706)
 
 | Tool | Wraps | Notes |
 | --- | --- | --- |
 | `docs_list` | `GET /api/docs/documents` | Every document you may read: id, slug, title, visibility. Never a body. |
+| `docs_tree` | `GET /api/docs/tree` | The library as its nesting rather than a flat list. Never a body. |
 | `docs_read` | `GET /api/docs/documents/[id]` | One document's title and full body, by id or slug (resolved against `docs_list` first). |
 | `docs_create` | `POST /api/docs/documents` | Creates a document. Omitting `body_markdown` creates an empty one. |
 | `docs_update` | `PATCH /api/docs/documents/[id]` | Updates title/body/visibility/parent (a parent change IS a move). |
 | `msg_channels` | `GET /api/msg/channels` | Every channel you are a member of. |
-| `msg_read` | `GET /api/msg/channels/[id]/messages` | Recent messages of one channel, or one thread's replies. `channel` is an id or a `#name`. |
+| `msg_read` | `GET /api/msg/channels/[id]/messages` | Recent messages of one channel, newest first. `channel` is an id or a `#name`. |
+| `msg_thread` | `GET /api/msg/channels/[id]/messages?thread_parent_id=` | One thread's replies, oldest first, so it reads as a conversation. |
 | `msg_send` | `POST /api/msg/channels/[id]/messages` | Posts a message. |
 
 **Auth: this machine's collector device token, not `BLI_OPERATOR_TOKEN`.**

package/dist/brief-tools.d.ts

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

package/dist/brief-tools.js

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

package/dist/docs-msg-tools.d.ts

@@ -9,13 +9,19 @@
  * on a machine with no collector pairing at all, so a missing session must
  * fail the ONE call that needed it, never the whole process.
  */
-import { loadAgentDoorSession } from "./agent-door-session.js";
-import { type FetchImpl } from "./agent-door.js";
-export interface DocsMsgDeps {
-    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 DocsMsgDeps = ToolDeps;
+/**
+ * `docs_list`'s narrowing, as the door's own query parameters (BLI-3737).
+ * The list itself is metadata only — asking for a whole library used to cost
+ * every document's prose, so an agent that wants one folder or one phrase
+ * says so here and the database does the filtering.
+ */
+export declare function docsListPath(args: {
+    parent_id?: unknown;
+    query?: unknown;
+    limit?: unknown;
+}): string;
 export declare function registerDocsMsgTools(server: {
     registerTool: (...args: never[]) => unknown;
 }, deps: DocsMsgDeps): void;

package/dist/docs-msg-tools.js

@@ -10,28 +10,37 @@
  * fail the ONE call that needed it, never the whole process.
  */
 import { z } from "zod";
-import { loadAgentDoorSession } from "./agent-door-session.js";
 import { callAgentDoor } from "./agent-door.js";
-function textResult(text, structured) {
-    return { content: [{ type: "text", text }], ...(structured ? { structuredContent: structured } : {}) };
+import { doorFailureText, errorResult, registrarFor, textResult, withSession, } from "./tool-result.js";
+/** Indented lines, deepest last — the same shape `cockpit docs tree` prints. */
+function renderDocTree(nodes, depth) {
+    return nodes
+        .map((node) => {
+        const line = `${"  ".repeat(depth)}${node.title} (${node.slug ?? node.id})`;
+        const children = node.children?.length ? `\n${renderDocTree(node.children, depth + 1)}` : "";
+        return `${line}${children}`;
+    })
+        .join("\n");
 }
-function errorResult(text) {
-    return { isError: true, content: [{ type: "text", text }] };
+function countTree(nodes) {
+    return nodes.reduce((count, node) => count + 1 + countTree(node.children ?? []), 0);
 }
-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);
-}
-function doorFailureText(door, response) {
-    if (response.transportError) {
-        return `Tower could not be reached for ${door} (${response.transportError}). Nothing was read or written.`;
-    }
-    const reason = typeof response.body.reason === "string" ? response.body.reason : typeof response.body.error === "string" ? response.body.error : "unknown_error";
-    const message = typeof response.body.message === "string" ? response.body.message : `Tower answered ${response.status}.`;
-    return `Tower refused ${door} (${reason}): ${message}`;
+/**
+ * `docs_list`'s narrowing, as the door's own query parameters (BLI-3737).
+ * The list itself is metadata only — asking for a whole library used to cost
+ * every document's prose, so an agent that wants one folder or one phrase
+ * says so here and the database does the filtering.
+ */
+export function docsListPath(args) {
+    const params = new URLSearchParams();
+    if (typeof args.parent_id === "string" && args.parent_id.length > 0)
+        params.set("parent_id", args.parent_id);
+    if (typeof args.query === "string" && args.query.trim().length > 0)
+        params.set("query", args.query);
+    if (typeof args.limit === "number" && Number.isInteger(args.limit))
+        params.set("limit", String(args.limit));
+    const search = params.toString();
+    return search.length > 0 ? `/api/docs/documents?${search}` : "/api/docs/documents";
 }
 async function resolveDocumentId(deps, session, ref) {
     const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/docs/documents");
@@ -51,18 +60,37 @@ async function resolveChannelId(deps, session, ref) {
     return match ? { status: "ok", id: match.id } : { status: "not_found" };
 }
 export function registerDocsMsgTools(server, deps) {
-    const register = server.registerTool.bind(server);
+    const register = registrarFor(server);
     register("docs_list", {
         title: "List Tower documents",
-        description: "Every document you may read: id, slug, title, visibility, source. Never a document's body — call docs_read for that.",
-        inputSchema: {},
-    }, async () => withSession(deps, async (session) => {
-        const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/docs/documents");
+        description: "Every document you may read: id, slug, title, visibility, source, parent_id and body_chars (how long the body is). "
+            + "Never a document's body — call docs_read for that. Narrow before reading: parent_id (a document id, or \"root\" for the "
+            + "top of the tree), query (a case-insensitive substring matched in the database over title AND body, never fuzzy), limit (1-1000).",
+        inputSchema: {
+            parent_id: z.string().min(1).max(64).optional().describe('A document id to list under, or "root" for the top of the tree.'),
+            query: z.string().min(1).max(200).optional().describe("Keep only documents whose title or body contains this text."),
+            limit: z.number().int().min(1).max(1000).optional().describe("At most this many documents."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", docsListPath(args));
         if (!response.ok)
             return errorResult(doorFailureText("docs_list", response));
         const documents = response.body.documents ?? [];
         return textResult(`${documents.length} document(s).`, { documents });
     }));
+    register("docs_tree", {
+        title: "Read the Tower document tree",
+        description: "The document library as its nesting, not as a flat list: every document you may read with its children "
+            + "under it, id, slug and title. Never a body — call docs_read for one.",
+        inputSchema: {},
+    }, async () => withSession(deps, async (session) => {
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/docs/tree");
+        if (!response.ok)
+            return errorResult(doorFailureText("docs_tree", response));
+        const tree = (Array.isArray(response.body.tree) ? response.body.tree : []);
+        const rendered = renderDocTree(tree, 0);
+        return textResult(`${countTree(tree)} document(s).${rendered ? `\n${rendered}` : ""}`, { tree });
+    }));
     register("docs_read", {
         title: "Read a Tower document",
         description: "One document's title and full body, by its id or slug (docs_list returns both).",
@@ -161,6 +189,84 @@ export function registerDocsMsgTools(server, deps) {
         const messages = response.body.messages ?? [];
         return textResult(`${messages.length} message(s) in ${ref}.`, { channelId: resolved.id, messages });
     }));
+    register("msg_thread", {
+        title: "Read a Tower message thread",
+        description: "The replies under one message, oldest first. `thread_parent_id` is the id of the message the thread hangs "
+            + "off — msg_read returns it. `channel` is a channel id, or its name with or without a leading #.",
+        inputSchema: {
+            channel: z.string().min(1).max(200),
+            thread_parent_id: z.string().uuid().describe("The id of the message the replies hang off."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const ref = String(args.channel ?? "");
+        const resolved = await resolveChannelId(deps, session, ref);
+        if (resolved.status === "list_failed")
+            return errorResult(resolved.text);
+        if (resolved.status === "not_found")
+            return errorResult(`No channel matches "${ref}" — check msg_channels for the id or name.`);
+        const parent = String(args.thread_parent_id ?? "");
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/msg/channels/${encodeURIComponent(resolved.id)}/messages?thread_parent_id=${encodeURIComponent(parent)}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("msg_thread", response));
+        const messages = (Array.isArray(response.body.messages) ? response.body.messages : []);
+        // Oldest first: a thread reads as a conversation, unlike the channel
+        // list, which the door returns newest-first.
+        const lines = [...messages]
+            .reverse()
+            .map((message) => `${String(message.created_at ?? "?")}  ${String(message.agent_label ?? message.user_id ?? "?")}  `
+            + `${String(message.content ?? "")}`)
+            .join("\n");
+        return textResult(`${messages.length} repl${messages.length === 1 ? "y" : "ies"} in ${ref}.${lines ? `\n${lines}` : ""}`, { channelId: resolved.id, threadParentId: parent, messages });
+    }));
+    register("msg_create_channel", {
+        title: "Create a Tower channel",
+        description: "Creates a channel and returns its id. `private` means membership decides who may read it. `member_emails` names who joins at birth BY EMAIL — an address Tower does not carry refuses the whole create, so no half-built channel is left behind.",
+        inputSchema: {
+            name: z.string().min(1).max(80).describe("The channel name. A leading # is accepted and dropped."),
+            description: z.string().max(500).optional(),
+            private: z.boolean().optional(),
+            member_emails: z.array(z.string().min(3).max(320)).max(200).optional(),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const raw = String(args.name ?? "");
+        const name = raw.startsWith("#") ? raw.slice(1) : raw;
+        if (name.trim() === "")
+            return errorResult("A channel needs a name. Nothing was created.");
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/msg/channels", {
+            name,
+            is_private: args.private === true,
+            ...(args.description ? { description: args.description } : {}),
+            ...(Array.isArray(args.member_emails) ? { member_emails: args.member_emails } : {}),
+        });
+        if (!response.ok)
+            return errorResult(doorFailureText("msg_create_channel", response));
+        const channel = response.body.channel;
+        const membersAdded = (response.body.members_added ?? []);
+        const membersFailed = (response.body.members_failed ?? []);
+        // A member the channel could not take is named in the SENTENCE, not
+        // just in the structured half: an agent that only reads the text
+        // would otherwise report a clean create over a partial one.
+        const failedNote = membersFailed.length > 0
+            ? ` ${membersFailed.length} member(s) were not added (${membersFailed.map((f) => f.reason ?? "unknown").join(", ")}).`
+            : "";
+        return textResult(`Created #${channel?.name ?? name} (${channel?.id ?? "?"}) with ${membersAdded.length} member(s) added.${failedNote}`, { channel, members_added: membersAdded, members_failed: membersFailed });
+    }));
+    register("msg_dm", {
+        title: "Open a Tower direct message",
+        description: "Opens (or re-opens) the direct message with one person, by their email address. Idempotent: the same address always resolves to the same channel, and you never name yourself.",
+        inputSchema: { email: z.string().min(3).max(320).describe("The other person's email address.") },
+    }, async (args) => withSession(deps, async (session) => {
+        const email = String(args.email ?? "").trim();
+        if (email === "")
+            return errorResult("A direct message needs the person's email address.");
+        const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/msg/channels", {
+            dm_participant_emails: [email],
+        });
+        if (!response.ok)
+            return errorResult(doorFailureText("msg_dm", response));
+        const channel = response.body.channel;
+        return textResult(`Direct message with ${email}: ${channel?.id ?? "?"}.`, { channel });
+    }));
     register("msg_send", {
         title: "Send a Tower message",
         description: "Posts a message to one channel. `channel` is a channel id, or its name with or without a leading #.",

package/dist/notes-tools.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `notes_*` MCP tools (BLI-3756) — the meeting-notes library, read by an
+ * agent, over the same `/api/notes/**` doors `cockpit notes` calls with the
+ * same device token.
+ *
+ * **The narrowing is always said out loud.** `lib/notes/api-doors.ts` gives a
+ * caller with no signed-in browser session a NARROWER read and names it in the
+ * answer's own `scope`/`degradedBecause` — a device token is exactly such a
+ * caller, so an agent reading this library is routinely seeing less than a
+ * person would in a browser. Every tool here appends that reason to its text.
+ * Swallowing it would let an agent conclude a note was never taken when in
+ * fact it simply was not this caller's to read, which is a fact invented out
+ * of a permission.
+ *
+ * Reads only. `notes move|share|unshare|paste|upload` are batch 2 — sharing is
+ * a deliberate act and the paste door takes a body on stdin by rule.
+ */
+import { type ToolDeps } from "./tool-result.js";
+export type NotesDeps = ToolDeps;
+interface ScopedBody {
+    scope?: string;
+    degradedBecause?: string | null;
+    degradedNote?: string;
+}
+/**
+ * The door's own words for "this answer is narrower than the browser's", or
+ * "" when it was not narrowed. Never rephrased here.
+ */
+export declare function narrowingNote(body: ScopedBody): string;
+export declare function registerNotesTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: NotesDeps): void;
+export {};