agent-recall-core 3.4.31 → 3.4.36

package/dist/tools-logic/recognition-builder.js

@@ -0,0 +1,289 @@
+/**
+ * recognition.ts — Loop 4 north-star: REAL-TIME RECOGNITION at session start.
+ *
+ * When a session opens, the agent must instantly know FOUR things from LOCAL
+ * data only — zero network, no Supabase, no LLM on the hot path, deterministic:
+ *
+ *   1. WHO            — identity / role (from palace/identity.ts + owner)
+ *   2. CAN_DO         — capabilities (palace/skills + capability-bearing corrections)
+ *   3. PROJECT        — project + progress (status board + journal + palace state)
+ *   4. PERSON         — "what kind of person" = blind-spots profile rendered as
+ *                       tendencies-to-watch, WITH an explicit low-confidence caveat
+ *                       (Loop 3 measured this profile at 0/13 predictive — surface,
+ *                       never over-claim).
+ *
+ * This module ASSEMBLES existing stores — it does NOT rebuild them. Every read
+ * is a pure, synchronous filesystem read of already-derived artifacts. The
+ * payload is deterministically ordered so the same on-disk state yields a
+ * byte-identical JSON across repeated runs (no timestamps, no Date.now in the
+ * output — those would break determinism and aren't part of "recognition").
+ *
+ * Honesty law: WHO is `'unknown'` when no identity card exists. We NEVER infer
+ * or fabricate a persona. CAN_DO and PERSON are honestly empty when nothing is
+ * known.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { palaceDir, journalDirs } from "../storage/paths.js";
+import { readIdentity } from "../palace/identity.js";
+import { listSkills } from "../palace/skills.js";
+import { listRooms, isRoomStale } from "../palace/rooms.js";
+import { readActiveCorrections } from "../storage/corrections.js";
+import { readBlindSpots } from "../storage/blind-spots-store.js";
+import { isJournalFile } from "../helpers/journal-filter.js";
+// ── Constants ──────────────────────────────────────────────────────────────────
+/**
+ * The mandatory low-confidence caveat for the person profile. Loop 3's
+ * leave-one-out eval measured the blind-spots profile at 0/13 predictive on real
+ * corrections, so it is surfaced for orientation only — never as validated truth.
+ */
+export const PERSON_LOW_CONFIDENCE_CAVEAT = "low-confidence: 0/13 predictive (Loop 3) — not validated, orientation only.";
+/**
+ * Trajectory-classification: a `## Next` line containing any of these reads as
+ * actionable work the human can pick up now ("needs-you"). Mirrors project-board's
+ * grammar but inverted for the recognition bucket.
+ */
+const NEEDS_YOU_RE = /\bnext\b|\btodo\b|\bfix\b|\bimplement\b|\bship\b|\badd\b|\bwire\b|\bfinish\b|\bcontinue\b/i;
+/** Days of journal silence past which a project is "stale". */
+const STALE_DAYS = 14;
+/**
+ * Corrections that read as a standing capability / permission / tool constraint.
+ * Used to surface "what they can (not) do" from the corrections store without an
+ * LLM — pure keyword match over the cleaned rule text.
+ */
+const PERMISSION_RE = /\b(push|publish|deploy|delete|version bump|approval|permission|credential|secret|token|never|always|must not|do not|forbid)\b/i;
+const TEMPLATE_STUB_RE = /_\(fill in/;
+// ── Helpers ──────────────────────────────────────────────────────────────────
+/** Trim + collapse whitespace; bounded slice at a word boundary for stable output. */
+function clean(text, maxLen = 200) {
+    const t = text.replace(/\s+/g, " ").trim();
+    if (t.length <= maxLen)
+        return t;
+    const sliced = t.slice(0, maxLen);
+    const lastSpace = sliced.lastIndexOf(" ");
+    return lastSpace > maxLen * 0.6 ? sliced.slice(0, lastSpace) : sliced;
+}
+/**
+ * Parse the identity card into WHO. Returns `unknown:true` + `name:'unknown'`
+ * when there is no real identity content (missing file or template stub only).
+ * NEVER fabricates a name or role.
+ */
+function readWho(project) {
+    const idPath = path.join(palaceDir(project), "identity.md");
+    const hasFile = fs.existsSync(idPath);
+    const raw = hasFile ? readIdentity(project) : "";
+    // No file, or the fallback "no identity card yet" sentinel from readIdentity:
+    // both mean the identity is unknown.
+    if (!hasFile || /No identity card yet/.test(raw)) {
+        return { name: "unknown", role: null, owner: null, unknown: true };
+    }
+    let name = null;
+    let role = null;
+    let owner = null;
+    // Track whether the card carries any SUBSTANTIVE authored body — a line that is
+    // not the heading, not the fill-in stub, not frontmatter/frontmatter-fence, and
+    // not the structural markers we already capture as role/owner. A freshly
+    // bootstrapped card (`# <slug>` + only a `_(fill in...)_` stub) has NONE, so
+    // its slug heading is not a real identity (Loop 5 carry-in fix).
+    let hasAuthoredBody = false;
+    let inFrontmatter = false;
+    for (const lineRaw of raw.split("\n")) {
+        const line = lineRaw.trim();
+        if (!line)
+            continue;
+        // Skip YAML frontmatter (--- … ---): it is bootstrap metadata, never identity.
+        if (line === "---") {
+            inFrontmatter = !inFrontmatter;
+            continue;
+        }
+        if (inFrontmatter)
+            continue;
+        // First ATX heading that is not an empty stub becomes the name.
+        if (name === null && line.startsWith("#")) {
+            const h = line.replace(/^#+\s*/, "").trim();
+            if (h && !TEMPLATE_STUB_RE.test(h))
+                name = h;
+            continue;
+        }
+        // Owner / source marker.
+        if (owner === null && /^-?\s*(source|owner|maintainer)\s*:/i.test(line)) {
+            const v = line.replace(/^-?\s*\w+\s*:\s*/i, "").trim();
+            if (v)
+                owner = clean(v, 160);
+            continue;
+        }
+        // Intention / role marker (skip frontmatter, blockquotes, template stubs).
+        // Handles both `**Intention:** value` (colon inside bold) and
+        // `**Intention**: value` / `Intention: value` forms — the leading marker
+        // and any stray bold/colon are stripped before capture.
+        if (role === null) {
+            if (line.startsWith(">") && TEMPLATE_STUB_RE.test(line))
+                continue;
+            const m = line.match(/^\*{0,2}(intention|role|purpose)\*{0,2}\s*:\*{0,2}\s*(.+)$/i);
+            if (m) {
+                const value = m[2].replace(/^\*+/, "").trim();
+                if (value && !TEMPLATE_STUB_RE.test(value)) {
+                    role = clean(value, 200);
+                    continue;
+                }
+            }
+        }
+        // Any remaining non-empty line that is NOT a fill-in stub counts as authored
+        // body — the human added real content beyond the bootstrap skeleton.
+        if (!TEMPLATE_STUB_RE.test(line))
+            hasAuthoredBody = true;
+    }
+    if (name === null) {
+        return { name: "unknown", role: null, owner: null, unknown: true };
+    }
+    // Honesty law (Loop 5 carry-in): a card whose heading is just the project slug
+    // with NO authored body — no role, no owner, no other real line, only the
+    // bootstrap fill-in stub — is NOT a real identity. `ensurePalaceInitialized`
+    // writes exactly this (`# <slug>` + `_(fill in...)_`), so it must read as
+    // unknown rather than echoing the slug back as a fabricated persona. A human
+    // who fills in an intention/owner/body makes `role`/`owner`/`hasAuthoredBody`
+    // truthy and the card becomes known.
+    const isBootstrapStub = name === project && role === null && owner === null && !hasAuthoredBody;
+    if (isBootstrapStub) {
+        return { name: "unknown", role: null, owner: null, unknown: true };
+    }
+    return { name, role, owner, unknown: false };
+}
+/** Assemble CAN_DO from the procedural skills store + capability-bearing corrections. */
+function readCapabilities(project, maxSkills, maxPermissions) {
+    // Skills — already deterministically slug-sorted by listSkills.
+    const skills = listSkills(project)
+        .slice(0, maxSkills)
+        .map((s) => ({
+        slug: s.meta.slug,
+        name: clean(s.meta.name, 80),
+        topic: clean(s.meta.topic, 40),
+        triggers: [...s.meta.triggers].sort((a, b) => a.localeCompare(b)),
+    }));
+    // Permission/capability signals from active corrections.
+    const permsAll = readActiveCorrections(project)
+        .filter((c) => c.rule && PERMISSION_RE.test(c.rule))
+        .map((c) => ({ id: c.id, rule: clean(c.rule, 160), severity: c.severity }));
+    // Deterministic order: P0 before P1, then by id (stable, date-prefixed).
+    permsAll.sort((a, b) => {
+        if (a.severity !== b.severity)
+            return a.severity === "p0" ? -1 : 1;
+        return a.id.localeCompare(b.id);
+    });
+    const permissions = permsAll.slice(0, maxPermissions);
+    return { skills, permissions };
+}
+/** Find the newest journal file + its `## Next` trajectory. Pure local fs scan. */
+function readProjectProgress(project, maxRooms) {
+    const dirs = journalDirs(project);
+    let lastDate = null;
+    let newestPath = null;
+    for (const dir of dirs) {
+        if (!fs.existsSync(dir))
+            continue;
+        let files;
+        try {
+            files = fs.readdirSync(dir).filter(isJournalFile);
+        }
+        catch {
+            continue;
+        }
+        for (const file of files) {
+            const m = file.match(/^(\d{4}-\d{2}-\d{2})/);
+            if (!m)
+                continue;
+            const d = m[1];
+            if (!lastDate || d > lastDate) {
+                lastDate = d;
+                newestPath = path.join(dir, file);
+            }
+        }
+    }
+    // Trajectory — first non-empty `## Next` line of the newest journal.
+    let trajectory = null;
+    if (newestPath && fs.existsSync(newestPath)) {
+        try {
+            const content = fs.readFileSync(newestPath, "utf-8");
+            const nextMatch = content.match(/^## Next\r?\n([\s\S]*?)(?=^##|\s*$)/m);
+            if (nextMatch) {
+                const lines = nextMatch[1]
+                    .split("\n")
+                    .map((l) => l.trim().replace(/^[-*]\s*/, ""))
+                    .filter(Boolean);
+                if (lines.length > 0)
+                    trajectory = clean(lines[0], 200);
+            }
+        }
+        catch {
+            // non-blocking
+        }
+    }
+    // Status bucket — deterministic from journal freshness + trajectory text.
+    let status;
+    if (!lastDate) {
+        status = "empty";
+    }
+    else {
+        // Day-granularity gap from the journal date (no time-of-day, so the bucket
+        // is stable within a calendar day — recognition is deterministic per-day).
+        const daysAgo = Math.floor((Date.parse(`${new Date().toISOString().slice(0, 10)}T00:00:00Z`) -
+            Date.parse(`${lastDate}T00:00:00Z`)) /
+            86_400_000);
+        if (daysAgo > STALE_DAYS)
+            status = "stale";
+        else if (trajectory && NEEDS_YOU_RE.test(trajectory))
+            status = "needs-you";
+        else
+            status = "backlog";
+    }
+    // Rooms — listRooms is salience-sorted; take top N, then re-sort
+    // deterministically by (salience desc, name asc) so ties are stable.
+    const rooms = listRooms(project)
+        .map((r) => ({ name: r.name, salience: r.salience, stale: isRoomStale(r) }))
+        .sort((a, b) => (b.salience !== a.salience ? b.salience - a.salience : a.name.localeCompare(b.name)))
+        .slice(0, maxRooms);
+    return { slug: project, last_journal_date: lastDate, status, trajectory, rooms };
+}
+/** Assemble the PERSON profile (read-only) with its mandatory low-confidence caveat. */
+function readPerson(project, maxTendencies) {
+    let tendencies = [];
+    const profile = readBlindSpots(project);
+    if (profile && profile.blind_spots.length > 0) {
+        tendencies = profile.blind_spots
+            .map((b) => ({
+            tendency: clean(b.tendency, 160),
+            severity: b.severity,
+            evidence_count: b.evidence_count,
+        }))
+            // Deterministic: P0 before P1, then by evidence desc, then by tendency text.
+            .sort((a, b) => {
+            if (a.severity !== b.severity)
+                return a.severity === "p0" ? -1 : 1;
+            if (b.evidence_count !== a.evidence_count)
+                return b.evidence_count - a.evidence_count;
+            return a.tendency.localeCompare(b.tendency);
+        })
+            .slice(0, maxTendencies);
+    }
+    return { tendencies, caveat: PERSON_LOW_CONFIDENCE_CAVEAT };
+}
+// ── Public API ──────────────────────────────────────────────────────────────
+/**
+ * Assemble the real-time recognition payload for a project from LOCAL stores
+ * only. Synchronous, deterministic, zero-network. Caller must have already
+ * resolved `project` to a concrete slug (this function does not auto-detect, so
+ * it never shells out to git — keeping the hot path pure and fast).
+ */
+export function buildRecognition(project, opts = {}) {
+    const maxSkills = opts.maxSkills ?? 8;
+    const maxPermissions = opts.maxPermissions ?? 5;
+    const maxRooms = opts.maxRooms ?? 3;
+    const maxTendencies = opts.maxTendencies ?? 3;
+    return {
+        who: readWho(project),
+        can_do: readCapabilities(project, maxSkills, maxPermissions),
+        project: readProjectProgress(project, maxRooms),
+        person: readPerson(project, maxTendencies),
+    };
+}
+//# sourceMappingURL=recognition-builder.js.map

package/dist/tools-logic/recognition-builder.js.map

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

package/dist/tools-logic/safety-consolidation.d.ts

@@ -0,0 +1,104 @@
+/**
+ * safety-consolidation.ts — the LOGIN-FREE, LLM-FREE background safety pass.
+ *
+ * The operator's #1 priority: the three maintenance steps that keep memory
+ * healthy (FSRS/salience decay, raw-archive retention, candidate graduation)
+ * must run AUTOMATICALLY and WITHOUT a Claude login or any OPENAI_API_KEY.
+ *
+ * Before this module those steps only fired when the un-cron'd overnight
+ * dreaming agent drained the async queue (`ar consolidate-async`), which fails
+ * often — so decay rarely ran, pruneRawArchive had ZERO callers (the archive
+ * grew unbounded), and crystallization candidates never graduated.
+ *
+ * This pass wires the EXISTING, already-headless primitives together:
+ *   (a) decay     → consolidateJournalToPalace (runs runDecayPass + markKeystones
+ *                   internally; pure regex/fs, no LLM)
+ *   (b) prune     → pruneRawArchive (the dead retention pass), gated by the
+ *                   `.consumed.json` marker which this pass advances by the
+ *                   deterministic "older than the retention window ⇒ distilled"
+ *                   rule (monotonic ⇒ idempotent)
+ *   (c) graduate  → findCrystallizationCandidates + a DETERMINISTIC threshold
+ *                   rule that re-titles the strongest member `CRYSTALLIZED: …`.
+ *                   No LLM-authored summary — that stays the optional dreaming
+ *                   path. Idempotent because findCrystallizationCandidates
+ *                   excludes already-CRYSTALLIZED titles.
+ *                   NOTE (sync side effect): when a candidate actually graduates,
+ *                   this step persists the mutated awareness state and calls
+ *                   renderAwareness, which (via writeAwareness) fires a GATED,
+ *                   non-blocking Supabase sync of the awareness markdown. The
+ *                   sync is a no-op unless Supabase is configured AND sync_enabled
+ *                   (readSupabaseConfig returns null otherwise), so it never
+ *                   requires a network round-trip or a login to complete the pass
+ *                   — it does NOT violate the login-free contract below. dryRun
+ *                   and "nothing graduated" paths perform NO write and NO sync.
+ *
+ * HARD contract:
+ *   - NONE of the three steps may require an LLM / OPENAI_API_KEY / Claude login.
+ *   - EACH step is wrapped in its own try/catch so one throwing does NOT abort
+ *     the others (best-effort, per-step isolation).
+ *   - dryRun computes counts but writes NOTHING.
+ */
+import { DEFAULT_ARCHIVE_RETENTION_DAYS } from "../storage/retention.js";
+export { DEFAULT_ARCHIVE_RETENTION_DAYS };
+/** Deterministic graduation floor: a crystallization candidate graduates when
+ *  its members together carry at least this many confirmations. Layered on top
+ *  of findCrystallizationCandidates' own minCluster/minTotalConfirm gates so the
+ *  rule is purely numeric — NO LLM judgement. Overridable via the runSafety
+ *  opt, the AGENT_RECALL_GRADUATION_MIN_CONFIRMATIONS env var, or config.json
+ *  `graduation_min_confirmations` (resolved in that order by
+ *  resolveGraduationMinConfirmations). */
+export declare const DEFAULT_GRADUATION_MIN_CONFIRMATIONS = 8;
+export interface SafetyDecayResult {
+    ran: boolean;
+    /** Skills + rooms scanned by the decay pass (0 when it could not run). */
+    scanned: number;
+    /** Objects flagged archived this pass (or that WOULD be, when dryRun). */
+    archived: number;
+    error?: string;
+}
+export interface SafetyPruneResult {
+    ran: boolean;
+    scanned: number;
+    /** Aged + distilled segments gzipped (0 in dryRun). */
+    gzipped: number;
+    /** Segments removed outright (only when mode === "remove"). */
+    removed: number;
+    /** Candidates matching BOTH gates (old AND consumed). */
+    eligible: number;
+    /** `lastConsumedAt` the marker was advanced TO (or would be, in dryRun). */
+    consumedThrough: string | null;
+    error?: string;
+}
+export interface SafetyGraduateResult {
+    ran: boolean;
+    /** Crystallization candidates surfaced this pass. */
+    candidates: number;
+    /** Candidates that crossed the deterministic threshold and graduated (or
+     *  would, in dryRun). */
+    graduated: number;
+    /** Titles graduated this pass (for traceability). */
+    graduatedTitles: string[];
+    error?: string;
+}
+export interface SafetyConsolidationResult {
+    project: string;
+    dryRun: boolean;
+    decay: SafetyDecayResult;
+    pruned: SafetyPruneResult;
+    graduated: SafetyGraduateResult;
+}
+export interface SafetyConsolidationOptions {
+    /** When true, compute counts but write nothing. Default false. */
+    dryRun?: boolean;
+    /** Override the raw-archive retention window (days). */
+    olderThanDays?: number;
+    /** Override the deterministic graduation confirmation floor. */
+    minConfirmations?: number;
+}
+/**
+ * Run the three best-effort, LOGIN-FREE, LLM-FREE safety-consolidation steps
+ * for a project. Each step is isolated in its own try/catch: one throwing never
+ * aborts the others. dryRun computes counts but writes nothing.
+ */
+export declare function runSafetyConsolidation(project: string, opts?: SafetyConsolidationOptions): Promise<SafetyConsolidationResult>;
+//# sourceMappingURL=safety-consolidation.d.ts.map

package/dist/tools-logic/safety-consolidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety-consolidation.d.ts","sourceRoot":"","sources":["../../src/tools-logic/safety-consolidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAoBH,OAAO,EACL,8BAA8B,EAE/B,MAAM,yBAAyB,CAAC;AAQjC,OAAO,EAAE,8BAA8B,EAAE,CAAC;AAE1C;;;;;;0CAM0C;AAC1C,eAAO,MAAM,oCAAoC,IAAI,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,OAAO,CAAC;IACb,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,OAAO,CAAC;IACb,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB;6BACyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,iBAAiB,CAAC;IACzB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,SAAS,EAAE,oBAAoB,CAAC;CACjC;AAED,MAAM,WAAW,0BAA0B;IACzC,kEAAkE;IAClE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAwID;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,EACf,IAAI,GAAE,0BAA+B,GACpC,OAAO,CAAC,yBAAyB,CAAC,CAmFpC"}