aiden-runtime 4.1.5 → 4.6.0

package/dist/core/v4/daemon/drain.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/drain.ts — v4.5 Phase 1: 5-step ordered shutdown drain.
+ *
+ * The shutdown sequence is order-sensitive. Getting it wrong wastes
+ * the drain budget on the wrong thing OR loses attribution on
+ * subprocess cleanup. Sequence:
+ *
+ *   Step 0: markShuttingDown(reason)         — record intent in DB
+ *   Step 1: notifySessions()                 — let sessions emit "shutting
+ *                                              down" while adapters are up
+ *   Step 2: drain active runs (timeout)
+ *           - on timeout: mark each still-active run with
+ *             resume_pending + interrupt + wait 5s for cooperation
+ *   Step 3: kill tool subprocesses           — BEFORE adapter teardown,
+ *                                              so they don't get reaped
+ *                                              by the cgroup and lose
+ *                                              attribution
+ *   Step 4: close resources                  — parallel: browser, docker,
+ *                                              cron, idempotency, sqlite
+ *                                              (resourceRegistry.reapAll)
+ *   Step 5: mark daemon_instances shutdown   — final DB write
+ *           release runtime lock
+ *           touch .clean_shutdown marker
+ *           process.exit(exitCode)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDraining = isDraining;
+exports._resetDrainStateForTests = _resetDrainStateForTests;
+exports.performDrain = performDrain;
+exports.signalToReason = signalToReason;
+const POST_INTERRUPT_GRACE_MS = 5000;
+/** True once a drain has started — used by signal handlers to de-bounce. */
+let _draining = false;
+function isDraining() { return _draining; }
+function _resetDrainStateForTests() { _draining = false; }
+async function performDrain(opts) {
+    if (_draining) {
+        // Idempotent — a second signal during drain is a no-op.
+        return { durationMs: 0, drainTimedOut: false, resumePendingIds: [], reapedResources: null };
+    }
+    _draining = true;
+    const startedAt = Date.now();
+    // ── Step 0: mark shutting down ────────────────────────────────────────
+    try {
+        opts.markShutdown?.(opts.reason, opts.exitCode ?? 0);
+    }
+    catch { /* noop */ }
+    // (Note: markShutdown is called twice — once here to set
+    // shutdown_reason early so observers see the daemon is exiting,
+    // again in Step 5 with the final exit_code.)
+    // ── Step 1: notify sessions ───────────────────────────────────────────
+    try {
+        await Promise.resolve(opts.notifySessions?.());
+    }
+    catch { /* never block on notify */ }
+    // ── Step 2: drain active runs with timeout ────────────────────────────
+    const activeIds = await Promise.resolve(opts.activeRuns?.() ?? []);
+    const resumePendingIds = [];
+    let drainTimedOut = false;
+    if (activeIds.length > 0 && opts.drainTimeoutMs > 0) {
+        // Implementation note: the daemon's run-completion path is
+        // event-driven, but Phase 1 doesn't yet have a "wait for runs
+        // to finish" primitive (Phase 5 will, when runs are wired to
+        // the agent loop). Phase 1's behaviour: simply wait
+        // drainTimeoutMs, then check if any runs are still active and
+        // mark them resume_pending. This is correct for Phase 1's
+        // shape (no triggers wired = no active daemon-runs to drain).
+        await sleep(opts.drainTimeoutMs);
+        const stillActive = await Promise.resolve(opts.activeRuns?.() ?? []);
+        if (stillActive.length > 0) {
+            drainTimedOut = true;
+            for (const runId of stillActive) {
+                try {
+                    await Promise.resolve(opts.markResumePending?.(runId, 'drain_timeout'));
+                }
+                catch { /* best-effort */ }
+                try {
+                    await Promise.resolve(opts.interruptRun?.(runId, 'shutdown'));
+                }
+                catch { /* best-effort */ }
+                resumePendingIds.push(runId);
+            }
+            await sleep(opts.postInterruptGraceMs ?? POST_INTERRUPT_GRACE_MS);
+        }
+    }
+    // ── Step 3: kill tool subprocesses BEFORE adapter teardown ────────────
+    try {
+        await Promise.resolve(opts.killToolSubprocesses?.('post-interrupt'));
+    }
+    catch { /* best-effort */ }
+    // ── Step 4: close resources (parallel) ────────────────────────────────
+    let reapedResources = null;
+    try {
+        const tasks = [];
+        if (opts.closeBrowser)
+            tasks.push(Promise.resolve(opts.closeBrowser()).catch(() => undefined));
+        if (opts.closeCron)
+            tasks.push(Promise.resolve(opts.closeCron()).catch(() => undefined));
+        if (opts.closeDocker)
+            tasks.push(Promise.resolve(opts.closeDocker()).catch(() => undefined));
+        if (opts.closeIdempotency)
+            tasks.push(Promise.resolve(opts.closeIdempotency()).catch(() => undefined));
+        if (opts.closeResources)
+            tasks.push(Promise.resolve(opts.closeResources())
+                .then((r) => {
+                if (r && typeof r === 'object' && 'reaped' in r && 'failed' in r) {
+                    reapedResources = r;
+                }
+            })
+                .catch(() => undefined));
+        if (tasks.length > 0)
+            await Promise.all(tasks);
+    }
+    catch { /* never block shutdown on resource close */ }
+    // ── Step 5: final markers + exit ──────────────────────────────────────
+    try {
+        opts.markShutdown?.(opts.reason, opts.exitCode ?? 0);
+    }
+    catch { /* noop */ }
+    try {
+        opts.touchCleanShutdown?.();
+    }
+    catch { /* noop */ }
+    try {
+        opts.removePid?.();
+    }
+    catch { /* noop */ }
+    const durationMs = Date.now() - startedAt;
+    if (opts.callProcessExit !== false) {
+        // Default — exit the process. Tests pass `callProcessExit: false`.
+        process.exit(opts.exitCode ?? 0);
+    }
+    return { durationMs, drainTimedOut, resumePendingIds, reapedResources };
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const t = setTimeout(resolve, ms);
+        if (typeof t.unref === 'function')
+            t.unref();
+    });
+}
+/** Convenience for callers that want a shutdown reason from a signal name. */
+function signalToReason(signal) {
+    switch (signal) {
+        case 'SIGINT': return 'sigint';
+        case 'SIGTERM': return 'sigterm';
+        case 'SIGUSR1': return 'sigusr1_restart';
+    }
+}

