@bli-cockpit/mcp 0.1.59 → 0.1.63

package/dist/docs-msg-helpers.js

@@ -0,0 +1,106 @@
+/**
+ * Helpers behind the `docs_*` and `msg_*` tools (split out of
+ * `docs-msg-tools.ts` to keep it under the file-size ratchet): id resolution,
+ * list shaping and one-line renderers. No tool is registered here.
+ */
+import { callAgentDoor } from "./agent-door.js";
+import { DEFAULT_LIST_LIMIT, doorFailureText } from "./tool-result.js";
+/** A canonical uuid: a ref that already IS an id needs no list read to resolve. */
+export const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+/** The door's own ceiling on `?limit=` (`/api/docs/documents` `DOCUMENT_LIST_MAX_LIMIT`). */
+export const DOCS_LIST_MAX = 1000;
+/**
+ * The tree as the text half prints it: id, title, slug, children. The door
+ * also sends visibility, source and a timestamp per node, which nothing here
+ * promised and which made the structured half 48 KB for 226 documents
+ * (BLI-10432). `docs_list` carries those fields for a flat read.
+ */
+export function slimTree(nodes) {
+    return nodes.map((node) => ({
+        id: node.id,
+        title: node.title,
+        slug: node.slug ?? null,
+        children: slimTree(Array.isArray(node.children) ? node.children : []),
+    }));
+}
+/** Indented lines, deepest last — the same shape `cockpit docs tree` prints. */
+export 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");
+}
+export function countTree(nodes) {
+    return nodes.reduce((count, node) => count + 1 + countTree(node.children ?? []), 0);
+}
+/**
+ * The fields `docs_list` promises, and only those. The door's row also carries
+ * `created_by`, `updated_by`, `created_at`, `import_truncated` and
+ * `missing_block_count`: 105 KB for 226 documents before this (BLI-10432).
+ */
+export function docListRow(row) {
+    return {
+        id: row.id,
+        slug: row.slug ?? null,
+        title: row.title,
+        visibility: row.visibility,
+        source: row.source ?? null,
+        parent_id: row.parent_id ?? null,
+        updated_at: row.updated_at,
+        body_chars: row.body_chars ?? null,
+    };
+}
+export function docListLine(row) {
+    return `${row.id}  ${row.slug ?? "-"}  ${row.title}  [${row.visibility}${row.source ? `, ${row.source}` : ""}, `
+        + `${row.body_chars ?? "?"} chars, parent ${row.parent_id ?? "root"}, updated ${row.updated_at}]`;
+}
+/**
+ * `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));
+    // No limit named: one page plus one row, so "more exist" is read off the
+    // door instead of guessed from a full page (BLI-10432).
+    else if (args.limit === undefined)
+        params.set("limit", String(DEFAULT_LIST_LIMIT + 1));
+    const search = params.toString();
+    return search.length > 0 ? `/api/docs/documents?${search}` : "/api/docs/documents";
+}
+export async function resolveDocumentId(deps, session, ref) {
+    // An id needs no lookup: the read itself answers 404 by name when it is
+    // wrong. Only a slug costs the whole-library list read (BLI-10432).
+    if (UUID_PATTERN.test(ref))
+        return { status: "ok", id: ref };
+    const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/docs/documents");
+    if (!response.ok)
+        return { status: "list_failed", text: doorFailureText("docs_list", response) };
+    const documents = (Array.isArray(response.body.documents) ? response.body.documents : []);
+    const match = documents.find((doc) => doc.id === ref || doc.slug === ref);
+    return match ? { status: "ok", id: match.id } : { status: "not_found" };
+}
+export async function resolveChannelId(deps, session, ref) {
+    const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/msg/channels");
+    if (!response.ok)
+        return { status: "list_failed", text: doorFailureText("msg_channels", response) };
+    const channels = (Array.isArray(response.body.channels) ? response.body.channels : []);
+    const bare = ref.startsWith("#") ? ref.slice(1) : ref;
+    const match = channels.find((channel) => channel.id === ref || channel.name === bare);
+    return match ? { status: "ok", id: match.id } : { status: "not_found" };
+}
+/** One message as a line: id (msg_thread's `thread_parent_id`), time, author, text. */
+export function messageLine(message) {
+    return `${String(message.id ?? "?")}  ${String(message.created_at ?? "?")}  `
+        + `${String(message.agent_label ?? message.user_id ?? "?")}  ${String(message.content ?? "")}`;
+}

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

