@bli-cockpit/mcp 0.1.58 → 0.1.61

package/dist/ops-tools.js

@@ -40,6 +40,34 @@ export const UNHEALTHY_VERDICTS = new Set([
     // BLI-3762: a job that wrote less than it owed is not healthy. Amber counts.
     "degraded",
 ]);
+/**
+ * A pipeline row as the board needs it. The door's row also carries its cron
+ * string, config file, host, artifact and a paragraph-long caveat per job,
+ * which the text half never printed: 34 KB for 26 jobs (BLI-10432).
+ */
+function pipelineRow(row) {
+    return {
+        id: row.id ?? null,
+        label: row.label ?? null,
+        verdict: row.verdict ?? null,
+        latestIso: row.latestIso ?? null,
+        ageHours: row.ageHours ?? null,
+        expectedIntervalHours: row.expectedIntervalHours ?? null,
+        staleAfterHours: row.staleAfterHours ?? null,
+        detail: row.detail ?? null,
+    };
+}
+/**
+ * The fleet and coverage blocks without their per-device and per-person rows
+ * unless `people: true` asked for them. Those rows were 155 KB of the board's
+ * 175 KB structured half on 2026-09-26 (BLI-10432).
+ */
+function summaryOnly(block, withPeople) {
+    if (withPeople || !block || typeof block !== "object" || Array.isArray(block))
+        return block;
+    const { devices: _devices, people: _people, ...rest } = block;
+    return rest;
+}
 function numberOf(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
@@ -51,14 +79,16 @@ export function registerOpsTools(server, deps) {
     register("ops_status", {
         title: "Read the Tower pipeline board",
         description: "Every scheduled job's verdict against its own expected interval, plus the collector fleet and collection "
-            + "coverage. A job's `detail` is the server's sentence for why — relayed as it stands. Status only: nothing "
-            + "here fires a job.",
+            + "coverage as one summary line each (`people: true` adds the per-device and per-person rows, about 150 KB). "
+            + "A job's `detail` is the server's sentence for why — relayed as it stands. The whole board can take 25 "
+            + "seconds to read. Status only: nothing here fires a job.",
         inputSchema: {
             job: z.string().min(1).max(100).optional().describe("One pipeline id instead of the whole board."),
             skips: z.boolean().optional().describe("Also return the open ingest-skip ledgers."),
             memory: z.boolean().optional().describe("Also return memory adoption and observed prompt-hook outcomes, delay bounds and cache reuse. No memory text."),
             turns: z.boolean().optional().describe("Also return 30-day JARVIS turn aggregates: latency, hops, tools, tokens and error classes."),
             tool_router: z.boolean().optional().describe("Also return the seven-day shadow tool-router agreement board."),
+            people: z.boolean().optional().describe("Also return every device and every person behind the fleet and coverage summaries. Large."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const params = new URLSearchParams();
@@ -73,6 +103,8 @@ export function registerOpsTools(server, deps) {
             return errorResult(doorFailureText("ops_status", response));
         const body = response.body;
         const rows = (Array.isArray(body.pipelines) ? body.pipelines : []);
+        const fleetSummary = typeof asRecord(body.fleet).summary === "string" ? String(asRecord(body.fleet).summary) : "";
+        const coverageSummary = typeof asRecord(body.coverage).summary === "string" ? String(asRecord(body.coverage).summary) : "";
         const unhealthy = rows.filter((row) => UNHEALTHY_VERDICTS.has(row.verdict ?? ""));
         const lines = rows
             .map((row) => `${(row.verdict ?? "?").padEnd(14)}  ${row.id ?? "?"}  ${row.detail ?? row.label ?? ""}`.trimEnd())
@@ -134,6 +166,8 @@ export function registerOpsTools(server, deps) {
         return textResult(`${rows.length} pipeline(s), ${unhealthy.length} unhealthy`
             + `${unhealthy.length > 0 ? `: ${unhealthy.map((row) => row.id ?? "?").join(", ")}` : "."}`
             + `${lines ? `\n${lines}` : ""}`
+            + `${fleetSummary ? `\nFLEET  ${fleetSummary}` : ""}`
+            + `${coverageSummary ? `\nCOVERAGE  ${coverageSummary}` : ""}`
             + `${ladderLine ? `\n${ladderLine}` : ""}`
             + `${memoryLines ? `\n${memoryLines}` : ""}`
             + `${experienceLines ? `\n${experienceLines}` : ""}`
@@ -141,10 +175,10 @@ export function registerOpsTools(server, deps) {
             + `${toolRouterLine ? `\n${toolRouterLine}` : ""}`, 
         // The API owns the wording and the timing boundary on every surface.
         {
-            pipelines: rows,
+            pipelines: rows.map(pipelineRow),
             unhealthy: unhealthy.map((row) => row.id ?? "?"),
-            ...(body.fleet ? { fleet: body.fleet } : {}),
-            ...(body.coverage ? { coverage: body.coverage } : {}),
+            ...(body.fleet ? { fleet: summaryOnly(body.fleet, args.people === true) } : {}),
+            ...(body.coverage ? { coverage: summaryOnly(body.coverage, args.people === true) } : {}),
             ...(body.skips ? { skips: body.skips } : {}),
             ...(body.ladder ? { ladder: body.ladder } : {}),
             ...(memory?.ok ? { memory: memory.body.memory, hooks: memory.body.hooks, experience: memory.body.experience } : {}),
@@ -196,7 +230,7 @@ export function registerOpsTools(server, deps) {
             query: z.string().min(1).max(500).optional().describe("Text to look for."),
             since: z.string().min(1).max(30).optional().describe("YYYY-MM-DD or ISO-8601."),
             until: z.string().min(1).max(30).optional().describe("YYYY-MM-DD or ISO-8601."),
-            limit: z.number().int().min(1).max(500).optional(),
+            limit: z.number().int().min(1).max(500).optional().describe("At most this many messages, newest first."),
         },
     }, async (args) => withSession(deps, async (session) => {
         const body = {};

package/dist/server.d.ts

@@ -19,7 +19,13 @@ export interface ServerDeps {
     fetchImpl: FetchImpl;
 }
 export declare const PACKAGE_NAME = "@bli-cockpit/mcp";
-export declare const PACKAGE_VERSION = "0.1.4";
+/**
+ * The version this server tells a client in `initialize`, read from the
+ * package's own `package.json` (which npm always ships). It was a literal
+ * `"0.1.4"` for fifty-six releases, so every client log named the wrong build
+ * (BLI-10432).
+ */
+export declare const PACKAGE_VERSION: string;
 export declare const emitEventInput: {
     ticket_id: z.ZodString;
     event_type: z.ZodString;
@@ -31,7 +37,7 @@ export declare const emitEventInput: {
     }>>;
     source: z.ZodOptional<z.ZodString>;
     actor_role: z.ZodOptional<z.ZodString>;
-    payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    payload: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
     note_md: z.ZodOptional<z.ZodString>;
     correlation_id: z.ZodOptional<z.ZodString>;
     idempotency_key: z.ZodOptional<z.ZodString>;

package/dist/server.js

@@ -4,6 +4,7 @@
  * Pure factory — accepts injected fetch + base URL + token so it can be
  * unit-tested without binding to a real network or transport.
  */
+import { createRequire } from "node:module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { registerBriefTools } from "./brief-tools.js";
@@ -30,7 +31,23 @@ import { registerWorkTools } from "./work-tools.js";
 import { registerCareersTools } from "./careers-tools.js";
 import { registerUsageTools } from "./usage-tools.js";
 export const PACKAGE_NAME = "@bli-cockpit/mcp";
-export const PACKAGE_VERSION = "0.1.4";
+/**
+ * The version this server tells a client in `initialize`, read from the
+ * package's own `package.json` (which npm always ships). It was a literal
+ * `"0.1.4"` for fifty-six releases, so every client log named the wrong build
+ * (BLI-10432).
+ */
+export const PACKAGE_VERSION = readPackageVersion();
+function readPackageVersion() {
+    try {
+        const manifest = createRequire(import.meta.url)("../package.json");
+        return typeof manifest.version === "string" ? manifest.version : "unknown";
+    }
+    catch (error) {
+        process.stderr.write(`[bli-cockpit-mcp] package.json unreadable; serving version "unknown" (${error instanceof Error ? error.message.split("\n")[0] : String(error)})\n`);
+        return "unknown";
+    }
+}
 // ---- input schemas (Zod raw shapes) -----------------------------------------
 export const emitEventInput = {
     ticket_id: z
@@ -44,7 +61,9 @@ export const emitEventInput = {
     event_version: z
         .number()
         .int()
-        .positive()
+        // `.min(1)`, not `.positive()`: the latter publishes `exclusiveMinimum`,
+        // which strict clients reject (BLI-10432).
+        .min(1)
         .optional()
         .describe("Event schema version. Defaults to 1 in the API."),
     kind: z
@@ -62,7 +81,9 @@ export const emitEventInput = {
         .optional()
         .describe("Actor role for the event. Defaults to operator."),
     payload: z
-        .record(z.string(), z.unknown())
+        // `looseObject`, not `record`: a record publishes `propertyNames`, a
+        // keyword strict clients reject (BLI-10432). Same values accepted.
+        .looseObject({})
         .optional()
         .describe("Event payload object. Defaults to {}."),
     note_md: z
@@ -335,7 +356,9 @@ function errorContent(err) {
         content: [
             {
                 type: "text",
-                text: code ? `[${code}] ${message}` : message,
+                // `ApiError`'s own message already opens with `[code]`; prefixing it
+                // again printed "[BLI-E003] [BLI-E003] …" (BLI-10432).
+                text: code && !message.startsWith(`[${code}]`) ? `[${code}] ${message}` : message,
             },
         ],
     };

package/dist/settings-tools.js

@@ -43,6 +43,9 @@ function sectionPayload(response, door) {
         return { visible: false, reason: "admin_only" };
     return { visible: false, reason: doorFailureText(door, response) };
 }
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
 function sectionWord(response) {
     if (response.ok)
         return "ok";
@@ -55,7 +58,8 @@ async function oneSection(deps, session, tool, path) {
     const response = await readSection(deps, session, path);
     if (!response.ok)
         return errorResult(doorFailureText(tool, response));
-    return textResult(JSON.stringify(response.body, null, 2), response.body);
+    // Compact JSON: indentation was a third of what a model paid for (BLI-10432).
+    return textResult(JSON.stringify(response.body), response.body);
 }
 export function registerSettingsTools(server, deps) {
     const register = registrarFor(server);
@@ -91,7 +95,7 @@ export function registerSettingsTools(server, deps) {
             .map((key) => `${key.padEnd(10)}  ${sectionWord(byKey[key])}`)
             .join("\n");
         const payload = Object.fromEntries(keys.map((key) => [key, sectionPayload(byKey[key], `settings ${key}`)]));
-        return textResult(`TOWER SETTINGS\n${lines}\n\n${JSON.stringify(payload, null, 2)}`, payload);
+        return textResult(`TOWER SETTINGS\n${lines}\n\n${JSON.stringify(payload)}`, payload);
     }));
     register("settings_list", {
         title: "List Tower env files",
@@ -112,17 +116,36 @@ export function registerSettingsTools(server, deps) {
     }));
     register("team_members", {
         title: "Read the Tower team directory",
-        description: "Who is on this team, their roles, and any invitations still open.",
+        description: "Who is on this team: every person on the roster or with an account, their standing (account or roster "
+            + "only), Tower role and team role, and the user id team_role takes.",
         inputSchema: {},
     }, async () => withSession(deps, async (session) => {
         const response = await readSection(deps, session, "/api/team/members");
         if (!response.ok)
             return errorResult(doorFailureText("team_members", response));
-        const members = (Array.isArray(response.body.members) ? response.body.members : []);
-        const lines = members
-            .map((member) => `${String(member.role ?? "?").padEnd(12)}  ${String(member.email ?? member.userId ?? "?")}`)
+        // The door answers `people`, one row per person with an optional
+        // `account`. This read `members`, a key the door no longer sends, and
+        // answered "0 member(s)." over a twelve-person team (BLI-10432).
+        const people = (Array.isArray(response.body.people) ? response.body.people : []);
+        const team = asRecord(response.body.currentTeam);
+        const lines = people
+            .map((person) => {
+            const account = asRecord(person.account);
+            const name = String(person.name ?? person.email ?? person.key ?? "?");
+            const email = typeof person.email === "string" && person.email !== name ? ` <${person.email}>` : "";
+            const roles = typeof account.role === "string"
+                ? `  role ${account.role}${typeof account.teamRole === "string" ? `, team ${account.teamRole}` : ""}`
+                : "";
+            const id = typeof account.userId === "string" ? `  id ${account.userId}` : "";
+            return `${name}${email}  ${String(person.standing ?? "?")}${person.active === false ? " (inactive)" : ""}${roles}${id}`;
+        })
             .join("\n");
-        return textResult(`${members.length} member(s).${lines ? `\n${lines}` : ""}`, response.body);
+        const heading = typeof team.name === "string" ? `${team.name}: ` : "";
+        const rosterError = typeof response.body.rosterError === "string"
+            ? ` The roster could not be read (${response.body.rosterError}), so people without an account may be missing.`
+            : "";
+        return textResult(`${heading}${people.length} person(s).${rosterError}${response.body.canManage === true ? "" : " Read-only: only an admin can invite or change roles."}`
+            + `${lines ? `\n${lines}` : ""}`, response.body);
     }));
     register("team_device_list", {
         title: "List the collector devices Tower knows",
@@ -134,9 +157,13 @@ export function registerSettingsTools(server, deps) {
         if (!response.ok)
             return errorResult(doorFailureText("team_device_list", response));
         const devices = (Array.isArray(response.body.devices) ? response.body.devices : []);
+        // The door's row names its owner and trust state, and carries no
+        // `cli_version`: every line used to print "?" there (BLI-10432). These
+        // are the fields `cockpit team device list` prints.
         const lines = devices
             .map((device) => `${String(device.device_id ?? "?")}  ${String(device.device_name ?? "?")}  `
-            + `${String(device.cli_version ?? "?")}  last seen ${String(device.last_seen_at ?? "never")}`)
+            + `${String(device.trust_state ?? "unknown")}  owner ${String(device.owner_label ?? "?")}  `
+            + `last seen ${String(device.last_seen_at ?? "never")}${typeof device.summary === "string" ? `  ${device.summary}` : ""}`)
             .join("\n");
         return textResult(`${devices.length} device(s).${lines ? `\n${lines}` : ""}`, response.body);
     }));

package/dist/tool-catalog.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Every `bli-tower` tool, sorted by what calling it DOES (BLI-10432).
+ *
+ * `npm run mcp:smoke` calls every READ and every DRY-RUN against production
+ * and never a WRITE; `tool-catalog.test.ts` fails when a registered tool is in
+ * none of the three lists, so a new tool joins the smoke (or is declared a
+ * write) the day it is registered, not the day somebody notices.
+ *
+ * Deliberately dependency-free: `scripts/smoke.ts` imports this file straight
+ * from `src/` under Node's type stripping, so it may import nothing.
+ */
+/** Tools that change nothing. The smoke calls every one. */
+export declare const READ_TOOLS: readonly ["get_ticket_timeline", "get_active_tickets", "docs_list", "docs_tree", "docs_read", "msg_channels", "msg_read", "msg_thread", "work_list_issues", "work_get_issue", "work_issue_history", "work_list_projects", "careers_list", "careers_show", "careers_resume_url", "careers_takehome_show", "careers_settings_show", "usage_people", "usage_sessions", "mail_accounts", "mail_inbox", "mail_read", "mail_search", "mail_attachment", "cal_today", "cal_week", "cal_next", "cal_find", "cal_calendars", "jarvis_ask", "jarvis_trace", "jarvis_check", "models_list", "models_card", "models_compare", "brief_read", "brief_history", "brief_status", "notes_folders", "notes_list", "notes_show", "notes_shelf", "notes_shelves", "notes_place", "notes_accounts", "ops_status", "slack_coverage", "slack_read", "memory_profile", "memory_consolidation", "settings_show", "settings_list", "model_show", "team_members", "team_device_list", "scout_board", "workbook_read", "tower_search"];
+/**
+ * Tools that write, but answer a dry run that writes nothing. The smoke calls
+ * each one ONLY with its dry-run flag set (`scripts/smoke.ts` says which).
+ */
+export declare const DRY_RUN_TOOLS: readonly ["ops_recompile", "memory_requeue"];
+/**
+ * Tools that change real data: send mail, post messages, file issues, move
+ * candidates, share calendars. Never called by the smoke; covered by the unit
+ * suites (`write-tools.test.ts` and each family's own).
+ */
+export declare const WRITE_TOOLS: readonly ["emit_event", "docs_create", "docs_update", "msg_create_channel", "msg_dm", "msg_send", "work_create_issue", "work_update_issue", "work_move_issue", "work_comment_issue", "careers_rescreen", "careers_send_takehome", "careers_invite", "careers_grade", "careers_decide", "careers_takehome_set", "careers_settings_set", "mail_send", "mail_sync", "mail_detach", "cal_create", "cal_share", "cal_sync", "cal_detach", "jarvis_dispatch", "notes_mkdir", "notes_rmdir", "notes_rename", "notes_upload", "notes_paste", "notes_share", "notes_unshare", "notes_move", "notes_sync", "notes_detach", "memory_experience", "scout_start", "scout_dismiss", "scout_undo", "brief_rewrite", "brief_correct", "brief_done", "brief_undone", "settings_set", "settings_delete", "model_set", "team_invite", "team_role", "team_device_revoke"];
+/** Reads that spend a model turn. The smoke's `--no-model` leaves these out. */
+export declare const MODEL_SPENDING_TOOLS: readonly ["jarvis_ask", "jarvis_check"];
+/**
+ * Reads whose answer IS one whole item (a document, a transcript, a thread),
+ * so its size is the item's and not a list the caller failed to narrow. The
+ * smoke does not hold these to the per-half budget.
+ */
+export declare const SINGLE_ITEM_TOOLS: readonly ["docs_read", "notes_show", "mail_read", "workbook_read", "jarvis_trace", "models_card", "careers_show", "memory_profile"];

package/dist/tool-catalog.js

@@ -0,0 +1,150 @@
+/**
+ * Every `bli-tower` tool, sorted by what calling it DOES (BLI-10432).
+ *
+ * `npm run mcp:smoke` calls every READ and every DRY-RUN against production
+ * and never a WRITE; `tool-catalog.test.ts` fails when a registered tool is in
+ * none of the three lists, so a new tool joins the smoke (or is declared a
+ * write) the day it is registered, not the day somebody notices.
+ *
+ * Deliberately dependency-free: `scripts/smoke.ts` imports this file straight
+ * from `src/` under Node's type stripping, so it may import nothing.
+ */
+/** Tools that change nothing. The smoke calls every one. */
+export const READ_TOOLS = [
+    "get_ticket_timeline",
+    "get_active_tickets",
+    "docs_list",
+    "docs_tree",
+    "docs_read",
+    "msg_channels",
+    "msg_read",
+    "msg_thread",
+    "work_list_issues",
+    "work_get_issue",
+    "work_issue_history",
+    "work_list_projects",
+    "careers_list",
+    "careers_show",
+    "careers_resume_url",
+    "careers_takehome_show",
+    "careers_settings_show",
+    "usage_people",
+    "usage_sessions",
+    "mail_accounts",
+    "mail_inbox",
+    "mail_read",
+    "mail_search",
+    "mail_attachment",
+    "cal_today",
+    "cal_week",
+    "cal_next",
+    "cal_find",
+    "cal_calendars",
+    "jarvis_ask",
+    "jarvis_trace",
+    "jarvis_check",
+    "models_list",
+    "models_card",
+    "models_compare",
+    "brief_read",
+    "brief_history",
+    "brief_status",
+    "notes_folders",
+    "notes_list",
+    "notes_show",
+    "notes_shelf",
+    "notes_shelves",
+    "notes_place",
+    "notes_accounts",
+    "ops_status",
+    "slack_coverage",
+    "slack_read",
+    "memory_profile",
+    "memory_consolidation",
+    "settings_show",
+    "settings_list",
+    "model_show",
+    "team_members",
+    "team_device_list",
+    "scout_board",
+    "workbook_read",
+    "tower_search",
+];
+/**
+ * Tools that write, but answer a dry run that writes nothing. The smoke calls
+ * each one ONLY with its dry-run flag set (`scripts/smoke.ts` says which).
+ */
+export const DRY_RUN_TOOLS = ["ops_recompile", "memory_requeue"];
+/**
+ * Tools that change real data: send mail, post messages, file issues, move
+ * candidates, share calendars. Never called by the smoke; covered by the unit
+ * suites (`write-tools.test.ts` and each family's own).
+ */
+export const WRITE_TOOLS = [
+    "emit_event",
+    "docs_create",
+    "docs_update",
+    "msg_create_channel",
+    "msg_dm",
+    "msg_send",
+    "work_create_issue",
+    "work_update_issue",
+    "work_move_issue",
+    "work_comment_issue",
+    "careers_rescreen",
+    "careers_send_takehome",
+    "careers_invite",
+    "careers_grade",
+    "careers_decide",
+    "careers_takehome_set",
+    "careers_settings_set",
+    "mail_send",
+    "mail_sync",
+    "mail_detach",
+    "cal_create",
+    "cal_share",
+    "cal_sync",
+    "cal_detach",
+    "jarvis_dispatch",
+    "notes_mkdir",
+    "notes_rmdir",
+    "notes_rename",
+    "notes_upload",
+    "notes_paste",
+    "notes_share",
+    "notes_unshare",
+    "notes_move",
+    "notes_sync",
+    "notes_detach",
+    "memory_experience",
+    "scout_start",
+    "scout_dismiss",
+    "scout_undo",
+    "brief_rewrite",
+    "brief_correct",
+    "brief_done",
+    "brief_undone",
+    "settings_set",
+    "settings_delete",
+    "model_set",
+    "team_invite",
+    "team_role",
+    "team_device_revoke",
+];
+/** Reads that spend a model turn. The smoke's `--no-model` leaves these out. */
+export const MODEL_SPENDING_TOOLS = ["jarvis_ask", "jarvis_check"];
+/**
+ * Reads whose answer IS one whole item (a document, a transcript, a thread),
+ * so its size is the item's and not a list the caller failed to narrow. The
+ * smoke does not hold these to the per-half budget.
+ */
+export const SINGLE_ITEM_TOOLS = [
+    "docs_read",
+    "notes_show",
+    "mail_read",
+    "workbook_read",
+    "jarvis_trace",
+    "models_card",
+    "careers_show",
+    "memory_profile",
+];

package/dist/tool-result.d.ts

@@ -36,6 +36,37 @@ export interface DoorSession {
     deviceToken: string;
 }
 export declare function textResult(text: string, structured?: Record<string, unknown>): ToolResult;
+/**
+ * A result whose TEXT half carries the data, not just a headline (BLI-10432).
+ *
+ * MCP clients do not agree on which half of a tool result the model reads.
+ * Claude Code, claude.ai and Claude Desktop hand the model `content` and
+ * render `structuredContent` for the person (or drop it); Codex hands the
+ * model `structuredContent` and drops `content`. So a tool that answered
+ * `"5 document(s)."` in text and the rows in `structuredContent` was blind on
+ * every Claude surface: the model was told five documents exist and never
+ * given one id. Every read is written so EACH half stands alone. Use this when
+ * there is no terser rendering worth writing by hand: the headline, then the
+ * structured half as one line of compact JSON.
+ */
+export declare function dataResult(headline: string, structured: Record<string, unknown>): ToolResult;
+/**
+ * The per-half byte budget a DEFAULT read is held to (BLI-10432): about 8k
+ * tokens. A list over it names how to narrow instead of shipping everything;
+ * a single-item read (one document, one transcript) may exceed it because the
+ * item IS what was asked for. `scripts/smoke.ts` measures every read against
+ * it and the per-call log below warns when a result crosses it.
+ */
+export declare const RESULT_BUDGET_BYTES: number;
+/**
+ * The page a list returns when the caller named no `limit` (BLI-10432).
+ * `work_list_issues` with no limit returned 1,000 issues WITH descriptions,
+ * 4.2 MB, which no agent can afford; a list now answers a page and says when
+ * more exist.
+ */
+export declare const DEFAULT_LIST_LIMIT = 50;
+/** "…, and more exist — pass a larger limit (up to N) or narrow the filter." */
+export declare function moreNote(more: boolean, max: number): string;
 export declare function errorResult(text: string): ToolResult;
 /**
  * The session is loaded fresh per call (a cheap file read) rather than once at
@@ -63,7 +94,16 @@ export type RegisterTool = (name: string, config: {
     description: string;
     inputSchema: Record<string, unknown>;
 }, handler: (args: Record<string, unknown>) => Promise<ToolResult>) => unknown;
-/** The one cast, so no tool family repeats it. */
+/**
+ * The one cast, so no tool family repeats it — and the one place every
+ * agent-door call is logged (BLI-10432): tool, outcome, milliseconds and the
+ * byte size of each half. Metadata only, never an argument or a body. A result
+ * over `RESULT_BUDGET_BYTES` logs as a warning so an oversized read names
+ * itself in the client's MCP log instead of silently eating a context window.
+ * `BLI_MCP_QUIET_TOOL_LOG=1` silences the answered and refused lines (the unit
+ * suites set it, since they exercise refusals on purpose); a handler that
+ * threw always prints.
+ */
 export declare function registrarFor(server: {
     registerTool: (...args: never[]) => unknown;
 }): RegisterTool;
@@ -93,5 +133,16 @@ export declare function queryString(params: URLSearchParams): string;
  * `server.test.ts` walks every registered tool's shape for exactly this.
  */
 export declare const CONFIRM_INPUT: z.ZodOptional<z.ZodBoolean>;
+/**
+ * An email address, in a schema every client can compile (BLI-10432).
+ *
+ * `z.string().email()` publishes zod's own address pattern, which opens with
+ * two negative lookaheads (`^(?!\.)(?!.*\.\.)…`). Lookaround is not RE2, and
+ * RE2 is what OpenAI's strict tool schemas and Google's function declarations
+ * compile patterns with, so one `mail_send` in the tool list was enough for a
+ * strict client to refuse the whole server. This pattern is lookaround-free;
+ * the mail and calendar doors validate the address again on the server.
+ */
+export declare const EMAIL_INPUT: z.ZodString;
 /** `null` when the caller confirmed; the refusal itself when they did not. */
 export declare function unconfirmed(args: Record<string, unknown>, sentence: string): ToolResult | null;

package/dist/tool-result.js

@@ -18,6 +18,41 @@ import { loadAgentDoorSession } from "./agent-door-session.js";
 export function textResult(text, structured) {
     return { content: [{ type: "text", text }], ...(structured ? { structuredContent: structured } : {}) };
 }
+/**
+ * A result whose TEXT half carries the data, not just a headline (BLI-10432).
+ *
+ * MCP clients do not agree on which half of a tool result the model reads.
+ * Claude Code, claude.ai and Claude Desktop hand the model `content` and
+ * render `structuredContent` for the person (or drop it); Codex hands the
+ * model `structuredContent` and drops `content`. So a tool that answered
+ * `"5 document(s)."` in text and the rows in `structuredContent` was blind on
+ * every Claude surface: the model was told five documents exist and never
+ * given one id. Every read is written so EACH half stands alone. Use this when
+ * there is no terser rendering worth writing by hand: the headline, then the
+ * structured half as one line of compact JSON.
+ */
+export function dataResult(headline, structured) {
+    return textResult(`${headline}\n${JSON.stringify(structured)}`, structured);
+}
+/**
+ * The per-half byte budget a DEFAULT read is held to (BLI-10432): about 8k
+ * tokens. A list over it names how to narrow instead of shipping everything;
+ * a single-item read (one document, one transcript) may exceed it because the
+ * item IS what was asked for. `scripts/smoke.ts` measures every read against
+ * it and the per-call log below warns when a result crosses it.
+ */
+export const RESULT_BUDGET_BYTES = 32 * 1024;
+/**
+ * The page a list returns when the caller named no `limit` (BLI-10432).
+ * `work_list_issues` with no limit returned 1,000 issues WITH descriptions,
+ * 4.2 MB, which no agent can afford; a list now answers a page and says when
+ * more exist.
+ */
+export const DEFAULT_LIST_LIMIT = 50;
+/** "…, and more exist — pass a larger limit (up to N) or narrow the filter." */
+export function moreNote(more, max) {
+    return more ? ` More exist — pass a larger limit (up to ${max}) or narrow the filter.` : "";
+}
 export function errorResult(text) {
     return { isError: true, content: [{ type: "text", text }] };
 }
@@ -69,9 +104,49 @@ function doorSentence(body, status) {
     const said = [headline ?? message, ...lines].filter(Boolean);
     return said.length > 0 ? said.join(" ") : `Tower answered ${status}.`;
 }
-/** The one cast, so no tool family repeats it. */
+/**
+ * The one cast, so no tool family repeats it — and the one place every
+ * agent-door call is logged (BLI-10432): tool, outcome, milliseconds and the
+ * byte size of each half. Metadata only, never an argument or a body. A result
+ * over `RESULT_BUDGET_BYTES` logs as a warning so an oversized read names
+ * itself in the client's MCP log instead of silently eating a context window.
+ * `BLI_MCP_QUIET_TOOL_LOG=1` silences the answered and refused lines (the unit
+ * suites set it, since they exercise refusals on purpose); a handler that
+ * threw always prints.
+ */
 export function registrarFor(server) {
-    return server.registerTool.bind(server);
+    const register = server.registerTool.bind(server);
+    return (name, config, handler) => register(name, config, async (args) => {
+        const started = Date.now();
+        let result;
+        try {
+            result = await handler(args);
+        }
+        catch (error) {
+            // A handler that throws would surface as a bare protocol error with no
+            // reason label; name it, log it, and answer by name instead.
+            const reason = error instanceof Error ? error.message.split("\n")[0] ?? "unknown" : String(error);
+            logToolCall("error", { tool: name, outcome: "threw", ms: Date.now() - started, reason: reason.slice(0, 200) });
+            return errorResult(`${name} failed inside the bli-tower server (tool_threw): ${reason}`);
+        }
+        const textBytes = Buffer.byteLength(result.content.map((part) => part.text).join(""));
+        const structuredBytes = result.structuredContent ? Buffer.byteLength(JSON.stringify(result.structuredContent)) : 0;
+        const oversized = Math.max(textBytes, structuredBytes) > RESULT_BUDGET_BYTES;
+        logToolCall(result.isError || oversized ? "warn" : "info", {
+            tool: name,
+            outcome: result.isError ? "refused" : oversized ? "answered_oversized" : "answered",
+            ms: Date.now() - started,
+            text_bytes: textBytes,
+            structured_bytes: structuredBytes,
+        });
+        return result;
+    });
+}
+function logToolCall(level, fields) {
+    if (level !== "error" && process.env.BLI_MCP_QUIET_TOOL_LOG === "1")
+        return;
+    // stdout is the MCP transport; every log line goes to stderr.
+    process.stderr.write(`[bli-cockpit-mcp tool] ${level} ${JSON.stringify(fields)}\n`);
 }
 /** `?a=1&b=2`, or "" when nothing was asked for. Never a bare `?`. */
 export function queryString(params) {
@@ -108,6 +183,21 @@ export const CONFIRM_INPUT = z
     .boolean()
     .optional()
     .describe("Must be true. This act is deliberate and is refused without it — the same rule as the CLI's --yes.");
+/**
+ * An email address, in a schema every client can compile (BLI-10432).
+ *
+ * `z.string().email()` publishes zod's own address pattern, which opens with
+ * two negative lookaheads (`^(?!\.)(?!.*\.\.)…`). Lookaround is not RE2, and
+ * RE2 is what OpenAI's strict tool schemas and Google's function declarations
+ * compile patterns with, so one `mail_send` in the tool list was enough for a
+ * strict client to refuse the whole server. This pattern is lookaround-free;
+ * the mail and calendar doors validate the address again on the server.
+ */
+export const EMAIL_INPUT = z
+    .string()
+    .min(3)
+    .max(320)
+    .regex(/^[^\s@]+@[^\s@]+\.[^\s@]+$/u, "an email address");
 /** `null` when the caller confirmed; the refusal itself when they did not. */
 export function unconfirmed(args, sentence) {
     if (args.confirm === true)