@bli-cockpit/mcp 0.1.105 → 0.1.107

package/README.md

@@ -109,7 +109,7 @@ about what an agent can reach.
 
 <!-- BEGIN GENERATED verb census — `npm run mcp:readme` -->
 
-**136 of 141 Tower verbs have an MCP twin.**
+**138 of 143 Tower verbs have an MCP twin.**
 Each tool goes through the SAME door its CLI verb calls, with the same
 collector device token — never a second route and never a service-role
 reader. `src/verb-census.test.ts` fails when a verb is in none of the
@@ -244,6 +244,8 @@ three tables below.
 | `cockpit setup` | `setup_read` | `GET /api/setup` |
 | `cockpit slack coverage` | `slack_coverage` | `GET /api/ops/slack/coverage` |
 | `cockpit slack read` | `slack_read` | `POST /api/ops/slack/read` |
+| `cockpit speed` | `speed_read` | `GET /api/* (every rail page's data door, see speed-tools.ts)` |
+| `cockpit speed --seen` | `speed_seen` | `GET /api/speed/seen` |
 | `cockpit team device doctor` | `team_device_doctor` | `POST /api/ambient/devices/[deviceId]/doctor` |
 | `cockpit team device list` | `team_device_list` | `GET /api/team/devices` |
 | `cockpit team device revoke` | `team_device_revoke` | `POST /api/ambient/devices/[deviceId]/revoke` |

package/dist/server.js

@@ -36,6 +36,7 @@ import { registerWorkTools } from "./work-tools.js";
 import { registerCareersTools } from "./careers-tools.js";
 import { registerRenameTools } from "./rename-tools.js";
 import { registerSetupTools } from "./setup-tools.js";
+import { registerSpeedTools } from "./speed-tools.js";
 import { registerUsageTools } from "./usage-tools.js";
 import { registerLogsTools } from "./logs-tools.js";
 import { registerBrainTools } from "./brain-tools.js";