package/dist/core/v4/daemon/eventLoopLag.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/eventLoopLag.ts — v4.5 Phase 1: event-loop responsiveness.
+ *
+ * A ticking timer measures how long it takes the event loop to fire
+ * a 100ms `setInterval`. Lag = `(actual - expected)`. A healthy
+ * loop reports lag ≤ a few ms; a saturated loop blows out into
+ * hundreds of ms.
+ *
+ * Consumed by:
+ *   - /health/live — endpoint returns 500 when lag > 5s for > 5s
+ *   - /metrics — `aiden_daemon_event_loop_lag_ms` gauge
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startEventLoopLagSampler = startEventLoopLagSampler;
+exports.stopEventLoopLagSampler = stopEventLoopLagSampler;
+exports.getEventLoopLagMs = getEventLoopLagMs;
+exports.getLastTickAt = getLastTickAt;
+exports.isEventLoopResponsive = isEventLoopResponsive;
+const SAMPLE_INTERVAL_MS = 100;
+let _timer = null;
+let _lastTickAt = 0;
+let _lastLagMs = 0;
+function tick() {
+    const now = Date.now();
+    if (_lastTickAt !== 0) {
+        _lastLagMs = Math.max(0, now - _lastTickAt - SAMPLE_INTERVAL_MS);
+    }
+    _lastTickAt = now;
+}
+/** Start the sampler. Idempotent. */
+function startEventLoopLagSampler() {
+    if (_timer)
+        return;
+    _lastTickAt = Date.now();
+    _lastLagMs = 0;
+    _timer = setInterval(tick, SAMPLE_INTERVAL_MS);
+    if (typeof _timer.unref === 'function')
+        _timer.unref();
+}
+/** Stop the sampler. Idempotent. */
+function stopEventLoopLagSampler() {
+    if (!_timer)
+        return;
+    clearInterval(_timer);
+    _timer = null;
+    _lastTickAt = 0;
+    _lastLagMs = 0;
+}
+/** Most-recent sampled lag in ms. Zero when sampler hasn't run yet. */
+function getEventLoopLagMs() {
+    return _lastLagMs;
+}
+/** Wall-clock time of the last successful tick (0 when never). */
+function getLastTickAt() {
+    return _lastTickAt;
+}
+/**
+ * Liveness verdict: true when the event loop has ticked within the
+ * tolerance window. The `tolerance` defaults to 5s, matching the
+ * /health/live endpoint's threshold.
+ */
+function isEventLoopResponsive(toleranceMs = 5000) {
+    if (_lastTickAt === 0)
+        return false;
+    return Date.now() - _lastTickAt <= toleranceMs;
+}

