deepdebug-local-agent 1.7.0 → 1.8.0

package/src/incident-detector/store.js

@@ -0,0 +1,119 @@
+/**
+ * store.js - the local detail store of detected errors (F3-11b). The TEXT of an error (message, stack trace) lives here and
+ * nowhere else: the control plane only ever gets metadata.
+ *
+ *   file        <storeDir>/incident-detail.jsonl, one JSON object per line, dir 0700 / file 0600, append only
+ *   rotation    at storeMaxBytes the file moves to incident-detail.jsonl.1 (one generation): disk use <= 2 x storeMaxBytes
+ *   record      {v, ts, errorHash, fingerprint, service, severity, windowStart, message, stack, stackBytes, truncated}
+ *               message/stack are masked by the DLP (when DLP is on) and cut to storeMessageChars/storeStackChars
+ *   sampling    samplesPerWindow records per errorHash and window (the count is in the candidate, not in this file)
+ *   queue       at most storeMaxQueue writes waiting; add() resolves when the record is queued OR dropped (never blocks the caller
+ *               for more than the queue allows: when full it waits for room, which slows the reading of the sources = backpressure)
+ *   getDetail   (errorHash, {limit}) reads the newest records back: this is the hook for `content.request` kind `incident.detail`
+ *               (F3-07 handler, NOT wired here: the contract/gateway kind and its ref scheme are not defined yet, see README.md)
+ *   never       logs a path, a message or a stack: counters only. A broken disk disables the store, not the detector.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { protectEgress } from "../dlp/index.js";
+
+const FILE = "incident-detail.jsonl";
+const cut = (s, n) => (typeof s === "string" && s.length > n ? s.slice(0, n) : s);
+
+export function createDetailStore({ dir, maxBytes, maxQueue, messageChars, stackChars, samplesPerWindow, env = process.env, now = Date.now }) {
+    const file = path.join(dir, FILE);
+    const stats = { written: 0, sampledOut: 0, dropped: 0, errors: 0, rotations: 0, redactions: 0, dlpDenied: 0 };
+    const samples = new Map();   // `${errorHash}|${windowStart}` -> records written
+    let queue = [];
+    let size = null;
+    let broken = false;
+    let writing = null;
+    let waiters = [];
+
+    async function ensure() {
+        if (size !== null) return;
+        await fs.promises.mkdir(dir, { recursive: true, mode: 0o700 });
+        size = await fs.promises.stat(file).then((s) => s.size, () => 0);
+    }
+
+    async function drain() {
+        try {
+            await ensure();
+            while (queue.length) {
+                const batch = queue;
+                queue = [];
+                const lines = batch.map((r) => JSON.stringify(r) + "\n");
+                const bytes = lines.reduce((n, l) => n + Buffer.byteLength(l), 0);
+                if (size > 0 && size + bytes > maxBytes) {
+                    await fs.promises.rename(file, `${file}.1`).catch(() => {});
+                    size = 0;
+                    stats.rotations++;
+                }
+                await fs.promises.appendFile(file, lines.join(""), { mode: 0o600 });
+                size += bytes;
+                stats.written += batch.length;
+                const w = waiters; waiters = []; for (const f of w) f();
+            }
+        } catch {
+            broken = true;      // disk full, permissions...: the detector keeps going without a store
+            stats.errors++;
+            stats.dropped += queue.length;
+            queue = [];
+        } finally {
+            writing = null;
+            const w = waiters; waiters = []; for (const f of w) f();
+        }
+    }
+
+    const mask = (text) => {
+        if (typeof text !== "string" || text === "") return text;
+        const r = protectEgress(text, { env, source: "incident-store" });
+        if (r.denied) { stats.dlpDenied++; return "[DLP_DENIED]"; }
+        if (r.total) stats.redactions += r.total;
+        return r.text;
+    };
+
+    return {
+        stats,
+        get broken() { return broken; },
+        get queued() { return queue.length; },
+        /** @returns {Promise<boolean>} true = queued. */
+        async add({ errorHash, fingerprint, service, severity, windowStart, message, stack }) {
+            if (broken) { stats.dropped++; return false; }
+            const key = `${errorHash}|${windowStart}`;
+            const n = samples.get(key) || 0;
+            if (n >= samplesPerWindow) { stats.sampledOut++; return false; }
+            if (samples.size > 50_000) samples.clear();   // bounded: a reset only lets a few extra samples through
+            samples.set(key, n + 1);
+            while (queue.length >= maxQueue && !broken) await new Promise((res) => { waiters.push(res); if (!writing) writing = drain(); });
+            if (broken) { stats.dropped++; return false; }
+            const m = typeof message === "string" ? message : "";
+            const st = typeof stack === "string" ? stack : "";
+            queue.push({
+                v: 1, ts: new Date(now()).toISOString(), errorHash, fingerprint, service, severity, windowStart,
+                message: mask(cut(m, messageChars)), stack: st ? mask(cut(st, stackChars)) : null,
+                stackBytes: Buffer.byteLength(st), truncated: m.length > messageChars || st.length > stackChars,
+            });
+            if (!writing) writing = drain();
+            return true;
+        },
+        /** Newest first. Reads both generations; a bad line is skipped. */
+        async getDetail(errorHash, { limit = 5 } = {}) {
+            if (writing) await writing;
+            const out = [];
+            for (const f of [file, `${file}.1`]) {
+                let text;
+                try { text = await fs.promises.readFile(f, "utf8"); } catch { continue; }
+                const lines = text.split("\n");
+                for (let i = lines.length - 1; i >= 0 && out.length < limit; i--) {
+                    if (!lines[i].includes(errorHash)) continue;
+                    try { const r = JSON.parse(lines[i]); if (r.errorHash === errorHash) out.push(r); } catch { /* skip */ }
+                }
+                if (out.length >= limit) break;
+            }
+            return out;
+        },
+        /** Waits until everything queued is on disk (tests, shutdown). */
+        async flush() { if (!writing && queue.length) writing = drain(); if (writing) await writing; },
+    };
+}

