deepdebug-local-agent 1.8.0 → 1.9.0

package/test/incident-detector/size-model.test.js

@@ -0,0 +1,127 @@
+// Contract 2.1 (c) on the detector side (F3-11b): incident.candidate carries `stackBytes` and `model` ONLY when the control plane announced
+// `incident.candidate.size-model` in ready.capabilities. Toward a 2.0 control plane the frame is exactly what it was (9 fields).
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ReferenceCp, TENANT, AGENT, waitFor } from "../la-protocol-v2/helpers/reference-cp.js";
+import { signingFor } from "../la-protocol-v2/helpers/la-rig.js";
+import { buildV2Link } from "../../src/la-protocol-v2/runtime.js";
+import { createAggregator } from "../../src/incident-detector/aggregator.js";
+import { createCandidateEmitter } from "../../src/incident-detector/emitter.js";
+import { resolveIncidentDetectorConfig } from "../../src/incident-detector/config.js";
+
+const tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), "la-size-"));
+const NINE = ["count", "environment", "errorHash", "fingerprint", "firstSeen", "lastSeen", "logCategory", "service", "severity"];
+const base = { errorHash: "a".repeat(32), fingerprint: "b".repeat(64), severity: "high", service: "svc", environment: "production", logCategory: "exception", tsMs: Date.now() };
+
+test("aggregator: stackBytes of a window is the biggest seen, saturating at 16 MiB; no stack = 0; it travels in every snapshot of the window", () => {
+    const out = [];
+    const agg = createAggregator({ windowMs: 60_000, flushMs: 0, maxTracked: 10, now: () => 1_000, onCandidate: (s) => out.push(s) });
+    agg.observe({ ...base, stackBytes: 100 });
+    agg.observe({ ...base, stackBytes: 5000 });
+    agg.observe({ ...base, stackBytes: 40 });
+    agg.observe({ ...base });                                   // no stack at all
+    assert.deepEqual(out.map((s) => s.stackBytes), [100, 5000, 5000, 5000]);
+    const big = createAggregator({ windowMs: 60_000, flushMs: 0, maxTracked: 10, now: () => 1_000, onCandidate: (s) => out.push(s) });
+    big.observe({ ...base, errorHash: "c".repeat(32), stackBytes: 2 ** 40 });
+    assert.equal(out.at(-1).stackBytes, 16 * 1024 * 1024);
+    for (const bad of [NaN, -5, Infinity, "12", null, undefined]) {
+        big.observe({ ...base, errorHash: "d".repeat(32), stackBytes: bad });
+    }
+    assert.equal(out.at(-1).stackBytes, 0);
+});
+
+function emitterFor({ caps = [], model = "stack-detector-1.8.0", snap = {} } = {}) {
+    const sent = [];
+    const session = { state: "ready", on() {}, off() {}, peerHas: (c) => caps.includes(c), async send(type, payload) { sent.push(payload); } };
+    const config = resolveIncidentDetectorConfig({ LOCAL_AGENT_INCIDENT_DETECTOR: "1", LOCAL_AGENT_INCIDENT_STORE_DIR: path.join(tmp(), "s") }, () => {});
+    const emitter = createCandidateEmitter({ session, config, model, env: {}, log: { warn() {}, info() {}, log() {} } });
+    emitter.submit({ ...base, count: 1, firstSeen: 1_000, lastSeen: 2_000, windowStart: 1_000, stackBytes: 123, ...snap });
+    return { sent, emitter };
+}
+
+test("emitter: toward a 2.0 control plane (no size-model capability) the payload is exactly the 9 fields; with it, + stackBytes and model", async () => {
+    let r = emitterFor();
+    await r.emitter.flush();
+    assert.deepEqual(Object.keys(r.sent[0]).sort(), NINE);
+    r = emitterFor({ caps: ["incident.candidate.size-model"] });
+    await r.emitter.flush();
+    assert.deepEqual(Object.keys(r.sent[0]).sort(), [...NINE, "model", "stackBytes"].sort());
+    assert.equal(r.sent[0].stackBytes, 123);
+    assert.equal(r.sent[0].model, "stack-detector-1.8.0");
+    // a capability that is not the size-model one changes nothing
+    r = emitterFor({ caps: ["something.else"] });
+    await r.emitter.flush();
+    assert.deepEqual(Object.keys(r.sent[0]).sort(), NINE);
+});
+
+test("emitter: a model label that the schema would refuse (space, slash, too long, empty) is not sent; stackBytes is clamped to 0..16 MiB", async () => {
+    for (const model of ["has space", "a/b", "x".repeat(49), "", null, "-lead"]) {
+        const r = emitterFor({ caps: ["incident.candidate.size-model"], model });
+        await r.emitter.flush();
+        assert.ok(!("model" in r.sent[0]), String(model));
+        assert.equal(r.sent[0].stackBytes, 123);
+    }
+    let r = emitterFor({ caps: ["incident.candidate.size-model"], snap: { stackBytes: 2 ** 40 } });
+    await r.emitter.flush();
+    assert.equal(r.sent[0].stackBytes, 16777216);
+    r = emitterFor({ caps: ["incident.candidate.size-model"], snap: { stackBytes: -3 } });
+    await r.emitter.flush();
+    assert.equal(r.sent[0].stackBytes, 0);
+    r = emitterFor({ caps: ["incident.candidate.size-model"], snap: { stackBytes: undefined } });
+    await r.emitter.flush();
+    assert.ok(!("stackBytes" in r.sent[0]), "no number, no field");
+});
+
+async function linkFor(cp, env, root = tmp()) {
+    const logs = [];
+    const log = { info: (m) => logs.push(m), log: (m) => logs.push(m), warn: (m) => logs.push(m), error: (m) => logs.push(m) };
+    const wsManager = { list: () => [{ id: "ws-1", root, tenantId: TENANT }] };
+    const link = await buildV2Link({ tenantId: TENANT, agentId: AGENT, signing: signingFor({ keyId: cp.keyId, publicKeyRaw: cp.publicKeyRaw }, "enforce"), wsManager, getWorkspaceRoot: () => root, log, env });
+    const transport = { send: (t) => cp.feed(t), close() {}, bufferedAmount: () => 0 };
+    cp.attach((t) => queueMicrotask(() => link.session.handleText(t, transport)), () => {});
+    link.session.attach(transport);
+    await waitFor(() => link.session.state === "ready");
+    return { link, logs };
+}
+
+for (const [label, caps] of [["a 2.1 control plane (announces size-model)", ["incident.candidate.size-model"]], ["a 2.0 control plane (announces nothing)", []]]) {
+    test(`end to end with ${label}: the candidate is closed-schema valid; stackBytes/model only with the capability; the text never on the wire`, async () => {
+        const dir = tmp(); const file = path.join(dir, "billing-api.log");
+        fs.writeFileSync(file, "");
+        const cp = new ReferenceCp({ capabilities: caps });
+        const { link } = await linkFor(cp, {
+            LOCAL_AGENT_INCIDENT_DETECTOR: "true", LOCAL_AGENT_INCIDENT_LOG_FILES: file, LOCAL_AGENT_INCIDENT_STORE_DIR: path.join(dir, "store"),
+            LOCAL_AGENT_INCIDENT_FILE_POLL_MS: "50", LOCAL_AGENT_INCIDENT_FLUSH_MS: "300", LOCAL_AGENT_DLP_MODE: "enforce",
+        });
+        try {
+            assert.equal(cp.registers[0].capabilities.includes("contract.v2.1"), true, "the LA announces it can read ready.capabilities");
+            await new Promise((r) => setTimeout(r, 120));
+            const stack = "\tat com.acme.SizeCanary.open(SizeCanary.java:44)\n\tat com.acme.Main.run(Main.java:9)";
+            fs.appendFileSync(file, `2026-11-03 10:00:00 ERROR c.a.Order : java.lang.IllegalStateException: SIZE-CANARY-1 order 1 not found\n${stack}\n2026-11-03 10:00:01 INFO nothing\n`);
+            await waitFor(() => cp.received.some((f) => f.type === "incident.candidate"), 5000);
+            assert.deepEqual(cp.errorsSent, [], "the CP's closed schema accepted every frame");
+            const p = cp.received.find((f) => f.type === "incident.candidate").payload;
+            if (caps.length) {
+                assert.deepEqual(Object.keys(p).sort(), [...NINE, "model", "stackBytes"].sort());
+                assert.equal(p.stackBytes, Buffer.byteLength(stack), "size of the stack as the source gave it");
+                assert.match(p.model, /^stack-detector-\d+\.\d+\.\d+$/);
+            } else {
+                assert.deepEqual(Object.keys(p).sort(), NINE, "identical to before 2.1");
+            }
+            const wire = cp.rawIn.join("\n");
+            for (const w of ["SIZE-CANARY-1", "SizeCanary", "SizeCanary.java"]) assert.ok(!wire.includes(w), w);
+        } finally { link.close(); }
+    });
+}
+
+test("every flag off: register/hello are byte-for-byte the baseline capabilities (no contract.v2.1, no llm.key, no webhook.*, no incident.candidate)", async () => {
+    const cp = new ReferenceCp({ capabilities: ["incident.candidate.size-model"] });
+    const { link } = await linkFor(cp, {});
+    assert.deepEqual([...cp.registers[0].capabilities].sort(), ["chunk.base64", "protocol.v2", "v1.commands"]);
+    assert.deepEqual([...cp.hellos[0].capabilities].sort(), ["chunk.base64", "protocol.v2", "v1.commands"]);
+    assert.deepEqual([...link.session.peerCapabilities], [], "a ready without capabilities (the LA did not announce contract.v2.1)");
+    link.close();
+});