package/dist/core/v4/daemon/health.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/health.ts — v4.5 Phase 1: health + metrics endpoints.
+ *
+ * Three layered health endpoints + a Prometheus-style /metrics:
+ *
+ *   /health/live       — 200 if the event loop is responsive
+ *                        (event-loop-lag sampler ticked within 5s).
+ *                        Returns 500 otherwise. Used by external
+ *                        watchdogs (Kubernetes liveness, simple
+ *                        curl checks).
+ *
+ *   /health/ready      — 200 if the daemon can accept new triggers
+ *                        AND the SQLite DB is writable. 503 otherwise.
+ *
+ *   /health/degraded   — 200 with { degraded: boolean, reasons }.
+ *                        Reasons surface resource-budget overruns,
+ *                        non-zero dead_letter count, stale cron
+ *                        heartbeat. Designed for dashboards, not
+ *                        load balancers.
+ *
+ *   /metrics           — text/plain Prometheus exposition format.
+ *
+ *   /api/daemon/status   — JSON: instance + uptime + version + counts
+ *   /api/daemon/resources — JSON: registry list + budgetByKind
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateDegraded = evaluateDegraded;
+exports.mountHealthEndpoints = mountHealthEndpoints;
+const eventLoopLag_1 = require("./eventLoopLag");
+function evaluateDegraded(deps) {
+    const reasons = [];
+    // Trigger bus health.
+    try {
+        const stats = deps.triggerBus.stats();
+        if (stats.deadLetter > 0) {
+            reasons.push({
+                code: 'dead_letter_nonzero',
+                message: `${stats.deadLetter} trigger event(s) in dead_letter`,
+            });
+        }
+        if (stats.oldestPendingMs != null && stats.oldestPendingMs > 60 * 60 * 1000) {
+            reasons.push({
+                code: 'pending_stale',
+                message: `oldest pending trigger is ${Math.round(stats.oldestPendingMs / 1000)}s old`,
+            });
+        }
+    }
+    catch (e) {
+        reasons.push({
+            code: 'trigger_bus_error',
+            message: e instanceof Error ? e.message : String(e),
+        });
+    }
+    // Event-loop lag.
+    const lag = (0, eventLoopLag_1.getEventLoopLagMs)();
+    if (lag > 1000) {
+        reasons.push({ code: 'event_loop_lag', message: `${lag}ms` });
+    }
+    return reasons;
+}
+/**
+ * Mount the v4.5 daemon health endpoints onto an Express router.
+ * Idempotent at the endpoint level (Express dedup is the caller's
+ * responsibility — call once during server boot).
+ */
+function mountHealthEndpoints(router, deps) {
+    router.get('/health/live', (_req, res) => {
+        const ok = (0, eventLoopLag_1.isEventLoopResponsive)(5000);
+        res
+            .status(ok ? 200 : 500)
+            .json({ ok, lagMs: (0, eventLoopLag_1.getEventLoopLagMs)() });
+    });
+    router.get('/health/ready', (_req, res) => {
+        try {
+            const row = deps.db.prepare('SELECT 1 AS v').get();
+            const dbOk = row?.v === 1;
+            res.status(dbOk ? 200 : 503).json({ ok: dbOk, db: dbOk ? 'ready' : 'unreachable' });
+        }
+        catch (e) {
+            res.status(503).json({
+                ok: false,
+                db: 'error',
+                error: e instanceof Error ? e.message : String(e),
+            });
+        }
+    });
+    router.get('/health/degraded', (_req, res) => {
+        const reasons = evaluateDegraded(deps);
+        res.status(200).json({ degraded: reasons.length > 0, reasons });
+    });
+    router.get('/metrics', (_req, res) => {
+        const mu = process.memoryUsage();
+        const ts = deps.triggerBus.stats();
+        const budgets = deps.resourceRegistry.budgetByKind();
+        const inst = deps.instanceTracker.current();
+        const uptimeSec = inst ? Math.floor((Date.now() - inst.startedAt) / 1000) : 0;
+        const lines = [];
+        const m = (name, value, help, type = 'gauge') => {
+            if (help)
+                lines.push(`# HELP ${name} ${help}`);
+            lines.push(`# TYPE ${name} ${type}`);
+            lines.push(`${name} ${value}`);
+        };
+        m('aiden_daemon_rss_bytes', mu.rss, 'Resident set size in bytes');
+        m('aiden_daemon_heap_used_bytes', mu.heapUsed, 'V8 heap used in bytes');
+        m('aiden_daemon_event_loop_lag_ms', (0, eventLoopLag_1.getEventLoopLagMs)(), 'Event loop lag in ms');
+        m('aiden_daemon_uptime_seconds', uptimeSec, 'Daemon uptime in seconds');
+        m('aiden_daemon_trigger_pending', ts.pending, 'Pending trigger events');
+        m('aiden_daemon_trigger_claimed', ts.claimed, 'Claimed trigger events');
+        m('aiden_daemon_trigger_running', ts.running, 'Running trigger events');
+        m('aiden_daemon_trigger_deadletter', ts.deadLetter, 'Dead-letter trigger events');
+        for (const [kind, b] of Object.entries(budgets)) {
+            lines.push(`# HELP aiden_daemon_resource_count Count of registered resources by kind`);
+            lines.push(`# TYPE aiden_daemon_resource_count gauge`);
+            lines.push(`aiden_daemon_resource_count{kind="${kind}"} ${b.count}`);
+            if (b.budgetUnits > 0) {
+                lines.push(`# HELP aiden_daemon_resource_budget Sum of budget units by kind`);
+                lines.push(`# TYPE aiden_daemon_resource_budget gauge`);
+                lines.push(`aiden_daemon_resource_budget{kind="${kind}"} ${b.budgetUnits}`);
+            }
+        }
+        res.type('text/plain; version=0.0.4').send(lines.join('\n') + '\n');
+    });
+    router.get('/api/daemon/status', (_req, res) => {
+        const inst = deps.instanceTracker.current();
+        const stats = deps.triggerBus.stats();
+        res.status(200).json({
+            instance: inst,
+            version: deps.version,
+            uptimeMs: inst ? Date.now() - inst.startedAt : 0,
+            triggers: stats,
+            eventLoopLagMs: (0, eventLoopLag_1.getEventLoopLagMs)(),
+        });
+    });
+    router.get('/api/daemon/resources', (_req, res) => {
+        const list = deps.resourceRegistry.list().map((r) => ({
+            id: r.id,
+            kind: r.kind,
+            owner: r.owner,
+            createdAt: r.createdAt,
+            lastUsedAt: r.lastUsedAt,
+            ttlMs: r.ttlMs,
+            budgetUnits: r.budgetUnits,
+            metadata: r.metadata,
+        }));
+        res.status(200).json({
+            total: list.length,
+            budgetByKind: deps.resourceRegistry.budgetByKind(),
+            resources: list,
+        });
+    });
+}

