@bli-cockpit/telemetry-core 0.1.33 → 0.1.35

package/dist/collector-heartbeat.d.ts

@@ -105,6 +105,9 @@ export declare const CollectorHeartbeatSchema: z.ZodObject<{
         hook_timeouts_24h: z.ZodOptional<z.ZodNumber>;
         hook_printed_24h: z.ZodOptional<z.ZodNumber>;
         hook_failed_24h: z.ZodOptional<z.ZodNumber>;
+        hook_via_daemon_24h: z.ZodOptional<z.ZodNumber>;
+        hook_via_direct_24h: z.ZodOptional<z.ZodNumber>;
+        hook_skipped_trivial_24h: z.ZodOptional<z.ZodNumber>;
         hook_stats_reason: z.ZodOptional<z.ZodString>;
         hook_performance: z.ZodOptional<z.ZodObject<{
             schema_version: z.ZodLiteral<"memory-hook-performance.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-daemon-endpoint.js";
 export * from "./memory-hook-stats.js";
 export * from "./memory-hook-performance.js";
 export * from "./memory-install-receipt.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-daemon-endpoint.js";
 export * from "./memory-hook-stats.js";
 export * from "./memory-hook-performance.js";
 export * from "./memory-install-receipt.js";

package/dist/memory-daemon-endpoint.d.ts

@@ -0,0 +1,114 @@
+/**
+ * WHERE THE RESIDENT MEMORY DAEMON LISTENS (BLI-3884).
+ *
+ * `@bli-cockpit/memory-mcp` RUNS the daemon (`bli-memory-mcp daemon`) and its
+ * hooks CALL it; `@bli-cockpit/local-collector` only ever ASKS whether it is
+ * answering (`cockpit doctor`'s `memory-daemon` row, `cockpit memory status`).
+ * The two packages are published separately and never import each other, so
+ * the address, the protocol words and the four numbers that govern the
+ * handshake live here, in the one package they both depend on — the same rule
+ * `memory-hook-stats.ts` next door was written under, and for the same reason:
+ * two copies of a wire contract kept in step by comment is the BLI-2541
+ * failure.
+ *
+ * ## The address
+ *
+ * macOS and Linux: a unix socket in the collector's own state directory,
+ * created 0600 inside a 0700 directory, so the endpoint is the OS user's and
+ * nobody else's. Windows: a named pipe, `\\.\pipe\bli-memory-<user>` — a
+ * Windows pipe has no directory and no mode bits, so the USER NAME is what
+ * makes it per-user, and the daemon never puts anything on the wire that a
+ * caller has not already got (see the protocol below).
+ *
+ * ## What may never travel on it
+ *
+ * The device token. The hook sends `{event, payload, cwd}` and nothing else;
+ * the daemon reads the machine's own session file itself. A protocol that
+ * carried the credential would put it in every hook process on the machine
+ * for no gain — the daemon is already running as the same user that can read
+ * the session file.
+ */
+/** The wire vocabulary's version, sent on every request and answer. */
+export declare const MEMORY_DAEMON_PROTOCOL_VERSION = "memory-daemon.v1";
+/** The socket file, in the collector's state directory. One spelling, here. */
+export declare const MEMORY_DAEMON_SOCKET_FILE_NAME = "memory-daemon.sock";
+/**
+ * The stamp a hook writes when it spawns a daemon, beside the socket. It is
+ * the rate limit: a machine where the daemon cannot start must not spawn one
+ * per prompt, so a hook that finds no daemon looks here first and only tries
+ * again an hour later.
+ */
+export declare const MEMORY_DAEMON_SPAWN_STAMP_FILE_NAME = "memory-daemon-spawn.json";
+/** Windows named pipes live in one flat namespace; the user makes it per-user. */
+export declare const MEMORY_DAEMON_PIPE_PREFIX = "\\\\.\\pipe\\bli-memory-";
+/**
+ * How long a hook may wait to CONNECT before giving up on the daemon.
+ *
+ * A connect to a live local socket is sub-millisecond. This budget is not
+ * sized for the connect; it is sized so that a daemon which is wedged,
+ * half-dead or being replaced costs a person 50 ms and then gets out of the
+ * way. The whole call still sits inside the hook's own `HOOK_BUDGETS`
+ * deadline, which was started before the connect.
+ */
+export declare const MEMORY_DAEMON_CONNECT_TIMEOUT_MS = 50;
+/** At most one spawn attempt per hour per machine. */
+export declare const MEMORY_DAEMON_SPAWN_INTERVAL_MS = 3600000;
+/** The daemon exits after this long with no request. Two hours. */
+export declare const MEMORY_DAEMON_IDLE_EXIT_MS = 7200000;
+/**
+ * How long a unix socket PATH may be, in bytes, before the platform refuses to
+ * bind it. `sun_path` is 104 on macOS/BSD and 108 on Linux; 100 is the safe
+ * floor under both. A real machine is nowhere near it — `/Users/<name>/.local/
+ * state/bli-cockpit/memory-daemon.sock` is about 60 characters — but a deeply
+ * nested HOME (a container, a temp directory in a test) is, and `bind` answers
+ * EINVAL, which reads as a bug rather than as a limit. The endpoint says so by
+ * name instead, and every hook simply goes the direct way.
+ */
+export declare const MEMORY_DAEMON_UNIX_PATH_MAX = 100;
+/**
+ * The largest single line either side will read. A prompt is capped at 1,000
+ * characters before it ever reaches the door, and a recall block is a few KB;
+ * 1 MB is far above both and bounds a peer that never sends a newline.
+ */
+export declare const MEMORY_DAEMON_MAX_LINE_BYTES = 1048576;
+export interface MemoryDaemonEndpoint {
+    /** Which kind of endpoint this platform gets. */
+    kind: "unix" | "pipe";
+    /** What `net.connect` / `server.listen` is handed. */
+    address: string;
+    /** The spawn rate-limit stamp. Always a real file, on both platforms. */
+    stampFile: string;
+    /** The directory both live in (the pipe's stamp lives here too). */
+    stateDir: string;
+    /**
+     * True when a unix socket at this address would exceed `sun_path`. Nothing
+     * is invented in that case — no second address, no temp directory that the
+     * daemon and the probe could disagree about; the daemon refuses by name and
+     * every hook keeps working on the direct path.
+     */
+    addressTooLong: boolean;
+}
+export interface MemoryDaemonEndpointOptions {
+    homeDir: string;
+    /** Defaults to this process's platform. Injected by the tests. */
+    platform?: NodeJS.Platform;
+    /** The OS user name. Only Windows uses it; ignored elsewhere. */
+    username?: string;
+}
+/**
+ * The one place the daemon's address is computed. Both packages call this;
+ * nobody joins a socket path by hand.
+ */
+export declare function memoryDaemonEndpoint(options: MemoryDaemonEndpointOptions): MemoryDaemonEndpoint;
+/**
+ * A Windows user name folded into something a pipe name may hold.
+ *
+ * Real ones carry spaces, dots and a `DOMAIN\user` prefix, and a pipe name is
+ * a path segment — an unfiltered name would either fail to bind or, worse,
+ * bind somewhere unintended. Everything outside `[A-Za-z0-9_-]` becomes `-`,
+ * the whole thing is lower-cased so two spellings of one account do not get
+ * two daemons, and a name that reduces to nothing falls back to `user`, which
+ * is still per-user in practice because the pipe is created by that user's
+ * own session.
+ */
+export declare function pipeUserSegment(username: string | undefined): string;

package/dist/memory-daemon-endpoint.js

@@ -0,0 +1,124 @@
+/**
+ * WHERE THE RESIDENT MEMORY DAEMON LISTENS (BLI-3884).
+ *
+ * `@bli-cockpit/memory-mcp` RUNS the daemon (`bli-memory-mcp daemon`) and its
+ * hooks CALL it; `@bli-cockpit/local-collector` only ever ASKS whether it is
+ * answering (`cockpit doctor`'s `memory-daemon` row, `cockpit memory status`).
+ * The two packages are published separately and never import each other, so
+ * the address, the protocol words and the four numbers that govern the
+ * handshake live here, in the one package they both depend on — the same rule
+ * `memory-hook-stats.ts` next door was written under, and for the same reason:
+ * two copies of a wire contract kept in step by comment is the BLI-2541
+ * failure.
+ *
+ * ## The address
+ *
+ * macOS and Linux: a unix socket in the collector's own state directory,
+ * created 0600 inside a 0700 directory, so the endpoint is the OS user's and
+ * nobody else's. Windows: a named pipe, `\\.\pipe\bli-memory-<user>` — a
+ * Windows pipe has no directory and no mode bits, so the USER NAME is what
+ * makes it per-user, and the daemon never puts anything on the wire that a
+ * caller has not already got (see the protocol below).
+ *
+ * ## What may never travel on it
+ *
+ * The device token. The hook sends `{event, payload, cwd}` and nothing else;
+ * the daemon reads the machine's own session file itself. A protocol that
+ * carried the credential would put it in every hook process on the machine
+ * for no gain — the daemon is already running as the same user that can read
+ * the session file.
+ */
+import { getUserLocalCockpitPaths } from "./paths.js";
+/** The wire vocabulary's version, sent on every request and answer. */
+export const MEMORY_DAEMON_PROTOCOL_VERSION = "memory-daemon.v1";
+/** The socket file, in the collector's state directory. One spelling, here. */
+export const MEMORY_DAEMON_SOCKET_FILE_NAME = "memory-daemon.sock";
+/**
+ * The stamp a hook writes when it spawns a daemon, beside the socket. It is
+ * the rate limit: a machine where the daemon cannot start must not spawn one
+ * per prompt, so a hook that finds no daemon looks here first and only tries
+ * again an hour later.
+ */
+export const MEMORY_DAEMON_SPAWN_STAMP_FILE_NAME = "memory-daemon-spawn.json";
+/** Windows named pipes live in one flat namespace; the user makes it per-user. */
+export const MEMORY_DAEMON_PIPE_PREFIX = "\\\\.\\pipe\\bli-memory-";
+/**
+ * How long a hook may wait to CONNECT before giving up on the daemon.
+ *
+ * A connect to a live local socket is sub-millisecond. This budget is not
+ * sized for the connect; it is sized so that a daemon which is wedged,
+ * half-dead or being replaced costs a person 50 ms and then gets out of the
+ * way. The whole call still sits inside the hook's own `HOOK_BUDGETS`
+ * deadline, which was started before the connect.
+ */
+export const MEMORY_DAEMON_CONNECT_TIMEOUT_MS = 50;
+/** At most one spawn attempt per hour per machine. */
+export const MEMORY_DAEMON_SPAWN_INTERVAL_MS = 3_600_000;
+/** The daemon exits after this long with no request. Two hours. */
+export const MEMORY_DAEMON_IDLE_EXIT_MS = 7_200_000;
+/**
+ * How long a unix socket PATH may be, in bytes, before the platform refuses to
+ * bind it. `sun_path` is 104 on macOS/BSD and 108 on Linux; 100 is the safe
+ * floor under both. A real machine is nowhere near it — `/Users/<name>/.local/
+ * state/bli-cockpit/memory-daemon.sock` is about 60 characters — but a deeply
+ * nested HOME (a container, a temp directory in a test) is, and `bind` answers
+ * EINVAL, which reads as a bug rather than as a limit. The endpoint says so by
+ * name instead, and every hook simply goes the direct way.
+ */
+export const MEMORY_DAEMON_UNIX_PATH_MAX = 100;
+/**
+ * The largest single line either side will read. A prompt is capped at 1,000
+ * characters before it ever reaches the door, and a recall block is a few KB;
+ * 1 MB is far above both and bounds a peer that never sends a newline.
+ */
+export const MEMORY_DAEMON_MAX_LINE_BYTES = 1_048_576;
+/**
+ * The one place the daemon's address is computed. Both packages call this;
+ * nobody joins a socket path by hand.
+ */
+export function memoryDaemonEndpoint(options) {
+    const paths = getUserLocalCockpitPaths(options.homeDir);
+    const platform = options.platform ?? process.platform;
+    const separator = paths.state_dir.includes("\\") ? "\\" : "/";
+    const stampFile = `${paths.state_dir}${separator}${MEMORY_DAEMON_SPAWN_STAMP_FILE_NAME}`;
+    if (platform === "win32") {
+        return {
+            kind: "pipe",
+            address: `${MEMORY_DAEMON_PIPE_PREFIX}${pipeUserSegment(options.username)}`,
+            stampFile,
+            stateDir: paths.state_dir,
+            // A named pipe is not a filesystem path and has no length problem.
+            addressTooLong: false,
+        };
+    }
+    const address = `${paths.state_dir}${separator}${MEMORY_DAEMON_SOCKET_FILE_NAME}`;
+    return {
+        kind: "unix",
+        address,
+        stampFile,
+        stateDir: paths.state_dir,
+        // Bytes, not characters, and no `Buffer`: this module is imported by the
+        // dashboard as well as by two CLIs.
+        addressTooLong: new TextEncoder().encode(address).length > MEMORY_DAEMON_UNIX_PATH_MAX,
+    };
+}
+/**
+ * A Windows user name folded into something a pipe name may hold.
+ *
+ * Real ones carry spaces, dots and a `DOMAIN\user` prefix, and a pipe name is
+ * a path segment — an unfiltered name would either fail to bind or, worse,
+ * bind somewhere unintended. Everything outside `[A-Za-z0-9_-]` becomes `-`,
+ * the whole thing is lower-cased so two spellings of one account do not get
+ * two daemons, and a name that reduces to nothing falls back to `user`, which
+ * is still per-user in practice because the pipe is created by that user's
+ * own session.
+ */
+export function pipeUserSegment(username) {
+    const folded = (username ?? "")
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/gu, "-")
+        .replace(/^-+|-+$/gu, "")
+        .slice(0, 48);
+    return folded.length > 0 ? folded : "user";
+}

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

@@ -45,6 +45,9 @@ export declare const MemoryHookCountsSchema: z.ZodObject<{
     timeouts: z.ZodNumber;
     failed: z.ZodNumber;
     skipped: z.ZodNumber;
+    via_daemon: z.ZodOptional<z.ZodNumber>;
+    via_direct: z.ZodOptional<z.ZodNumber>;
+    skipped_trivial: z.ZodOptional<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. */
@@ -62,6 +65,9 @@ export declare const MemoryHookStatsFileSchema: z.ZodObject<{
         timeouts: z.ZodNumber;
         failed: z.ZodNumber;
         skipped: z.ZodNumber;
+        via_daemon: z.ZodOptional<z.ZodNumber>;
+        via_direct: z.ZodOptional<z.ZodNumber>;
+        skipped_trivial: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
 export type MemoryHookStatsFile = z.infer<typeof MemoryHookStatsFileSchema>;
@@ -74,6 +80,18 @@ export interface MemoryHookWindow {
     printed: number;
     timeouts: number;
     failed: number;
+    /**
+     * BLI-3884. How many of those runs the resident daemon answered, and how
+     * many took the original direct path. Summed only over buckets that CARRY
+     * the field, so a window spanning an upgrade reports what was measured
+     * rather than crediting the old rows to `direct`.
+     */
+    viaDaemon: number;
+    viaDirect: number;
+    /** True when at least one bucket in the window named a route at all. */
+    viaMeasured: boolean;
+    /** Trivial prompts the hook declined to search for (BLI-3881). A subset of skips. */
+    skippedTrivial: number;
     /** Buckets that were inside the window and had something in them. */
     hours: number;
 }

package/dist/memory-hook-stats.js

@@ -46,6 +46,36 @@ export const MemoryHookCountsSchema = z
     timeouts: z.number().int().min(0),
     failed: z.number().int().min(0),
     skipped: z.number().int().min(0),
+    /**
+     * WHICH ROUTE ANSWERED (BLI-3884). `via_daemon` counts runs the resident
+     * local daemon answered; `via_direct` counts runs that went the original
+     * way — a fresh process, a cold connection, the whole gate.
+     *
+     * Both are OPTIONAL and both are absent on a machine older than the
+     * daemon, which must read as "not measured" and never as "no daemon
+     * ever answered". They do not have to sum to `runs`: a run that never
+     * reached either route (no payload, no session) has no route to name,
+     * and is counted in `skipped` alone.
+     */
+    via_daemon: z.number().int().min(0).optional(),
+    via_direct: z.number().int().min(0).optional(),
+    /**
+     * BLI-3881 — the SUBSET of `skipped` the hook declined to search for.
+     *
+     * "ok", "continue", "y", a slash command: a turn whose whole text carries
+     * no subject to recall against. Searching one spends a person's whole
+     * budget on a query that can only return noise, so the hook returns early
+     * and this counts how often — because a hook that stops doing something
+     * and says nothing is indistinguishable from a hook that broke.
+     *
+     * OPTIONAL, and it must stay optional: a file written by a memory-mcp
+     * older than this ticket has no such key, and `MemoryHookCountsSchema` is
+     * strict, so a required field would make every existing machine's history
+     * `hook_stats_unrecognised_shape` overnight. It is counted BESIDE
+     * `skipped`, never instead of it, so `runs = printed + empty + timeouts +
+     * failed + skipped` still holds.
+     */
+    skipped_trivial: z.number().int().min(0).optional(),
 })
     .strict();
 /** `YYYY-MM-DDTHH` in UTC — the bucket key, and the reason the window is exact. */
@@ -69,7 +99,7 @@ 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 };
+    return { runs: 0, printed: 0, empty: 0, timeouts: 0, failed: 0, skipped: 0, skipped_trivial: 0 };
 }
 /**
  * Sum one event's buckets over the last `hours` hours, ending at `now`.
@@ -83,7 +113,17 @@ 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 };
+    const total = {
+        runs: 0,
+        printed: 0,
+        timeouts: 0,
+        failed: 0,
+        viaDaemon: 0,
+        viaDirect: 0,
+        viaMeasured: false,
+        skippedTrivial: 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.
@@ -96,6 +136,14 @@ export function summariseMemoryHookWindow(file, event, options) {
         total.printed += counts.printed;
         total.timeouts += counts.timeouts;
         total.failed += counts.failed;
+        if (counts.via_daemon !== undefined || counts.via_direct !== undefined) {
+            total.viaMeasured = true;
+            total.viaDaemon += counts.via_daemon ?? 0;
+            total.viaDirect += counts.via_direct ?? 0;
+        }
+        // Absent means an older writer never counted one, which sums as zero and
+        // is honest: that machine genuinely skipped none, because it could not.
+        total.skippedTrivial += counts.skipped_trivial ?? 0;
         total.hours += 1;
     }
     return total;

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

@@ -113,6 +113,9 @@ export declare const MemoryInstallReceiptSchema: z.ZodObject<{
     hook_timeouts_24h: z.ZodOptional<z.ZodNumber>;
     hook_printed_24h: z.ZodOptional<z.ZodNumber>;
     hook_failed_24h: z.ZodOptional<z.ZodNumber>;
+    hook_via_daemon_24h: z.ZodOptional<z.ZodNumber>;
+    hook_via_direct_24h: z.ZodOptional<z.ZodNumber>;
+    hook_skipped_trivial_24h: z.ZodOptional<z.ZodNumber>;
     hook_stats_reason: z.ZodOptional<z.ZodString>;
     hook_performance: z.ZodOptional<z.ZodObject<{
         schema_version: z.ZodLiteral<"memory-hook-performance.v1">;

package/dist/memory-install-receipt.js

@@ -132,6 +132,28 @@ export const MemoryInstallReceiptSchema = z
     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(),
+    /**
+     * WHICH ROUTE ANSWERED THE RECALL (BLI-3884).
+     *
+     * `hook_via_daemon_24h` counts prompt hooks the machine's resident local
+     * daemon answered from a warm connection; `hook_via_direct_24h` counts
+     * the ones that spawned, connected and proved the token themselves. Both
+     * optional, and BOTH ABSENT on a machine older than the daemon — which
+     * reads as "not measured", never as "the daemon answered nothing". They
+     * do not have to sum to `hook_runs_24h`: a run that never reached either
+     * route (no payload, no session) names no route at all.
+     */
+    hook_via_daemon_24h: z.number().int().min(0).optional(),
+    hook_via_direct_24h: z.number().int().min(0).optional(),
+    /**
+     * BLI-3881: runs the hook DECLINED to search for — "ok", "continue", a
+     * slash command. It is a subset of the skips inside `hook_runs_24h`, and
+     * it exists because a hook that quietly stops searching looks exactly like
+     * a hook that broke. Optional like the four above: absent means the
+     * machine is on a memory-mcp older than the rule, never that it skipped
+     * none.
+     */
+    hook_skipped_trivial_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(),
     /** Observed ordinary invocations, not legacy floors or a full host trace. */

package/package.json

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