deepdebug-local-agent 1.8.0 → 1.10.0

package/src/la-protocol-v2/webhooks/handler.js

@@ -0,0 +1,125 @@
+/**
+ * handler.js - `webhook.forward` (F3-12 consumer, contract 2.1 (b)). Registered by install.js only with LOCAL_AGENT_WEBHOOK_FORWARD=true.
+ *
+ *   one frame (no `chunk`, body <= 9216 bytes)   decoded here, handed to the sink, acked after the sink returned
+ *   chunks                                       every chunk acked `accepted` as it is stored; the ack of the LAST one means "rebuilt, hash
+ *                                                verified AND delivered to the local consumer" (the CP answers the webhook only then)
+ *   refusals                                     non-fatal `rejected` acks with the wire code (chunk_out_of_order, chunk_inconsistent,
+ *                                                payload_too_large, rate_limited, schema_violation for a body that is not canonical base64);
+ *                                                the assembly is dropped. A sink that throws is `internal`; no sink = protocol_unsupported.
+ *   delivery deadline                            the final ack waits for the sink up to config.deliveryMs (default 10 s); past it the ack is
+ *                                                `rejected timeout` (the CP treats the webhook as not delivered). install.js tells the session to
+ *                                                wait for this handler, so the ack never goes out as `accepted` before the delivery happened.
+ *   resends                                      the ids delivered in the last config.dedupeMs (10 min, at most config.dedupeMax) are remembered in
+ *                                                memory with the sha256 of their body: the same id AND the same body again is acked `accepted`
+ *                                                without being processed again (a CP fallback or a retry must not inflate the detector's count). Same
+ *                                                id with another body is a new webhook. Nothing but the id and the hash is kept; nothing is logged.
+ * The body is in memory only: it is zeroed once the sink has settled (also after a timeout); nothing is written, logged or counted by content
+ * (counters by code). The sink is `async ({webhookId, source, contentType, body:Buffer}) => void`: it must finish its work with the body
+ * before it resolves.
+ */
+import crypto from "node:crypto";
+import { isCanonicalBase64, loadContract, webhookChunkSizeViolation } from "../contract.js";
+import { createWebhookAssembler } from "./assembler.js";
+
+const DEFAULT_TIMERS = { setTimeout, clearTimeout };
+
+export function createWebhookHandler({ config, getSink, now = Date.now, timers }) {
+    const limits = loadContract().limits;
+    const T = timers || DEFAULT_TIMERS;
+    const assembler = createWebhookAssembler({ limits, config, now, ...(timers ? { timers } : {}) });
+    const deliveryMs = config.deliveryMs ?? 10_000;
+    const dedupeMs = config.dedupeMs ?? 600_000;
+    const dedupeMax = config.dedupeMax ?? 1024;
+    const stats = { frames: 0, single: 0, chunks: 0, delivered: 0, refused: {}, deliveryFailed: 0, deliveryTimeouts: 0, deduped: 0 };
+    const refused = (code) => { stats.refused[code] = (stats.refused[code] || 0) + 1; return { reject: code }; };
+
+    const seen = new Map();        // webhookId -> { sha, until } (insertion order = expiry order: the window is constant)
+    const inflight = new Set();    // webhookIds whose sink has not settled yet (only matters after a timeout)
+    const prune = () => {
+        const t = now();
+        for (const [id, e] of seen) { if (e.until > t && seen.size <= dedupeMax) break; seen.delete(id); }
+    };
+    const remember = (id, sha) => { seen.delete(id); seen.set(id, { sha, until: now() + dedupeMs }); prune(); };
+    const isResend = (id, sha) => { prune(); const e = seen.get(id); return !!e && e.sha === sha; };
+
+    const resends = new Map();     // webhookId -> { next, total, sha, startedAt }: a resend of an already delivered chunked webhook in progress
+    function resendChunk(p, chunk, rs) {
+        const { index, total, last } = chunk;
+        const t = now();
+        const fail = (code) => { resends.delete(p.webhookId); return refused(code); };
+        if (rs && t - rs.startedAt >= config.assemblyMs) { resends.delete(p.webhookId); rs = undefined; }
+        if (!rs) {
+            if (index !== 0) return refused("chunk_out_of_order");
+            if (resends.size >= config.maxOpen) return refused("rate_limited");
+            rs = { next: 0, total, sha: p.bodySha256, startedAt: t };
+            resends.set(p.webhookId, rs);
+        } else if (rs.total !== total || rs.sha !== p.bodySha256) return fail("chunk_inconsistent");
+        else if (index !== rs.next) return fail("chunk_out_of_order");
+        if (last !== (index === total - 1) || webhookChunkSizeViolation(p, chunk, limits.webhookChunkRawBytes) || !isCanonicalBase64(p.bodyB64)) return fail("chunk_inconsistent");
+        rs.next = index + 1;
+        if (last) { resends.delete(p.webhookId); stats.deduped++; }
+        return { accept: true };
+    }
+
+    async function deliver(webhook, sha) {
+        const sink = getSink();
+        if (!sink) { webhook.body.fill(0); return refused("protocol_unsupported"); }
+        const id = webhook.webhookId;
+        if (inflight.has(id)) { webhook.body.fill(0); return refused("rate_limited"); }   // a timed-out attempt of this id is still running: try again later
+        inflight.add(id);
+        let timedOut = false;
+        let timer = null;
+        const work = Promise.resolve().then(() => sink(webhook));
+        // the body is zeroed when the sink settles, not before (after a timeout the sink may still be reading it)
+        work.then(() => { inflight.delete(id); if (timedOut) { stats.delivered++; remember(id, sha); } webhook.body.fill(0); },
+                  () => { inflight.delete(id); webhook.body.fill(0); });
+        const deadline = new Promise((_, reject) => {
+            timer = T.setTimeout(() => { timedOut = true; const e = new Error("local delivery deadline"); e.code = "timeout"; reject(e); }, deliveryMs);
+            if (timer && typeof timer.unref === "function") timer.unref();
+        });
+        try {
+            await Promise.race([work, deadline]);
+            stats.delivered++;
+            remember(id, sha);
+            return { accept: true };
+        } catch (e) {
+            if (timedOut) { stats.deliveryTimeouts++; return refused("timeout"); }
+            stats.deliveryFailed++;
+            return refused(e && e.code === "rate_limited" ? "rate_limited" : "internal");
+        } finally {
+            if (timer) T.clearTimeout(timer);
+        }
+    }
+
+    return {
+        stats,
+        assembler,
+        async handle(ctx) {
+            stats.frames++;
+            const p = ctx.params;
+            if (!ctx.chunk) {
+                stats.single++;
+                if (!isCanonicalBase64(p.bodyB64)) return refused("schema_violation");
+                const body = Buffer.from(p.bodyB64, "base64");
+                if (body.length > limits.webhookSingleFrameRawBytes) return refused("payload_too_large");
+                const sha = crypto.createHash("sha256").update(body).digest("hex");
+                if (isResend(p.webhookId, sha)) { stats.deduped++; body.fill(0); return { accept: true }; }
+                return deliver({ webhookId: p.webhookId, source: p.source, contentType: p.contentType, body }, sha);
+            }
+            stats.chunks++;
+            // a resend of a webhook already delivered (same id, same body hash) starts at chunk 0: every chunk of it is acked in order, nothing is
+            // stored or processed again. A chunk with index > 0 that does not belong to an assembly or to a resend in progress stays what it was:
+            // chunk_out_of_order (also for "a chunk after the last one": the contract's invalid trace).
+            if (!assembler.has(p.webhookId)) {
+                const rs = resends.get(p.webhookId);
+                if (rs || (ctx.chunk.index === 0 && isResend(p.webhookId, p.bodySha256))) return resendChunk(p, ctx.chunk, rs);
+            }
+            const r = assembler.accept({ params: p, chunk: ctx.chunk });
+            if (!r.ok) return refused(r.code);
+            if (!r.done) return { accept: true };
+            return deliver(r.webhook, p.bodySha256);
+        },
+        clear() { assembler.clear(); resends.clear(); },
+    };
+}