package/test/la-protocol-v2/contract-v21.test.js

@@ -0,0 +1,107 @@
+// Contract 2.1 as the Local Agent applies it: the 2.1 vectors are all classified (contract.test.js runs EVERY vector; here the new ones are pinned
+// by group so a re-sync that loses them fails), the two stateless rules, the deferral of those rules to the handlers, and ready.capabilities.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ReferenceCp, waitFor } from "./helpers/reference-cp.js";
+import { inMemory } from "./helpers/la-rig.js";
+import { loadContract, semanticRules, webhookChunkSizeViolation, llmKeyIdMismatch, RULE_CODES } from "../../src/la-protocol-v2/contract.js";
+
+const contract = loadContract();
+const VECTORS = path.join(path.dirname(fileURLToPath(import.meta.url)), "../contract/la-protocol-v2/vectors");
+const load = (f) => JSON.parse(fs.readFileSync(path.join(VECTORS, f), "utf8")).vectors;
+const sha = (s) => crypto.createHash("sha256").update(Buffer.from(s, "utf8")).digest("hex");
+
+test("the copy is revision 2.1 and every 2.1 vector group is present with at least its valid and invalid cases", () => {
+    assert.equal(contract.index.revision, "2.1");
+    const groups = [
+        ["config.update", /^llm-key-/, 6, 27],       // (a): llm-key-* in config.update (the ack and register ones are checked below)
+        ["webhook.forward", /^wh-chunk-/, 9, 24],    // (b)
+        ["incident.candidate", /^candidate-/, 7, 14],// (c)
+        ["ready", /^ready-caps-/, 4, 8],             // (d)
+    ];
+    for (const [file, re, minValid, minInvalid] of groups) {
+        const vs = load(`${file}.vectors.json`).filter((v) => re.test(v.name));
+        assert.ok(vs.filter((v) => v.expect.valid).length >= minValid, `${file}: valid`);
+        assert.ok(vs.filter((v) => !v.expect.valid).length >= minInvalid, `${file}: invalid`);
+        for (const v of vs) {   // and every one is classified as declared
+            const r = contract.validateFrame(v.message);
+            assert.equal(r.ok, v.expect.valid === true, `${file} :: ${v.name}`);
+            // payload_too_large is the session-level refinement of schema_violation for a maxLength under /payload (as in contract.test.js)
+            if (!v.expect.valid) assert.ok(r.code === v.expect.code || (v.expect.code === "schema_violation" && r.code === "payload_too_large"), `${file} :: ${v.name} -> ${r.code}`);
+        }
+    }
+    assert.ok(load("register.vectors.json").some((v) => v.name === "capabilities-llm-key-and-webhook-chunked" && contract.validateFrame(v.message).ok));
+    assert.ok(load("ack.vectors.json").some((v) => v.name === "llm-key-ack-with-key-field" && !contract.validateFrame(v.message).ok), "an ack with a key field is refused by the closed schema");
+});
+
+test("rules: webhook-chunk-size -> chunk_inconsistent, llmKey-id-sha256 -> schema_violation (the codes the vectors expect), RULE_CODES is that table", () => {
+    assert.deepEqual({ ...RULE_CODES }, { "byteLength-decoded": "chunk_inconsistent", "webhook-chunk-size": "chunk_inconsistent", "llmKey-id-sha256": "schema_violation" });
+    const bad = load("webhook.forward.vectors.json").find((v) => v.name === "wh-chunk-non-last-chunk-too-short");
+    let r = contract.validateFrame(bad.message);
+    assert.deepEqual([r.ok, r.code, r.rules], [false, "chunk_inconsistent", ["webhook-chunk-size"]]);
+    const badKey = load("config.update.vectors.json").find((v) => v.name === "llm-key-key-id-differs-from-sha256-of-key");
+    r = contract.validateFrame(badKey.message);
+    assert.deepEqual([r.ok, r.code, r.rules], [false, "schema_violation", ["llmKey-id-sha256"]]);
+});
+
+test("rules: skipRules defers a rule to the caller (the session does it for the two 2.1 rules: a non-fatal rejected ack instead of a fatal error)", () => {
+    const bad = load("webhook.forward.vectors.json").find((v) => v.name === "wh-chunk-non-last-chunk-too-short");
+    assert.equal(contract.validateFrame(bad.message, { skipRules: ["webhook-chunk-size"] }).ok, true, "schema-valid: only the rule was skipped");
+    const badKey = load("config.update.vectors.json").find((v) => v.name === "llm-key-key-id-differs-from-sha256-of-key");
+    assert.equal(contract.validateFrame(badKey.message, { skipRules: ["llmKey-id-sha256"] }).ok, true);
+    assert.deepEqual(semanticRules(bad.message), ["webhook-chunk-size"]);
+    assert.deepEqual(semanticRules(bad.message, { skip: ["webhook-chunk-size"] }), []);
+});
+
+test("rule functions: webhook chunk sizes for 0, 1, 16384, 16385 and 1 MiB bodies; llmKey id", () => {
+    const b64 = (n) => Buffer.alloc(n).toString("base64");
+    const ok = (bodyBytes, index, total, n) => !webhookChunkSizeViolation({ bodyB64: b64(n), bodyBytes }, { index, total, last: index === total - 1 });
+    assert.ok(ok(0, 0, 1, 0), "an empty body is one empty chunk");
+    assert.ok(ok(1, 0, 1, 1));
+    assert.ok(ok(16384, 0, 1, 16384));
+    assert.ok(ok(16385, 0, 2, 16384) && ok(16385, 1, 2, 1));
+    assert.ok(!ok(16385, 0, 1, 16385), "16385 bytes in one chunk is over the chunk size");
+    assert.ok(!ok(16385, 0, 3, 16384), "wrong total");
+    assert.ok(ok(1048576, 63, 64, 16384));
+    assert.ok(!ok(100, 1, 1, 100), "index beyond total");
+    assert.equal(webhookChunkSizeViolation({ bodyB64: "AAA", bodyBytes: 2 }, { index: 0, total: 1, last: true }), true, "non-canonical base64");
+    assert.equal(llmKeyIdMismatch({ op: "set", key: "k".repeat(20), keyId: sha("k".repeat(20)) }), false);
+    assert.equal(llmKeyIdMismatch({ op: "set", key: "k".repeat(20), keyId: sha("x") }), true);
+    assert.equal(llmKeyIdMismatch({ op: "revoke", keyId: sha("x") }), false);
+    assert.equal(llmKeyIdMismatch(undefined), false);
+});
+
+test("session: ready.capabilities is kept (peerHas, a read-only copy), announced in the `ready` event, empty for a 2.0 control plane", async () => {
+    // a CP that announces something, to an LA that announced contract.v2.1
+    const cp = new ReferenceCp({ capabilities: ["incident.candidate.size-model", "x.other"] });
+    const env = inMemory(cp, { sessionOptions: { capabilities: ["protocol.v2", "contract.v2.1"] } });
+    let ev = null;
+    env.session.on("ready", (e) => { ev = e; });
+    env.start();
+    await waitFor(() => env.session.state === "ready");
+    assert.equal(env.session.peerHas("incident.candidate.size-model"), true);
+    assert.equal(env.session.peerHas("nope"), false);
+    assert.deepEqual(ev.capabilities.sort(), ["incident.candidate.size-model", "x.other"]);
+    env.session.peerCapabilities.push("hack");   // a copy: it changes nothing
+    assert.equal(env.session.peerHas("hack"), false);
+    env.session.close();
+});
+
+test("session: toward a 2.0 control plane (no capabilities in ready) peerHas is false for everything; an LA that did NOT announce contract.v2.1 never gets the field", async () => {
+    const cp = new ReferenceCp();
+    const env = inMemory(cp).start();
+    await waitFor(() => env.session.state === "ready");
+    assert.equal(env.session.peerHas("incident.candidate.size-model"), false);
+    env.session.close();
+    // the CP has capabilities but this LA did not announce contract.v2.1: the reference CP (like the gateway) sends the 2.0 ready
+    const cp2 = new ReferenceCp({ capabilities: ["incident.candidate.size-model"] });
+    const env2 = inMemory(cp2).start();
+    await waitFor(() => env2.session.state === "ready");
+    assert.equal(env2.session.peerHas("incident.candidate.size-model"), false);
+    assert.ok(!("capabilities" in JSON.parse(env2.wire.toLa[0]).payload));
+    env2.session.close();
+});

