agent-nuvira 3.3.8 → 3.3.9

package/dist/learning/session-recall.js

@@ -0,0 +1,305 @@
+/**
+ * Session recall (Phase 4 follow-on) — SEMANTIC recall across past asks.
+ *
+ * WHY THIS EXISTS, AND WHY IT IS OPT-IN.
+ * The deterministic session digest (`session-digest.ts`) shows the LAST few asks
+ * in a project. That is good for continuity, but it is recency-based: an ask from
+ * three weeks ago about the SAME subject is invisible if ten unrelated asks
+ * happened since. This module adds *semantic* recall — embed each finished ask,
+ * and at the start of a new turn retrieve the past asks that mean the same thing,
+ * above an explicit cosine THRESHOLD, so relevance is by meaning rather than by
+ * a literal token overlap (`goalsLookSame`) or by recency.
+ *
+ * It is deliberately OFF unless asked for (`NUVIRA_SESSION_RECALL=1`). Semantics
+ * introduce an embedding dependency whose tiers can be slow to fail over; a
+ * feature that makes an ordinary turn wait on a model download would be a worse
+ * bug than the recall it buys. So, exactly like `--resume`, an ordinary run pays
+ * nothing: no read, no embed, no query.
+ *
+ * WHY IT CANNOT RE-OPEN FALSE SUCCESS. A recalled ask is HISTORY, presented as
+ * however it ENDED (`acted` / `incomplete` / `failed` / `cancelled`) — never as a
+ * completion the current work inherits. The block says so outright, and nothing
+ * here is read to decide whether a step is done: completion still derives from
+ * artifacts on disk. A recalled "the build works" is a sentence the past model
+ * wrote, quoted, not a fact the framework adopts.
+ *
+ * Bounded + best-effort throughout: a fixed entry cap, a fixed top-k, a fixed
+ * block size, and every read/write/embed wrapped so a corrupt index or a missing
+ * embedding tier degrades to "no recall", never a broken turn.
+ */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { envBuff, resolveNuviraHome } from '../config/paths.js';
+import { embed } from '../memory/embedder.js';
+import { cosineSimilarity } from '../memory/vector-store.js';
+/** The environment key that turns semantic recall on (`1`/`true`/`yes`). */
+export const SESSION_RECALL_ENV = 'NUVIRA_SESSION_RECALL';
+/** Cosine floor a past ask must clear to be recalled (0-1). */
+export const DEFAULT_RECALL_THRESHOLD = 0.5;
+/** How many past asks to surface at most. */
+export const DEFAULT_RECALL_TOP_K = 3;
+/** Hard cap on the index (oldest dropped) — recall must never grow unbounded. */
+export const MAX_INDEX_ENTRIES = 500;
+/** Hard cap on the rendered block — it rides in prompts. */
+export const MAX_RECALL_BLOCK_CHARS = 1_200;
+const CURRENT_VERSION = 1;
+// ─── Enablement ─────────────────────────────────────────────────────────────
+/** Words a reader treats as OFF (same vocabulary the process-env page uses). */
+const OFF_WORDS = new Set(['0', 'false', 'off', 'no']);
+/**
+ * Is semantic recall on? DEFAULT ON — like checkpointing, an operator can turn
+ * it off, but a fresh install gets the feature rather than a switch that does
+ * nothing until someone reads the docs. `0`/`false`/`off`/`no` turn it off;
+ * unset (or any other value) leaves it ON.
+ */
+export function sessionRecallEnabled(env = process.env) {
+    const raw = env[SESSION_RECALL_ENV];
+    if (typeof raw !== 'string')
+        return true;
+    return !OFF_WORDS.has(raw.trim().toLowerCase());
+}
+// Keep the repo's env indirection working too (`NUVIRA_` then `BUFF_`).
+function recallEnabledViaHelper() {
+    const raw = envBuff('SESSION_RECALL');
+    if (typeof raw !== 'string')
+        return undefined;
+    return !OFF_WORDS.has(raw.trim().toLowerCase());
+}
+/**
+ * Resolve whether semantic recall is on, with the repo's precedence:
+ * an explicit FLAG wins, then the environment, then config, then the default
+ * (ON). This is the single place the decision is made, so the CLI, the loop and
+ * the dashboard cannot disagree.
+ */
+export function resolveSessionRecall(input = {}) {
+    if (input.flag !== undefined)
+        return input.flag;
+    const viaEnv = recallEnabledViaHelper();
+    if (viaEnv !== undefined)
+        return viaEnv;
+    const cfg = input.configManager?.getAll().memory?.sessionRecall;
+    return cfg !== false;
+}
+function enabled() {
+    return resolveSessionRecall();
+}
+// ─── Storage ────────────────────────────────────────────────────────────────
+function memoryDir() {
+    return envBuff('MEMORY_DIR') || join(resolveNuviraHome(), 'memory');
+}
+function indexPath() {
+    return join(memoryDir(), 'session-recall-index.json');
+}
+function normalizeProjectPath(projectPath) {
+    try {
+        return resolve(projectPath);
+    }
+    catch {
+        return projectPath;
+    }
+}
+function readIndex() {
+    try {
+        if (!existsSync(indexPath()))
+            return { version: CURRENT_VERSION, entries: [] };
+        const data = JSON.parse(readFileSync(indexPath(), 'utf-8'));
+        if (!data || typeof data !== 'object' || !Array.isArray(data.entries)) {
+            return { version: CURRENT_VERSION, entries: [] };
+        }
+        const entries = data.entries.filter(isRecallEntry);
+        return { version: CURRENT_VERSION, entries };
+    }
+    catch {
+        return { version: CURRENT_VERSION, entries: [] };
+    }
+}
+function isRecallEntry(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const e = value;
+    return (typeof e.id === 'string' &&
+        typeof e.projectPath === 'string' &&
+        typeof e.goal === 'string' &&
+        Array.isArray(e.vector) &&
+        e.vector.every((n) => typeof n === 'number' && Number.isFinite(n)));
+}
+function writeIndex(index) {
+    try {
+        mkdirSync(memoryDir(), { recursive: true });
+        writeFileSync(indexPath(), JSON.stringify(index, null, 2), 'utf-8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isZeroVector(vector) {
+    return vector.length === 0 || vector.every((n) => n === 0);
+}
+// ─── Indexing ───────────────────────────────────────────────────────────────
+/** A stable id for one ask in a project, so re-indexing a turn overwrites it. */
+function entryId(projectPath, goal, savedAt) {
+    return `${normalizeProjectPath(projectPath)}#${savedAt}#${goal.slice(0, 48)}`;
+}
+/**
+ * Index one finished ask for later semantic recall. Returns whether an entry was
+ * written. Best-effort and NO-OP when recall is off or embeddings are
+ * unavailable (a zero vector is never stored — it would only ever be a
+ * meaningless match).
+ */
+export async function indexSessionTurn(input, opts = {}) {
+    const on = opts.enabled ?? enabled();
+    if ((!opts.force && !on) || !input.goal.trim())
+        return false;
+    const embedFn = opts.embedFn ?? ((t) => embed(t));
+    let vector;
+    try {
+        vector = await embedFn(input.goal);
+    }
+    catch {
+        return false;
+    }
+    if (isZeroVector(vector))
+        return false;
+    const savedAt = input.savedAt ?? Date.now();
+    const entry = {
+        id: entryId(input.projectPath, input.goal, savedAt),
+        projectPath: normalizeProjectPath(input.projectPath),
+        goal: input.goal.slice(0, 240),
+        outcome: (input.outcome ?? 'unknown').slice(0, 24),
+        savedAt,
+        vector,
+    };
+    const index = readIndex();
+    const entries = [...index.entries.filter((e) => e.id !== entry.id), entry];
+    // Oldest-first eviction past the cap.
+    if (entries.length > MAX_INDEX_ENTRIES)
+        entries.splice(0, entries.length - MAX_INDEX_ENTRIES);
+    return writeIndex({ version: CURRENT_VERSION, entries });
+}
+// ─── Recall ─────────────────────────────────────────────────────────────────
+/**
+ * The past asks semantically closest to `query`, above the threshold.
+ *
+ * `scope: 'project'` (default) limits recall to the current project directory —
+ * the same scoping the rest of the continuity stack uses, so a new task is not
+ * handed another project's history. `scope: 'all'` searches every project and
+ * names each hit's project in the block.
+ */
+export async function recallPastSessions(query, opts = {}) {
+    if (!query.trim())
+        return [];
+    const on = opts.enabled ?? enabled();
+    if (!opts.force && !on)
+        return [];
+    const index = readIndex();
+    if (index.entries.length === 0)
+        return [];
+    const scope = opts.scope ?? 'project';
+    const wanted = opts.projectPath ? normalizeProjectPath(opts.projectPath) : '';
+    const candidates = scope === 'all' || !wanted ? index.entries : index.entries.filter((e) => e.projectPath === wanted);
+    if (candidates.length === 0)
+        return [];
+    const embedFn = opts.embedFn ?? ((t) => embed(t));
+    let queryVector;
+    try {
+        queryVector = await embedFn(query);
+    }
+    catch {
+        return [];
+    }
+    if (isZeroVector(queryVector))
+        return [];
+    const threshold = opts.threshold ?? DEFAULT_RECALL_THRESHOLD;
+    const topK = Math.max(1, opts.topK ?? DEFAULT_RECALL_TOP_K);
+    const hits = [];
+    for (const entry of candidates) {
+        let similarity;
+        try {
+            similarity = cosineSimilarity(queryVector, entry.vector);
+        }
+        catch {
+            continue;
+        }
+        if (!Number.isFinite(similarity) || similarity < threshold)
+            continue;
+        hits.push({ entry, similarity });
+    }
+    hits.sort((a, b) => b.similarity - a.similarity);
+    return hits.slice(0, topK);
+}
+/**
+ * Render recall hits as a bounded, model-readable block ('' when there are none).
+ *
+ * The header is load-bearing: it states that these are PAST asks — history for
+ * context only, NOT a status — so a recalled line cannot be read as proof the
+ * current work is done. Each hit carries how it ENDED and its project when the
+ * recall crossed projects.
+ */
+export function formatSessionRecall(hits, opts = {}) {
+    if (hits.length === 0)
+        return '';
+    const now = opts.now ?? Date.now();
+    const projectScoped = opts.projectPath !== undefined;
+    const lines = [
+        '[Semantically similar PAST asks — history for context only. This is NOT a status of the current work; verify artifacts on disk before assuming anything is done.]',
+    ];
+    for (const { entry, similarity } of hits) {
+        const age = relativeAge(entry.savedAt, now);
+        const where = projectScoped ? '' : ` [${shortenPath(entry.projectPath)}]`;
+        lines.push(`• (${Math.round(similarity * 100)}% match)${where} ${age} — ${entry.outcome}: "${entry.goal}"`);
+    }
+    let block = lines.join('\n');
+    if (block.length > MAX_RECALL_BLOCK_CHARS) {
+        block = `${block.slice(0, MAX_RECALL_BLOCK_CHARS)}\n[recall truncated to fit the context budget]`;
+    }
+    return block;
+}
+function relativeAge(ts, now) {
+    const mins = Math.max(0, Math.round((now - ts) / 60_000));
+    if (mins < 1)
+        return 'just now';
+    if (mins < 60)
+        return `${mins}m ago`;
+    const hours = Math.round(mins / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    return `${Math.round(hours / 24)}d ago`;
+}
+function shortenPath(p) {
+    const parts = p.split(/[\\/]/).filter(Boolean);
+    return parts.slice(-2).join('/') || p;
+}
+/**
+ * List every indexed past ask, newest first. Best-effort. The vectors are part of
+ * each entry; a caller that only needs a summary maps them away.
+ */
+export function listRecallEntries() {
+    return readIndex().entries.slice().sort((a, b) => b.savedAt - a.savedAt);
+}
+/** Remove one indexed past ask by id. Returns whether it was present. */
+export function removeRecallEntry(id) {
+    try {
+        const index = readIndex();
+        const next = index.entries.filter((e) => e.id !== id);
+        if (next.length === index.entries.length)
+            return false;
+        return writeIndex({ version: CURRENT_VERSION, entries: next });
+    }
+    catch {
+        return false;
+    }
+}
+/** Remove the recall index (used by `nuvira retrieval clear`-style resets / tests). */
+export function clearSessionRecallIndex() {
+    try {
+        if (!existsSync(indexPath()))
+            return false;
+        rmSync(indexPath(), { force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=session-recall.js.map

package/dist/learning/session-recall.js.map

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

package/dist/learning/session-store.d.ts

@@ -0,0 +1,172 @@
+/**
+ * WS5 (#27) — Phase 4b/4c: the PERSISTENT SESSION STORE (the L2 layer).
+ *
+ * WHY THIS EXISTS. The resume ledger (`step-checkpoint.ts`) makes a re-run cheap
+ * by replaying unchanged MODEL CALLS, and the task checkpoints
+ * (`agents/checkpoint-store.ts`) skip COMPLETED pipeline tasks. Both are keyed by
+ * what a run FINISHED. Neither survives the one failure a long-running agent
+ * actually hits: the PROCESS dies mid-turn (a closed laptop, a killed terminal,
+ * a quota-killed provider). At that instant the conversation lived only in
+ * memory, and the next process starts cold — it re-derives the whole context and
+ * re-pays for the steps that were already done.
+ *
+ * WHAT IT STORES, AND WHAT IT REFUSES TO STORE. At every step boundary the loop
+ * hands over its live `ToolMessage[]` thread plus a small accumulator (steps,
+ * successful tools, mutated paths). The store keeps a bounded, REDACTED copy on
+ * disk. It is a transcript — nothing more. It does NOT record a completion
+ * state, an outcome, or any verdict: completion is still derived from the
+ * filesystem and the run's own facts (see the Part 1/Part 2 lesson). Re-importing
+ * the transcript gives the next process the CONVERSATION, not a claim that the
+ * work is done.
+ *
+ * WHY THE HEAD IS REPLACED ON REHYDRATION. The first messages of a loop thread
+ * are the system prompt (tool contract) and the `[Project context]` block. Those
+ * are reconstructible, and they DRIFT between runs (the file tree, the git
+ * digest). Persisting them would both age and bloat the record. So the store
+ * counts the leading head messages at save time (`headLength`) and the caller
+ * re-injects a FRESH head over the stored conversation tail on resume: the
+ * contract is current, the history is intact.
+ *
+ * WHY A COMPLETED SESSION IS NOT RESUMABLE. If a turn ran to a clean end, its
+ * transcript is history — re-feeding a finished conversation would have the model
+ * continue a conversation that is over, and risk narrating a stale "done". So
+ * `finish()` marks a snapshot closed, and the resumable lookup skips closed
+ * snapshots. The transcript is still kept (bounded) for a human to read; it is
+ * simply not replayed.
+ *
+ * WHY NOTHING HAPPENS WITHOUT A REQUEST. Opening the store is the ONLY thing that
+ * reads or writes the session directory. An ordinary run never touches it, pays
+ * no filesystem cost, and cannot inherit another run's conversation.
+ *
+ * Everything here is best-effort: a corrupt record is a MISS, never a crash, and
+ * a failed write reports (or stays silent) without breaking the turn that asked.
+ */
+import type { ToolMessage } from '../inference/interface.js';
+/** The environment key a deployment uses to turn session persistence OFF. */
+export declare const SESSION_ENABLE_ENV = "NUVIRA_SESSION_STORE";
+/**
+ * Is session persistence on? DEFAULT ON — like checkpointing, a fresh install
+ * gets continuity and an operator can turn it off. `0`/`false`/`off`/`no` turn
+ * it off; unset (or any other value) leaves it ON.
+ */
+export declare function sessionStoreEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** The config/env shape a resolver reads (structural, so no import cycle). */
+export interface StoreConfigSource {
+    getAll(): {
+        memory?: {
+            sessionStore?: boolean;
+        };
+    };
+}
+/**
+ * Resolve whether session persistence is on, with the repo's precedence: an
+ * explicit FLAG wins, then the environment, then config, then the default (ON).
+ * One place decides, so the CLI, the loop and the dashboard cannot disagree.
+ */
+export declare function resolveSessionStore(input?: {
+    flag?: boolean;
+    configManager?: StoreConfigSource | null;
+}): boolean;
+/** Bound on stored conversation messages — the most recent N are kept. */
+export declare const MAX_SESSION_MESSAGES = 48;
+/** Bound on a single stored message's content (the rest is clipped). */
+export declare const MAX_MESSAGE_CHARS = 8000;
+/** The accumulators the loop reports at a step boundary. */
+export interface SessionAccumulators {
+    /** Steps completed so far this turn. */
+    steps: number;
+    /** Tool names that ran successfully (in order). */
+    successfulTools: string[];
+    /** Paths mutated successfully (in order). */
+    mutatedPaths: string[];
+    /** Tool names that errored, when the caller tracks them. */
+    erroredTools?: string[];
+}
+/** A persisted session snapshot: the conversation tail plus the accumulators. */
+export interface SessionSnapshot {
+    id: string;
+    goal: string;
+    cwd: string;
+    savedAt: number;
+    /** Monotonic save counter, so a reader can tell updates apart. */
+    revision: number;
+    /** False once the turn ran to a clean end (and is therefore not resumable). */
+    open: boolean;
+    /** Leading thread messages that are reconstructible and must be replaced. */
+    headLength: number;
+    messages: ToolMessage[];
+    accumulators: SessionAccumulators;
+}
+/** Read a snapshot, best-effort. A corrupt record is a miss, never a crash. */
+export declare function loadSessionSnapshot(id: string): SessionSnapshot | null;
+/**
+ * The writer a loop threads through its step boundaries.
+ *
+ * `save` is called once per completed step; `finish` once, when the turn ends
+ * cleanly. Both are best-effort — a read-only home directory degrades to "no
+ * continuity", never to a failed turn.
+ */
+export interface SessionStore {
+    readonly id: string;
+    /** Snapshot the current thread + accumulators at a step boundary. */
+    save(thread: readonly ToolMessage[], accumulators: SessionAccumulators): void;
+    /** Mark the turn finished so the transcript is history, not a resume point. */
+    finish(thread?: readonly ToolMessage[], accumulators?: SessionAccumulators): void;
+    /** Whether the most recent write reached the disk. */
+    lastSaved(): boolean;
+}
+export declare function openSession(input: {
+    goal: string;
+    cwd: string;
+    id?: string;
+}): SessionStore;
+/**
+ * The session id for this ask, in this directory, possibly WORDED DIFFERENTLY.
+ *
+ * Same contract as `resolveRecordIdFor` in the resume ledger: the exact id if a
+ * snapshot exists, else the newest OPEN snapshot in this directory whose goal
+ * `goalsLookSame`. A snapshot for a different ask is never returned — the caller
+ * would otherwise rehydrate a conversation it never had.
+ */
+export declare function resolveSessionIdFor(goal: string, cwd: string, options?: {
+    onlyOpen?: boolean;
+}): string;
+/**
+ * The resumable snapshot for this ask, or null when there is nothing to resume.
+ *
+ * Only OPEN snapshots qualify (see the module docstring): a transcript from a
+ * turn that ended cleanly is history, and re-feeding it would have the model
+ * continue a finished conversation.
+ */
+export declare function findResumableSessionFor(goal: string, cwd: string): SessionSnapshot | null;
+/**
+ * Rebuild a loop thread from a stored snapshot and a FRESH head.
+ *
+ * The fresh head (system prompt, current project context) replaces the stored
+ * head; the stored conversation tail — the goal and everything done after it —
+ * is preserved. The result is what the next process loops over: it already knows
+ * what the dead process did, so those steps are neither re-run nor re-paid.
+ */
+export declare function rehydrateThread(head: readonly ToolMessage[], snapshot: SessionSnapshot): ToolMessage[];
+/** A bounded, human-facing line describing a resumable snapshot. */
+export declare function formatSessionResume(snapshot: SessionSnapshot): string;
+/**
+ * List every stored session snapshot, newest first. Best-effort: a corrupt or
+ * unreadable record is skipped, never thrown.
+ */
+export declare function listSessionSnapshots(): SessionSnapshot[];
+/** Remove one snapshot. Returns whether a file was removed. */
+export declare function clearSession(id: string): boolean;
+/**
+ * Bound the session directory: drop snapshots older than `maxAgeMs` and keep at
+ * most `maxCount` (newest first). Returns how many files were removed.
+ *
+ * Best-effort and never throws — a prune that fails leaves the records (a disk
+ * full of old transcripts is a smaller problem than a broken turn).
+ */
+export declare function pruneSessions(options?: {
+    maxAgeMs?: number;
+    maxCount?: number;
+    now?: number;
+}): number;
+//# sourceMappingURL=session-store.d.ts.map

package/dist/learning/session-store.d.ts.map

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