nodedex 0.1.0

package/dist/middleware/reflect/arc-inactivity-timer.js

@@ -0,0 +1,175 @@
+// ═══════════════════════════════════════════════════════════════════════════════
+// DEBT 5 Phase 10 — INACTIVITY SAFETY NET (server-side timer)
+// ═══════════════════════════════════════════════════════════════════════════════
+//
+// Per design §3.8 safety net 3: when an agent has pass01_done turns sitting
+// idle past a threshold (default 30 min) and no new captures since, the
+// conversation is likely abandoned (user walked away, agent crashed, session
+// closed without explicit arc-extract). Fire arc extraction so residue isn't
+// permanently lost.
+//
+// Why this is the UNIVERSAL fallback per inventory §4:
+//   - PreCompact hook (safety net 1) requires Claude Code emit a PreCompact event
+//   - SessionEnd hook (safety net 2) is NOT available in Claude Code today
+//   - Inactivity timer needs NO framework cooperation — pure server-side
+//
+// Config (env):
+//   NODEDEX_ARC_INACTIVITY_INTERVAL_MS  default 60_000 (1 min check cadence)
+//   NODEDEX_ARC_INACTIVITY_THRESHOLD_MS default 1_800_000 (30 min idle threshold)
+//   NODEDEX_ARC_INACTIVITY_ENABLED      'on' to enable, 'off' (default) to skip
+//
+// DEFAULT OFF — opt-in via env. Reason: until per-turn capture is on
+// (NODEDEX_ARC_EXTRACTION=1), there will be no pass01_done turns and the
+// timer is a no-op anyway. Once arc-mode is enabled, operators flip this
+// on to get the auto-trigger safety net.
+import { runArcExtraction } from "./arc-pipeline.js";
+import { intFromEnv } from "./config.js";
+let _intervalHandle = null;
+function getIntervalMs() {
+    return intFromEnv("NODEDEX_ARC_INACTIVITY_INTERVAL_MS", 60_000, 1000);
+}
+function getThresholdMs() {
+    const raw = process.env.NODEDEX_ARC_INACTIVITY_THRESHOLD_MS;
+    if (raw) {
+        const n = Number.parseInt(raw, 10);
+        if (Number.isFinite(n) && n >= 60_000)
+            return n;
+    }
+    return 1_800_000; // 30 min default
+}
+function arcInactivityEnabled() {
+    return (process.env.NODEDEX_ARC_INACTIVITY_ENABLED ?? "").toLowerCase() === "on";
+}
+/**
+ * Run one inactivity check. For each stale agent, fire arc extraction with
+ * trigger_source='inactivity'. Per-agent failures are logged but don't stop
+ * the tick. Exported so tests can drive it directly without setInterval.
+ */
+export async function runInactivityTick(db, thresholdMs = getThresholdMs()) {
+    const agents = db.getAgentsWithStalePass01Turns(thresholdMs);
+    const stats = {
+        checked: agents.length,
+        extracted: 0,
+        skipped_in_progress: 0,
+        skipped_rate_limited: 0,
+        skipped_min_range: 0,
+        errors: 0,
+    };
+    for (const agentId of agents) {
+        try {
+            const r = await runArcExtraction(db, {
+                agent_id: agentId,
+                trigger_source: "inactivity",
+            });
+            switch (r.status) {
+                case "extracted":
+                    stats.extracted++;
+                    break;
+                case "in_progress":
+                    stats.skipped_in_progress++;
+                    break;
+                case "rate_limited":
+                    stats.skipped_rate_limited++;
+                    break;
+                case "min_range_too_small":
+                    stats.skipped_min_range++;
+                    break;
+                case "no_turns": // race: turns were extracted between query and run
+                case "pipeline_incomplete": // v2 failed after retries — turns stay re-extractable, next tick retries
+                case "pipeline_failed":
+                    stats.errors++;
+                    break;
+            }
+        }
+        catch (e) {
+            stats.errors++;
+            console.warn(`[arc-inactivity] runArcExtraction threw for agent=${agentId.slice(0, 8)}: ${e?.message}`);
+        }
+    }
+    if (stats.checked > 0) {
+        console.log(`[arc-inactivity] tick: checked=${stats.checked} extracted=${stats.extracted} in_progress=${stats.skipped_in_progress} rate_limited=${stats.skipped_rate_limited} min_range=${stats.skipped_min_range} errors=${stats.errors}`);
+    }
+    return stats;
+}
+/**
+ * Start the inactivity check timer. Idempotent — calling twice is a no-op
+ * after the first call. Honor the enabled flag — if off, do nothing.
+ * Returns true if the timer started, false if it was disabled or already running.
+ */
+export function startArcInactivityTimer(db) {
+    if (!arcInactivityEnabled()) {
+        console.log("[arc-inactivity] disabled (set NODEDEX_ARC_INACTIVITY_ENABLED=on to enable)");
+        return false;
+    }
+    if (_intervalHandle !== null) {
+        return false;
+    }
+    const intervalMs = getIntervalMs();
+    const thresholdMs = getThresholdMs();
+    console.log(`[arc-inactivity] starting: interval=${intervalMs}ms threshold=${thresholdMs}ms`);
+    _intervalHandle = setInterval(() => {
+        runInactivityTick(db).catch((e) => {
+            console.warn(`[arc-inactivity] tick threw: ${e?.message}`);
+        });
+    }, intervalMs);
+    // Allow the process to exit even with the timer scheduled (don't block
+    // shutdown). Node's setInterval refs by default; unref releases.
+    if (typeof _intervalHandle.unref === "function")
+        _intervalHandle.unref();
+    return true;
+}
+function bootSweepDelayMs() {
+    return intFromEnv("NODEDEX_ARC_BOOT_SWEEP_DELAY_MS", 90_000, 5_000);
+}
+/**
+ * One-shot BOOT SWEEP — recover arcs stranded by a restart.
+ *
+ * The per-turn auto-trigger fires arc extraction fire-and-forget, so a restart
+ * mid-extraction kills it and leaves the turns `pass01_done` with nothing to
+ * re-trigger them. Without this they wait up to the full inactivity threshold
+ * (default 30 min) — or forever if the inactivity timer is off.
+ *
+ * After a short settle delay this runs ONE inactivity-style tick using the delay
+ * itself as the idle window, so it sweeps turns that were already sitting at boot
+ * but NOT a conversation that resumed afterwards (those are < delay old and the
+ * normal auto-trigger owns them). Distinct from the proactive inactivity timer:
+ * this is restart RECOVERY, so it's gated only on arc mode being on — a user who
+ * turned off the 30-min inactivity sweep still doesn't want a restart to strand
+ * captured turns. Off-switch: NODEDEX_ARC_BOOT_SWEEP=off. runArcExtraction's own
+ * in-flight + rate guards keep it from racing a live trigger.
+ */
+export function startBootArcSweep(db) {
+    if (process.env.NODEDEX_ARC_EXTRACTION !== "1")
+        return false; // no pass01_done turns otherwise
+    if ((process.env.NODEDEX_ARC_BOOT_SWEEP ?? "").toLowerCase() === "off") {
+        console.log("[arc-boot-sweep] disabled (NODEDEX_ARC_BOOT_SWEEP=off)");
+        return false;
+    }
+    const delayMs = bootSweepDelayMs();
+    console.log(`[arc-boot-sweep] scheduled in ${Math.round(delayMs / 1000)}s (recovers arcs a restart left mid-extraction)`);
+    const h = setTimeout(() => {
+        runInactivityTick(db, delayMs)
+            .then((s) => { if (s.checked > 0)
+            console.log(`[arc-boot-sweep] swept ${s.extracted}/${s.checked} stranded arc(s)`); })
+            .catch((e) => console.warn(`[arc-boot-sweep] threw: ${e?.message ?? e}`));
+    }, delayMs);
+    if (typeof h.unref === "function")
+        h.unref();
+    return true;
+}
+/**
+ * Stop the inactivity check timer. Used on shutdown + by tests.
+ */
+export function stopArcInactivityTimer() {
+    if (_intervalHandle !== null) {
+        clearInterval(_intervalHandle);
+        _intervalHandle = null;
+    }
+}
+/**
+ * For tests only — reports whether the timer is currently running.
+ */
+export function _isArcInactivityTimerRunningForTests() {
+    return _intervalHandle !== null;
+}
+//# sourceMappingURL=arc-inactivity-timer.js.map

