agent-recall-core 3.4.27 → 3.4.30

package/dist/relevance/precision.js

@@ -0,0 +1,279 @@
+/**
+ * Precision meter — `injection_precision = used / injected`
+ * (v3.5.0 P-C, Ambient Relevance Loop, spec §5 + §6 "Precision guardrail").
+ *
+ * Purpose: this is the north-star metric that proves "intelligence, not
+ * storage." Of the memories AgentRecall surfaces (`injected`), how many
+ * does the agent actually act on (`used`)? A falling number is the
+ * early-warning that the Surfacer threshold is mis-tuned (noise > signal).
+ *
+ * Storage shape — append-only JSONL, one file per kind, per project:
+ *
+ *   ~/.agent-recall/projects/<slug>/_precision/injections.jsonl
+ *   ~/.agent-recall/projects/<slug>/_precision/usages.jsonl
+ *
+ * Design contract:
+ *   • `recordInjection`/`recordUsage` are fire-and-forget — they NEVER
+ *     throw. Losing a measurement line is acceptable; killing a user turn
+ *     is not. Errors are swallowed silently (mirrors stager.ts).
+ *   • `getPrecisionKPI` is tolerant of malformed lines (skipped, not
+ *     fatal), missing files (treated as empty), and missing fields.
+ *   • `precision` is **null** (not NaN) when `injected === 0` — the
+ *     dashboard can render "—" instead of "NaN%".
+ *   • `precision` is clamped to `[0, 1]` via `Math.min(1, used / injected)`
+ *     (matches the existing pattern in storage/corrections.ts:373 — under
+ *     data corruption / duplicate-usage events, the raw ratio can exceed
+ *     1.0, which is nonsense as a "precision" metric).
+ *   • `per_source` groups by the prefix of `candidate_id` before ':'
+ *     (e.g. `palace:room:slug` → bucket `palace`). Unprefixed ids land in
+ *     the `unknown` bucket so they're still visible.
+ *
+ * Worker done-definition self-check:
+ *   (1) error paths: `readJsonl` returns [] on read failure, JSON.parse
+ *       wrapped in try/catch per line; recordInjection/Usage's outer
+ *       try/catch swallows fs errors.
+ *   (2) no global binaries — pure node:fs/path/crypto, no shell-outs.
+ *   (3) ternary ordering — only branch is `injected > 0 ? clamp : null`,
+ *       null is the explicit zero-denominator case.
+ *   (4) time logic — `cutoff` is computed in ms-since-epoch from `Date.now()`
+ *       which is TZ-agnostic; `ts` strings are ISO-8601 (also TZ-agnostic).
+ *       No local-date filename is used here so no TZ bug surface.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { sanitizeProject } from "../storage/paths.js";
+import { ensureDir } from "../storage/fs-utils.js";
+import { getRoot } from "../types.js";
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Resolve the per-project precision directory. Mirrors stager's `_staging/` convention. */
+function precisionDir(project) {
+    const safe = sanitizeProject(project);
+    return path.join(getRoot(), "projects", safe, "_precision");
+}
+function injectionsPath(project) {
+    return path.join(precisionDir(project), "injections.jsonl");
+}
+function usagesPath(project) {
+    return path.join(precisionDir(project), "usages.jsonl");
+}
+/**
+ * Parse a JSONL file. Bad lines (truncated writes, manual edits) are
+ * silently skipped — never throws. Missing file → empty array.
+ *
+ * Generic over the row shape; caller is responsible for narrowing.
+ */
+function readJsonl(filePath) {
+    if (!fs.existsSync(filePath))
+        return [];
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    const lines = raw.split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            out.push(JSON.parse(trimmed));
+        }
+        catch {
+            // Malformed line — skip, never throw.
+        }
+    }
+    return out;
+}
+/**
+ * Append one row to a JSONL file. Wraps the `fs.appendFileSync` call so
+ * the public recorders can swallow fs errors at the boundary.
+ */
+function appendJsonl(filePath, row) {
+    ensureDir(path.dirname(filePath));
+    fs.appendFileSync(filePath, JSON.stringify(row) + "\n", "utf-8");
+}
+/**
+ * Extract the source prefix from a candidate id.
+ * `palace:room:slug` → `palace`. Unprefixed → `unknown`.
+ */
+function sourceOf(candidateId) {
+    if (typeof candidateId !== "string" || candidateId.length === 0)
+        return "unknown";
+    const idx = candidateId.indexOf(":");
+    if (idx <= 0)
+        return "unknown";
+    return candidateId.slice(0, idx);
+}
+/**
+ * Narrow an unknown value to `InjectionEvent` shape (defensive — JSONL may
+ * have been edited by hand). Returns null on miss.
+ */
+function asInjectionEvent(v) {
+    if (!v || typeof v !== "object")
+        return null;
+    const o = v;
+    if (typeof o.ts !== "string")
+        return null;
+    if (!Array.isArray(o.candidate_ids))
+        return null;
+    if (typeof o.turn_hash !== "string")
+        return null;
+    const cids = o.candidate_ids.filter((c) => typeof c === "string");
+    return { ts: o.ts, candidate_ids: cids, turn_hash: o.turn_hash };
+}
+function asUsageEvent(v) {
+    if (!v || typeof v !== "object")
+        return null;
+    const o = v;
+    if (typeof o.ts !== "string")
+        return null;
+    if (typeof o.candidate_id !== "string")
+        return null;
+    if (typeof o.turn_hash !== "string")
+        return null;
+    return {
+        ts: o.ts,
+        candidate_id: o.candidate_id,
+        turn_hash: o.turn_hash,
+        evidence: typeof o.evidence === "string" ? o.evidence : "",
+    };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Append one injection event to `_precision/injections.jsonl`.
+ *
+ * NEVER THROWS. Mirrors `stage()` — the read/write loop continues
+ * regardless of fs errors. Losing a measurement is acceptable; killing a
+ * user turn is not.
+ */
+export function recordInjection(project, ev) {
+    try {
+        if (!ev || typeof ev !== "object")
+            return;
+        const safe = {
+            ts: typeof ev.ts === "string" && ev.ts.length > 0
+                ? ev.ts
+                : new Date().toISOString(),
+            candidate_ids: Array.isArray(ev.candidate_ids)
+                ? ev.candidate_ids.filter((c) => typeof c === "string")
+                : [],
+            turn_hash: typeof ev.turn_hash === "string" ? ev.turn_hash : "",
+        };
+        appendJsonl(injectionsPath(project), safe);
+    }
+    catch {
+        // Swallow — see contract above.
+    }
+}
+/**
+ * Append one usage event to `_precision/usages.jsonl`.
+ *
+ * NEVER THROWS. One row per used candidate; the caller is expected to
+ * dedupe at the detection layer (one usage row per (turn_hash, candidate_id)).
+ */
+export function recordUsage(project, ev) {
+    try {
+        if (!ev || typeof ev !== "object")
+            return;
+        const safe = {
+            ts: typeof ev.ts === "string" && ev.ts.length > 0
+                ? ev.ts
+                : new Date().toISOString(),
+            candidate_id: typeof ev.candidate_id === "string" ? ev.candidate_id : "",
+            turn_hash: typeof ev.turn_hash === "string" ? ev.turn_hash : "",
+            evidence: typeof ev.evidence === "string" ? ev.evidence : "",
+        };
+        if (!safe.candidate_id)
+            return; // can't bucket without an id
+        appendJsonl(usagesPath(project), safe);
+    }
+    catch {
+        // Swallow.
+    }
+}
+/**
+ * Compute the precision KPI over the trailing `windowDays` (default 14).
+ *
+ * Algorithm (spec §6):
+ *   • cutoff = now - windowDays * 86400_000 ms
+ *   • injected = Σ ev.candidate_ids.length over injections with ts ≥ cutoff
+ *   • used     = count of usage rows with ts ≥ cutoff
+ *   • precision = injected > 0 ? Math.min(1, used / injected) : null
+ *   • per_source = { <prefix>: { injected, used } } grouped by id-prefix
+ *
+ * Invariants:
+ *   • `precision` is never NaN; it is either a finite number in [0, 1] or null.
+ *   • Malformed jsonl lines are tolerated (skipped by `readJsonl`).
+ *   • Empty project → injected=0, used=0, precision=null, per_source={}.
+ */
+export function getPrecisionKPI(project, windowDays) {
+    const days = typeof windowDays === "number" && Number.isFinite(windowDays) && windowDays > 0
+        ? windowDays
+        : 14;
+    const cutoffMs = Date.now() - days * 86400_000;
+    const rawInjections = readJsonl(injectionsPath(project));
+    const rawUsages = readJsonl(usagesPath(project));
+    const injections = [];
+    for (const r of rawInjections) {
+        const ev = asInjectionEvent(r);
+        if (!ev)
+            continue;
+        const t = Date.parse(ev.ts);
+        if (!Number.isFinite(t))
+            continue; // unparseable ts → skip
+        if (t < cutoffMs)
+            continue;
+        injections.push(ev);
+    }
+    const usages = [];
+    for (const r of rawUsages) {
+        const ev = asUsageEvent(r);
+        if (!ev)
+            continue;
+        const t = Date.parse(ev.ts);
+        if (!Number.isFinite(t))
+            continue;
+        if (t < cutoffMs)
+            continue;
+        usages.push(ev);
+    }
+    let injected = 0;
+    const perSource = {};
+    for (const ev of injections) {
+        for (const cid of ev.candidate_ids) {
+            injected++;
+            const src = sourceOf(cid);
+            if (!perSource[src])
+                perSource[src] = { injected: 0, used: 0 };
+            perSource[src].injected++;
+        }
+    }
+    const used = usages.length;
+    for (const ev of usages) {
+        const src = sourceOf(ev.candidate_id);
+        if (!perSource[src])
+            perSource[src] = { injected: 0, used: 0 };
+        perSource[src].used++;
+    }
+    // Clamp [0, 1]: data corruption (duplicate usages, late-arriving rows after
+    // injections were rotated out, etc.) can push raw used/injected above 1.0.
+    // Matches storage/corrections.ts:373 — "150% precision" is nonsense.
+    // null (not NaN) is the explicit zero-denominator case so the dashboard
+    // can render "—" rather than "NaN%".
+    const precision = injected > 0 ? Math.min(1, used / injected) : null;
+    return {
+        window_days: days,
+        injected,
+        used,
+        precision,
+        per_source: perSource,
+    };
+}
+//# sourceMappingURL=precision.js.map

package/dist/relevance/precision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"precision.js","sourceRoot":"","sources":["../../src/relevance/precision.ts"],"names":[],"mappings":"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"}