@@ -9,19 +9,9 @@
  * 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 { 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;
+import { type DocsMsgDeps } from "./docs-msg-helpers.js";
+export { docsListPath } from "./docs-msg-helpers.js";
+export type { DocsMsgDeps } from "./docs-msg-helpers.js";
 export declare function registerDocsMsgTools(server: {
     registerTool: (...args: never[]) => unknown;
 }, deps: DocsMsgDeps): void;

package/dist/docs-msg-tools.js

@@ -11,72 +11,31 @@
  */
 import { z } from "zod";
 import { callAgentDoor } from "./agent-door.js";
-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 countTree(nodes) {
-    return nodes.reduce((count, node) => count + 1 + countTree(node.children ?? []), 0);
-}
-/**
- * `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");
-    if (!response.ok)
-        return { status: "list_failed", text: doorFailureText("docs_list", response) };
-    const documents = (Array.isArray(response.body.documents) ? response.body.documents : []);
-    const match = documents.find((doc) => doc.id === ref || doc.slug === ref);
-    return match ? { status: "ok", id: match.id } : { status: "not_found" };
-}
-async function resolveChannelId(deps, session, ref) {
-    const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/msg/channels");
-    if (!response.ok)
-        return { status: "list_failed", text: doorFailureText("msg_channels", response) };
-    const channels = (Array.isArray(response.body.channels) ? response.body.channels : []);
-    const bare = ref.startsWith("#") ? ref.slice(1) : ref;
-    const match = channels.find((channel) => channel.id === ref || channel.name === bare);
-    return match ? { status: "ok", id: match.id } : { status: "not_found" };
-}
+import { DEFAULT_LIST_LIMIT, doorFailureText, errorResult, moreNote, registrarFor, textResult, withSession, } from "./tool-result.js";
+import { DOCS_LIST_MAX, slimTree, renderDocTree, countTree, docListRow, docListLine, resolveDocumentId, resolveChannelId, messageLine, docsListPath } from "./docs-msg-helpers.js";
+export { docsListPath } from "./docs-msg-helpers.js";
 export function registerDocsMsgTools(server, deps) {
     const register = registrarFor(server);
     register("docs_list", {
         title: "List Tower 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).",
+            + "top of the tree), query (a case-insensitive substring matched in the database over title AND body, never fuzzy), "
+            + `limit (1-1000, default ${DEFAULT_LIST_LIMIT}; the answer says when more exist).`,
         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."),
+            limit: z.number().int().min(1).max(1000).optional().describe(`At most this many documents. Default ${DEFAULT_LIST_LIMIT}.`),
         },
     }, 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 });
+        const all = (Array.isArray(response.body.documents) ? response.body.documents : []);
+        const more = args.limit === undefined && all.length > DEFAULT_LIST_LIMIT;
+        const rows = more ? all.slice(0, DEFAULT_LIST_LIMIT) : all;
+        const lines = rows.map(docListLine).join("\n");
+        return textResult(`${rows.length} document(s).${moreNote(more, DOCS_LIST_MAX)}${lines ? `\n${lines}` : ""}`, { documents: rows.map(docListRow), more });
     }));
     register("docs_tree", {
         title: "Read the Tower document tree",
@@ -87,9 +46,9 @@ export function registerDocsMsgTools(server, deps) {
         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 tree = slimTree((Array.isArray(response.body.tree) ? response.body.tree : []));
         const rendered = renderDocTree(tree, 0);
-        return textResult(`${countTree(tree)} document(s).${rendered ? `\n${rendered}` : ""}`, { tree });
+        return textResult(`${countTree(tree)} document(s), each as "title (slug or id)"; docs_read takes either.${rendered ? `\n${rendered}` : ""}`, { tree });
     }));
     register("docs_read", {
         title: "Read a Tower document",
@@ -112,10 +71,10 @@ export function registerDocsMsgTools(server, deps) {
         title: "Create a Tower document",
         description: "Creates a new document. Omitting body creates an empty one, matching the browser's own default.",
         inputSchema: {
-            title: z.string().min(1).max(200),
-            body_markdown: z.string().max(200_000).optional(),
-            parent_id: z.string().uuid().optional(),
-            visibility: z.enum(["org", "private"]).optional(),
+            title: z.string().min(1).max(200).describe("The document's title."),
+            body_markdown: z.string().max(200_000).optional().describe("The body, markdown. Omit for an empty document."),
+            parent_id: z.string().uuid().optional().describe("A document id to nest this one under. Omit for the top of the tree."),
+            visibility: z.enum(["org", "private"]).optional().describe("org: everyone signed in may read it. private: only you."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const response = await callAgentDoor(session, deps.fetchImpl, "POST", "/api/docs/documents", {
@@ -135,10 +94,10 @@ export function registerDocsMsgTools(server, deps) {
             + "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(),
+            title: z.string().min(1).max(200).optional().describe("A new title."),
+            body_markdown: z.string().max(200_000).optional().describe("The WHOLE new body, markdown. It replaces the old one; it is not appended."),
+            visibility: z.enum(["org", "private"]).optional().describe("org: everyone signed in may read it. private: only you."),
+            parent_id: z.string().uuid().nullable().optional().describe("Move it under this document id; null moves it to the top of the tree."),
             allow_empty: z
                 .boolean()
                 .optional()
@@ -169,21 +128,40 @@ export function registerDocsMsgTools(server, deps) {
     }));
     register("msg_channels", {
         title: "List Tower channels",
-        description: "Every channel you are a member of.",
+        description: "Every channel you are a member of: id, name (a direct message has none and lists its participants instead), "
+            + "private, and description. msg_read takes the id or the name.",
         inputSchema: {},
     }, async () => withSession(deps, async (session) => {
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", "/api/msg/channels");
         if (!response.ok)
             return errorResult(doorFailureText("msg_channels", response));
-        const channels = response.body.channels ?? [];
-        return textResult(`${channels.length} channel(s).`, { channels });
+        const channels = (Array.isArray(response.body.channels) ? response.body.channels : []);
+        const rows = channels.map((channel) => ({
+            id: channel.id,
+            name: channel.name ?? null,
+            description: channel.description ?? null,
+            is_private: channel.is_private === true,
+            is_dm: channel.is_dm === true,
+            ...(channel.is_dm === true ? { dm_participants: channel.dm_participants ?? [] } : {}),
+            archived_at: channel.archived_at ?? null,
+        }));
+        const lines = rows
+            .map((row) => {
+            const label = row.is_dm
+                ? `DM with ${JSON.stringify(row.dm_participants ?? [])}`
+                : `#${String(row.name ?? "?")}${row.is_private ? " (private)" : ""}`;
+            return `${String(row.id)}  ${label}${row.archived_at ? " [archived]" : ""}`
+                + `${row.description ? `  ${String(row.description)}` : ""}`;
+        })
+            .join("\n");
+        return textResult(`${rows.length} channel(s).${lines ? `\n${lines}` : ""}`, { channels: rows });
     }));
     register("msg_read", {
         title: "Read a Tower channel",
         description: "Recent messages of one channel, newest first. `channel` is a channel id, or its name with or without a leading #.",
         inputSchema: {
-            channel: z.string().min(1).max(200),
-            limit: z.number().int().min(1).max(200).optional(),
+            channel: z.string().min(1).max(200).describe("A channel id, or its name with or without a leading #."),
+            limit: z.number().int().min(1).max(200).optional().describe("At most this many messages, newest first."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const ref = String(args.channel ?? "");
@@ -196,15 +174,19 @@ export function registerDocsMsgTools(server, deps) {
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/msg/channels/${encodeURIComponent(resolved.id)}/messages${query}`);
         if (!response.ok)
             return errorResult(doorFailureText("msg_read", response));
-        const messages = response.body.messages ?? [];
-        return textResult(`${messages.length} message(s) in ${ref}.`, { channelId: resolved.id, messages });
+        const messages = (Array.isArray(response.body.messages) ? response.body.messages : []);
+        // The text half carries the messages themselves, each with its id,
+        // which is what msg_thread takes. It used to say only "2 message(s)",
+        // so a Claude-family client never saw one (BLI-10432).
+        const lines = messages.map(messageLine).join("\n");
+        return textResult(`${messages.length} message(s) in ${ref}, newest first; each line is id, time, author, text.${lines ? `\n${lines}` : ""}`, { 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),
+            channel: z.string().min(1).max(200).describe("A channel id, or its name with or without a leading #."),
             thread_parent_id: z.string().uuid().describe("The id of the message the replies hang off."),
         },
     }, async (args) => withSession(deps, async (session) => {
@@ -221,11 +203,7 @@ export function registerDocsMsgTools(server, deps) {
         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");
+        const lines = [...messages].reverse().map(messageLine).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", {
@@ -233,9 +211,9 @@ export function registerDocsMsgTools(server, deps) {
         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(),
+            description: z.string().max(500).optional().describe("One line saying what the channel is for."),
+            private: z.boolean().optional().describe("true: only members may read it. Default false."),
+            member_emails: z.array(z.string().min(3).max(320)).max(200).optional().describe("Email addresses of the people who join at birth. You join either way."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const raw = String(args.name ?? "");
@@ -281,9 +259,9 @@ export function registerDocsMsgTools(server, deps) {
         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 #.",
         inputSchema: {
-            channel: z.string().min(1).max(200),
-            content: z.string().min(1).max(8_000),
-            thread_parent_id: z.string().uuid().optional(),
+            channel: z.string().min(1).max(200).describe("A channel id, or its name with or without a leading #."),
+            content: z.string().min(1).max(8_000).describe("The message text."),
+            thread_parent_id: z.string().uuid().optional().describe("Reply in the thread under this message id (msg_read prints ids)."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const ref = String(args.channel ?? "");

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

@@ -0,0 +1,16 @@
+/**
+ * The Notion half of the `docs_*` tools (BLI-10430) — the same door
+ * `cockpit docs link` calls, over this machine's device token. A sibling of
+ * `docs-msg-tools.ts` rather than more of it, the same split the collector
+ * makes (`commands/docs-notion.ts`).
+ *
+ * `docs_link` → `PUT /api/docs/documents/[id]/notion-link` (or `DELETE` with
+ * `clear: true`). A link makes the Notion page the truth: the next sync pulls
+ * it over the Tower copy and keeps the copy as a version.
+ * `docs_sync_status` → `GET /api/docs/notion-sync[?document_id=]`: Tower's half
+ * of the sync state, metadata only.
+ */
+import { type DocsMsgDeps } from "./docs-msg-helpers.js";
+export declare function registerDocsNotionTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: DocsMsgDeps): void;

