@bli-cockpit/telemetry-core 0.1.30 → 0.1.31

package/dist/collector-heartbeat.d.ts

@@ -99,6 +99,11 @@ export declare const CollectorHeartbeatSchema: z.ZodObject<{
         }, z.core.$strict>;
         reasons: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         bin_found: z.ZodOptional<z.ZodBoolean>;
+        hook_runs_24h: z.ZodOptional<z.ZodNumber>;
+        hook_timeouts_24h: z.ZodOptional<z.ZodNumber>;
+        hook_printed_24h: z.ZodOptional<z.ZodNumber>;
+        hook_failed_24h: z.ZodOptional<z.ZodNumber>;
+        hook_stats_reason: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>;
     setup_receipt: z.ZodOptional<z.ZodObject<{
         schema_version: z.ZodLiteral<"setup-receipt.v1">;

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export * from "./evidence-reconcile.js";
 export * from "./evidence-upload.js";
 export * from "./ingest-dto.js";
 export * from "./local-config.js";
+export * from "./memory-hook-stats.js";
 export * from "./memory-install-receipt.js";
 export * from "./paths.js";
 export * from "./privacy.js";

package/dist/index.js

@@ -9,6 +9,7 @@ export * from "./evidence-reconcile.js";
 export * from "./evidence-upload.js";
 export * from "./ingest-dto.js";
 export * from "./local-config.js";
+export * from "./memory-hook-stats.js";
 export * from "./memory-install-receipt.js";
 export * from "./paths.js";
 export * from "./privacy.js";

package/dist/memory-hook-stats.d.ts

@@ -0,0 +1,105 @@
+/**
+ * THE HOOK COUNTER, SHARED (BLI-3788).
+ *
+ * `@bli-cockpit/memory-mcp` WRITES this file — one hook run at a time, on the
+ * machine, counts only — and `@bli-cockpit/local-collector` READS it once a
+ * tick to put `hook_timeouts_24h` on the heartbeat's memory receipt. The two
+ * packages are published separately and never import each other, so the
+ * contract between them lives here, in the one package they both depend on:
+ * the file's address, its shape, and the rule for turning hourly buckets into
+ * a 24-hour number.
+ *
+ * The alternative was two copies of a JSON shape kept in step by comment, and
+ * BLI-2541 is what that costs — a fixture built from our own formatting rather
+ * than from the real thing, green while the fleet was broken.
+ *
+ * WHY IT EXISTS AT ALL: a prompt hook that misses its deadline prints NOTHING,
+ * deliberately. That is right for the person and blind for the operator, and
+ * QA tick 18 found the recall silently missing on 4 of 6 runs with no surface
+ * anywhere reporting it. These counts are that silence made countable.
+ *
+ * WHAT MAY NEVER BE IN IT: a prompt, a memory, a container tag, a path, a
+ * token, or any string that did not come from the hook's own closed reason
+ * vocabulary. Counts and hour labels, nothing else.
+ */
+import { z } from "zod";
+export declare const MEMORY_HOOK_STATS_SCHEMA_VERSION = "memory-hook-stats.v1";
+/** The file name, in the collector's state directory. One spelling, here. */
+export declare const MEMORY_HOOK_STATS_FILE_NAME = "memory-hook-stats.json";
+/** The three hook events, spelled as the bin's subcommands are. */
+export declare const MEMORY_HOOK_STAT_EVENTS: readonly ["session-start", "prompt", "stop"];
+export type MemoryHookStatEvent = (typeof MEMORY_HOOK_STAT_EVENTS)[number];
+/**
+ * One hour of one event.
+ *
+ * `timeouts` is counted apart from `failed` (a refusal, an outage, an
+ * unpaired machine — different fixes) and apart from `empty` (the record was
+ * genuinely silent, which is an answer and not a fault). Collapsing them is
+ * exactly how "the door is slow" and "the shelf is empty" became one
+ * unreadable number in the first place.
+ */
+export declare const MemoryHookCountsSchema: z.ZodObject<{
+    runs: z.ZodNumber;
+    printed: z.ZodNumber;
+    empty: z.ZodNumber;
+    timeouts: z.ZodNumber;
+    failed: z.ZodNumber;
+    skipped: z.ZodNumber;
+}, z.core.$strict>;
+export type MemoryHookCounts = z.infer<typeof MemoryHookCountsSchema>;
+/** `YYYY-MM-DDTHH` in UTC — the bucket key, and the reason the window is exact. */
+export declare const MEMORY_HOOK_BUCKET_PATTERN: RegExp;
+export declare const MemoryHookStatsFileSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"memory-hook-stats.v1">;
+    buckets: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodEnum<{
+        "session-start": "session-start";
+        prompt: "prompt";
+        stop: "stop";
+    }> & z.core.$partial, z.ZodObject<{
+        runs: z.ZodNumber;
+        printed: z.ZodNumber;
+        empty: z.ZodNumber;
+        timeouts: z.ZodNumber;
+        failed: z.ZodNumber;
+        skipped: z.ZodNumber;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type MemoryHookStatsFile = z.infer<typeof MemoryHookStatsFileSchema>;
+export declare function memoryHookStatsFilePath(homeDir: string): string;
+/** The hour a moment belongs to. UTC, so two machines agree on a boundary. */
+export declare function memoryHookHourBucket(at: Date): string;
+export declare function emptyMemoryHookCounts(): MemoryHookCounts;
+export interface MemoryHookWindow {
+    runs: number;
+    printed: number;
+    timeouts: number;
+    failed: number;
+    /** Buckets that were inside the window and had something in them. */
+    hours: number;
+}
+/**
+ * Sum one event's buckets over the last `hours` hours, ending at `now`.
+ *
+ * The window is inclusive of the hour `now` falls in, so a run three minutes
+ * ago counts; that makes the last bucket partial, which is the honest
+ * direction for a gauge whose whole job is to notice that something is going
+ * wrong RIGHT NOW.
+ */
+export declare function summariseMemoryHookWindow(file: MemoryHookStatsFile, event: MemoryHookStatEvent, options: {
+    now: Date;
+    hours?: number;
+}): MemoryHookWindow;
+/**
+ * Parse what is on disk, or say why not.
+ *
+ * A file this version does not recognise is REPLACED by the writer and
+ * reported as unreadable by the reader — never merged into a shape it was not
+ * written in, which would publish a number nobody can explain.
+ */
+export declare function parseMemoryHookStats(raw: string): {
+    ok: true;
+    file: MemoryHookStatsFile;
+} | {
+    ok: false;
+    reason: string;
+};

package/dist/memory-hook-stats.js

@@ -0,0 +1,122 @@
+/**
+ * THE HOOK COUNTER, SHARED (BLI-3788).
+ *
+ * `@bli-cockpit/memory-mcp` WRITES this file — one hook run at a time, on the
+ * machine, counts only — and `@bli-cockpit/local-collector` READS it once a
+ * tick to put `hook_timeouts_24h` on the heartbeat's memory receipt. The two
+ * packages are published separately and never import each other, so the
+ * contract between them lives here, in the one package they both depend on:
+ * the file's address, its shape, and the rule for turning hourly buckets into
+ * a 24-hour number.
+ *
+ * The alternative was two copies of a JSON shape kept in step by comment, and
+ * BLI-2541 is what that costs — a fixture built from our own formatting rather
+ * than from the real thing, green while the fleet was broken.
+ *
+ * WHY IT EXISTS AT ALL: a prompt hook that misses its deadline prints NOTHING,
+ * deliberately. That is right for the person and blind for the operator, and
+ * QA tick 18 found the recall silently missing on 4 of 6 runs with no surface
+ * anywhere reporting it. These counts are that silence made countable.
+ *
+ * WHAT MAY NEVER BE IN IT: a prompt, a memory, a container tag, a path, a
+ * token, or any string that did not come from the hook's own closed reason
+ * vocabulary. Counts and hour labels, nothing else.
+ */
+import { z } from "zod";
+import { getUserLocalCockpitPaths } from "./paths.js";
+export const MEMORY_HOOK_STATS_SCHEMA_VERSION = "memory-hook-stats.v1";
+/** The file name, in the collector's state directory. One spelling, here. */
+export const MEMORY_HOOK_STATS_FILE_NAME = "memory-hook-stats.json";
+/** The three hook events, spelled as the bin's subcommands are. */
+export const MEMORY_HOOK_STAT_EVENTS = ["session-start", "prompt", "stop"];
+/**
+ * One hour of one event.
+ *
+ * `timeouts` is counted apart from `failed` (a refusal, an outage, an
+ * unpaired machine — different fixes) and apart from `empty` (the record was
+ * genuinely silent, which is an answer and not a fault). Collapsing them is
+ * exactly how "the door is slow" and "the shelf is empty" became one
+ * unreadable number in the first place.
+ */
+export const MemoryHookCountsSchema = z
+    .object({
+    runs: z.number().int().min(0),
+    printed: z.number().int().min(0),
+    empty: z.number().int().min(0),
+    timeouts: z.number().int().min(0),
+    failed: z.number().int().min(0),
+    skipped: z.number().int().min(0),
+})
+    .strict();
+/** `YYYY-MM-DDTHH` in UTC — the bucket key, and the reason the window is exact. */
+export const MEMORY_HOOK_BUCKET_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}$/u;
+export const MemoryHookStatsFileSchema = z
+    .object({
+    schema_version: z.literal(MEMORY_HOOK_STATS_SCHEMA_VERSION),
+    // `partialRecord`, not `record`: a record keyed by an enum is EXHAUSTIVE
+    // in zod 4 — every event would be required — and an hour in which only
+    // the prompt hook ran is the ordinary case, not a malformed file.
+    buckets: z.record(z.string().regex(MEMORY_HOOK_BUCKET_PATTERN), z.partialRecord(z.enum(MEMORY_HOOK_STAT_EVENTS), MemoryHookCountsSchema)),
+})
+    .strict();
+export function memoryHookStatsFilePath(homeDir) {
+    const paths = getUserLocalCockpitPaths(homeDir);
+    const separator = paths.state_dir.includes("\\") ? "\\" : "/";
+    return `${paths.state_dir}${separator}${MEMORY_HOOK_STATS_FILE_NAME}`;
+}
+/** The hour a moment belongs to. UTC, so two machines agree on a boundary. */
+export function memoryHookHourBucket(at) {
+    return at.toISOString().slice(0, 13);
+}
+export function emptyMemoryHookCounts() {
+    return { runs: 0, printed: 0, empty: 0, timeouts: 0, failed: 0, skipped: 0 };
+}
+/**
+ * Sum one event's buckets over the last `hours` hours, ending at `now`.
+ *
+ * The window is inclusive of the hour `now` falls in, so a run three minutes
+ * ago counts; that makes the last bucket partial, which is the honest
+ * direction for a gauge whose whole job is to notice that something is going
+ * wrong RIGHT NOW.
+ */
+export function summariseMemoryHookWindow(file, event, options) {
+    const hours = options.hours ?? 24;
+    const earliest = memoryHookHourBucket(new Date(options.now.getTime() - (hours - 1) * 3_600_000));
+    const latest = memoryHookHourBucket(options.now);
+    const total = { runs: 0, printed: 0, timeouts: 0, failed: 0, hours: 0 };
+    for (const [bucket, events] of Object.entries(file.buckets)) {
+        // Lexical order is chronological for this key, which is the only reason a
+        // string comparison is allowed to stand in for a date one here.
+        if (bucket < earliest || bucket > latest)
+            continue;
+        const counts = events[event];
+        if (!counts)
+            continue;
+        total.runs += counts.runs;
+        total.printed += counts.printed;
+        total.timeouts += counts.timeouts;
+        total.failed += counts.failed;
+        total.hours += 1;
+    }
+    return total;
+}
+/**
+ * Parse what is on disk, or say why not.
+ *
+ * A file this version does not recognise is REPLACED by the writer and
+ * reported as unreadable by the reader — never merged into a shape it was not
+ * written in, which would publish a number nobody can explain.
+ */
+export function parseMemoryHookStats(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, reason: "hook_stats_unparseable" };
+    }
+    const result = MemoryHookStatsFileSchema.safeParse(parsed);
+    if (!result.success)
+        return { ok: false, reason: "hook_stats_unrecognised_shape" };
+    return { ok: true, file: result.data };
+}

