@bli-cockpit/telemetry-core 0.1.35 → 0.1.36

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/telemetry-core",
-  "version": "0.1.35",
+  "version": "0.1.36",
   "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": {