@bli-cockpit/cli 0.2.193 → 0.2.194

package/dist/commands/local-args-tower-speed.js

@@ -0,0 +1,31 @@
+import { optionalNonEmpty, optionalPositiveInteger, optionalUrl, parseNamedArgs } from "./local-arg-values.js";
+import { SPEED_PAGE_NAMES } from "./speed-pages.js";
+/** The most runs one page gets; a speed check is a handful of reads, not a load test. */
+export const SPEED_MAX_RUNS = 50;
+/** `cockpit speed [--page <name>]... [--runs <n>] [--json]` (BLI-13033). */
+export function parseSpeedArgs(args) {
+    const values = parseNamedArgs(args, {
+        allowedFlags: ["--page", "--runs", "--json", "--home", "--dashboard-url"],
+        valueFlags: ["--page", "--runs", "--home", "--dashboard-url"],
+    });
+    if (values.positionals.length) {
+        throw new Error("speed takes --page <name>, not a subcommand. Pages: " + SPEED_PAGE_NAMES.join(", ") + ".");
+    }
+    const pages = (values.flagValues.get("--page") ?? []).map((name) => name.trim().toLowerCase());
+    const unknown = pages.filter((name) => !SPEED_PAGE_NAMES.includes(name));
+    if (unknown.length) {
+        throw new Error(`Unknown speed page: ${unknown.join(", ")}. Pages: ${SPEED_PAGE_NAMES.join(", ")}.`);
+    }
+    const runs = optionalPositiveInteger(values.flags.get("--runs"), "--runs");
+    if (runs !== undefined && runs > SPEED_MAX_RUNS) {
+        throw new Error(`--runs takes at most ${SPEED_MAX_RUNS}.`);
+    }
+    return {
+        kind: "speed",
+        pages: [...new Set(pages)],
+        runs,
+        json: values.booleans.has("--json"),
+        homeDir: optionalNonEmpty(values.flags.get("--home")),
+        dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),
+    };
+}

package/dist/commands/local-args-tower.js

@@ -38,6 +38,7 @@ export { parseModelsArgs } from "./local-args-tower-models.js";
 export { parseMailArgs } from "./local-args-tower-mail.js";
 export { parseCalArgs } from "./local-args-tower-cal.js";
 export { parseSetupArgs } from "./local-args-tower-setup.js";
+export { parseSpeedArgs } from "./local-args-tower-speed.js";
 export { parseUsageArgs } from "./local-args-tower-usage.js";
 export { parseLogsArgs } from "./local-args-tower-logs.js";
 export { parseBrainArgs } from "./local-args-tower-brain.js";

package/dist/commands/local-args.js

@@ -19,7 +19,7 @@ import { parseGlossaryArgs } from "./glossary.js";
 import { parseRootsArgs } from "./roots.js";
 import { SURFACE_ALIASES } from "./local-help.js";
 import { parseAgentRulesArgs, parseAnalyzeArgs, parseAutostartArgs, parseBackfillArgs, parseCleanArgs, parseDoctorArgs, parseInstallArgs, parseLoginArgs, parseMemoryArgs, parseLogoutArgs, parseOnboardArgs, parseReleaseArgs, parseServeArgs, parseSessionsArgs, parseSourcesArgs, parseStartArgs, parseStatusArgs, parseSyncArgs, parseUpdateArgs, } from "./local-args-collector.js";
-import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseGithubArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, parseUsageArgs, parseSetupArgs, parseLogsArgs, parseBrainArgs, parseCareersArgs, parseRenameArgs, } from "./local-args-tower.js";
+import { parseBriefArgs, parseCorrectArgs, parseDocsArgs, parseIssueArgs, parseJarvisArgs, parseMailArgs, parseCalArgs, parseModelArgs, parseMsgArgs, parseNotesArgs, parseOpsArgs, parseProjectArgs, parseModelsArgs, parseScoutArgs, parseGithubArgs, parseSearchArgs, parseSettingsArgs, parseSlackArgs, parseTeamArgs, parseWorkbookArgs, parseUsageArgs, parseSetupArgs, parseSpeedArgs, parseLogsArgs, parseBrainArgs, parseCareersArgs, parseRenameArgs, } from "./local-args-tower.js";
 // `normalizeUrl` has always been part of this module's surface — `local.ts` and
 // `local-auth.ts` import it from here — so it stays exported from this address
 // even though it now lives next door. The same goes for the four names the
