aiden-runtime 4.1.4 → 4.5.0

package/dist/core/v4/loopTrace.js

@@ -0,0 +1,257 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/loopTrace.ts — Phase v4.1.5+ Path A.
+ *
+ * Env-var-gated per-turn audit log for diagnosing tool-call loops
+ * (the user-reported "30+ skill_view calls in 0ms each" failure mode
+ * from v4.1.5 visual smoke). Default OFF — adds zero overhead when
+ * `AIDEN_DEBUG_LOOP !== '1'`.
+ *
+ * When enabled, captures:
+ *   - Full tool-call sequence (name, args, timing) for the turn
+ *   - Assembled system prompt at turn start
+ *   - MEMORY.md + USER.md content hashes (sha256, first 12 hex)
+ *   - Recent skills list (last 10 `skill_view` calls)
+ *   - Conversation history snapshot (last 5 turns)
+ *
+ * Auto-writes to `<paths.logsDir>/loop-trace-{ISO-timestamp}.json` at
+ * turn end IF the turn triggered loop detection (10+ tool calls OR
+ * 5+ consecutive same-name). Quiet otherwise — non-loop turns don't
+ * spam the logs directory.
+ *
+ * A/B harness reproduction lesson: the original 30+ loop the user
+ * observed could not be reproduced with a fresh `[system, user]`
+ * history (see `scripts/smoke-prompt-bias-ab.ts` results). The loop
+ * is either stochastic gpt-5.5 behaviour, history-poisoning from
+ * prior turns, or MEMORY/USER context-specific. This logger captures
+ * the EXACT context next time the loop happens in live use so we
+ * can A/B against the real failure case.
+ *
+ * Pure module — no Display dependency, no event-emitter, no side
+ * effects beyond the gated file write. Safe to import from anywhere.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoopTracer = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+// ── Tracer ──────────────────────────────────────────────────────────────────
+const ARGS_CAP = 200;
+const HISTORY_TAIL_DEPTH = 5;
+const RECENT_SKILLS_MAX = 10;
+/**
+ * Tracks tool calls for one turn. Construct fresh per turn (the
+ * counters and recent-skills list are turn-scoped). Idempotent
+ * `finalize()` — multiple calls produce one file at most.
+ */
+class LoopTracer {
+    constructor(rawOpts) {
+        this.systemPrompt = '';
+        this.history = [];
+        this.toolStart = new Map();
+        this.sequence = [];
+        this.lastName = null;
+        this.consecSame = 0;
+        this.maxConsec = 0;
+        this.warnFired = false;
+        this.finalized = false;
+        this.recentSkills = [];
+        this.enabled = rawOpts.enabled ?? (process.env.AIDEN_DEBUG_LOOP === '1');
+        this.opts = {
+            paths: rawOpts.paths,
+            providerId: rawOpts.providerId,
+            modelId: rawOpts.modelId,
+            enabled: this.enabled,
+            toolCountThreshold: rawOpts.toolCountThreshold ?? 10,
+            consecSameThreshold: rawOpts.consecSameThreshold ?? 5,
+            warnConsecThreshold: rawOpts.warnConsecThreshold ?? 8,
+            onLoopWarning: rawOpts.onLoopWarning ?? (() => { }),
+        };
+    }
+    isEnabled() { return this.enabled; }
+    /**
+     * Set the assembled system prompt for this turn. Called once at turn
+     * start (before any tool calls). Stored verbatim; no truncation.
+     */
+    setSystemPrompt(prompt) {
+        if (!this.enabled)
+            return;
+        this.systemPrompt = prompt;
+    }
+    /**
+     * Set the turn's conversation history snapshot. The tracer keeps
+     * only the last `HISTORY_TAIL_DEPTH` messages on finalize.
+     */
+    setHistory(messages) {
+        if (!this.enabled)
+            return;
+        this.history = messages;
+    }
+    /**
+     * Record the start of a tool call. Pair with `endTool(id, name)` to
+     * capture the duration. Caller must pass a stable `id` (the tool
+     * call request id) so before/after pairs find each other.
+     */
+    startTool(id, _name) {
+        if (!this.enabled)
+            return;
+        this.toolStart.set(id, Date.now());
+    }
+    /**
+     * Record the end of a tool call. Computes duration from the matching
+     * `startTool` call. Updates consec-same counter; fires the live
+     * warning when threshold crosses.
+     */
+    endTool(id, name, args) {
+        if (!this.enabled)
+            return;
+        const start = this.toolStart.get(id);
+        this.toolStart.delete(id);
+        const durationMs = start === undefined ? 0 : (Date.now() - start);
+        let argsPreview;
+        try {
+            argsPreview = JSON.stringify(args ?? {});
+        }
+        catch {
+            argsPreview = String(args);
+        }
+        if (argsPreview.length > ARGS_CAP)
+            argsPreview = `${argsPreview.slice(0, ARGS_CAP - 1)}…`;
+        this.sequence.push({
+            name, argsPreview, durationMs,
+            ts: new Date().toISOString(),
+        });
+        // Consec-same accounting.
+        if (name === this.lastName) {
+            this.consecSame += 1;
+        }
+        else {
+            this.consecSame = 1;
+            this.lastName = name;
+        }
+        if (this.consecSame > this.maxConsec)
+            this.maxConsec = this.consecSame;
+        // Skill-view tracking (separate from sequence for quick reference).
+        if (name === 'skill_view' || name === 'lookup_tool_schema') {
+            const tk = args;
+            const target = tk?.name ?? tk?.toolName ?? '(unknown)';
+            this.recentSkills.push(target);
+            if (this.recentSkills.length > RECENT_SKILLS_MAX) {
+                this.recentSkills = this.recentSkills.slice(-RECENT_SKILLS_MAX);
+            }
+        }
+        // Live warning at the loud threshold.
+        if (!this.warnFired && this.consecSame >= this.opts.warnConsecThreshold) {
+            this.warnFired = true;
+            try {
+                this.opts.onLoopWarning(`[loop] same tool '${name}' called ${this.consecSame}× — Ctrl+C to interrupt`);
+            }
+            catch { /* defensive */ }
+        }
+    }
+    /**
+     * Compute whether a snapshot would be written if `finalize()` ran
+     * now. Useful for tests + the live warning path. Pure read.
+     */
+    shouldEmit() {
+        if (!this.enabled)
+            return false;
+        return (this.sequence.length >= this.opts.toolCountThreshold ||
+            this.maxConsec >= this.opts.consecSameThreshold);
+    }
+    /**
+     * Write the trace to disk if thresholds tripped. Idempotent —
+     * subsequent calls are no-ops. Returns the snapshot path or `null`
+     * if nothing was written.
+     */
+    async finalize() {
+        if (this.finalized)
+            return null;
+        this.finalized = true;
+        if (!this.enabled)
+            return null;
+        if (!this.shouldEmit())
+            return null;
+        const snapshot = await this.buildSnapshot();
+        const ts = snapshot.capturedAt.replace(/[:.]/g, '-');
+        const filename = `loop-trace-${ts}.json`;
+        const filePath = node_path_1.default.join(this.opts.paths.logsDir, filename);
+        try {
+            await node_fs_1.promises.mkdir(this.opts.paths.logsDir, { recursive: true });
+            await node_fs_1.promises.writeFile(filePath, JSON.stringify(snapshot, null, 2), 'utf8');
+            return filePath;
+        }
+        catch {
+            // Diagnostic logging must never break the turn. Silently swallow
+            // write failures — power user with AIDEN_DEBUG_LOOP=1 will notice
+            // missing files and can re-run with stricter perms if needed.
+            return null;
+        }
+    }
+    /** Test-accessor: synchronous read of the current consec-same state. */
+    getMaxConsecutive() { return this.maxConsec; }
+    /** Test-accessor: tool call count so far. */
+    getToolCount() { return this.sequence.length; }
+    // ── Internals ────────────────────────────────────────────────────────────
+    async buildSnapshot() {
+        const reason = this.maxConsec >= this.opts.consecSameThreshold
+            ? (this.sequence.length >= this.opts.toolCountThreshold
+                ? 'consecutive_same'
+                : 'consecutive_same')
+            : 'tool_count';
+        const memoryMdHash = await hashFileFirst12(this.opts.paths.memoryMd);
+        const userMdHash = await hashFileFirst12(this.opts.paths.userMd);
+        const historyTail = this.history.slice(-HISTORY_TAIL_DEPTH).map((m) => ({
+            role: m.role,
+            contentPreview: trunc(typeof m.content === 'string' ? m.content : JSON.stringify(m.content), 300),
+        }));
+        return {
+            schemaVersion: 1,
+            capturedAt: new Date().toISOString(),
+            reason,
+            toolCallCount: this.sequence.length,
+            maxConsecSame: this.maxConsec,
+            consecSameName: this.maxConsec >= 2 ? this.lastName : null,
+            toolSequence: this.sequence,
+            systemPrompt: this.systemPrompt,
+            memoryMdHash,
+            userMdHash,
+            recentSkills: this.recentSkills,
+            historyTail,
+            envHints: {
+                provider: this.opts.providerId,
+                model: this.opts.modelId,
+            },
+        };
+    }
+}
+exports.LoopTracer = LoopTracer;
+// ── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Read a file and return the sha256 hash, first 12 hex chars.
+ * Returns `null` if the file is missing or unreadable. Pure-async.
+ * 12 hex is enough collision resistance for context-fingerprinting
+ * without bloating the trace file with full 64-char hashes.
+ */
+async function hashFileFirst12(filePath) {
+    try {
+        const content = await node_fs_1.promises.readFile(filePath, 'utf8');
+        const hash = node_crypto_1.default.createHash('sha256').update(content).digest('hex');
+        return hash.slice(0, 12);
+    }
+    catch {
+        return null;
+    }
+}
+function trunc(s, n) {
+    return s.length <= n ? s : `${s.slice(0, n - 1)}…`;
+}