package/src/la-protocol-v2/webhooks/install.js

@@ -0,0 +1,22 @@
+/**
+ * install.js - puts the webhook receiver on a v2 link (F3-12 consumer). Called by runtime.js only when LOCAL_AGENT_WEBHOOK_FORWARD=true,
+ * v2 is on AND the incident detector is on (the local consumer). Returns link.webhooks = { handler, setSink(fn) }.
+ */
+import { createWebhookHandler } from "./handler.js";
+
+export const WEBHOOK_CAPABILITIES = Object.freeze(["webhook.forward", "webhook.chunked"]);
+
+export function installWebhookReceiver({ link, config }) {
+    let sink = null;
+    const handler = createWebhookHandler({ config, getSink: () => sink });
+    // the ack of the last chunk means "delivered to the local consumer": the session must wait for the handler (which has its own, shorter
+    // deadline: deliveryMs) instead of acking `accepted` after handlerAckMs (2 s). +1 s so the handler's own `rejected timeout` always wins.
+    link.session.setHandler("webhook.forward", (ctx) => handler.handle(ctx), { ackMs: (config.deliveryMs ?? 10_000) + 1_000 });
+    // a new session (not resumed) forgets the chunks of the old one: the CP restarts its numbering and its in-flight webhooks fail
+    const onReady = (e) => { if (!e.resumed) handler.clear(); };
+    link.session.on("ready", onReady);
+    const closeLink = link.close.bind(link);
+    link.close = () => { link.session.off("ready", onReady); handler.clear(); closeLink(); };
+    link.webhooks = { handler, setSink: (fn) => { sink = typeof fn === "function" ? fn : null; } };
+    return link.webhooks;
+}