@@ -138,6 +138,8 @@ export function parseLocalArgs(argv) {
             return parseSetupArgs(argv.slice(1));
         case "usage":
             return parseUsageArgs(argv.slice(1));
+        case "speed":
+            return parseSpeedArgs(argv.slice(1));
         case "logs":
             return parseLogsArgs(argv.slice(1));
         case "brain":

package/dist/commands/local-help-commands-tower.js

@@ -175,6 +175,24 @@ export const TOWER_COMMAND_HELP = [
             "--json writes one machine-readable object to stdout; every reason and receipt line stays on stderr.",
         ],
     ],
+    [
+        "speed",
+        [
+            "Usage: cockpit speed [--page <name>]... [--runs <n>] [--dashboard-url <url>] [--json]",
+            "",
+            "Times every Tower rail page's data door from this terminal, with this machine's device token.",
+            "Per page: the first run is reported as cold, the rest as warm; p50 and p95 are over the warm runs",
+            "(nearest rank). Also the HTTP status, the response size and the door's own Server-Timing total.",
+            "Slowest first. A page your account may not open (Careers for a member) reads \"not permitted\", not as a failure.",
+            "--page <name> limits the run to one page; repeat it for several. Names: today, meeting-notes, careers, scout,",
+            "messages, mail, docs, memory, tickets, setup, usage, calendar, workbook, settings.",
+            "--runs <n> sets the requests per page (default 5, at most 50).",
+            "--json writes one object to stdout ({ ok, runs, pages: [...] }); every log line stays on stderr.",
+            "It times the DATA DOOR the page opens on, not the page's HTML or paint, and it never uses the local read cache.",
+            "Exits 1 when any page failed; a page that is not permitted does not fail the run.",
+            "The same measurement is the speed_read MCP tool.",
+        ],
+    ],
     [
         "usage",
         [

package/dist/commands/local-help.js

@@ -83,6 +83,7 @@ export const rootCommandNames = new Set([
     "rename",
     "setup",
     "usage",
+    "speed",
     "logs",
     "brain",
     ...SURFACE_ALIASES.keys(),
@@ -153,6 +154,7 @@ export function localCommandHelp(command) {
         "  cockpit calendar [same verbs and flags as cockpit cal]",
         "  cockpit messages [same verbs and flags as cockpit msg]",
         "  cockpit meeting-notes [same verbs and flags as cockpit notes]",
+        "  cockpit speed [--page <name>]... [--runs <n>] [--dashboard-url <url>] [--json]",
         "  cockpit usage people [--by-repo | --by-topic | --by-subject | --by-task] [--min-confidence high|medium|low] [--person <email|me>] [--all] [--detail] [--since <n>d|<n>h|<iso>] [--until <iso>] [--include-automated] [--dashboard-url <url>] [--json]",
         "",
         `Default dashboard: ${DEFAULT_DASHBOARD_URL}. Omit --dashboard-url for normal production use; pass it only for staging/custom dashboards or to force a different pairing.`,

package/dist/commands/local.js

@@ -52,6 +52,7 @@ import { runCareers } from "./careers.js";
 import { runRename } from "./rename-scope.js";
 import { runSetup } from "./setup.js";
 import { runUsage } from "./usage.js";
+import { runSpeed } from "./speed.js";
 import { runLogs } from "./logs.js";
 import { runBrain } from "./brain.js";
 import { parseLocalArgs } from "./local-args.js";
@@ -249,6 +250,7 @@ export async function runLocalCockpitCli(argv, io = { ...defaultIo(), runDoctorA
                 return await runRename(command, io);
             case "setup": return await runSetup(command, io);
             case "usage": return await runUsage(command, io);
+            case "speed": return await runSpeed(command, io);
             case "logs": return await runLogs(command, io);
             case "brain": return await runBrain(command, io);
         }

package/dist/commands/public-root.js

@@ -21,7 +21,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.193");
+    writeLine(io?.stdout ?? process.stdout, "0.2.194");
     return 0;
   }
 

package/dist/commands/speed-math.js

@@ -0,0 +1,135 @@
+/**
+ * The arithmetic and the layout behind `cockpit speed` (BLI-13033). Pure: no
+ * clock, no network, so the timing math, the ranking and the "not permitted"
+ * rule are all tested with plain numbers.
+ */
+/** 401 is a bad token (a failure to fix); 403 is a page this caller may not open. */
+export function classifyStatus(status) {
+    if (status === 403)
+        return "not_permitted";
+    if (status !== null && status >= 200 && status < 300)
+        return "ok";
+    return "failed";
+}
+/** Nearest-rank percentile over unsorted values. 0 < p <= 100. Null on no values. */
+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;
+}
+/** `total;dur=123.4` out of a Server-Timing header. */
+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),
+    };
+}
+/**
+ * Slowest first by median. Pages that answered come first, then pages that
+ * failed (a failure is something to fix, so it sits above the pages that were
+ * simply not open to this account), then pages not permitted.
+ */
+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);
+    });
+}
+function pad(value, width, right = false) {
+    return right ? value.padStart(width) : value.padEnd(width);
+}
+function ms(value) {
+    return value === null ? "-" : `${Math.round(value)} ms`;
+}
+function size(bytes) {
+    if (bytes === null)
+        return "-";
+    if (bytes < 1024)
+        return `${bytes} B`;
+    return bytes < 1024 * 1024 ? `${(bytes / 1024).toFixed(1)} KB` : `${(bytes / 1024 / 1024).toFixed(2)} MB`;
+}
+/** The ranked table a person reads. Already ranked: this lays out, it does not sort. */
+export function renderSpeedTable(ranked, runs) {
+    const rows = ranked.map((page, index) => {
+        if (page.outcome === "ok") {
+            return [
+                String(index + 1),
+                page.page,
+                ms(page.cold_ms),
+                ms(page.p50_ms),
+                ms(page.p95_ms),
+                String(page.http_status ?? "-"),
+                size(page.bytes),
+                page.server_total_ms === null ? "-" : ms(page.server_total_ms),
+            ];
+        }
+        const word = page.outcome === "not_permitted" ? "not permitted" : `FAILED (${page.reason ?? "unknown"})`;
+        return [String(index + 1), page.page, word, "", "", String(page.http_status ?? "-"), "-", "-"];
+    });
+    const head = ["#", "PAGE", "COLD", "P50", "P95", "HTTP", "BYTES", "SERVER"];
+    const widths = head.map((title, column) => Math.max(title.length, ...rows.map((row) => (row[column] ?? "").length)));
+    const line = (cells) => cells.map((cell, column) => pad(cell, widths[column] ?? 0, column >= 2 && column !== 5)).join("  ").trimEnd();
+    return [
+        line(head),
+        ...rows.map(line),
+        "",
+        `${runs} run${runs === 1 ? "" : "s"} per page: the first is cold, p50 and p95 are over the warm runs${runs === 1 ? " (only the cold run was made)" : ""}. SERVER is the door's own Server-Timing total.`,
+    ];
+}