package/dist/relevance/promoter.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Promoter — curates the staging buffer into the palace/journal at session
+ * boundaries (v3.5.0 P-A, spec §4 "Promote", §5).
+ *
+ * Flow:
+ *   1. Read up to N most-recent staged exchanges via `readStaging`.
+ *   2. Apply a pure-function durability heuristic — `isDurableSignal` — to
+ *      drop chitchat, single-word turns, tool-only exchanges.
+ *   3. Dedupe survivors against the project's recent journal titles
+ *      (`tooSimilarToExistingJournal`, threshold 0.7).
+ *   4. Write the survivors via the existing `journalWrite` tool, then clear
+ *      the staging file up to the newest promoted timestamp.
+ *
+ * Design notes:
+ *   • The heuristic is intentionally cheap and pure. It is the FIRST pass —
+ *     the in-room model (called separately by `sessionEndReflect`) is the
+ *     true fine-grain judge. Here we just trim the obvious noise.
+ *   • `opts.dryRun` runs the whole pipeline without writing the journal or
+ *     clearing staging — used by tests and the dashboard preview.
+ *   • Threshold ordering inside `isDurableSignal` is high-confidence first
+ *     (explicit markers) then weaker signals (length + lexical proxy)
+ *     (worker done-def rule 3).
+ */
+import { type StagedExchange } from "./stager.js";
+export interface PromoteResult {
+    promoted: number;
+    skipped: number;
+    /** Counters keyed by reason for downstream dashboards and tests. */
+    reasons: Record<string, number>;
+}
+export interface PromoteOptions {
+    /** When true, runs the heuristic + dedup but writes nothing. */
+    dryRun?: boolean;
+}
+/**
+ * Decide whether a staged exchange carries a durable signal.
+ *
+ * Returns TRUE on any of:
+ *   1. Explicit marker (`decision`, `bug`, `gotcha`, …).
+ *   2. Correction shape (`no … wrong`, `actually`, `correction`, `the right way`).
+ *   3. Contains a wikilink or fenced code block (durable artifact).
+ *   4. Length ≥ 120 chars AND has both an "important word" and an action verb
+ *      (noun-verb proxy — catches substantive sentences).
+ *
+ * Returns FALSE for chitchat ("ok", "thanks"), single-sentence questions,
+ * and tool-only turns (no user/assistant text).
+ */
+export declare function isDurableSignal(e: StagedExchange): boolean;
+/**
+ * Promote durable staged exchanges into the journal.
+ *
+ * Idempotent within a session: once promoted, the corresponding staging
+ * entries are cleared (only the newest-promoted timestamp is used as the
+ * `beforeTs` cursor, so any post-promote stage() calls survive).
+ *
+ * `opts.dryRun = true` runs the full pipeline (incl. dedup) but writes
+ * nothing and clears nothing. Useful for tests and dashboard previews.
+ */
+export declare function promote(project: string, opts?: PromoteOptions): Promise<PromoteResult>;
+//# sourceMappingURL=promoter.d.ts.map

package/dist/relevance/promoter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promoter.d.ts","sourceRoot":"","sources":["../../src/relevance/promoter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,EAA4B,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAoC5E,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,cAAc,GAAG,OAAO,CAmB1D;AAqFD;;;;;;;;;GASG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,cAAmB,GACxB,OAAO,CAAC,aAAa,CAAC,CA+JxB"}