aiden-runtime 4.5.0 → 4.6.0

package/dist/core/v4/providerFallback.js

@@ -427,16 +427,49 @@ class FallbackAdapter {
      * provider key, but isolation prevents one slow subagent from
      * starving siblings via parent-side cooldown state.
      */
-    clone() {
+    clone(opts) {
+        // v4.6 Phase 2P — optional `providerId` filter restricts the clone
+        // to slots matching the named provider. Used by `spawn_sub_agent`'s
+        // per-spawn provider override: fanout (and future callers) pass a
+        // specific provider name so the child's FallbackAdapter rotates
+        // only within that provider's slots, preserving the diversity
+        // invariant fanout depends on. When omitted, full-slot clone is
+        // the Phase 1 behaviour (unchanged).
+        //
+        // Caller is responsible for validating `providerId` against
+        // `getProviderIds()` before calling — an unknown providerId
+        // here yields a degenerate clone (zero slots), which the
+        // FallbackAdapter's own dispatch path treats as "no providers"
+        // and would error on first call. Defending here would mask the
+        // upstream validation gap; we prefer fail-loud at the validation
+        // layer instead.
+        const slots = opts?.providerId
+            ? this.slots.filter((s) => s.providerId === opts.providerId)
+            : this.slots;
         return new FallbackAdapter({
             apiMode: this.apiMode,
-            slots: this.slots,
+            slots,
             cooldownMs: this.cooldownMs,
             now: this.clock,
             onRateLimit: this.onRateLimit,
             onFallback: this.onFallback,
         });
     }
+    /**
+     * v4.6 Phase 2P — return the set of provider IDs the adapter knows
+     * about (deduplicated, key-present slots only). Used by
+     * `spawn_sub_agent`'s per-spawn provider override validation: the
+     * spec's `provider` field must name one of these. Sorted for
+     * stable diagnostic output in error messages.
+     */
+    getProviderIds() {
+        const seen = new Set();
+        for (const slot of this.slots) {
+            if (slot.keyPresent)
+                seen.add(slot.providerId);
+        }
+        return [...seen].sort();
+    }
     /**
      * Diagnostic snapshot for `/providers`. Per-slot cooldown is reported
      * in seconds remaining (0 when the slot is fresh) so the slash command

package/dist/core/v4/runtimeToggles.js

@@ -52,14 +52,41 @@ const ENV_VAR = {
     // env (this is mostly a UX toggle) but included for symmetry with
     // the other subsystem toggles.
     suggestions: 'AIDEN_SUGGESTIONS',
+    // v4.6 Phase 2M — keyword-based per-turn tool narrowing.
+    // Default OFF: smart models (GPT-5.5, Claude Sonnet 4.5+, Opus)
+    // pick tools fine from a full catalog. PlannerGuard adds latency
+    // (1 LLM call when mode=llm_classified) and occasionally strips
+    // tools the model genuinely needed. Opt in for small local models
+    // that get overwhelmed by 50+ tool schemas.
+    planner_guard: 'AIDEN_PLANNER_GUARD',
 };
 const CONFIG_KEY = {
     sandbox: 'runtime_toggles.sandbox',
     tce: 'runtime_toggles.tce',
     browser_depth: 'runtime_toggles.browser_depth',
     suggestions: 'runtime_toggles.suggestions',
+    planner_guard: 'runtime_toggles.planner_guard',
+};
+const ALL_KEYS = [
+    'sandbox', 'tce', 'browser_depth', 'suggestions', 'planner_guard',
+];
+/**
+ * v4.6 Phase 2M — per-key default. Pre-2M every toggle defaulted to
+ * `true` (sandbox/tce/browser-depth/suggestions all ship on); the
+ * `planner_guard` toggle is the first to default `false`, so the
+ * resolver needs a per-key default map rather than a hardcoded `true`.
+ *
+ * Smart models (GPT-5.5, Claude Sonnet 4.5+, Opus) pick from the
+ * full tool catalog without help — keyword-based narrowing is a
+ * legacy workaround for smaller local models, opt in when needed.
+ */
+const DEFAULT_VALUE = {
+    sandbox: true,
+    tce: true,
+    browser_depth: true,
+    suggestions: true,
+    planner_guard: false,
 };
-const ALL_KEYS = ['sandbox', 'tce', 'browser_depth', 'suggestions'];
 // ── Resolver primitives ────────────────────────────────────────────────────
 /**
  * Strict env interpretation matching existing v4.2/v4.3/v4.4
@@ -122,8 +149,8 @@ function buildRuntimeToggles(deps = {}) {
         const cfgValue = readConfig(deps.configRead, key);
         if (cfgValue !== null)
             return { value: cfgValue, source: 'config' };
-        // 4. default
-        return { value: true, source: 'default' };
+        // 4. default (v4.6 Phase 2M — per-key, see DEFAULT_VALUE)
+        return { value: DEFAULT_VALUE[key], source: 'default' };
     }
     function fire(key) {
         const set = subscribers.get(key);

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,
+    };
+}