aiden-runtime 4.5.0 → 4.6.1

package/dist/core/v4/selfimprovement/recoveryStore.js

@@ -0,0 +1,307 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/selfimprovement/recoveryStore.ts — v4.6 Phase 3b.
+ *
+ * Durable cross-session failure ledger + recovery report writer.
+ * Backed by the v7 schema's `failure_signatures` + `recovery_reports`
+ * tables. The store is the single write path for both halves of the
+ * self-improvement loop:
+ *
+ *   1. `recordFailureOccurrence(...)` — called on every classified
+ *      failure (TCE write-through at the aidenAgent classify site).
+ *      Upserts the signature row, increments `occurrences`, updates
+ *      `last_seen_at`.
+ *
+ *   2. `recordRecovery(...)` — called when a previously-failed
+ *      signature is observed succeeding (or when the agent's TCE
+ *      surfaces a structured recovery report at turn end).
+ *      Inserts a `recovery_reports` row + bumps the signature's
+ *      `recovered_count` + sets `last_recovery_report_id`.
+ *
+ * Reads:
+ *
+ *   * `listTopFailures(limit)` — operator dashboard query.
+ *   * `getBySignature(signature)` — `/recovery show` detail surface.
+ *   * `listForSession(sessionId)` — used by future plugin hooks that
+ *     want per-session summaries (currently unused; the operator
+ *     command path goes via `listTopFailures` + `getBySignature`).
+ *   * `listReportsForSignature(signatureId, limit)` — the recovery
+ *     history for one signature.
+ *
+ * Singleton pattern mirrors `spawnPause` (Phase 3a): `initRecoveryStore({db})`
+ * at boot; `getRecoveryStore()` thereafter. Production wiring opens the
+ * daemon DB once at REPL/daemon/MCP boot and re-uses the singleton
+ * across REPL turns and daemon-fired turns. Tests reset via
+ * `_resetRecoveryStoreForTests()`.
+ *
+ * Failure mode: NEVER throws. A persistence failure (locked DB,
+ * schema drift, etc.) returns 0 / null and logs a warning. The
+ * TCE write-through path treats the store as best-effort — losing
+ * a signature increment does not break a turn.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecoveryStore = void 0;
+exports.initRecoveryStore = initRecoveryStore;
+exports.getRecoveryStore = getRecoveryStore;
+exports._resetRecoveryStoreForTests = _resetRecoveryStoreForTests;
+// ── Implementation ───────────────────────────────────────────────────────
+/**
+ * SQLite-backed store. Constructed with a `better-sqlite3` Database
+ * handle that already has the v7 migration applied. The store does
+ * NOT run migrations itself — that's the caller's job (typically
+ * `openDaemonDb` + `runMigrations`).
+ */
+class RecoveryStore {
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Upsert a failure signature + bump occurrences. Returns the
+     * signature row id, or 0 on persistence failure (logged). The
+     * caller (TCE write-through path) treats the return as best-effort.
+     */
+    recordFailureOccurrence(opts) {
+        const now = opts.now ?? Date.now;
+        const ts = now();
+        try {
+            // SQLite-native UPSERT — single round trip per failure. The
+            // `excluded.x` syntax references the row we tried to insert.
+            const r = this.db.prepare(`
+        INSERT INTO failure_signatures
+          (signature, tool_name, failure_category, args_hash,
+           first_seen_at, last_seen_at, occurrences, recovered_count)
+        VALUES (?, ?, ?, ?, ?, ?, 1, 0)
+        ON CONFLICT(signature) DO UPDATE SET
+          last_seen_at = excluded.last_seen_at,
+          occurrences  = failure_signatures.occurrences + 1
+        RETURNING id
+      `).get(opts.signature, opts.toolName, opts.category, opts.argsHash ?? null, ts, ts);
+            return r?.id ?? 0;
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn('[recoveryStore] recordFailureOccurrence failed:', err instanceof Error ? err.message : String(err));
+            return 0;
+        }
+    }
+    /**
+     * Record a successful recovery. Inserts a `recovery_reports`
+     * row + atomically bumps the signature's `recovered_count` and
+     * `last_recovery_report_id`. Returns the new report id, or 0 on
+     * failure.
+     */
+    recordRecovery(opts) {
+        const now = opts.now ?? Date.now;
+        const ts = now();
+        try {
+            // Two-statement transaction — insert then update — keeps the
+            // signature's `last_recovery_report_id` consistent with the
+            // newly-inserted report row.
+            const txn = this.db.transaction(() => {
+                const ins = this.db.prepare(`
+          INSERT INTO recovery_reports
+            (signature_id, run_id, session_id, failed_attempts,
+             successful_strategy, changed_parameters, verification,
+             created_at, notes)
+          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `).run(opts.signatureId, opts.runId ?? null, opts.sessionId ?? null, opts.failedAttempts, opts.successfulStrategy, opts.changedParameters ? JSON.stringify(opts.changedParameters) : null, opts.verification ?? null, ts, opts.notes ?? null);
+                const reportId = Number(ins.lastInsertRowid);
+                this.db.prepare(`
+          UPDATE failure_signatures
+             SET recovered_count = recovered_count + 1,
+                 last_recovery_report_id = ?
+           WHERE id = ?
+        `).run(reportId, opts.signatureId);
+                return reportId;
+            });
+            return txn();
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn('[recoveryStore] recordRecovery failed:', err instanceof Error ? err.message : String(err));
+            return 0;
+        }
+    }
+    /**
+     * Top N recurring failure signatures, sorted by occurrence count
+     * descending. Backs `/recovery list`. Joins the most recent
+     * recovery_report so the operator sees what worked last.
+     */
+    listTopFailures(limit = 10) {
+        const cap = Math.max(1, Math.min(limit, 500));
+        try {
+            const rows = this.db.prepare(`
+        SELECT
+          s.signature                   AS signature,
+          s.tool_name                   AS toolName,
+          s.failure_category            AS failureCategory,
+          s.occurrences                 AS occurrences,
+          s.recovered_count             AS recoveredCount,
+          s.last_seen_at                AS lastSeenAt,
+          r.successful_strategy         AS lastRecoveryStrategy
+        FROM failure_signatures s
+        LEFT JOIN recovery_reports r
+          ON r.id = s.last_recovery_report_id
+        ORDER BY s.occurrences DESC, s.last_seen_at DESC
+        LIMIT ?
+      `).all(cap);
+            return rows;
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn('[recoveryStore] listTopFailures failed:', err instanceof Error ? err.message : String(err));
+            return [];
+        }
+    }
+    /**
+     * Lookup one signature by its canonical string. Backs `/recovery
+     * show`. Returns null when no signature row exists yet.
+     */
+    getBySignature(signature) {
+        try {
+            const row = this.db.prepare(`
+        SELECT
+          id                      AS id,
+          signature               AS signature,
+          tool_name               AS toolName,
+          failure_category        AS failureCategory,
+          args_hash               AS argsHash,
+          first_seen_at           AS firstSeenAt,
+          last_seen_at            AS lastSeenAt,
+          occurrences             AS occurrences,
+          recovered_count         AS recoveredCount,
+          last_recovery_report_id AS lastRecoveryReportId
+        FROM failure_signatures WHERE signature = ?
+      `).get(signature);
+            return row ?? null;
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn('[recoveryStore] getBySignature failed:', err instanceof Error ? err.message : String(err));
+            return null;
+        }
+    }
+    /**
+     * Recovery reports linked to one signature, most recent first.
+     * Used by `/recovery show` to render the recovery history below
+     * the signature header.
+     */
+    listReportsForSignature(signatureId, limit = 50) {
+        const cap = Math.max(1, Math.min(limit, 500));
+        try {
+            const rows = this.db.prepare(`
+        SELECT
+          id                    AS id,
+          signature_id          AS signatureId,
+          run_id                AS runId,
+          session_id            AS sessionId,
+          failed_attempts       AS failedAttempts,
+          successful_strategy   AS successfulStrategy,
+          changed_parameters    AS changedParameters,
+          verification          AS verification,
+          created_at            AS createdAt,
+          notes                 AS notes
+        FROM recovery_reports
+         WHERE signature_id = ?
+         ORDER BY created_at DESC
+         LIMIT ?
+      `).all(signatureId, cap);
+            return rows;
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn('[recoveryStore] listReportsForSignature failed:', err instanceof Error ? err.message : String(err));
+            return [];
+        }
+    }
+    /**
+     * Recovery reports written during one session, used by future
+     * plugin hooks + the `/recovery` command's per-session view.
+     * Wraps a single SELECT — no aggregation. Empty array when no
+     * recoveries happened.
+     */
+    listForSession(sessionId) {
+        try {
+            const rows = this.db.prepare(`
+        SELECT
+          id                    AS id,
+          signature_id          AS signatureId,
+          run_id                AS runId,
+          session_id            AS sessionId,
+          failed_attempts       AS failedAttempts,
+          successful_strategy   AS successfulStrategy,
+          changed_parameters    AS changedParameters,
+          verification          AS verification,
+          created_at            AS createdAt,
+          notes                 AS notes
+        FROM recovery_reports
+         WHERE session_id = ?
+         ORDER BY created_at DESC
+      `).all(sessionId);
+            return rows;
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn('[recoveryStore] listForSession failed:', err instanceof Error ? err.message : String(err));
+            return [];
+        }
+    }
+    /**
+     * Operator escape hatch — `/recovery clear <signature>` lets the
+     * operator say "this is fixed, stop counting it." Cascades to
+     * the linked recovery_reports rows so the signature genuinely
+     * disappears. Returns true when a row was deleted.
+     */
+    clearSignature(signature) {
+        try {
+            const sig = this.getBySignature(signature);
+            if (!sig)
+                return false;
+            const txn = this.db.transaction(() => {
+                this.db.prepare(`DELETE FROM recovery_reports WHERE signature_id = ?`).run(sig.id);
+                this.db.prepare(`DELETE FROM failure_signatures WHERE id = ?`).run(sig.id);
+            });
+            txn();
+            return true;
+        }
+        catch (err) {
+            // eslint-disable-next-line no-console
+            console.warn('[recoveryStore] clearSignature failed:', err instanceof Error ? err.message : String(err));
+            return false;
+        }
+    }
+}
+exports.RecoveryStore = RecoveryStore;
+// ── Module-level singleton ───────────────────────────────────────────────
+let _singleton = null;
+/**
+ * Initialise the process-wide store. Called once at REPL / daemon /
+ * MCP boot, after `runMigrations` has applied v7. Re-init replaces
+ * the singleton so tests can swap DBs cleanly.
+ */
+function initRecoveryStore(opts) {
+    _singleton = new RecoveryStore(opts.db);
+    return _singleton;
+}
+/**
+ * Read the current singleton. Returns null when not initialised so
+ * callers on the hot path (TCE write-through) can no-op silently
+ * instead of throwing. The slash command path (`/recovery list`)
+ * does its own "not initialised" error reporting.
+ */
+function getRecoveryStore() {
+    return _singleton;
+}
+/**
+ * Test-only — drop the singleton so the next `initRecoveryStore`
+ * call wires a fresh state.
+ */
+function _resetRecoveryStoreForTests() {
+    _singleton = null;
+}