package/dist/commands/speed-pages.js

@@ -0,0 +1,38 @@
+/**
+ * Which door each rail page opens on (BLI-13033).
+ *
+ * `cockpit speed` times the DATA DOOR of every rail page: the API read the
+ * page's first useful content comes from, or (where the page reads the
+ * database straight from the server) the nearest door that reads the same
+ * rows. It does not time the page's HTML, hydration or paint, so a number here
+ * is the floor of what a person waits, never more than that.
+ *
+ * Order is the rail's order (`ck-rail.tsx` `NAV_ITEMS`). The MCP twin
+ * (`packages/bli-cockpit-mcp/src/speed-tools.ts`) carries its own copy, and a
+ * test in that package fails when the two lists drift.
+ */
+/** The pages in rail order. `memoryContainer` is the tag `cockpit memory profile` would use here. */
+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" },
+    ];
+}
+export const SPEED_PAGE_NAMES = speedPages("x").map((page) => page.name);

package/dist/commands/speed.js

@@ -0,0 +1,130 @@
+/**
+ * `cockpit speed` (BLI-13033) — how long each Tower rail page's data door takes,
+ * measured from this terminal with this machine's own device token.
+ *
+ * For every page: one request per run, the first reported as cold and the rest
+ * as warm, then p50, p95, the HTTP status, the response size and the door's
+ * own `Server-Timing` header. A page this account may not open (Careers for a
+ * member) reads "not permitted", which is an answer, not a failure.
+ *
+ * What a number is: wall-clock from sending the request to the last byte of the
+ * body, on THIS machine, so it includes the network between here and Tower. It
+ * is the data door, not the page's HTML or paint (`speed-pages.ts` says which
+ * door stands for which page). Reads only, and never the local read cache or
+ * the warm-connection route: a speed number that a cache answered would be a
+ * lie about Tower.
+ *
+ * stdout is `--json`'s alone; every log line goes to stderr, metadata only (a
+ * page name, a status, a millisecond count). The device token is attached by
+ * the shared Tower client and never printed.
+ */
+import { resolveContainerTag } from "@bli-cockpit/memory-mcp/dist/container-tag.js";
+import { writeLine } from "./cli-io.js";
+import { classifyStatus, rankPages, renderSpeedTable, summarizeSamples, } from "./speed-math.js";
+import { speedPages } from "./speed-pages.js";
+import { loadPairedSession, towerFailureDetail, towerRequest } from "../tower-client.js";
+export const DEFAULT_SPEED_RUNS = 5;
+const REQUEST_DEADLINE_MS = 60_000;
+export async function runSpeed(command, io, deps = {}) {
+    const now = deps.now ?? (() => performance.now());
+    const log = (line) => writeLine(io.stderr, line);
+    const session = await loadPairedSession("speed", command.homeDir);
+    const dashboardUrl = command.dashboardUrl ?? session.dashboard_url;
+    const runs = command.runs ?? DEFAULT_SPEED_RUNS;
+    const everyPage = speedPages(resolveContainerTag({ cwd: process.cwd() }).containerTag);
+    const chosen = command.pages.length > 0
+        ? everyPage.filter((page) => command.pages.includes(page.name))
+        : everyPage;
+    const results = [];
+    for (const page of chosen) {
+        const samples = [];
+        for (let run = 0; run < runs; run += 1) {
+            const sample = await timeOneRead(page, { dashboardUrl, deviceToken: session.device_token, io, now, log });
+            samples.push(sample);
+            // A page this account may not open answers the same way every time.
+            if (classifyStatus(sample.status) === "not_permitted")
+                break;
+        }
+        const summary = summarizeSamples(page, samples);
+        results.push(summary);
+        log(`[speed cli] page measured ${JSON.stringify({
+            page: summary.page,
+            outcome: summary.outcome,
+            http_status: summary.http_status,
+            runs: samples.length,
+            failed_runs: summary.failed_runs,
+            p50_ms: summary.p50_ms,
+            ...(summary.reason ? { reason: summary.reason } : {}),
+        })}`);
+    }
+    const ranked = rankPages(results);
+    const failed = ranked.filter((page) => page.outcome === "failed").length;
+    const notPermitted = ranked.filter((page) => page.outcome === "not_permitted").length;
+    log(`[speed cli] done ${JSON.stringify({
+        pages: ranked.length,
+        measured: ranked.length - failed - notPermitted,
+        failed,
+        not_permitted: notPermitted,
+        runs,
+    })}`);
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify({
+            ok: failed === 0,
+            measured_at: new Date().toISOString(),
+            dashboard_url: dashboardUrl,
+            runs,
+            pages: ranked,
+        }));
+    }
+    else {
+        for (const line of renderSpeedTable(ranked, runs))
+            writeLine(io.stdout, line);
+    }
+    return failed === 0 ? 0 : 1;
+}
+async function timeOneRead(page, context) {
+    const startedAt = context.now();
+    const answer = await towerRequest({
+        dashboardUrl: context.dashboardUrl,
+        path: page.path,
+        method: "GET",
+        deviceToken: context.deviceToken,
+        fetch: context.io.fetch,
+        label: `speed-${page.name}`,
+        timeoutMs: REQUEST_DEADLINE_MS,
+        // The client's per-request success trace would print 70 lines here; the
+        // failure lines stay.
+        log: (line) => {
+            if (!line.startsWith("[tower client] responded"))
+                context.log(line);
+        },
+    });
+    if (!answer.ok) {
+        return {
+            status: null,
+            ms: context.now() - startedAt,
+            bytes: 0,
+            serverTiming: null,
+            failure: `${answer.reason}: ${towerFailureDetail(answer.reason, answer.detail)}`.slice(0, 120),
+        };
+    }
+    let bytes = 0;
+    try {
+        bytes = (await answer.response.arrayBuffer()).byteLength;
+    }
+    catch {
+        return {
+            status: answer.response.status,
+            ms: context.now() - startedAt,
+            bytes: 0,
+            serverTiming: null,
+            failure: "body_read_failed",
+        };
+    }
+    return {
+        status: answer.response.status,
+        ms: context.now() - startedAt,
+        bytes,
+        serverTiming: answer.response.headers.get("server-timing"),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.193",
+  "version": "0.2.194",
   "private": false,
   "type": "module",
   "bin": {
@@ -28,7 +28,7 @@
   },
   "dependencies": {
     "@bli-cockpit/memory-mcp": "0.1.57",
-    "@bli-cockpit/mcp": "0.1.105",
+    "@bli-cockpit/mcp": "0.1.106",
     "@bli-cockpit/telemetry-core": "0.1.66"
   },
   "repository": {