package/test/contract/la-protocol-v2/vectors/ack.vectors.json

@@ -144,6 +144,97 @@
         }
       },
       "why": "agentId is required on ack/error (the gateway refuses a frame without it: agent_mismatch)"
+    },
+    {
+      "name": "llm-key-ack-accepted",
+      "why": "the LA answers a set or a revoke with the plain ack",
+      "expect": {
+        "valid": true
+      },
+      "message": {
+        "schemaVersion": 2,
+        "type": "ack",
+        "msgId": "00000000-0000-4000-8000-000000000001",
+        "seq": 0,
+        "tenantId": "3f2b8c1e-5a4d-4e7b-9c21-0a1b2c3d4e5f",
+        "workspaceId": "ws-1",
+        "ts": "2026-10-29T10:00:00Z",
+        "payload": {
+          "ackSeq": 5,
+          "status": "accepted"
+        },
+        "agentId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
+      }
+    },
+    {
+      "name": "llm-key-ack-rejected-schema-violation",
+      "why": "the LA refuses an expired key or an id that does not match: rejected + schema_violation",
+      "expect": {
+        "valid": true
+      },
+      "message": {
+        "schemaVersion": 2,
+        "type": "ack",
+        "msgId": "00000000-0000-4000-8000-000000000001",
+        "seq": 0,
+        "tenantId": "3f2b8c1e-5a4d-4e7b-9c21-0a1b2c3d4e5f",
+        "workspaceId": "ws-1",
+        "ts": "2026-10-29T10:00:00Z",
+        "payload": {
+          "ackSeq": 5,
+          "status": "rejected",
+          "errorCode": "schema_violation"
+        },
+        "agentId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
+      }
+    },
+    {
+      "name": "llm-key-ack-with-key-field",
+      "why": "an ack has no field that could carry the key",
+      "expect": {
+        "valid": false,
+        "code": "schema_violation",
+        "keyword": "additionalProperties"
+      },
+      "message": {
+        "schemaVersion": 2,
+        "type": "ack",
+        "msgId": "00000000-0000-4000-8000-000000000001",
+        "seq": 0,
+        "tenantId": "3f2b8c1e-5a4d-4e7b-9c21-0a1b2c3d4e5f",
+        "workspaceId": "ws-1",
+        "ts": "2026-10-29T10:00:00Z",
+        "payload": {
+          "ackSeq": 1,
+          "status": "accepted",
+          "key": "sk-vector-not-a-real-key-0001"
+        },
+        "agentId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
+      }
+    },
+    {
+      "name": "llm-key-ack-with-key-id-field",
+      "why": "nor the key id",
+      "expect": {
+        "valid": false,
+        "code": "schema_violation",
+        "keyword": "additionalProperties"
+      },
+      "message": {
+        "schemaVersion": 2,
+        "type": "ack",
+        "msgId": "00000000-0000-4000-8000-000000000001",
+        "seq": 0,
+        "tenantId": "3f2b8c1e-5a4d-4e7b-9c21-0a1b2c3d4e5f",
+        "workspaceId": "ws-1",
+        "ts": "2026-10-29T10:00:00Z",
+        "payload": {
+          "ackSeq": 1,
+          "status": "accepted",
+          "keyId": "6ff70dd0f5a066910d2c77d289584f4774569fb9216f4a371c0efe1968526f48"
+        },
+        "agentId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
+      }
     }
   ]
 }