package/dist/core/v4/selfimprovement/signatureBuilder.js

@@ -0,0 +1,158 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/selfimprovement/signatureBuilder.ts — v4.6 Phase 3b.
+ *
+ * Builds a stable, deterministic signature string for a failed tool
+ * call so equivalent failures collapse into one `failure_signatures`
+ * row. The shape is:
+ *
+ *     <tool_name>:<failure_category>[:<args_hash_prefix>]
+ *
+ * The `args_hash_prefix` field is OPTIONAL. When the caller supplies
+ * `args`, this module normalises them (strips volatile fields like
+ * timestamps, run IDs, UUIDs, monotonic counters), serialises the
+ * result deterministically, and takes the first 6 hex chars of a
+ * SHA-256 digest. When `args` is omitted, the signature collapses to
+ * `<tool>:<category>` only — same logical failure, broader grouping.
+ *
+ * Granularity trade-offs:
+ *
+ *   * Too granular ("every failure unique") → no aggregation; the
+ *     `occurrences` column never increments past 1; operators can't
+ *     see "this tool fails the same way over and over."
+ *   * Too coarse ("only tool+category") → "file_read failed with
+ *     `not_found`" groups EVERY missing file together; the operator
+ *     can't tell which paths are sore points.
+ *
+ * The args-hash compromise: same tool + same category + same
+ * normalized args → same signature (good); same tool + same category
+ * + meaningfully different args → different signatures (also good).
+ * Volatile fields are stripped BEFORE hashing so re-hashing on a
+ * later turn produces the same signature even when only the
+ * timestamp / call id changes.
+ *
+ * Volatile field list (`VOLATILE_KEYS`) — defensive; covers the
+ * fields Aiden's tool layer tends to thread through args. Plugin
+ * authors who emit custom volatile keys should pre-normalise before
+ * calling this module.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFailureSignature = buildFailureSignature;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+// ── Implementation ───────────────────────────────────────────────────────
+/**
+ * Keys whose values are stripped from the args object before hashing.
+ * These are fields that DO change between otherwise-identical
+ * failures (turn timestamps, run row ids, etc.) so leaving them in
+ * would prevent any signature from ever grouping.
+ *
+ * The list is intentionally narrow — only fields Aiden's tool layer
+ * is known to inject. Plugins emitting custom volatile keys must
+ * pre-normalise their args before calling this module.
+ */
+const VOLATILE_KEYS = new Set([
+    'timestamp',
+    'ts',
+    'requestId',
+    'request_id',
+    'runId',
+    'run_id',
+    'callId',
+    'call_id',
+    'sessionId',
+    'session_id',
+    'turnId',
+    'turn_id',
+    'eventId',
+    'event_id',
+    'createdAt',
+    'created_at',
+    'updatedAt',
+    'updated_at',
+    // Common UUID/idempotency-key names.
+    'uuid',
+    'idempotencyKey',
+    'idempotency_key',
+]);
+/**
+ * Deterministically stringify a value. Sorts object keys so
+ * `{a:1, b:2}` and `{b:2, a:1}` produce identical bytes. Strips
+ * volatile keys from any nested object before stringifying.
+ *
+ * Non-JSON-serialisable values (functions, symbols, circular refs)
+ * collapse to the literal string `'[unserializable]'` so the hash
+ * remains stable. Better-than-throwing is the right trade-off for
+ * a write-through hot path.
+ */
+function deterministicStringify(value) {
+    const seen = new WeakSet();
+    const visit = (v) => {
+        if (v === null || v === undefined)
+            return null;
+        const t = typeof v;
+        if (t === 'string' || t === 'number' || t === 'boolean')
+            return v;
+        if (t === 'function' || t === 'symbol')
+            return '[unserializable]';
+        if (typeof v === 'bigint')
+            return v.toString();
+        if (Array.isArray(v)) {
+            if (seen.has(v))
+                return '[circular]';
+            seen.add(v);
+            return v.map(visit);
+        }
+        if (t === 'object') {
+            const obj = v;
+            if (seen.has(obj))
+                return '[circular]';
+            seen.add(obj);
+            const out = {};
+            const keys = Object.keys(obj).filter((k) => !VOLATILE_KEYS.has(k));
+            keys.sort();
+            for (const k of keys)
+                out[k] = visit(obj[k]);
+            return out;
+        }
+        return '[unserializable]';
+    };
+    try {
+        return JSON.stringify(visit(value));
+    }
+    catch {
+        return '[unserializable]';
+    }
+}
+/**
+ * Build a failure signature. Pure function — no I/O, no side
+ * effects. Safe to call on the hot path of every classified
+ * failure; SHA-256 of a small JSON string is cheap (microseconds).
+ */
+function buildFailureSignature(input) {
+    const base = `${input.toolName}:${input.category}`;
+    if (input.args === undefined) {
+        return { signature: base };
+    }
+    const normalized = deterministicStringify(input.args);
+    // Empty / trivially-null args don't deserve a hash suffix —
+    // collapse to the base signature so "args: {}" and "no args"
+    // group together.
+    if (normalized === 'null' || normalized === '{}' || normalized === '[]') {
+        return { signature: base };
+    }
+    const digest = node_crypto_1.default.createHash('sha256').update(normalized).digest('hex');
+    const argsHash = digest.slice(0, 6);
+    return {
+        signature: `${base}:${argsHash}`,
+        argsHash,
+    };
+}