@bli-cockpit/mcp 0.1.2 → 0.1.4

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).",
@@ -103,13 +131,20 @@ export function registerDocsMsgTools(server, deps) {
     }));
     register("docs_update", {
         title: "Update a Tower document",
-        description: "Updates a document's title, body, visibility, or parent (a parent change IS a move). Only the fields you pass change.",
+        description: "Updates a document's title, body, visibility, or parent (a parent change IS a move). Only the fields you "
+            + "pass change. Emptying a document that holds text needs allow_empty: true.",
         inputSchema: {
             id: z.string().min(1).max(200).describe("A document id, or its slug."),
             title: z.string().min(1).max(200).optional(),
             body_markdown: z.string().max(200_000).optional(),
             visibility: z.enum(["org", "private"]).optional(),
             parent_id: z.string().uuid().nullable().optional(),
+            allow_empty: z
+                .boolean()
+                .optional()
+                .describe("Only when you mean to CLEAR the page. A body_markdown that would empty a document that holds "
+                + "text is refused with refused_empty_body unless this is true (BLI-3757 — a blank save is far more "
+                + "often a surface that lost the content than a person who meant it)."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const ref = String(args.id ?? "");
@@ -123,6 +158,9 @@ export function registerDocsMsgTools(server, deps) {
             ...(args.body_markdown !== undefined ? { body_markdown: args.body_markdown } : {}),
             ...(args.visibility !== undefined ? { visibility: args.visibility } : {}),
             ...(args.parent_id !== undefined ? { parent_id: args.parent_id } : {}),
+            // BLI-3759: sent only when the caller asked for it; the door's own
+            // refusal comes back verbatim otherwise, never retried with the flag.
+            ...(args.allow_empty ? { allow_empty: true } : {}),
         });
         if (!response.ok)
             return errorResult(doorFailureText("docs_update", response));
@@ -161,6 +199,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/jarvis-answer-envelope.d.ts

@@ -34,7 +34,7 @@
  * Every key of the envelope, in the order it is written. The literal list IS
  * the contract: both copies assert against it, so a drift is a red suite.
  */
-export declare const JARVIS_ANSWER_ENVELOPE_KEYS: readonly ["ok", "answer", "sources", "turn_id", "thread_id", "trace_thread_id", "degraded", "degraded_reasons"];
+export declare const JARVIS_ANSWER_ENVELOPE_KEYS: readonly ["ok", "answer", "sources", "turn_id", "thread_id", "trace_thread_id", "proposal_id", "degraded", "degraded_reasons"];
 /**
  * The closed set of ways an answer can be second-rate without being a failure.
  * A degraded answer is still an answer — it is printed, returned and counted —
@@ -77,6 +77,16 @@ export interface JarvisAnswerEnvelope {
      * `thread_id` above and deliberately named apart from it.
      */
     trace_thread_id: string | null;
+    /**
+     * BLI-3755: the coding-arm proposal this turn made, when it made one.
+     *
+     * It is what an AGENT surface is given INSTEAD of the eight-hex approval
+     * code, which is never sent here: a code a program can read is a code it
+     * could approve with, and that is not approval. The person fetches the code
+     * on a surface a person reads and hands it back. Null on every turn that
+     * proposed no coding task, which is nearly all of them.
+     */
+    proposal_id: string | null;
     degraded: boolean;
     degraded_reasons: JarvisDegradedReason[];
 }
@@ -103,5 +113,7 @@ export interface JarvisAnswerEnvelopeInput {
     trace?: ReadonlyArray<{
         status?: string;
     }> | null;
+    /** `body.proposalId` — BLI-3755's coding-arm proposal id, when the turn made one. */
+    proposalId?: string | null;
 }
 export declare function buildJarvisAnswerEnvelope(input: JarvisAnswerEnvelopeInput): JarvisAnswerEnvelope;

package/dist/jarvis-answer-envelope.js

@@ -41,6 +41,7 @@ export const JARVIS_ANSWER_ENVELOPE_KEYS = [
     "turn_id",
     "thread_id",
     "trace_thread_id",
+    "proposal_id",
     "degraded",
     "degraded_reasons",
 ];
@@ -76,6 +77,7 @@ export function buildJarvisAnswerEnvelope(input) {
         turn_id: turnId,
         thread_id: input.thread ?? null,
         trace_thread_id: input.traceThread ?? null,
+        proposal_id: input.proposalId ?? null,
         degraded: reasons.length > 0,
         degraded_reasons: reasons,
     };

package/dist/jarvis-door.js

@@ -72,7 +72,14 @@ export async function takeTurn(deps, session, door, body, remember) {
     // `accept: application/json` (which `callAgentDoor` always sends) is what
     // makes the dashboard answer one JSON body instead of the NDJSON stream the
     // terminal takes — an MCP tool has nobody to show live trace lines to.
-    const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/jarvis/cli", body, TURN_TIMEOUT_MS);
+    const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/jarvis/cli", 
+    // BLI-3755: every turn this server takes says who is reading the answer.
+    // An MCP tool result is read by a MODEL, so the coding arm withholds its
+    // approval code and answers with a `proposal_id` instead — the one thing
+    // this server could not prove about a code it relayed was that a person
+    // had ever seen it. Sent on every tool, not just the dispatch, because the
+    // arm is on the belt of every turn.
+    { ...body, surface: "agent" }, TURN_TIMEOUT_MS);
     if (!response.ok) {
         log(`${TAG} turn failed ${JSON.stringify({
             door,
@@ -102,6 +109,7 @@ export async function takeTurn(deps, session, door, body, remember) {
         modelFallback: reply.model?.fallback,
         revised: reply.revised,
         trace: reply.trace,
+        proposalId: reply.proposalId,
     });
     remember({ turnId: envelope.turn_id, traceThreadId: envelope.trace_thread_id });
     log(`${TAG} answered ${JSON.stringify({
@@ -109,6 +117,9 @@ export async function takeTurn(deps, session, door, body, remember) {
         reply_chars: envelope.answer.length,
         sources: envelope.sources.length,
         trace_steps: reply.trace?.length ?? 0,
+        // BLI-3755: whether this turn left a coding-arm proposal behind. The id
+        // itself is in the envelope; this line says one was made.
+        proposal_recorded: envelope.proposal_id !== null,
         degraded: envelope.degraded,
         degraded_reasons: envelope.degraded_reasons,
         has_turn_id: envelope.turn_id !== null,
@@ -117,6 +128,10 @@ export async function takeTurn(deps, session, door, body, remember) {
     const footer = [
         envelope.turn_id ? `turn_id: ${envelope.turn_id} (open it with jarvis_trace)` : null,
         envelope.thread_id ? `thread_id: ${envelope.thread_id}` : null,
+        envelope.proposal_id
+            ? `proposal_id: ${envelope.proposal_id} — the person fetches the approval code for it themself, `
+                + `in a Tower tab, their Slack DM, or their own \`cockpit jarvis\` terminal. You were not sent one.`
+            : null,
         envelope.degraded ? `degraded: ${envelope.degraded_reasons.join(", ")}` : null,
     ]
         .filter((line) => line !== null)

package/dist/jarvis-tools.d.ts

@@ -32,16 +32,24 @@
  * and cannot compute a code for any plan, so an invented code is refused by
  * the dashboard exactly as it always was.
  *
- * Lock 2 is weaker on THIS surface than it is in a terminal, and saying so is
- * the honest thing to do. In a terminal the person types the code themselves.
- * Through MCP the code arrives as a tool argument, and the dashboard cannot
- * tell a code a person handed their agent from one the agent lifted out of the
- * previous answer by itself. So: this tool takes the code as a parameter, it
- * NEVER derives, guesses or fabricates one, its description tells the model in
- * plain words that the code must come from the person, and every relay is
- * logged (presence and length only, never the code). Anything stronger — a
- * per-code single use, an out-of-band confirmation — is a server-side change
- * to the gate itself and belongs with the gate, not here.
+ * Lock 2 is weaker on THIS surface than it is in a terminal: in a terminal the
+ * person types the code themselves, while through MCP it arrives as a tool
+ * argument and nothing on the wire distinguishes a code a person handed their
+ * agent from one the agent lifted out of the previous answer. BLI-3755 closed
+ * the two halves of that gap where the gate lives, not here:
+ *
+ *   * `jarvis_ask` and `jarvis_dispatch` tell the dashboard they are an AGENT
+ *     surface (`jarvis-door.ts` sends it on every turn), so a proposal comes
+ *     back with a `proposal_id` and NO code. There is nothing in the previous
+ *     answer to lift. The person fetches the code where a person reads — a
+ *     Tower tab, their Slack DM, their own `cockpit jarvis` — and hands it on.
+ *   * A code is spendable ONCE. A replay is refused with `approval_code_spent`,
+ *     so a code that did reach an agent buys at most the one run the person
+ *     approved.
+ *
+ * What is unchanged here: this server holds no secret and cannot compute a code
+ * for any plan, it never derives, guesses or fabricates one, and every relay is
+ * logged (presence and length only, never the code).
  */
 import { type JarvisDeps } from "./jarvis-door.js";
 export type { JarvisDeps } from "./jarvis-door.js";

package/dist/jarvis-tools.js

@@ -32,16 +32,24 @@
  * and cannot compute a code for any plan, so an invented code is refused by
  * the dashboard exactly as it always was.
  *
- * Lock 2 is weaker on THIS surface than it is in a terminal, and saying so is
- * the honest thing to do. In a terminal the person types the code themselves.
- * Through MCP the code arrives as a tool argument, and the dashboard cannot
- * tell a code a person handed their agent from one the agent lifted out of the
- * previous answer by itself. So: this tool takes the code as a parameter, it
- * NEVER derives, guesses or fabricates one, its description tells the model in
- * plain words that the code must come from the person, and every relay is
- * logged (presence and length only, never the code). Anything stronger — a
- * per-code single use, an out-of-band confirmation — is a server-side change
- * to the gate itself and belongs with the gate, not here.
+ * Lock 2 is weaker on THIS surface than it is in a terminal: in a terminal the
+ * person types the code themselves, while through MCP it arrives as a tool
+ * argument and nothing on the wire distinguishes a code a person handed their
+ * agent from one the agent lifted out of the previous answer. BLI-3755 closed
+ * the two halves of that gap where the gate lives, not here:
+ *
+ *   * `jarvis_ask` and `jarvis_dispatch` tell the dashboard they are an AGENT
+ *     surface (`jarvis-door.ts` sends it on every turn), so a proposal comes
+ *     back with a `proposal_id` and NO code. There is nothing in the previous
+ *     answer to lift. The person fetches the code where a person reads — a
+ *     Tower tab, their Slack DM, their own `cockpit jarvis` — and hands it on.
+ *   * A code is spendable ONCE. A replay is refused with `approval_code_spent`,
+ *     so a code that did reach an agent buys at most the one run the person
+ *     approved.
+ *
+ * What is unchanged here: this server holds no secret and cannot compute a code
+ * for any plan, it never derives, guesses or fabricates one, and every relay is
+ * logged (presence and length only, never the code).
  */
 import { z } from "zod";
 import { callAgentDoor } from "./agent-door.js";
@@ -167,10 +175,13 @@ export function registerJarvisTools(server, deps) {
         title: "Dispatch a coding task to JARVIS's coding arm",
         description: "Asks JARVIS to run a coding task on the runner: it clones the repo, works, pushes a branch "
             + "and opens a pull request. It never merges. TWO CALLS, always. Call this once WITHOUT "
-            + "approval_code to get the plan and the 8-character confirmation code back; show both to the "
-            + "person; call it again with the code THEY give you and the same instruction. Never derive, "
-            + "guess, or reuse a code the person has not just handed you — a code you produce yourself is "
-            + "exactly what the approval gate exists to refuse.",
+            + "approval_code: you get the plan and a proposal_id back, and DELIBERATELY no code — a code "
+            + "you can read is a code you could approve with. Show the person the plan and the "
+            + "proposal_id and ask them to fetch the code themself, in a Tower browser tab, their Slack "
+            + "DM with JARVIS, or their own `cockpit jarvis` terminal. Then call this again with the code "
+            + "THEY give you and the same instruction. A code approves exactly ONE run: a reused one is "
+            + "refused (approval_code_spent) and the answer is a fresh approval, never a retry. Never "
+            + "derive, guess, or reuse a code the person has not just handed you.",
         inputSchema: {
             instruction: z
                 .string()
@@ -188,8 +199,8 @@ export function registerJarvisTools(server, deps) {
                 .min(1)
                 .max(64)
                 .optional()
-                .describe("The 8-character hex confirmation code THE PERSON read back to you from the previous "
-                + "call's plan. Omit it on the first call."),
+                .describe("The 8-character hex confirmation code THE PERSON fetched for this proposal and handed "
+                + "to you. Omit it on the first call — that call is never given one."),
             thread: z.string().min(1).max(200).optional().describe('Defaults to "main".'),
         },
     }, async (args) => withSession(deps, async (session) => {
@@ -212,7 +223,7 @@ export function registerJarvisTools(server, deps) {
         const question = [
             code.length > 0
                 ? "Dispatch this coding task to the coding arm now."
-                : "Propose a coding task for the coding arm. Do not dispatch it yet — read back the plan and the confirmation code so the person can approve it.",
+                : "Propose a coding task for the coding arm. Do not dispatch it yet — read back the plan and the proposal id so the person can fetch the approval code themselves.",
             ...(typeof args.repo === "string" ? [`Repo: ${args.repo}`] : []),
             "",
             String(args.instruction ?? ""),

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 {};

package/dist/notes-tools.js

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