@bli-cockpit/cli 0.2.81 → 0.2.82

package/dist/commands/heartbeat.js

@@ -31,6 +31,7 @@ import { shouldSuppressFleetReceipts, } from "../dev-build.js";
 import { getCollectorRuntimePaths, readLocalCollectorSessionFile, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
 import { readMemoryReceiptFile } from "./memory-install-receipt.js";
 import { readMemoryHookCounts } from "./memory-hook-counts.js";
+import { readMemoryHookPerformance } from "./memory-hook-performance.js";
 const HEARTBEAT_TIMEOUT_MS = 5_000;
 /**
  * The label form of one approved root.
@@ -191,11 +192,16 @@ export async function readHeartbeatMemoryReceipt(options) {
         homeDir: options.homeDir ?? os.homedir(),
         ...(options.now ? { now: options.now } : {}),
     });
+    const performance = await readMemoryHookPerformance({
+        homeDir: options.homeDir ?? os.homedir(),
+        ...(options.now ? { now: options.now } : {}),
+    });
     return {
         receipt: {
             ...result.receipt,
             ...(hooks.counts ?? {}),
             hook_stats_reason: hooks.reason,
+            hook_performance: performance,
         },
         reason: result.reason,
     };

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

@@ -321,6 +321,9 @@ export function localSubcommandHelp(command) {
                 "      --memory-days N changes the window (1-30) and implies --memory. Searches are",
                 "      NOT counted — nothing in Tower records one, and the gauge says so rather than",
                 "      printing a zero you would read as nobody searching.",
+                "      It also shows ordinary prompt-hook observations: outcome counts, 100 ms",
+                "      duration bounds, actual vector-cache reuse and named coverage gaps. These",
+                "      are hook-body timings, not full host wait or retrieval-quality scores.",
                 "  cockpit ops recompile --person <email|name|id> [--dry-run]",
                 "      Writes that person's page again, now. Your own page is always yours to",
                 "      recompile; somebody else's is for the people who read across the team.",

package/dist/commands/memory-hook-performance.js

@@ -0,0 +1,175 @@
+/** Read independent observations; never turn a missing sample into a zero. */
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { MemoryHookSampleSchema, MemoryHookSamplingLeaseSchema, memoryHookSamplesDirectory, blankHistogram, addDuration, } from "@bli-cockpit/telemetry-core";
+const HOUR_MS = 3_600_000;
+export const HOOK_SAMPLE_RETENTION_HOURS = 48;
+export const HOOK_SAMPLE_READ_LIMIT = 20_000;
+const MAX_SAMPLE_BYTES = 1_024;
+const READ_BUDGET_MS = 1_000;
+const HOUR_DIRECTORY = /^\d{4}-\d{2}-\d{2}T\d{2}$/u;
+const SAMPLE_FILE = /^[a-f0-9-]{36}\.json$/u;
+export async function readMemoryHookPerformance(options) {
+    const now = options.now ?? new Date();
+    const directory = memoryHookSamplesDirectory(options.homeDir);
+    const start = now.getTime() - 24 * HOUR_MS;
+    const reasons = new Set();
+    const result = {
+        schema_version: "memory-hook-performance.v1",
+        window_start: new Date(start).toISOString(),
+        window_end: now.toISOString(),
+        sampling_since: null,
+        samples: 0,
+        outcomes: { printed: 0, empty: 0, timeouts: 0, failed: 0, skipped: 0 },
+        duration_by_cache: {
+            hit: blankHistogram(), miss: blankHistogram(), shared: blankHistogram(), unknown: blankHistogram(),
+        },
+        producer_versions: [],
+        invalid_samples: 0,
+        incomplete_samples: 0,
+        unreadable_samples: 0,
+        capped: false,
+        reasons: [],
+    };
+    const versions = new Map();
+    const started = performance.now();
+    let filesRead = 0;
+    try {
+        const lease = await renewLease(directory, now, reasons);
+        result.sampling_since = lease.continuous_since;
+        if (Date.parse(lease.continuous_since) > start)
+            reasons.add("partial_window");
+        // Exactly the 25 hour directories touching this rolling 24-hour window.
+        // Timestamp filtering below trims both partial boundary hours.
+        hours: for (let offset = 0; offset <= 24; offset += 1) {
+            const hour = new Date(now.getTime() - offset * HOUR_MS).toISOString().slice(0, 13);
+            let entries;
+            try {
+                entries = await fs.opendir(path.join(directory, hour));
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    reasons.add("read_failed");
+                continue;
+            }
+            for await (const entry of entries) {
+                if (!entry.isFile() || !SAMPLE_FILE.test(entry.name))
+                    continue;
+                if (filesRead >= (options.maxFiles ?? HOOK_SAMPLE_READ_LIMIT) ||
+                    performance.now() - started >= (options.readBudgetMs ?? READ_BUDGET_MS)) {
+                    result.capped = true;
+                    reasons.add("read_limit");
+                    break hours;
+                }
+                filesRead += 1;
+                const file = path.join(directory, hour, entry.name);
+                let raw;
+                try {
+                    const stat = await fs.stat(file);
+                    if (stat.size > MAX_SAMPLE_BYTES) {
+                        result.invalid_samples += 1;
+                        continue;
+                    }
+                    raw = await fs.readFile(file, "utf8");
+                }
+                catch {
+                    result.unreadable_samples += 1;
+                    continue;
+                }
+                if (!raw.endsWith("\n")) {
+                    // Could be a live writer or one killed by the host. Leave it for the
+                    // next tick, and keep the incomplete observation out of every rate.
+                    result.incomplete_samples += 1;
+                    continue;
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(raw);
+                }
+                catch {
+                    result.invalid_samples += 1;
+                    continue;
+                }
+                const sample = MemoryHookSampleSchema.safeParse(parsed);
+                if (!sample.success || sample.data.recorded_at.slice(0, 13) !== hour) {
+                    result.invalid_samples += 1;
+                    continue;
+                }
+                const at = Date.parse(sample.data.recorded_at);
+                if (at < start || at > now.getTime())
+                    continue;
+                const version = sample.data.producer_version;
+                if (!versions.has(version) && versions.size >= 16) {
+                    result.capped = true;
+                    reasons.add("read_limit");
+                    break hours;
+                }
+                result.samples += 1;
+                result.outcomes[sample.data.outcome] += 1;
+                addDuration(result.duration_by_cache[sample.data.embed_cache], sample.data.elapsed_ms);
+                versions.set(version, (versions.get(version) ?? 0) + 1);
+            }
+        }
+        await pruneExpiredHours(directory, now, reasons);
+    }
+    catch {
+        reasons.add("read_failed");
+    }
+    if (!result.samples)
+        reasons.add("no_samples");
+    if (result.invalid_samples)
+        reasons.add("invalid_samples");
+    if (result.incomplete_samples)
+        reasons.add("incomplete_samples");
+    if (result.unreadable_samples)
+        reasons.add("unreadable_samples");
+    result.producer_versions = [...versions].sort(([a], [b]) => a.localeCompare(b))
+        .map(([version, samples]) => ({ version, samples }));
+    result.reasons = [...reasons];
+    return result;
+}
+async function renewLease(directory, now, reasons) {
+    let continuousSince = now.toISOString();
+    try {
+        const previous = MemoryHookSamplingLeaseSchema.safeParse(JSON.parse(await fs.readFile(path.join(directory, "lease.json"), "utf8")));
+        if (!previous.success || Date.parse(previous.data.continuous_since) > now.getTime())
+            reasons.add("lease_invalid");
+        else if (Date.parse(previous.data.expires_at) <= now.getTime())
+            reasons.add("lease_expired");
+        else
+            continuousSince = previous.data.continuous_since;
+    }
+    catch (error) {
+        reasons.add(error.code === "ENOENT" ? "lease_absent" : "lease_invalid");
+    }
+    const lease = {
+        schema_version: "memory-hook-sampling-lease.v1",
+        continuous_since: continuousSince,
+        expires_at: new Date(now.getTime() + HOOK_SAMPLE_RETENTION_HOURS * HOUR_MS).toISOString(),
+    };
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    const temporary = path.join(directory, `${randomUUID()}.lease.tmp`);
+    await fs.writeFile(temporary, `${JSON.stringify(lease)}\n`, { flag: "wx", mode: 0o600 });
+    await fs.rename(temporary, path.join(directory, "lease.json"));
+    return lease;
+}
+async function pruneExpiredHours(directory, now, reasons) {
+    const oldest = new Date(now.getTime() - HOOK_SAMPLE_RETENTION_HOURS * HOUR_MS).toISOString().slice(0, 13);
+    try {
+        const entries = await fs.opendir(directory);
+        let pruned = 0;
+        for await (const entry of entries) {
+            if (!entry.isDirectory() || !HOUR_DIRECTORY.test(entry.name) || entry.name >= oldest)
+                continue;
+            // Cleanup belongs to the collector and cannot delay a prompt. A bounded
+            // number of expired hours is enough to catch up over successive ticks.
+            await fs.rm(path.join(directory, entry.name), { recursive: true, force: true });
+            if (++pruned >= 8)
+                break;
+        }
+    }
+    catch {
+        reasons.add("cleanup_failed");
+    }
+}

package/dist/commands/ops-render-memory.js

@@ -101,6 +101,8 @@ export function renderMemoryHooks(hooks, dim) {
     for (const device of ranked) {
         const line = `  ${device.line ?? `${device.displayName ?? "?"}: (no line)`}`;
         lines.push((device.timeouts ?? 0) > 0 ? line : dim(line));
+        if (device.performanceLine)
+            lines.push(`    ${device.performanceLine}`);
     }
     return lines;
 }

package/dist/commands/public-root.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.81",
+  "version": "0.2.82",
   "private": false,
   "type": "module",
   "bin": {
@@ -27,8 +27,8 @@
     "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-cli-verb-help.mjs && node ../../scripts/assert-public-cli-runtime-files.mjs && node ../../scripts/assert-public-cli-no-fleet-posts.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
-    "@bli-cockpit/memory-mcp": "0.1.13",
-    "@bli-cockpit/mcp": "0.1.15",
-    "@bli-cockpit/telemetry-core": "0.1.32"
+    "@bli-cockpit/memory-mcp": "0.1.14",
+    "@bli-cockpit/mcp": "0.1.16",
+    "@bli-cockpit/telemetry-core": "0.1.33"
   }
 }