@bli-cockpit/telemetry-core 0.1.35 → 0.1.37

package/dist/collector-heartbeat.d.ts

@@ -108,6 +108,7 @@ export declare const CollectorHeartbeatSchema: z.ZodObject<{
         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_billing_exhausted_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-experience.d.ts

@@ -0,0 +1,37 @@
+export type ExperienceStore = "bli" | "supermemory" | "both";
+export type ExperienceVerdict = "win" | "loss" | "noise";
+export interface MemoryExperience {
+    id: string;
+    store: ExperienceStore;
+    verdict: ExperienceVerdict;
+    reason: string;
+    created_at: string;
+}
+export interface ExperienceReceipt extends MemoryExperience {
+    shipped: boolean;
+}
+export type ExperienceSender = (entry: MemoryExperience) => Promise<{
+    ok: boolean;
+    reason?: string;
+}>;
+export declare function validateExperience(store: string, verdict: string, reason: string): void;
+export declare function experienceLine(entry: MemoryExperience, agent: string, project: string): string;
+export declare function appendExperience(input: {
+    store: ExperienceStore;
+    verdict: ExperienceVerdict;
+    reason: string;
+}, options: {
+    homeDir?: string;
+    agent: string;
+    project: string;
+}): Promise<ExperienceReceipt>;
+export declare function shipExperience(entry: ExperienceReceipt, send: ExperienceSender, homeDir?: string): Promise<{
+    shipped: boolean;
+    reason: string;
+}>;
+/** Bounded work, no throwing into collection. UUIDs make concurrent drains idempotent. */
+export declare function drainExperiences(send: ExperienceSender, homeDir?: string): Promise<{
+    attempted: number;
+    shipped: number;
+    reason: string;
+}>;

package/dist/memory-experience.js

@@ -0,0 +1,85 @@
+/** Append-only experience receipts shared by the CLI and MCP. BLI-3893. */
+import { appendFile, mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import path from "node:path";
+export function validateExperience(store, verdict, reason) {
+    if (!["bli", "supermemory", "both"].includes(store))
+        throw new Error("store must be bli, supermemory or both");
+    if (!["win", "loss", "noise"].includes(verdict))
+        throw new Error("verdict must be win, loss or noise");
+    if (!reason.trim() || [...reason].length > 500 || /[\r\n\x00-\x1f\x7f]/u.test(reason)) {
+        throw new Error("reason must be one nonempty line of at most 500 characters; opinions only, no prompts, memory bodies or secrets");
+    }
+}
+const markers = { bli: "[bli]", supermemory: "◪", both: "[bli]+◪" };
+export function experienceLine(entry, agent, project) {
+    const stamp = new Date(Date.parse(entry.created_at) + 7 * 3600000).toISOString().slice(0, 16).replace("T", " ");
+    const label = (value) => value.replace(/[\r\n·]/gu, " ");
+    return `- ${stamp} ICT · ${label(agent)} · ${label(project)} · ${entry.store} ${markers[entry.store]} · ${entry.verdict}: ${entry.reason}`;
+}
+function paths(home) {
+    return { log: path.join(home, ".codex", "AGENT-EXPERIENCE.md"), queue: path.join(home, ".codex", "agent-experience-outbox") };
+}
+async function saveReceipt(home, entry) {
+    const target = path.join(paths(home).queue, `${entry.id}.json`);
+    const temp = `${target}.${randomUUID()}.tmp`;
+    await writeFile(temp, JSON.stringify(entry), { mode: 0o600 });
+    await rename(temp, target);
+}
+export async function appendExperience(input, options) {
+    validateExperience(input.store, input.verdict, input.reason);
+    const home = options.homeDir ?? homedir();
+    const entry = { ...input, id: randomUUID(), created_at: new Date().toISOString(), shipped: false };
+    await mkdir(paths(home).queue, { recursive: true });
+    // Persist the retry before the human receipt so a crash never loses delivery.
+    await saveReceipt(home, entry);
+    await appendFile(paths(home).log, `${experienceLine(entry, options.agent, options.project)}\n`, { mode: 0o600 });
+    return entry;
+}
+export async function shipExperience(entry, send, homeDir = homedir()) {
+    try {
+        const result = await send(entry);
+        if (!result.ok)
+            return { shipped: false, reason: result.reason ?? "experience_refused" };
+        await saveReceipt(homeDir, { ...entry, shipped: true });
+        return { shipped: true, reason: "accepted" };
+    }
+    catch {
+        return { shipped: false, reason: "experience_delivery_failed" };
+    }
+}
+/** Bounded work, no throwing into collection. UUIDs make concurrent drains idempotent. */
+export async function drainExperiences(send, homeDir = homedir()) {
+    let attempted = 0, shipped = 0;
+    try {
+        let files;
+        try {
+            files = await readdir(paths(homeDir).queue);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return { attempted, shipped, reason: "empty" };
+            throw error;
+        }
+        for (const file of files.sort()) {
+            if (!/^[0-9a-f-]{36}\.json$/u.test(file))
+                continue;
+            const entry = JSON.parse(await readFile(path.join(paths(homeDir).queue, file), "utf8"));
+            if (entry.shipped)
+                continue;
+            validateExperience(entry.store, entry.verdict, entry.reason);
+            attempted++;
+            const result = await shipExperience(entry, send, homeDir);
+            if (!result.shipped)
+                return { attempted, shipped, reason: result.reason };
+            shipped++;
+            if (attempted >= 20)
+                return { attempted, shipped, reason: "batch_cap" };
+        }
+        return { attempted, shipped, reason: "exhausted" };
+    }
+    catch {
+        return { attempted, shipped, reason: "experience_outbox_unreadable" };
+    }
+}

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

@@ -48,6 +48,7 @@ export declare const MemoryHookCountsSchema: z.ZodObject<{
     via_daemon: z.ZodOptional<z.ZodNumber>;
     via_direct: z.ZodOptional<z.ZodNumber>;
     skipped_trivial: z.ZodOptional<z.ZodNumber>;
+    billing_exhausted: 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. */
@@ -68,6 +69,7 @@ export declare const MemoryHookStatsFileSchema: z.ZodObject<{
         via_daemon: z.ZodOptional<z.ZodNumber>;
         via_direct: z.ZodOptional<z.ZodNumber>;
         skipped_trivial: z.ZodOptional<z.ZodNumber>;
+        billing_exhausted: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
 export type MemoryHookStatsFile = z.infer<typeof MemoryHookStatsFileSchema>;
@@ -92,6 +94,13 @@ export interface MemoryHookWindow {
     viaMeasured: boolean;
     /** Trivial prompts the hook declined to search for (BLI-3881). A subset of skips. */
     skippedTrivial: number;
+    /**
+     * BLI-3891: runs the provider refused because the account has no credit. A
+     * subset of `failed`, summed only over buckets that carry the field, so a
+     * window spanning an upgrade reports what was measured rather than crediting
+     * older runs to zero.
+     */
+    billingExhausted: number;
     /** Buckets that were inside the window and had something in them. */
     hours: number;
 }

package/dist/memory-hook-stats.js

@@ -76,6 +76,23 @@ export const MemoryHookCountsSchema = z
      * failed + skipped` still holds.
      */
     skipped_trivial: z.number().int().min(0).optional(),
+    /**
+     * BLI-3891 — the SUBSET of `failed` that was the ACCOUNT, not the code.
+     *
+     * The provider refused the embedding because there is no credit left
+     * (`provider_billing_exhausted`). On 2026-09-06 that state made every
+     * recall on every machine miss its deadline and print nothing, and the
+     * only number anywhere would have said "timeouts", which sends a person
+     * to re-fit a budget rather than to a billing page.
+     *
+     * Counted BESIDE `failed`, never instead of it, so
+     * `runs = printed + empty + timeouts + failed + skipped` still holds, and
+     * OPTIONAL for the same reason `skipped_trivial` is: a file written by an
+     * older memory-mcp has no such key, this schema is strict, and a required
+     * field would make every existing machine's history
+     * `hook_stats_unrecognised_shape` overnight.
+     */
+    billing_exhausted: z.number().int().min(0).optional(),
 })
     .strict();
 /** `YYYY-MM-DDTHH` in UTC — the bucket key, and the reason the window is exact. */
@@ -99,7 +116,16 @@ 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, skipped_trivial: 0 };
+    return {
+        runs: 0,
+        printed: 0,
+        empty: 0,
+        timeouts: 0,
+        failed: 0,
+        skipped: 0,
+        skipped_trivial: 0,
+        billing_exhausted: 0,
+    };
 }
 /**
  * Sum one event's buckets over the last `hours` hours, ending at `now`.
@@ -122,6 +148,7 @@ export function summariseMemoryHookWindow(file, event, options) {
         viaDirect: 0,
         viaMeasured: false,
         skippedTrivial: 0,
+        billingExhausted: 0,
         hours: 0,
     };
     for (const [bucket, events] of Object.entries(file.buckets)) {
@@ -144,6 +171,10 @@ export function summariseMemoryHookWindow(file, event, options) {
         // 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;
+        // Same rule (BLI-3891): absent means an older writer never counted one,
+        // which sums as zero and is honest — that machine genuinely had none it
+        // could name.
+        total.billingExhausted += counts.billing_exhausted ?? 0;
         total.hours += 1;
     }
     return total;

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

@@ -116,6 +116,7 @@ export declare const MemoryInstallReceiptSchema: z.ZodObject<{
     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_billing_exhausted_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

@@ -154,6 +154,15 @@ export const MemoryInstallReceiptSchema = z
      * none.
      */
     hook_skipped_trivial_24h: z.number().int().min(0).optional(),
+    /**
+     * BLI-3891: runs whose recall failed because the PROVIDER ACCOUNT has no
+     * credit. A subset of `hook_failed_24h`, and the reason it is on the
+     * receipt at all: on 2026-09-06 every machine's recall died for four hours
+     * and the only word any surface had for it was "missed the deadline",
+     * which sends a person to re-fit a budget instead of to a billing page.
+     * Optional like the counts above — absent reads as "not reported".
+     */
+    hook_billing_exhausted_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.35",
+  "version": "0.1.37",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",
@@ -13,6 +13,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./memory-experience": {
+      "types": "./dist/memory-experience.d.ts",
+      "import": "./dist/memory-experience.js"
     }
   },
   "publishConfig": {