package/dist/memory-install-receipt.d.ts

@@ -109,6 +109,11 @@ export declare const MemoryInstallReceiptSchema: z.ZodObject<{
     }, z.core.$strict>;
     reasons: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     bin_found: z.ZodOptional<z.ZodBoolean>;
+    hook_runs_24h: z.ZodOptional<z.ZodNumber>;
+    hook_timeouts_24h: z.ZodOptional<z.ZodNumber>;
+    hook_printed_24h: z.ZodOptional<z.ZodNumber>;
+    hook_failed_24h: z.ZodOptional<z.ZodNumber>;
+    hook_stats_reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type MemoryInstallReceipt = z.infer<typeof MemoryInstallReceiptSchema>;
 /** Every piece is `ok`. The one question the board asks first. */

package/dist/memory-install-receipt.js

@@ -103,6 +103,36 @@ export const MemoryInstallReceiptSchema = z
      * (`no_bin_no_write`).
      */
     bin_found: z.boolean().optional(),
+    /**
+     * DID THE HOOKS ACTUALLY WORK? (BLI-3788)
+     *
+     * The five words above say a hook is REGISTERED. They cannot say whether
+     * it did anything, and a prompt hook that loses its deadline prints
+     * nothing by design — so a machine could read `memory: claude mcp ✓ hooks
+     * ✓` while two thirds of that person's turns silently got no recall (QA
+     * tick 18). These four counts, summed over the last 24 hours from the
+     * hook's own on-disk counter, are that gap closed:
+     *
+     *   `hook_runs_24h`      hooks that ran at all — the denominator, without
+     *                        which a timeout count says nothing
+     *   `hook_timeouts_24h`  runs that lost the clock and printed nothing
+     *   `hook_printed_24h`   runs that injected a block
+     *   `hook_failed_24h`    runs that could not run (a refusal, an outage)
+     *
+     * An honestly EMPTY shelf is in none of them but `runs`, because zero hits
+     * is a real answer and not a fault. All four are optional: a collector or
+     * a memory-mcp older than this ticket reports none, and absent must read
+     * as "not reported", never as zero.
+     *
+     * They are a FLOOR. Two hooks finishing in the same millisecond can lose
+     * one increment to the file rename, which understates and cannot invent.
+     */
+    hook_runs_24h: z.number().int().min(0).optional(),
+    hook_timeouts_24h: z.number().int().min(0).optional(),
+    hook_printed_24h: z.number().int().min(0).optional(),
+    hook_failed_24h: z.number().int().min(0).optional(),
+    /** Named when the counts are absent because the file could not be read. */
+    hook_stats_reason: ReasonLabelSchema.optional(),
 })
     .strict();
 /** Every piece is `ok`. The one question the board asks first. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/telemetry-core",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",