package/dist/core/v4/daemon/idempotencyStore.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/daemon/idempotencyStore.ts — v4.5 Phase 1: L1/L2 cache.
+ *
+ * Two-tier cache for "exactly once" semantics on webhook deliveries
+ * (Phase 3) and authenticated API runs (Phase 1+).
+ *
+ *   L1 — in-memory `Map<scopeKey, IdempotencyEntry>` for hot path.
+ *   L2 — SQLite `idempotency_keys` for durability across restarts.
+ *
+ * Workflow:
+ *   - getOrSet(scope, key, fingerprint, compute):
+ *       1. Look up L1; if hit and unexpired → return cached.
+ *       2. Look up L2; if hit and unexpired → reseed L1 → return cached.
+ *       3. Miss: invoke compute(), persist to L2 + L1, return.
+ *   - Daemon boot calls `reseed()` once to load unexpired L2 rows
+ *     into L1 (warm-start the in-memory cache).
+ *   - A background sweep deletes L2 rows whose `expires_at < now`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_L1_ENTRIES = exports.SWEEP_INTERVAL_MS = exports.DEFAULT_TTL_MS = void 0;
+exports.createIdempotencyStore = createIdempotencyStore;
+exports.DEFAULT_TTL_MS = 60 * 60 * 1000; // 1 hour
+exports.SWEEP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+exports.MAX_L1_ENTRIES = 4096;
+function scopeKey(scope, key) {
+    return `${scope}::${key}`;
+}
+function createIdempotencyStore(opts) {
+    const db = opts.db;
+    const defaultTtl = opts.defaultTtlMs ?? exports.DEFAULT_TTL_MS;
+    const sweepInterval = opts.sweepIntervalMs ?? exports.SWEEP_INTERVAL_MS;
+    const l1 = new Map();
+    // ── L1 eviction (FIFO past cap) ──
+    function l1Insert(entry) {
+        const k = scopeKey(entry.scope, entry.key);
+        l1.set(k, entry);
+        if (l1.size > exports.MAX_L1_ENTRIES) {
+            const first = l1.keys().next().value;
+            if (first !== undefined)
+                l1.delete(first);
+        }
+    }
+    function readFromL2(scope, key, now) {
+        const row = db
+            .prepare(`SELECT * FROM idempotency_keys WHERE scope = ? AND key = ?`)
+            .get(scope, key);
+        if (!row)
+            return null;
+        if (row.expires_at <= now)
+            return null;
+        return {
+            scope: row.scope,
+            key: row.key,
+            fingerprint: row.fingerprint,
+            responseJson: row.response_json,
+            statusCode: row.status_code,
+            createdAt: row.created_at,
+            expiresAt: row.expires_at,
+        };
+    }
+    function writeToL2(entry) {
+        db.prepare(`INSERT OR REPLACE INTO idempotency_keys
+         (scope, key, fingerprint, response_json, status_code, created_at, expires_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`).run(entry.scope, entry.key, entry.fingerprint, entry.responseJson, entry.statusCode, entry.createdAt, entry.expiresAt);
+    }
+    // Initial reseed from L2 (cheap — bounded by `MAX_L1_ENTRIES`).
+    function reseedFromL2() {
+        const now = Date.now();
+        const rows = db
+            .prepare(`SELECT * FROM idempotency_keys
+          WHERE expires_at > ?
+          ORDER BY created_at DESC
+          LIMIT ?`)
+            .all(now, exports.MAX_L1_ENTRIES);
+        let loaded = 0;
+        for (const row of rows) {
+            l1Insert({
+                scope: row.scope,
+                key: row.key,
+                fingerprint: row.fingerprint,
+                responseJson: row.response_json,
+                statusCode: row.status_code,
+                createdAt: row.created_at,
+                expiresAt: row.expires_at,
+            });
+            loaded += 1;
+        }
+        return { loaded };
+    }
+    function sweep(now) {
+        const cutoff = now ?? Date.now();
+        const r = db
+            .prepare(`DELETE FROM idempotency_keys WHERE expires_at < ?`)
+            .run(cutoff);
+        // Also evict expired L1 entries.
+        for (const [k, v] of l1) {
+            if (v.expiresAt < cutoff)
+                l1.delete(k);
+        }
+        return { deleted: r.changes };
+    }
+    // Background sweep timer.
+    let sweepTimer = null;
+    if (sweepInterval > 0) {
+        sweepTimer = setInterval(() => {
+            try {
+                sweep();
+            }
+            catch { /* never let sweep crash */ }
+        }, sweepInterval);
+        if (typeof sweepTimer.unref === 'function')
+            sweepTimer.unref();
+    }
+    return {
+        async getOrSet(scope, key, fingerprint, compute, ttlMs) {
+            const now = Date.now();
+            const sk = scopeKey(scope, key);
+            let entry = l1.get(sk);
+            if (!entry || entry.expiresAt <= now) {
+                const fromL2 = readFromL2(scope, key, now);
+                if (fromL2) {
+                    l1Insert(fromL2);
+                    entry = fromL2;
+                }
+            }
+            if (entry) {
+                if (fingerprint != null && entry.fingerprint != null && entry.fingerprint !== fingerprint) {
+                    // Fingerprint mismatch — treat as a new request. Compute fresh.
+                }
+                else {
+                    return { responseJson: entry.responseJson, statusCode: entry.statusCode };
+                }
+            }
+            const computed = await compute();
+            const ttl = ttlMs ?? defaultTtl;
+            const newEntry = {
+                scope,
+                key,
+                fingerprint,
+                responseJson: computed.responseJson,
+                statusCode: computed.statusCode,
+                createdAt: now,
+                expiresAt: now + ttl,
+            };
+            writeToL2(newEntry);
+            l1Insert(newEntry);
+            return computed;
+        },
+        get(scope, key) {
+            const now = Date.now();
+            const sk = scopeKey(scope, key);
+            let entry = l1.get(sk);
+            if (!entry || entry.expiresAt <= now) {
+                const fromL2 = readFromL2(scope, key, now);
+                if (!fromL2)
+                    return null;
+                l1Insert(fromL2);
+                entry = fromL2;
+            }
+            return { responseJson: entry.responseJson, statusCode: entry.statusCode };
+        },
+        set(scope, key, fingerprint, response, ttlMs) {
+            const now = Date.now();
+            const ttl = ttlMs ?? defaultTtl;
+            const entry = {
+                scope,
+                key,
+                fingerprint,
+                responseJson: response.responseJson,
+                statusCode: response.statusCode,
+                createdAt: now,
+                expiresAt: now + ttl,
+            };
+            writeToL2(entry);
+            l1Insert(entry);
+        },
+        sweepExpired(now) {
+            return sweep(now);
+        },
+        reseed() {
+            return reseedFromL2();
+        },
+        stats() {
+            const row = db
+                .prepare(`SELECT COUNT(*) AS c FROM idempotency_keys`)
+                .get();
+            return { l1: l1.size, l2: row.c };
+        },
+        close() {
+            if (sweepTimer) {
+                clearInterval(sweepTimer);
+                sweepTimer = null;
+            }
+            l1.clear();
+        },
+    };
+}