package/dist/middleware/reflect/arc-inactivity-timer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arc-inactivity-timer.js","sourceRoot":"","sources":["../../../src/middleware/reflect/arc-inactivity-timer.ts"],"names":[],"mappings":"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"}

package/dist/middleware/reflect/arc-pipeline.d.ts

@@ -0,0 +1,33 @@
+import type { WorkspaceDB, ConversationTurnRow } from "../../store/database.js";
+import type { Pass1Item, ReflectResult } from "./types.js";
+import type { LLMProvider } from "../../engine/ai-provider.js";
+export declare function lazyFillPass01(db: WorkspaceDB, provider: LLMProvider, turns: ConversationTurnRow[]): Promise<void>;
+export type ArcTriggerSource = 'phase_tag' | 'mcp_tool' | 'api' | 'precompact' | 'inactivity' | 'auto';
+export interface ArcExtractionOpts {
+    agent_id: string;
+    start_turn?: number;
+    end_turn?: number;
+    trigger_source: ArcTriggerSource;
+    re_extract?: boolean;
+}
+export interface ArcExtractionResult {
+    range_id: string | null;
+    turns_consumed: number;
+    status: 'extracted' | 'no_turns' | 'pipeline_failed' | 'pipeline_incomplete' | 'in_progress' | 'rate_limited' | 'min_range_too_small';
+    start_turn?: number;
+    end_turn?: number;
+    reflect_result: ReflectResult | null;
+    error?: string;
+    rate_limited_retry_after_ms?: number;
+}
+export declare function _resetArcGuardsForTests(): void;
+export declare function runArcExtraction(db: WorkspaceDB, opts: ArcExtractionOpts): Promise<ArcExtractionResult>;
+export declare function buildArcConsolidatedInput(agentId: string, turns: ConversationTurnRow[]): {
+    agentResponse: string;
+    userMessage: string;
+    agentThinking: string;
+    sceneCardFormatted: string;
+    sceneCardMerged: any;
+    items: Pass1Item[];
+};
+//# sourceMappingURL=arc-pipeline.d.ts.map

package/dist/middleware/reflect/arc-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arc-pipeline.d.ts","sourceRoot":"","sources":["../../../src/middleware/reflect/arc-pipeline.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAEhF,OAAO,KAAK,EAAE,SAAS,EAAsB,aAAa,EAA0B,MAAM,YAAY,CAAC;AAUvG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAO/D,wBAAsB,cAAc,CAAC,EAAE,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,mBAAmB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAexH;AAID,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,UAAU,GAAG,KAAK,GAAG,YAAY,GAAG,YAAY,GAAG,MAAM,CAAC;AAEvG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,gBAAgB,CAAC;IACjC,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,WAAW,GACX,UAAU,GACV,iBAAiB,GACjB,qBAAqB,GACrB,aAAa,GACb,cAAc,GACd,qBAAqB,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,aAAa,GAAG,IAAI,CAAC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2BAA2B,CAAC,EAAE,MAAM,CAAC;CACtC;AAiCD,wBAAgB,uBAAuB,IAAI,IAAI,CAG9C;AAID,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,WAAW,EACf,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,mBAAmB,CAAC,CAiV9B;AAgBD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,EAAE,GAAG;IACxF,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,GAAG,CAAC;IACrB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB,CA+DA"}