package/test/la-protocol-v2/contract.test.js

@@ -82,10 +82,10 @@ for (const file of vectorFiles) {
     }
 }
 
-test("vectors: counts (176 frames = 34 valid + 142 invalid in this copy, plus the bodies of file.list)", () => {
-    assert.equal(valid + invalid, 176);
-    assert.equal(valid, 34);
-    assert.equal(invalid, 142);
+test("vectors: counts (294 frames = 67 valid + 227 invalid in this copy (contract 2.1), plus the bodies of file.list)", () => {
+    assert.equal(valid + invalid, 294);
+    assert.equal(valid, 67);
+    assert.equal(invalid, 227);
     assert.equal(bodyVectors, 54, "file.list.body.vectors.json (F3-07c): 54 bodies");
 });
 
@@ -120,7 +120,9 @@ test("limits come from index.json and are the documented ones", () => {
     assert.deepEqual({ ...contract.limits }, {
         maxFrameBytes: 49152, chunkRawBytes: 32768, maxChunks: 64, maxContentBytes: 2097152, maxRetries: 3, ackTimeoutMs: 5000,
         handshakeTimeoutMs: 10000, heartbeatSeconds: 30, sessionDeadSeconds: 90, dedupeWindowSeconds: 600, clockSkewSeconds: 60,
+        webhookChunkRawBytes: 16384, webhookMaxChunks: 64, webhookMaxBytes: 1048576, webhookSingleFrameRawBytes: 9216, webhookAssemblySeconds: 30, webhookMaxOpenAssemblies: 4,
     });
+    assert.equal(contract.index.revision, "2.1");
 });
 
 // ------------------------------------------------------------------------------------------------ strict JSON

package/test/la-protocol-v2/helpers/reference-cp.js

@@ -26,12 +26,13 @@ const DEFAULT_LIMITS = { maxFrameBytes: 49152, chunkRawBytes: 32768, maxChunks:
 
 export class ReferenceCp {
     constructor({ tenantId = TENANT, agentId = AGENT, privateKey, publicKeyRaw, keyId = "vh-cp-test", requireEnforce = false,
-        now = Date.now, limits = {}, workspaceId = "", skewSeconds = 60 } = {}) {
+        now = Date.now, limits = {}, workspaceId = "", skewSeconds = 60, capabilities = [] } = {}) {
         this.publicKeyRaw = publicKeyRaw;
         this.contract = loadContract();
         if (!privateKey) ({ privateKey, publicKeyRaw: this.publicKeyRaw } = newKeyPair());
         Object.assign(this, { tenantId, agentId, privateKey, keyId, requireEnforce, now, skewSeconds, workspaceId });
         this.limits = { ...DEFAULT_LIMITS, ...limits };
+        this.capabilities = capabilities;   // contract 2.1: what this CP announces in ready.capabilities (only to an LA that announced contract.v2.1)
         this.sessionId = uuid();
         this.laSeq = 0; this.cpSeq = 0;
         this.ring = new Map();
@@ -223,7 +224,9 @@ export class ReferenceCp {
 
     #sendReady(resumed) {
         const f = this.#envelope("ready", 0, null, this.workspaceId);
-        this.#sign(f, "ready", { protocol: 2, sessionId: this.sessionId, resumed, peerLastSeq: this.laSeq, limits: { ...this.limits } }, this.workspaceId);
+        const announced = (this.registers.at(-1) || {}).capabilities || [];
+        const caps = this.capabilities.length > 0 && announced.includes("contract.v2.1") ? { capabilities: [...this.capabilities] } : {};
+        this.#sign(f, "ready", { protocol: 2, sessionId: this.sessionId, resumed, peerLastSeq: this.laSeq, limits: { ...this.limits }, ...caps }, this.workspaceId);
         this.sendFn(JSON.stringify(f));
     }
 
@@ -240,9 +243,9 @@ export class ReferenceCp {
     }
 
     /** Sends a CP->LA data frame (job.assign, content.request, ...). Retransmitted (re-signed) until acked. */
-    sendData(type, payload, { workspaceId = this.workspaceId, requestId } = {}) {
+    sendData(type, payload, { workspaceId = this.workspaceId, requestId, chunk } = {}) {
         const seq = ++this.cpSeq;
-        const u = { seq, type, payload, workspaceId, requestId, msgId: uuid(), retries: 0, timer: null };
+        const u = { seq, type, payload, workspaceId, requestId, chunk, msgId: uuid(), retries: 0, timer: null };
         this.unacked.set(seq, u);
         this.#transmit(u);
         return seq;
@@ -250,6 +253,7 @@ export class ReferenceCp {
 
     #transmit(u) {
         const f = this.#envelope(u.type, u.seq, u.requestId, u.workspaceId);
+        if (u.chunk) f.chunk = u.chunk;
         f.msgId = u.msgId;
         if (this.laSeq > 0) f.ack = this.laSeq;
         this.#sign(f, u.type, u.payload, u.workspaceId);