@@ -440,6 +441,8 @@ export function createServer(deps, options = {}) {
     // BLI-12385: GitHub PR read, and merge / retitle / re-run behind the two-step code.
     registerGithubTools(server, deps);
     registerSetupTools(server, { fetchImpl: deps.fetchImpl });
+    // BLI-13033: how long each rail page's data door takes, the twin of `cockpit speed`.
+    registerSpeedTools(server, { fetchImpl: deps.fetchImpl });
     registerUsageTools(server, { fetchImpl: deps.fetchImpl });
     // BLI-3708: the mailboxes a person attached. Reads, a send and a sync over
     // the same /api/mail/** doors `cockpit mail` calls; `add-imap` deliberately

package/dist/setup-tools.js

@@ -5,7 +5,7 @@ export function registerSetupTools(server, deps) {
     registrarFor(server)("setup_read", {
         title: "Compare agent setups and outcomes",
         description: "Read machine setup names and windowed (default 30-day) merged PR volume, tokens per merged PR and session yield. Compare exact emails. Differences are observations, not evidence that a setting causes better results. Missing or stale setup and incomplete token coverage are labeled. Members see their own outcomes; team comparisons require super_admin.",
-        inputSchema: { since: z.string().max(40).optional().describe("7d, 30d, or an ISO date before now."), person: z.string().max(200).optional().describe("Only this person, by exact email address."), compare: z.string().max(401).optional().describe("Two exact email addresses separated by a comma.") },
+        inputSchema: { since: z.string().max(40).optional().describe("7d, 30d, or an ISO date before now."), person: z.string().max(200).optional().describe("Only this person, by exact first name, display name or email address."), compare: z.string().max(401).optional().describe("Two people, by exact first name, display name or email address, separated by a comma (for example edward,ian). An ambiguous name is refused with its candidates.") },
     }, async (args) => withSession(deps, async (session) => {
         const query = new URLSearchParams();
         if (args.since)

package/dist/speed-tools.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `speed_read` (BLI-13033) — the MCP twin of `cockpit speed`: how long each
+ * Tower rail page's data door takes, measured from where this server runs,
+ * with this machine's device token.
+ *
+ * This package declares no dependency on `@bli-cockpit/local-collector`, so
+ * the page list and the arithmetic below are COPIES of
+ * `cockpit-local-collector/src/commands/speed-pages.ts` and `speed-math.ts`.
+ * `speed-tools.test.ts` fails when the two page lists drift.
+ *
+ * Reads only. Every request is a plain GET on a door the browser also uses;
+ * nothing is cached on this side, so the number is Tower's, not ours.
+ */
+import { type ToolDeps } from "./tool-result.js";
+export interface SpeedPage {
+    name: string;
+    label: string;
+    path: string;
+    note?: string;
+}
+export declare function speedPages(memoryContainer: string): SpeedPage[];
+export declare const SPEED_PAGE_NAMES: string[];
+export interface SpeedSample {
+    status: number | null;
+    ms: number;
+    bytes: number;
+    serverTiming: string | null;
+    failure?: string;
+}
+export type SpeedOutcome = "ok" | "not_permitted" | "failed";
+export interface PageSpeed {
+    page: string;
+    label: string;
+    door: string;
+    outcome: SpeedOutcome;
+    cold_ms: number | null;
+    p50_ms: number | null;
+    p95_ms: number | null;
+    runs: number;
+    failed_runs: number;
+    http_status: number | null;
+    bytes: number | null;
+    server_timing: string | null;
+    server_total_ms: number | null;
+    reason?: string;
+    note?: string;
+}
+export declare function classifyStatus(status: number | null): SpeedOutcome;
+export declare function percentile(values: readonly number[], p: number): number | null;
+export declare function serverTotalMs(header: string | null): number | null;
+export declare function summarizeSamples(page: {
+    name: string;
+    label: string;
+    path: string;
+    note?: string;
+}, samples: readonly SpeedSample[]): PageSpeed;
+export declare function rankPages(pages: readonly PageSpeed[]): PageSpeed[];
+export declare function registerSpeedTools(server: {
+    registerTool: (...args: never[]) => unknown;
+}, deps: ToolDeps): void;

package/dist/speed-tools.js

@@ -0,0 +1,253 @@
+/**
+ * `speed_read` (BLI-13033) — the MCP twin of `cockpit speed`: how long each
+ * Tower rail page's data door takes, measured from where this server runs,
+ * with this machine's device token.
+ *
+ * This package declares no dependency on `@bli-cockpit/local-collector`, so
+ * the page list and the arithmetic below are COPIES of
+ * `cockpit-local-collector/src/commands/speed-pages.ts` and `speed-math.ts`.
+ * `speed-tools.test.ts` fails when the two page lists drift.
+ *
+ * Reads only. Every request is a plain GET on a door the browser also uses;
+ * nothing is cached on this side, so the number is Tower's, not ours.
+ */
+import { z } from "zod";
+import { callAgentDoor } from "./agent-door.js";
+import { dataResult, doorFailureText, errorResult, registrarFor, withSession } from "./tool-result.js";
+export function speedPages(memoryContainer) {
+    return [
+        { name: "today", label: "Today (JARVIS home)", path: "/api/jarvis/brief" },
+        { name: "meeting-notes", label: "Meeting notes", path: "/api/notes/library" },
+        { name: "careers", label: "Careers", path: "/api/careers/applications" },
+        { name: "scout", label: "Scout", path: "/api/cockpit/scout" },
+        { name: "messages", label: "Messages", path: "/api/msg/channels" },
+        { name: "mail", label: "Mail", path: "/api/mail/inbox" },
+        { name: "docs", label: "Docs", path: "/api/docs/tree" },
+        {
+            name: "memory",
+            label: "Memory",
+            path: `/api/memory/profile?container=${encodeURIComponent(memoryContainer)}`,
+            note: "the page reads agent_memories on the server; the profile door is the nearest read",
+        },
+        { name: "tickets", label: "Tickets", path: "/api/work/issues" },
+        { name: "setup", label: "Setup", path: "/api/setup" },
+        { name: "usage", label: "Usage", path: "/api/usage/people?since=30d" },
+        { name: "calendar", label: "Calendar", path: "/api/cal/week" },
+        { name: "workbook", label: "Workbook", path: "/api/cockpit/workbook" },
+        { name: "settings", label: "Settings", path: "/api/settings/personal" },
+    ];
+}
+// END copied
+export const SPEED_PAGE_NAMES = speedPages("x").map((page) => page.name);
+export function classifyStatus(status) {
+    if (status === 403)
+        return "not_permitted";
+    if (status !== null && status >= 200 && status < 300)
+        return "ok";
+    return "failed";
+}
+export function percentile(values, p) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((a, b) => a - b);
+    const rank = Math.max(1, Math.ceil((p / 100) * sorted.length));
+    return sorted[Math.min(rank, sorted.length) - 1] ?? null;
+}
+export function serverTotalMs(header) {
+    if (!header)
+        return null;
+    for (const part of header.split(",")) {
+        const [name, ...params] = part.trim().split(";");
+        if (name?.trim() !== "total")
+            continue;
+        for (const param of params) {
+            const [key, value] = param.trim().split("=");
+            if (key === "dur" && value !== undefined && Number.isFinite(Number(value)))
+                return Number(value);
+        }
+    }
+    return null;
+}
+const round1 = (value) => (value === null ? null : Math.round(value * 10) / 10);
+export function summarizeSamples(page, samples) {
+    const base = { page: page.name, label: page.label, door: page.path, ...(page.note ? { note: page.note } : {}) };
+    const last = samples[samples.length - 1];
+    const good = samples.filter((sample) => classifyStatus(sample.status) === "ok");
+    const denied = samples.find((sample) => classifyStatus(sample.status) === "not_permitted");
+    if (good.length === 0) {
+        const first = samples[0];
+        const outcome = denied ? "not_permitted" : "failed";
+        return {
+            ...base,
+            outcome,
+            cold_ms: null,
+            p50_ms: null,
+            p95_ms: null,
+            runs: samples.length,
+            failed_runs: denied ? 0 : samples.length,
+            http_status: (denied ?? first)?.status ?? null,
+            bytes: null,
+            server_timing: null,
+            server_total_ms: null,
+            reason: denied
+                ? "not permitted for this account"
+                : (first?.failure ?? (first?.status === null || first === undefined ? "no_response" : `http_${first.status}`)),
+        };
+    }
+    const cold = samples[0] && classifyStatus(samples[0].status) === "ok" ? samples[0] : null;
+    const warm = good.filter((sample) => sample !== cold);
+    const timed = (warm.length > 0 ? warm : good).map((sample) => sample.ms);
+    const lastGood = good[good.length - 1] ?? last;
+    return {
+        ...base,
+        outcome: "ok",
+        cold_ms: round1(cold ? cold.ms : null),
+        p50_ms: round1(percentile(timed, 50)),
+        p95_ms: round1(percentile(timed, 95)),
+        runs: samples.length,
+        failed_runs: samples.length - good.length,
+        http_status: lastGood?.status ?? null,
+        bytes: lastGood?.bytes ?? null,
+        server_timing: lastGood?.serverTiming ?? null,
+        server_total_ms: serverTotalMs(lastGood?.serverTiming ?? null),
+    };
+}
+export function rankPages(pages) {
+    const tier = (page) => (page.outcome === "ok" ? 0 : page.outcome === "failed" ? 1 : 2);
+    return [...pages].sort((a, b) => {
+        if (tier(a) !== tier(b))
+            return tier(a) - tier(b);
+        return (b.p50_ms ?? 0) - (a.p50_ms ?? 0) || a.page.localeCompare(b.page);
+    });
+}
+// END copied
+const REQUEST_DEADLINE_MS = 60_000;
+const MAX_RUNS = 50;
+const DEFAULT_RUNS = 5;
+async function timeOneRead(fetchImpl, session, page) {
+    const startedAt = performance.now();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_DEADLINE_MS);
+    timer.unref?.();
+    try {
+        const response = await fetchImpl(`${session.dashboardUrl}${page.path}`, {
+            method: "GET",
+            headers: { authorization: `Bearer ${session.deviceToken}`, accept: "application/json" },
+            signal: controller.signal,
+        });
+        const bytes = (await response.arrayBuffer()).byteLength;
+        return {
+            status: response.status,
+            ms: performance.now() - startedAt,
+            bytes,
+            serverTiming: response.headers.get("server-timing"),
+        };
+    }
+    catch (error) {
+        const aborted = error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError");
+        return {
+            status: null,
+            ms: performance.now() - startedAt,
+            bytes: 0,
+            serverTiming: null,
+            failure: aborted ? "turn_timed_out" : "gateway_unreachable",
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * `speed_seen` (BLI-13054) — the MCP twin of `cockpit speed --seen`: what real
+ * visits experienced, per page, from the page-view beacons the browser sends.
+ * One GET on `/api/speed/seen`; the door counts in the database on the caller's
+ * own row policies, so this side only relays and words the answer.
+ */
+const SEEN_WINDOW = /^\d{1,4}[mhd]$/;
+export function registerSpeedTools(server, deps) {
+    registrarFor(server)("speed_seen", {
+        title: "What real visits saw on each Tower page",
+        description: "Per Tower page, from real page views: visit count, p50 and p95 milliseconds until real content first showed "
+            + "(the last-known screen or the fresh one), the share painted from the last-known screen (snapshot), and median "
+            + "HTML and script transfer where the browser reported them. Slowest first. A person sees their own visits; "
+            + "`everyone` needs super_admin and is refused for anyone else. Window `since` is <n>m, <n>h or <n>d (default 24h, "
+            + "at most 30d). Read only. Twin of `cockpit speed --seen`.",
+        inputSchema: {
+            since: z.string().max(10).optional().describe("Window such as 90m, 24h or 7d (default 24h, at most 30d)."),
+            everyone: z.boolean().optional().describe("Every person's visits (super_admin only)."),
+            pages: z.array(z.enum(SPEED_PAGE_NAMES)).max(14).optional()
+                .describe("Only these pages. Omit for every page."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const since = typeof args.since === "string" ? args.since.trim().toLowerCase() : "24h";
+        if (!SEEN_WINDOW.test(since))
+            return errorResult("speed_seen: `since` takes <n>m, <n>h or <n>d, for example 24h.");
+        const everyone = args.everyone === true;
+        const query = new URLSearchParams({ since });
+        if (everyone)
+            query.set("everyone", "1");
+        const response = await callAgentDoor(session, deps.fetchImpl, "GET", `/api/speed/seen?${query}`);
+        if (!response.ok)
+            return errorResult(doorFailureText("speed_seen", response));
+        const asked = Array.isArray(args.pages) ? args.pages : [];
+        const body = response.body;
+        const pages = (body.pages ?? [])
+            .filter((page) => asked.length === 0 || asked.includes(page.page))
+            .sort((a, b) => b.p50_ms - a.p50_ms || a.page.localeCompare(b.page));
+        const lines = pages.map((page, index) => `${index + 1}. ${page.page}  ${page.visits} visit${page.visits === 1 ? "" : "s"}  p50 ${Math.round(page.p50_ms)} ms  `
+            + `p95 ${Math.round(page.p95_ms)} ms  snapshot ${Math.round(page.snapshot_share * 100)}%`);
+        const who = everyone ? "everyone's visits" : "your visits";
+        return dataResult(pages.length === 0
+            ? `No page views recorded in the last ${since} (${who}).`
+            : `Real page views over the last ${since} (${who}), slowest first:\n${lines.join("\n")}`, { ok: true, since, everyone, pages });
+    }));
+    registrarFor(server)("speed_read", {
+        title: "Time every Tower page's data door",
+        description: "How long each Tower rail page's data door takes, measured from where this server runs with this machine's "
+            + "device token: per page the first (cold) run, p50 and p95 over the warm runs, HTTP status, response bytes and "
+            + "the door's own Server-Timing total, slowest first. A page the account may not open reads `not_permitted`, "
+            + "not a failure. Times the data door, not the page's HTML or paint. Read only. Twin of `cockpit speed`.",
+        inputSchema: {
+            pages: z.array(z.enum(SPEED_PAGE_NAMES)).max(14).optional()
+                .describe("Only these pages. Omit for every page."),
+            runs: z.number().int().min(1).max(MAX_RUNS).optional().describe("Requests per page (default 5)."),
+            container: z.string().min(1).max(200).optional()
+                .describe("The memory container tag to time the Memory page with. Without it the Memory page is left out."),
+        },
+    }, async (args) => withSession(deps, async (session) => {
+        const runs = typeof args.runs === "number" ? args.runs : DEFAULT_RUNS;
+        const asked = Array.isArray(args.pages) ? args.pages : [];
+        const container = typeof args.container === "string" ? args.container : null;
+        const skipped = [];
+        const chosen = speedPages(container ?? "-").filter((page) => {
+            if (asked.length > 0 && !asked.includes(page.name))
+                return false;
+            if (page.name === "memory" && container === null) {
+                skipped.push("memory");
+                return false;
+            }
+            return true;
+        });
+        if (chosen.length === 0) {
+            return errorResult("speed_read has nothing to time: the Memory page needs a `container` tag.");
+        }
+        const results = [];
+        for (const page of chosen) {
+            const samples = [];
+            for (let run = 0; run < runs; run += 1) {
+                const sample = await timeOneRead(deps.fetchImpl, session, page);
+                samples.push(sample);
+                if (classifyStatus(sample.status) === "not_permitted")
+                    break;
+            }
+            results.push(summarizeSamples(page, samples));
+        }
+        const ranked = rankPages(results);
+        const failed = ranked.filter((page) => page.outcome === "failed").length;
+        const lines = ranked.map((page, index) => page.outcome === "ok"
+            ? `${index + 1}. ${page.page}  cold ${Math.round(page.cold_ms ?? 0)} ms  p50 ${Math.round(page.p50_ms ?? 0)} ms  p95 ${Math.round(page.p95_ms ?? 0)} ms  HTTP ${page.http_status}  ${page.bytes} B${page.server_total_ms === null ? "" : `  server ${Math.round(page.server_total_ms)} ms`}`
+            : `${index + 1}. ${page.page}  ${page.outcome === "not_permitted" ? "not permitted" : `FAILED (${page.reason})`}`);
+        return dataResult(`Tower page speed, slowest first (${runs} run${runs === 1 ? "" : "s"} per page; first is cold, p50/p95 over warm runs):\n${lines.join("\n")}`
+            + (skipped.length ? `\nLeft out: ${skipped.join(", ")} (pass container).` : ""), { ok: failed === 0, runs, pages: ranked, skipped });
+    }));
+}

package/dist/tool-catalog.d.ts

@@ -10,7 +10,7 @@
  * 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", "docs_sync_status", "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", "rename_pending", "github_pr", "setup_read", "usage_people", "usage_sessions", "mail_accounts", "mail_inbox", "mail_read", "mail_search", "mail_attachment", "mail_sync_status", "cal_today", "cal_week", "cal_next", "cal_find", "cal_calendars", "cal_sync_status", "jarvis_ask", "jarvis_trace", "jarvis_check", "models_list", "models_card", "models_compare", "brief_read", "brief_history", "brief_status", "brief_missed", "notes_folders", "notes_list", "glossary_list", "notes_show", "notes_shelf", "notes_shelves", "notes_place", "notes_accounts", "notes_recordings", "notes_recording", "notes_sync_status", "notes_granola_status", "ops_status", "slack_coverage", "slack_read", "memory_rules", "memory_profile", "memory_consolidation", "settings_show", "settings_list", "model_show", "team_members", "team_device_list", "scout_board", "workbook_read", "tower_search", "sources_check", "logs_digest", "brain_status"];
+export declare const READ_TOOLS: readonly ["get_ticket_timeline", "get_active_tickets", "docs_list", "docs_tree", "docs_read", "docs_sync_status", "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", "rename_pending", "github_pr", "setup_read", "speed_read", "speed_seen", "usage_people", "usage_sessions", "mail_accounts", "mail_inbox", "mail_read", "mail_search", "mail_attachment", "mail_sync_status", "cal_today", "cal_week", "cal_next", "cal_find", "cal_calendars", "cal_sync_status", "jarvis_ask", "jarvis_trace", "jarvis_check", "models_list", "models_card", "models_compare", "brief_read", "brief_history", "brief_status", "brief_missed", "notes_folders", "notes_list", "glossary_list", "notes_show", "notes_shelf", "notes_shelves", "notes_place", "notes_accounts", "notes_recordings", "notes_recording", "notes_sync_status", "notes_granola_status", "ops_status", "slack_coverage", "slack_read", "memory_rules", "memory_profile", "memory_consolidation", "settings_show", "settings_list", "model_show", "team_members", "team_device_list", "scout_board", "workbook_read", "tower_search", "sources_check", "logs_digest", "brain_status"];
 /**
  * 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).

package/dist/tool-catalog.js

@@ -32,6 +32,8 @@ export const READ_TOOLS = [
     "rename_pending",
     "github_pr",
     "setup_read",
+    "speed_read",
+    "speed_seen",
     "usage_people",
     "usage_sessions",
     "mail_accounts",

package/dist/verb-census.js

@@ -242,6 +242,10 @@ export const MCP_TWINS = {
     "brain status": { tool: "brain_status", door: "GET /api/brain/incidents" },
     "usage sessions": { tool: "usage_sessions", door: "GET /api/usage/sessions" },
     "setup": { tool: "setup_read", door: "GET /api/setup" },
+    // BLI-13033: times the data door of every rail page; the twin runs the same GETs.
+    "speed": { tool: "speed_read", door: "GET /api/* (every rail page's data door, see speed-tools.ts)" },
+    // BLI-13054: a mode flag, entered by hand like `jarvis --trace`.
+    "speed --seen": { tool: "speed_seen", door: "GET /api/speed/seen" },
     "usage people": { tool: "usage_people", door: "GET /api/usage/people" },
     "glossary list": { tool: "glossary_list", door: "GET /api/glossary" },
     "glossary add": { tool: "glossary_add", door: "POST /api/glossary" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/mcp",
-  "version": "0.1.105",
+  "version": "0.1.107",
   "private": false,
   "description": "bli-tower: an MCP server over BLI Cockpit's agent doors: JARVIS (jarvis_*), documents (docs_*), channels (msg_*), issues (work_*), the daily page (brief_*), meeting notes (notes_*), the ops board (ops_status/slack_*), settings/team/model, Scout and the workbook, plus the legacy event-stream tools (emit_event, get_ticket_timeline, get_active_tickets).",
   "type": "module",
@@ -37,7 +37,7 @@
     "readme": "npm run build && node scripts/write-readme-census.mjs"
   },
   "dependencies": {
-    "@bli-cockpit/telemetry-core": "0.1.66",
+    "@bli-cockpit/telemetry-core": "0.1.67",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.3.6"
   },