package/src/la-protocol-v2/runtime.js

@@ -56,6 +56,11 @@ export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWo
         }
     }
     const contentCaps = contentCfg.enabled ? ["content.diff", "content.file", "content.file.list"] : []; // content.file.list: F3-07c, how the front finds out what exists (the gateway only sends file.list to agents that announce it)
+    // F3-11b: incident detector (logs -> incident.candidate, metadata only), behind LOCAL_AGENT_INCIDENT_DETECTOR (default off: nothing below changes anything)
+    const { resolveIncidentDetectorConfig } = await import("../incident-detector/config.js");
+    const incidentCfg = resolveIncidentDetectorConfig(env, (m) => log.warn(m));
+    const hasIncidentSource = incidentCfg.enabled && (incidentCfg.files.length > 0 || incidentCfg.stdin || !!incidentCfg.loki);
+    const incidentCaps = hasIncidentSource ? ["incident.candidate"] : [];
     const link = createV2Link({
         log,
         sessionOptions: {
@@ -65,7 +70,7 @@ export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWo
             signing,
             laVersion: agentVersion(),
             // only what this build implements: the transport, the handshake and the v1 commands on the same connection
-            capabilities: ["protocol.v2", "v1.commands", "chunk.base64", ...contentCaps],
+            capabilities: ["protocol.v2", "v1.commands", "chunk.base64", ...contentCaps, ...incidentCaps],
             getWorkspaces: () => {
                 const open = (wsManager?.list?.() || []).map((w) => ({
                     workspaceId: String(w.id || ""),
@@ -87,5 +92,9 @@ export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWo
         const { installContentHandlers } = await import("./content-handlers/install.js");
         installContentHandlers({ link, tenantId: tenant, wsManager, getWorkspaceRoot, config: contentCfg, env, log });
     }
+    if (incidentCfg.enabled) {
+        const { installIncidentDetector } = await import("../incident-detector/index.js");
+        installIncidentDetector({ link, workspaceId: WORKSPACE_ID.test(identityWs) ? identityWs : "", config: incidentCfg, env, log });
+    }
     return link;
 }

package/test/incident-detector/parity.test.js

@@ -0,0 +1,66 @@
+/**
+ * F3-11b: the Node detector against vectors generated from the Java code (scripts/incident-parity/gen.sh).
+ * Every field of every case must match byte for byte: errorHash (group hash), group key, fingerprint, errorType, first user
+ * frame, normalised message/frame, significance, noise class; and the natural-key dedup (LogEntryDedup).
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+    computeGroupHash, normalizeGroupKey, computeFingerprint, extractErrorType, extractFirstUserFrame, normaliseMessage, normaliseFrame,
+    isSignificant, classifyNoise, naturalKey,
+} from "../../src/incident-detector/normalize.js";
+
+const VECTORS = JSON.parse(fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "parity.vectors.json"), "utf8"));
+const nl = (v) => (v === undefined ? null : v);
+
+test("the vector file says where it came from and is big enough to mean something", () => {
+    assert.equal(VECTORS.schema, "incident-parity-vectors/1");
+    assert.match(VECTORS.source.commit, /^[0-9a-f]{40}$/);
+    assert.ok(Object.keys(VECTORS.source.files).length >= 5);
+    assert.ok(VECTORS.cases.length >= 100, `${VECTORS.cases.length} cases`);
+    assert.ok(VECTORS.dedup.length >= 5);
+});
+
+for (const c of VECTORS.cases) {
+    test(`parity: ${c.name}`, () => {
+        const e = c.expect;
+        const message = nl(c.message);
+        const stack = nl(c.stack);
+        assert.equal(isSignificant({ severity: c.severity, message, stacktrace: stack }), e.significant, "significant");
+        assert.equal(normalizeGroupKey(message == null ? "" : message.split("\n")[0]), e.groupKey, "groupKey");
+        assert.equal(computeGroupHash(message), e.groupHash, "errorHash");
+        assert.equal(extractErrorType(message, stack), e.errorType, "errorType");
+        assert.equal(extractFirstUserFrame(stack), e.firstFrame, "firstFrame");
+        assert.equal(normaliseMessage(message), e.normalisedMessage, "normalisedMessage");
+        assert.equal(normaliseFrame(e.firstFrame), e.normalisedFrame, "normalisedFrame");
+        assert.equal(computeFingerprint(message, stack), e.fingerprint, "fingerprint");
+        assert.equal(classifyNoise(message), e.noiseClass, "noiseClass");
+    });
+}
+
+for (const d of VECTORS.dedup) {
+    test(`parity dedup: ${d.name}`, () => {
+        const nanos = (iso) => {
+            if (iso == null) return null;
+            const m = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d{1,9}))?Z$/.exec(iso);
+            assert.ok(m, iso);
+            return BigInt(Date.parse(`${m[1]}Z`)) * 1_000_000n + BigInt((m[2] || "").padEnd(9, "0"));
+        };
+        const keys = d.entries.map((x) => naturalKey(x.service, nanos(x.ts), x.message));
+        assert.deepEqual(keys, d.keys, "natural keys");
+        // filterNew: drop what is known or repeated inside the batch; an entry without a key is always kept
+        const known = new Set(d.known);
+        const seen = new Set();
+        const kept = [];
+        keys.forEach((k, i) => {
+            if (k == null) { kept.push(i); return; }
+            if (known.has(k) || seen.has(k)) return;
+            seen.add(k);
+            kept.push(i);
+        });
+        assert.deepEqual(kept, d.kept, "kept entries");
+    });
+}