package/dist/docs-notion-tools.js

@@ -0,0 +1,89 @@
+/**
+ * The Notion half of the `docs_*` tools (BLI-10430) — the same door
+ * `cockpit docs link` calls, over this machine's device token. A sibling of
+ * `docs-msg-tools.ts` rather than more of it, the same split the collector
+ * makes (`commands/docs-notion.ts`).
+ *
+ * `docs_link` → `PUT /api/docs/documents/[id]/notion-link` (or `DELETE` with
+ * `clear: true`). A link makes the Notion page the truth: the next sync pulls
+ * it over the Tower copy and keeps the copy as a version.
+ * `docs_sync_status` → `GET /api/docs/notion-sync[?document_id=]`: Tower's half
+ * of the sync state, metadata only.
+ */
+import { z } from "zod";
+import { callAgentDoor } from "./agent-door.js";
+import { resolveDocumentId } from "./docs-msg-helpers.js";
+import { doorFailureText, errorResult, registrarFor, textResult, withSession } from "./tool-result.js";
+export function registerDocsNotionTools(server, deps) {
+    const register = registrarFor(server);
+    register("docs_link", {
+        title: "Link a Tower document to a Notion page",
+        description: "Ties a document to a Notion page so the two-way sync moves it both ways, or unties it with clear: true. "
+            + "The page becomes the truth: the next sync pulls it over this copy and keeps the copy as a version. "
+            + "Refusals keep Tower's reason: invalid_notion_page, notion_page_already_linked, document_not_writable.",
+        inputSchema: {
+            id: z.string().min(1).max(200).describe("A document id, or its slug."),
+            notion_page: z
+                .string()
+                .min(1)
+                .max(500)
+                .optional()
+                .describe("The Notion page URL (app.notion.com/p/… or notion.so/…) or its page id."),
+            clear: z.boolean().optional().describe("true to untie the document from Notion instead."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const clear = args.clear === true;
+        const notionPage = typeof args.notion_page === "string" ? args.notion_page : undefined;
+        if (clear === Boolean(notionPage)) {
+            return errorResult("docs_link needs exactly one of notion_page (to link) or clear: true (to unlink).");
+        }
+        const ref = String(args.id ?? "");
+        const resolved = await resolveDocumentId(deps, session, ref);
+        if (resolved.status === "list_failed")
+            return errorResult(resolved.text);
+        if (resolved.status === "not_found")
+            return errorResult(`No document matches "${ref}" — check docs_list for the id or slug.`);
+        const path = `/api/docs/documents/${encodeURIComponent(resolved.id)}/notion-link`;
+        const response = clear
+            ? await callAgentDoor(session, deps.fetchImpl, "DELETE", path)
+            : await callAgentDoor(session, deps.fetchImpl, "PUT", path, { notion_page: notionPage });
+        if (!response.ok)
+            return errorResult(doorFailureText("docs_link", response));
+        const outcome = String(response.body.outcome ?? "");
+        const document = response.body.document;
+        return textResult(`${outcome || "done"}: "${document?.title ?? ""}" (${document?.id ?? resolved.id}).`, {
+            outcome,
+            document,
+        });
+    }));
+    register("docs_sync_status", {
+        title: "Read the Tower-Notion sync status",
+        description: "Every document linked to a Notion page (or one, by id or slug) with its sync state: synced (the body is what "
+            + "both sides last agreed on), tower_changed (edited in Tower since; the next write-back pushes it), never_synced "
+            + "(linked, no baseline yet). Tower's half only: a Notion edit shows up at the next pull. Never a body.",
+        inputSchema: {
+            id: z.string().min(1).max(200).optional().describe("A document id or slug, for one document's status."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        let path = "/api/docs/notion-sync";
+        if (typeof args.id === "string" && args.id.length > 0) {
+            const resolved = await resolveDocumentId(deps, session, args.id);
+            if (resolved.status === "list_failed")
+                return errorResult(resolved.text);
+            if (resolved.status === "not_found")
+                return errorResult(`No document matches "${args.id}" — check docs_list for the id or slug.`);
+            path = `${path}?document_id=${encodeURIComponent(resolved.id)}`;
+        }
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", path);
+        if (!response.ok)
+            return errorResult(doorFailureText("docs_sync_status", response));
+        const counts = response.body.counts;
+        const summary = Object.entries(counts?.by_state ?? {})
+            .map(([state, count]) => `${count} ${state}`)
+            .join(", ");
+        return textResult(`${counts?.linked ?? 0} linked: ${summary}.`, {
+            counts,
+            documents: response.body.documents ?? [],
+        });
+    }));
+}

package/dist/mail-tools.js

@@ -26,12 +26,12 @@
  */
 import { z } from "zod";
 import { callAgentDoor } from "./agent-door.js";
-import { CONFIRM_INPUT, doorFailureText, errorResult, queryString, registrarFor, textResult, unconfirmed, withSession, } from "./tool-result.js";
+import { CONFIRM_INPUT, EMAIL_INPUT, doorFailureText, errorResult, queryString, registrarFor, textResult, unconfirmed, withSession, } from "./tool-result.js";
 function messageLine(message) {
     const from = message.from_address?.address ?? "(no sender)";
     return `${message.is_unread ? "*" : " "} ${message.internal_date.slice(0, 16)}  ${from}  ${message.subject ?? "(no subject)"}  [thread ${message.thread_id ?? "?"}]`;
 }
-const ADDRESS = z.string().email().max(320);
+const ADDRESS = EMAIL_INPUT.describe("An email address.");
 export function registerMailTools(server, deps) {
     const register = registrarFor(server);
     register("mail_accounts", {
@@ -56,11 +56,11 @@ export function registerMailTools(server, deps) {
         description: "Messages across every mailbox you may read, newest first. Never a body — call mail_read on a thread for that. "
             + "`account_id` narrows to one mailbox; `unread` and `label` filter; `before` (an ISO instant) pages backwards.",
         inputSchema: {
-            account_id: z.string().uuid().optional(),
-            unread: z.boolean().optional(),
-            label: z.string().min(1).max(100).optional(),
-            before: z.string().min(1).max(40).optional(),
-            limit: z.number().int().min(1).max(200).optional(),
+            account_id: z.string().uuid().optional().describe("One mailbox id (mail_accounts). Omit for every mailbox you may read."),
+            unread: z.boolean().optional().describe("true: unread messages only."),
+            label: z.string().min(1).max(100).optional().describe("Only messages carrying this provider label, e.g. INBOX or IMPORTANT."),
+            before: z.string().min(1).max(40).optional().describe("An ISO instant: messages received before it, for the next page back."),
+            limit: z.number().int().min(1).max(200).optional().describe("At most this many messages, newest first."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const query = new URLSearchParams();
@@ -84,30 +84,51 @@ export function registerMailTools(server, deps) {
     }));
     register("mail_read", {
         title: "Read one conversation",
-        description: "One thread with every message's text body, oldest first. Thread ids come from mail_inbox or mail_search. "
-            + "Read the thread before saying what somebody wrote — a snippet is the first 240 characters and nothing more.",
-        inputSchema: { thread_id: z.string().uuid() },
+        description: "One thread with every message's text body, oldest first, and each message's attachments by id (the id "
+            + "mail_attachment takes). Thread ids come from mail_inbox or mail_search. Read the thread before saying what "
+            + "somebody wrote — a snippet is the first 240 characters and nothing more.",
+        inputSchema: { thread_id: z.string().uuid().describe("A thread id, as mail_inbox or mail_search print it.") },
     }, async (args) => withSession(deps, async (session) => {
         const threadId = String(args.thread_id ?? "");
-        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/mail/threads/${encodeURIComponent(threadId)}`);
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", 
+        // `?attachments=1` adds each message's attachment pointers. Without
+        // it no tool here ever showed an attachment id, so mail_attachment
+        // could not be reached from an agent at all (BLI-10432).
+        `/api/mail/threads/${encodeURIComponent(threadId)}?attachments=1`);
         if (!response.ok)
             return errorResult(doorFailureText("mail_read", response));
         const thread = response.body.thread;
         const messages = (Array.isArray(response.body.messages) ? response.body.messages : []);
+        const attachments = (response.body.attachments && typeof response.body.attachments === "object"
+            ? response.body.attachments
+            : {});
         const rendered = messages
-            .map((message) => `--- ${message.internal_date} ${message.from_address?.address ?? "(no sender)"} [${message.id}]\n`
-            + (message.body_text ?? message.snippet ?? "(no text body — this message is HTML only)").trim())
+            .map((message) => {
+            const files = (attachments[message.id] ?? [])
+                .map((file) => `\n  attachment ${file.id}  ${file.filename ?? "(unnamed)"}  ${file.mime_type ?? "?"}  ${file.size_bytes ?? "?"} bytes${file.is_inline ? "  (inline)" : ""}`)
+                .join("");
+            return `--- ${message.internal_date} ${message.from_address?.address ?? "(no sender)"} [${message.id}]\n`
+                + (message.body_text ?? message.snippet ?? "(no text body — this message is HTML only)").trim()
+                + files;
+        })
             .join("\n\n");
-        return textResult(`${thread?.subject ?? "(no subject)"} — ${thread?.account_address ?? "?"}, ${messages.length} message(s)\n\n${rendered}`, { thread, messages });
+        // The HTML body is the text body again with markup, and nothing on
+        // this surface renders it; its length stays so an HTML-only message
+        // still says it has one.
+        const slim = messages.map(({ body_html: html, ...rest }) => ({
+            ...rest,
+            body_html_chars: typeof html === "string" ? html.length : 0,
+        }));
+        return textResult(`${thread?.subject ?? "(no subject)"} — ${thread?.account_address ?? "?"}, ${messages.length} message(s)\n\n${rendered}`, { thread, messages: slim, attachments });
     }));
     register("mail_search", {
         title: "Search your mail",
         description: "Full text over the subject and plain-text body of every message you may read. Quoted phrases and OR work the way "
             + "they do in a search box. Returns headers only; call mail_read on a hit's thread to read it.",
         inputSchema: {
-            query: z.string().min(1).max(400),
-            account_id: z.string().uuid().optional(),
-            limit: z.number().int().min(1).max(200).optional(),
+            query: z.string().min(1).max(400).describe("Words to find. Quoted phrases and OR work."),
+            account_id: z.string().uuid().optional().describe("One mailbox id (mail_accounts). Omit for every mailbox you may read."),
+            limit: z.number().int().min(1).max(200).optional().describe("At most this many matches, newest first."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const query = new URLSearchParams({ q: String(args.query ?? "") });
@@ -129,12 +150,12 @@ export function registerMailTools(server, deps) {
             + "that is never something to guess. `in_reply_to_message_id` (a message id from mail_read) threads the reply. "
             + "This actually sends mail to real people: confirm must be true.",
         inputSchema: {
-            account_id: z.string().uuid(),
-            to: z.array(ADDRESS).min(1).max(50),
-            cc: z.array(ADDRESS).max(50).optional(),
-            subject: z.string().max(998),
-            text: z.string().min(1).max(500_000),
-            in_reply_to_message_id: z.string().uuid().optional(),
+            account_id: z.string().uuid().describe("The mailbox it goes out from (mail_accounts). Never guessed."),
+            to: z.array(ADDRESS).min(1).max(50).describe("Recipient email addresses."),
+            cc: z.array(ADDRESS).max(50).optional().describe("Copied email addresses."),
+            subject: z.string().max(998).describe("The subject line."),
+            text: z.string().min(1).max(500_000).describe("The plain-text body."),
+            in_reply_to_message_id: z.string().uuid().optional().describe("A message id from mail_read: send this as a reply in that thread."),
             confirm: CONFIRM_INPUT,
         },
     }, async (args) => withSession(deps, async (session) => {
@@ -160,7 +181,7 @@ export function registerMailTools(server, deps) {
         title: "Describe an attachment",
         description: "The filename, mime type and size of one attachment. Attachments are POINTERS in Tower — nothing is stored — and "
             + "the bytes are not returned here: `cockpit mail attachment <id> --out <path>` downloads the file at a terminal.",
-        inputSchema: { attachment_id: z.string().uuid() },
+        inputSchema: { attachment_id: z.string().uuid().describe("An attachment id, as mail_read lists it.") },
     }, async (args) => withSession(deps, async (session) => {
         const id = String(args.attachment_id ?? "");
         const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/mail/attachments/${encodeURIComponent(id)}?meta=1`);
@@ -174,7 +195,7 @@ export function registerMailTools(server, deps) {
         title: "Read a mailbox now",
         description: "Runs one sync pass on one mailbox instead of waiting for the 15-minute cron, and answers with what landed or the "
             + "reason it did not (token_revoked, history_gap, auth_failed, quota…). Only the mailbox's OWNER may do this.",
-        inputSchema: { account_id: z.string().uuid() },
+        inputSchema: { account_id: z.string().uuid().describe("A mailbox id you own (mail_accounts).") },
     }, async (args) => withSession(deps, async (session) => {
         const id = String(args.account_id ?? "");
         const response = await callAgentDoor(session, deps.fetchImpl, "POST", `/api/mail/accounts/${encodeURIComponent(id)}/sync`);
@@ -190,7 +211,7 @@ export function registerMailTools(server, deps) {
         title: "Detach a mailbox",
         description: "Removes a mailbox from Tower along with its stored mail and its credential. The mail itself is untouched at the "
             + "provider — this unhooks Tower, it does not delete anybody's email. Irreversible here: confirm must be true.",
-        inputSchema: { account_id: z.string().uuid(), confirm: CONFIRM_INPUT },
+        inputSchema: { account_id: z.string().uuid().describe("A mailbox id you own (mail_accounts)."), confirm: CONFIRM_INPUT },
     }, async (args) => withSession(deps, async (session) => {
         const refusal = unconfirmed(args, "Detaching removes this mailbox's stored mail from Tower.");
         if (refusal)