deepdebug-local-agent 1.7.0 → 1.9.0

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

@@ -32,6 +32,8 @@ const WORKSPACE_ID = /^[A-Za-z0-9_.-]{0,64}$/;
 const SHA256 = /^[0-9a-f]{64}$/;
 const CAPABILITY = /^[a-z0-9]+([._-][a-z0-9]+)*$/;
 const DEDUPE_ENTRIES = 512;
+// Contract 2.1: two stateless rules the handlers apply themselves (non-fatal `rejected` ack, state checked before size, as in the reference model)
+const DEFERRED_RULES = Object.freeze(["webhook-chunk-size", "llmKey-id-sha256"]);
 const noop = () => {};
 
 const DEFAULTS = Object.freeze({
@@ -58,6 +60,8 @@ function deepEqual(a, b) {
 }
 
 export class V2Session extends EventEmitter {
+    #peerCaps = new Set();
+
     /**
      * @param {object} o
      * @param {string} o.tenantId             lower-case UUID of the tenant (configured, never read from a payload)
@@ -66,6 +70,8 @@ export class V2Session extends EventEmitter {
      * @param {{mode:string}} o.signing       the signing config of request-signing.js (mode + trusted keys + nonce cache)
      * @param {string} o.laVersion            semver
      * @param {string[]} [o.capabilities]
+     * @param {() => string[]} [o.dynamicCapabilities] announced in addition at EVERY attach (register and hello of that attach carry the same
+     *        snapshot): what can change between connections, e.g. `llm.key.held` (contract 2.1 (e)) only while a valid key is held
      * @param {() => Array<{workspaceId:string,pathSha256?:string}>} [o.getWorkspaces]
      * @param {() => {diskFreeBytes?:number, graphify?:object}} [o.getHealth]
      * @param {{info:Function,warn:Function}} [o.log]
@@ -81,6 +87,7 @@ export class V2Session extends EventEmitter {
         this.signing = o.signing;
         this.laVersion = o.laVersion;
         this.capabilities = [...new Set(o.capabilities || [])].filter((c) => CAPABILITY.test(c) && c.length <= 48).sort();
+        this.dynamicCapabilities = typeof o.dynamicCapabilities === "function" ? o.dynamicCapabilities : null;
         this.getWorkspaces = o.getWorkspaces || (() => []);
         this.getHealth = o.getHealth || (() => ({}));
         this.log = o.log || { info: noop, warn: noop };
@@ -95,12 +102,13 @@ export class V2Session extends EventEmitter {
         this.state = STATE.IDLE;
         this.sessionId = null;        // set by `ready`
         this.everReady = false;
+        this.#peerCaps = new Set();   // what the CP announced in `ready.capabilities` (2.1); empty = a 2.0 CP
         this.sendSeq = 0;             // last LA->CP data seq assigned
         this.lastRecvSeq = 0;         // highest contiguous CP->LA data seq received
         this.recvRing = new Map();    // seq -> msgId of the last DEDUPE_ENTRIES received
         this.unacked = new Map();     // seq -> outbound record, in seq order
         this.waiters = [];            // frames waiting for a window slot (FIFO)
-        this.handlers = new Map();    // type -> fn(ctx) -> {accept:true}|{reject:code}
+        this.handlers = new Map();    // type -> { fn(ctx) -> {accept:true}|{reject:code}, ackMs }
         this.tracker = new ChunkStreamTracker(this.limits);
         this.transport = null;
         this.inbound = Promise.resolve();
@@ -114,10 +122,25 @@ export class V2Session extends EventEmitter {
 
     // ---------------------------------------------------------------------------------------- public API
 
-    /** Registers the handler of a CP->LA data type. Without one the frame is acked `rejected` (protocol_unsupported). */
-    setHandler(type, fn) {
+    /**
+     * Registers the handler of a CP->LA data type. Without one the frame is acked `rejected` (protocol_unsupported).
+     * `opts.ackMs`: how long this handler may take before the session acks `accepted` on its own (default `handlerAckMs`, 2 s). A handler whose ack
+     * MEANS something (webhook.forward: the last chunk is acked only after the local delivery) raises it and enforces its own, shorter timeout.
+     * Inbound frames are processed one at a time, so a slow handler delays the frames behind it: keep this small (the CP retransmits after 5 s).
+     */
+    setHandler(type, fn, opts = {}) {
         if (!this.contract.canReceive(type) || this.contract.typeInfo(type).control) throw new ProtocolError("unknown_type");
-        this.handlers.set(type, fn);
+        const ackMs = Number.isFinite(opts.ackMs) ? Math.min(Math.max(opts.ackMs, 1), 14_000) : null;
+        this.handlers.set(type, { fn, ackMs });
+    }
+
+    /** The capabilities of THIS attach: the static ones plus the dynamic ones, sorted, deduplicated, valid names only. */
+    #announced() {
+        let extra = [];
+        try { extra = this.dynamicCapabilities ? this.dynamicCapabilities() : []; } catch { extra = []; }
+        const all = new Set([...this.capabilities, ...(Array.isArray(extra) ? extra : [])].filter((c) => typeof c === "string" && CAPABILITY.test(c) && c.length <= 48));
+        if (!all.has("llm.key")) all.delete("llm.key.held");   // contract 2.1 (e): `llm.key.held` alone is a schema violation, so it is never sent alone
+        return [...all].sort();
     }
 
     /** A new socket is open: starts (or resumes) the handshake. */
@@ -129,10 +152,11 @@ export class V2Session extends EventEmitter {
         this.transport = transport;
         this.state = STATE.AWAIT_READY;
         for (const rec of this.unacked.values()) this.#cancelRecTimer(rec);
+        const capabilities = this.#announced();
         const payload = {
             protocol: 2,
             laVersion: this.laVersion,
-            capabilities: this.capabilities,
+            capabilities,
             signatureMode: this.signing.mode,
             workspaces: this.#workspaces(),
             ...(this.everReady && this.sessionId ? { resume: { sessionId: this.sessionId, lastRecvSeq: this.lastRecvSeq } } : {}),
@@ -141,7 +165,7 @@ export class V2Session extends EventEmitter {
         const health = this.getHealth() || {};
         const hello = {
             laVersion: this.laVersion,
-            capabilities: this.capabilities,
+            capabilities,
             signatureMode: this.signing.mode,
             clockEpochMs: this.now(),
             diskFreeBytes: Number.isSafeInteger(health.diskFreeBytes) && health.diskFreeBytes >= 0 ? health.diskFreeBytes : 0,
@@ -227,6 +251,12 @@ export class V2Session extends EventEmitter {
         this.waiters = keep;
     }
 
+    /** Did the CP announce this capability in its last `ready` (contract 2.1)? Absent = 2.0 behaviour. */
+    peerHas(capability) { return this.#peerCaps.has(capability); }
+
+    /** A copy of what the CP announced in its last `ready` (changing it changes nothing). */
+    get peerCapabilities() { return [...this.#peerCaps]; }
+
     get snapshot() {
         return { state: this.state, sessionId: this.sessionId, sendSeq: this.sendSeq, lastRecvSeq: this.lastRecvSeq,
             unacked: this.unacked.size, waiting: this.waiters.length, limits: { ...this.limits }, stats: { ...this.stats } };
@@ -392,7 +422,7 @@ export class V2Session extends EventEmitter {
         if (!isPlainObject(f)) return this.#refuse("bad_frame");
         const ref = { refSeq: Number.isSafeInteger(f.seq) && f.seq > 0 ? f.seq : undefined, refMsgId: typeof f.msgId === "string" && f.msgId.length === 36 ? f.msgId : undefined };
         // 3-4. allowlist + closed schema
-        const v = this.contract.validateFrame(f);
+        const v = this.contract.validateFrame(f, { skipRules: DEFERRED_RULES });
         if (!v.ok) return this.#refuse(v.code, ref);
         // 5-6. tenant and agent are the configured ones
         if (f.tenantId !== this.tenantId) return this.#refuse("tenant_mismatch", ref);
@@ -453,6 +483,7 @@ export class V2Session extends EventEmitter {
         };
         this.tracker.chunkRawBytes = this.limits.chunkRawBytes;
         this.tracker.maxChunks = this.limits.maxChunks;
+        this.#peerCaps = new Set(Array.isArray(p.capabilities) ? p.capabilities : []);
         this.#cancelTimer("handshake");
         if (!p.resumed) this.#resetSession();
         this.sessionId = p.sessionId;
@@ -469,7 +500,7 @@ export class V2Session extends EventEmitter {
         }
         this.#startHeartbeat();
         this.log.info(`[la-v2] ready resumed=${p.resumed} session=${p.sessionId.slice(0, 8)} peerLastSeq=${p.peerLastSeq}`);
-        this.emit("ready", { resumed: p.resumed, sessionId: p.sessionId, limits: { ...this.limits } });
+        this.emit("ready", { resumed: p.resumed, sessionId: p.sessionId, limits: { ...this.limits }, capabilities: [...this.#peerCaps] });
         this.#pump();
     }
 
@@ -514,16 +545,18 @@ export class V2Session extends EventEmitter {
         while (this.recvRing.size > DEDUPE_ENTRIES) this.recvRing.delete(this.recvRing.keys().next().value);
         if (f.ack !== undefined) this.#ackUpTo(f.ack);
 
-        const handler = this.handlers.get(f.type);
-        if (!handler) { this.#sendAck(seq, "rejected", "protocol_unsupported"); return; }
-        const ctx = Object.freeze({ type: f.type, seq, msgId, requestId: f.requestId, workspaceId: f.workspaceId, params });
+        const entry = this.handlers.get(f.type);
+        if (!entry) { this.#sendAck(seq, "rejected", "protocol_unsupported"); return; }
+        const handler = entry.fn;
+        const ackMs = entry.ackMs ?? this.opts.handlerAckMs;
+        const ctx = Object.freeze({ type: f.type, seq, msgId, requestId: f.requestId, workspaceId: f.workspaceId, params, chunk: f.chunk });
         let verdict;
         let slow;
         try {
             const run = Promise.resolve().then(() => handler(ctx));
             run.catch(noop);
-            // a handler that has not decided in handlerAckMs is acked `accepted` (it goes on in the background)
-            verdict = await Promise.race([run, new Promise((r) => { slow = this.#timer(() => r({ accept: true }), this.opts.handlerAckMs); })]);
+            // a handler that has not decided in its ackMs (default handlerAckMs) is acked `accepted` (it goes on in the background)
+            verdict = await Promise.race([run, new Promise((r) => { slow = this.#timer(() => r({ accept: true }), ackMs); })]);
         } catch {
             verdict = { reject: "internal" };
         } finally {
@@ -587,6 +620,7 @@ export class V2Session extends EventEmitter {
         this.#failAll(code);
         this.sessionId = null;
         this.everReady = false;
+        this.#peerCaps = new Set();
         this.sendSeq = 0;
         this.lastRecvSeq = 0;
         this.recvRing.clear();

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

@@ -0,0 +1,85 @@
+/**
+ * assembler.js - rebuilds a chunked `webhook.forward` in memory (F3-12 consumer, contract 2.1 (b)).
+ *
+ * The CP sends a body above 9216 bytes as chunks of exactly 16384 raw bytes (the last one is the rest), up to 64 chunks = 1 MiB. Every
+ * chunk repeats webhookId, source, contentType, bodyBytes and bodySha256. This class keeps ONE assembly per webhookId, in memory only,
+ * with the limits of the contract (index.json) and applies the rules in the order of the reference model (state first, size after):
+ *
+ *   no assembly yet           index must be 0 (chunk_out_of_order, also for "a chunk after the one flagged last": that assembly is gone)
+ *   last flag                 last must be true only on the last index (chunk_inconsistent)
+ *   size rule                 `webhook-chunk-size`: total, and the decoded size of this chunk (chunk_inconsistent)
+ *   capacity                  open assemblies <= maxOpen, buffered bytes <= maxBufferedBytes, bodyBytes <= maxBodyBytes (rate_limited | payload_too_large)
+ *   later chunks              total/source/contentType/bodyBytes/bodySha256 unchanged (chunk_inconsistent); index == next (chunk_out_of_order)
+ *   last chunk                the body has bodyBytes bytes and hashes to bodySha256 (chunk_inconsistent)
+ * Any refusal DROPS that assembly (the buffer is zeroed). An assembly older than assemblyMs without its last chunk is dropped too.
+ * Never logs, counts by content, or keeps anything after delivery: the caller gets the body once and zeroes it.
+ */
+import crypto from "node:crypto";
+import { isCanonicalBase64, webhookChunkSizeViolation } from "../contract.js";
+
+export function createWebhookAssembler({ limits, config, now = Date.now, timers = { setTimeout, clearTimeout } }) {
+    const chunkRaw = limits.webhookChunkRawBytes;
+    const open = new Map();   // webhookId -> assembly
+    const stats = { started: 0, completed: 0, expired: 0, refused: {}, bytesHeld: 0 };
+
+    function drop(id, why) {
+        const a = open.get(id);
+        if (!a) return;
+        open.delete(id);
+        if (a.timer) timers.clearTimeout(a.timer);
+        a.buffer.fill(0);
+        stats.bytesHeld -= a.buffer.length;
+        if (why === "expired") stats.expired++;
+    }
+    const refuse = (id, code) => { drop(id, "refused"); stats.refused[code] = (stats.refused[code] || 0) + 1; return { ok: false, code }; };
+
+    return {
+        stats,
+        get openCount() { return open.size; },
+        /** Is there an assembly in progress for this webhookId? */
+        has(id) { return open.has(id); },
+        /**
+         * @param {{params:object, chunk:{index:number,total:number,last:boolean}}} o params = the signed payload of the frame
+         * @returns {{ok:false, code:string} | {ok:true, done:false} | {ok:true, done:true, webhook:{webhookId:string, source:string, contentType:string, body:Buffer}}}
+         */
+        accept({ params, chunk }) {
+            const { webhookId, source, contentType, bodyBytes, bodySha256 } = params;
+            const { index, total, last } = chunk;
+            let a = open.get(webhookId);
+            if (a && now() - a.startedAt >= config.assemblyMs) { drop(webhookId, "expired"); a = undefined; }
+            if (!a) {
+                if (index !== 0) return refuse(webhookId, "chunk_out_of_order");
+                if (last !== (index === total - 1)) return refuse(webhookId, "chunk_inconsistent");
+                if (webhookChunkSizeViolation(params, chunk, chunkRaw)) return refuse(webhookId, "chunk_inconsistent");
+                if (bodyBytes > config.maxBodyBytes) return refuse(webhookId, "payload_too_large");
+                if (open.size >= config.maxOpen || stats.bytesHeld + bodyBytes > config.maxBufferedBytes) return refuse(webhookId, "rate_limited");
+                a = { total, next: 0, source, contentType, bodyBytes, bodySha256, buffer: Buffer.alloc(bodyBytes), startedAt: now(), timer: null };
+                a.timer = timers.setTimeout(() => drop(webhookId, "expired"), config.assemblyMs);
+                if (a.timer && typeof a.timer.unref === "function") a.timer.unref();
+                open.set(webhookId, a);
+                stats.bytesHeld += bodyBytes;
+                stats.started++;
+            } else {
+                if (a.total !== total || a.source !== source || a.contentType !== contentType || a.bodyBytes !== bodyBytes || a.bodySha256 !== bodySha256) return refuse(webhookId, "chunk_inconsistent");
+                if (index !== a.next) return refuse(webhookId, "chunk_out_of_order");
+                if (last !== (index === total - 1)) return refuse(webhookId, "chunk_inconsistent");
+                if (webhookChunkSizeViolation(params, chunk, chunkRaw)) return refuse(webhookId, "chunk_inconsistent");
+            }
+            if (!isCanonicalBase64(params.bodyB64)) return refuse(webhookId, "chunk_inconsistent");
+            const piece = Buffer.from(params.bodyB64, "base64");
+            piece.copy(a.buffer, index * chunkRaw);
+            a.next = index + 1;
+            if (!last) return { ok: true, done: false };
+            const digest = crypto.createHash("sha256").update(a.buffer).digest("hex");
+            if (digest !== a.bodySha256) return refuse(webhookId, "chunk_inconsistent");
+            // hand over the buffer: the assembly stops being ours (it is not zeroed here: the caller does it after delivery)
+            open.delete(webhookId);
+            if (a.timer) timers.clearTimeout(a.timer);
+            stats.bytesHeld -= a.buffer.length;
+            stats.completed++;
+            return { ok: true, done: true, webhook: { webhookId, source: a.source, contentType: a.contentType, body: a.buffer } };
+        },
+        /** Drops every assembly (a new session, shutdown). */
+        clear() { for (const id of [...open.keys()]) drop(id, "cleared"); },
+    };
+}

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

@@ -0,0 +1,51 @@
+/**
+ * config.js - LOCAL_AGENT_WEBHOOK_FORWARD flag and limits of the webhook receiver (F3-12 consumer, contract 2.1 (b)).
+ *
+ *   false (default)  `webhook.forward` keeps being acked `rejected protocol_unsupported`, the capabilities `webhook.forward` and
+ *                    `webhook.chunked` are NOT announced (so the control plane keeps its own behaviour for this agent): nothing of this
+ *                    folder is loaded.
+ *   true             the agent receives the webhook bodies the control plane strips and forwards (one frame <= 9216 bytes, or chunks of
+ *                    16 KiB up to 1 MiB), rebuilds them IN MEMORY, verifies the sha256 and hands them to the local incident detector.
+ *                    Needs LOCAL_AGENT_PROTOCOL_V2=true AND LOCAL_AGENT_INCIDENT_DETECTOR=true (the detector is the local consumer: with
+ *                    no consumer the handler is not registered and no capability is announced).
+ *
+ *   LOCAL_AGENT_WEBHOOK_DELIVERY_MS   how long the ack of a webhook (a single frame or the LAST chunk) waits for the local delivery (default 10 s,
+ *                                     max 14 s: the control plane retransmits after 5 s and gives up on a webhook at 15 s). Past it: `rejected timeout`.
+ *   LOCAL_AGENT_WEBHOOK_DEDUPE_MS / _MAX   how long (default 10 min) and how many (default 1024) delivered webhookIds are remembered in memory
+ *                                     so that a resend is acked `accepted` without being processed again.
+ *
+ * The limits default to the contract (index.json) and can only be tightened, never raised above it: a bad value falls back to the default.
+ */
+export const WEBHOOK_FLAG = "LOCAL_AGENT_WEBHOOK_FORWARD";
+
+const TRUE = new Set(["true", "1", "yes", "on"]);
+const FALSE = new Set(["", "false", "0", "no", "off"]);
+
+function int(raw, def, min, max) {
+    const n = Number.parseInt(String(raw ?? ""), 10);
+    return Number.isFinite(n) && n >= min && n <= max ? n : def;
+}
+
+/** @param {{webhookMaxBytes:number, webhookMaxChunks:number, webhookAssemblySeconds:number, webhookMaxOpenAssemblies:number}} limits the contract limits */
+export function resolveWebhookConfig(env = process.env, warn = console.warn, limits = { webhookMaxBytes: 1048576, webhookMaxChunks: 64, webhookAssemblySeconds: 30, webhookMaxOpenAssemblies: 4 }) {
+    const raw = String(env[WEBHOOK_FLAG] ?? "").trim().toLowerCase();
+    if (!TRUE.has(raw)) {
+        if (!FALSE.has(raw)) warn(`[la-webhook] unrecognised ${WEBHOOK_FLAG} value; the webhook receiver stays off`);
+        return { enabled: false };
+    }
+    const maxOpen = int(env.LOCAL_AGENT_WEBHOOK_MAX_OPEN, limits.webhookMaxOpenAssemblies, 1, limits.webhookMaxOpenAssemblies);
+    const maxBodyBytes = int(env.LOCAL_AGENT_WEBHOOK_MAX_BYTES, limits.webhookMaxBytes, 1, limits.webhookMaxBytes);
+    return {
+        enabled: true,
+        maxBodyBytes,
+        maxOpen,
+        // bytes held by assemblies in progress (the README of the contract: 4 MiB)
+        maxBufferedBytes: int(env.LOCAL_AGENT_WEBHOOK_MAX_BUFFERED_BYTES, 4 * 1024 * 1024, maxBodyBytes, 16 * 1024 * 1024),
+        assemblyMs: int(env.LOCAL_AGENT_WEBHOOK_ASSEMBLY_MS, limits.webhookAssemblySeconds * 1000, 100, limits.webhookAssemblySeconds * 1000),
+        // at most this many entries of one webhook go to the detector (an Alertmanager group can carry hundreds of alerts)
+        maxEntries: int(env.LOCAL_AGENT_WEBHOOK_MAX_ENTRIES, 200, 1, 5000),
+        deliveryMs: int(env.LOCAL_AGENT_WEBHOOK_DELIVERY_MS, 10_000, 100, 14_000),
+        dedupeMs: int(env.LOCAL_AGENT_WEBHOOK_DEDUPE_MS, 600_000, 1_000, 3_600_000),
+        dedupeMax: int(env.LOCAL_AGENT_WEBHOOK_DEDUPE_MAX, 1024, 16, 65_536),
+    };
+}

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"
+      }
     }
   ]
 }