deepdebug-local-agent 1.8.0 → 1.9.0

package/.claude/context.md

@@ -15,7 +15,8 @@ Cloud Run service (`deepdebug-local-agent-qa` / `deepdebug-local-agent`) for the
 variant.
 
 **Does not:** call LLMs or hold provider keys (the thinking happens in vh-agents via
-vh-litellm), decide tenant policy, or merge anything.
+vh-litellm). The one exception, behind `LOCAL_AGENT_LLM_KEY` (default off): the VIRTUAL key of the AI
+gateway delivered by `config.update` (F3-09), kept in memory or a 0600 file, never logged; there is no LLM client yet, decide tenant policy, or merge anything.
 
 ## Neighbours
 

package/CLAUDE.md

@@ -7,7 +7,7 @@
    layers, simplicity, testing, review checklist, `node.md`).
 3. `README.md`: features, legacy connectors, configuration.
 
-Non-negotiables: no LLM calls and no provider keys here; exec with argument arrays only;
+Non-negotiables: no LLM calls and no provider keys here (the one exception, approved by Edu 2026-11-03, is the VIRTUAL key of the AI gateway delivered by `config.update`, F3-09, `client` tenants only: flag `LOCAL_AGENT_LLM_KEY`, memory by default and a 0600 file in a 0700 dir only with `LOCAL_AGENT_LLM_KEY_FILE`, never in logs or acks; there is still no LLM client); exec with argument arrays only;
 paths confined to the workspace; never log secrets or raw customer log payloads beyond
 what an incident needs; PRs target `main` (merging publishes the npm package).
 Personal, uncommitted notes go in `CLAUDE.local.md` (gitignored).

package/docs/la-protocol-v2.md

@@ -146,10 +146,27 @@ the same rules as the Java monitor (errorHash, fingerprint, significance, noise;
 (9 metadata fields, no text) per errorHash window. Announces the capability `incident.candidate`. The detail stays in a local JSONL store (0600, DLP-masked).
 Needs `LOCAL_AGENT_PROTOCOL_V2=true`. Details, limits and hooks: `src/incident-detector/README.md`. The `incident.detail` content kind is NOT served yet.
 
+## Contract 2.1 consumers (F3-09 / F3-12 / F3-11b, flags default false)
+
+The contract copy is revision 2.1 (`src/la-protocol-v2/contract/CONTRACT_SOURCE.json` names the gateway commit and branch). With every flag off the agent announces exactly what it
+announced before (`protocol.v2 v1.commands chunk.base64`); `contract.v2.1` is announced only when one of the three features below is on.
+- **LLM key** (`LOCAL_AGENT_LLM_KEY`, capability `llm.key`; `src/la-protocol-v2/llm-key/`): `config.update.llmKey` `set` / `revoke`. The virtual key of the AI gateway is held in a
+  private field (memory) or, with `LOCAL_AGENT_LLM_KEY_FILE`, in a 0600 file outside every workspace; it is never in an ack, a log, the audit or a frame. A key whose id is not the
+  sha256 of the key, or that has expired, is `rejected schema_violation`. There is NO LLM client in the agent: `link.llm.request(path, init)` is the hook (https endpoint of the control
+  plane, Authorization set by the holder, redirects refused) and nothing calls it yet. Memory by default; the file only with `LOCAL_AGENT_LLM_KEY_FILE` (file 0600, directory 0700;
+  exception to "no keys here" approved by Edu 2026-11-03, recorded in `CLAUDE.md`). `llm.key.held` (contract 2.1 (e)): at EVERY connect the agent adds this capability to `register` AND `hello`
+  only while the holder has a valid, unexpired key (never without `llm.key`); a revoked or expired key stops being announced on the next connection, so the control plane delivers a new one.
+- **Webhooks** (`LOCAL_AGENT_WEBHOOK_FORWARD`, capabilities `webhook.forward` + `webhook.chunked`; `src/la-protocol-v2/webhooks/`): one frame (<= 9216 bytes) or chunks (16 KiB, <= 64, <= 1 MiB)
+  rebuilt IN MEMORY with the contract limits (30 s, 4 assemblies, 4 MiB), sha256 verified, handed to the incident detector (`src/incident-detector/sources/webhook-source.js`, then the
+  same pipeline and the DLP-masked local store). The ack of the last chunk (or of the single frame) is sent only after the local delivery finished, waiting up to `LOCAL_AGENT_WEBHOOK_DELIVERY_MS`
+  (default 10 s, max 14 s; the session does not ack `accepted` after 2 s for this type); past it the ack is `rejected timeout`. Delivered ids (+ sha256 of the body) are remembered in memory for 10 min (max 1024):
+  a resend (same id and body) is acked `accepted`, chunk by chunk, without being processed again, so the detector's count is not inflated. Needs `LOCAL_AGENT_INCIDENT_DETECTOR=true`.
+- **Candidate size and model** (no new flag, part of `LOCAL_AGENT_INCIDENT_DETECTOR`): `incident.candidate` carries `stackBytes` and `model` only if `ready.capabilities` listed `incident.candidate.size-model`.
+
 ## Tests
 
-`npm test` (node:test). The incident detector (F3-11b) is in `test/incident-detector/` (`parity.test.js` against `parity.vectors.json`, `units`, `sources`, `wiring`); the rest of v2 in `test/la-protocol-v2/`:
-`contract.test.js` (all 176 frame vectors of F3-22, valid and invalid, the 54 `file.list` body vectors, plus the drift check), `traces.test.js` (the 26
+`npm test` (node:test). Contract 2.1: `contract-v21.test.js`, `webhook-receiver.test.js` (assembler, handler, the 8 traces, end to end), `llm-key.test.js` (including the sweep for the key), `test/incident-detector/size-model.test.js`. The incident detector (F3-11b) is in `test/incident-detector/` (`parity.test.js` against `parity.vectors.json`, `units`, `sources`, `wiring`); the rest of v2 in `test/la-protocol-v2/`:
+`contract.test.js` (all 294 frame vectors of F3-22 + 2.1, valid and invalid, the 54 `file.list` body vectors, plus the drift check), `traces.test.js` (the 34
 traces), `session-inbound.test.js`, `session-outbound.test.js`, `link.test.js`, `tunnel-e2e.test.js` (the real
 `src/server.js` against a reference CP; flag off = v1 frames), and for F3-07 `content-path-guard.test.js`,
 `content-handlers.test.js`, `content-wiring.test.js` (flag, runtime wiring, real `src/server.js`), and for F3-07b

package/env.example

@@ -92,4 +92,9 @@ LOG_LEVEL=info
 # LOCAL_AGENT_INCIDENT_STDIN=true      read log lines from the agent's own stdin
 # LOCAL_AGENT_INCIDENT_STORE_DIR=~/.deepdebug/incidents   LOCAL_AGENT_INCIDENT_WINDOW_MS=300000   LOCAL_AGENT_INCIDENT_FLUSH_MS=30000
 # LOCAL_AGENT_INCIDENT_MAX_EMITS_PER_MINUTE=60   LOCAL_AGENT_INCIDENT_MAX_PENDING=500   LOCAL_AGENT_INCIDENT_MAX_TRACKED=5000
+# LOCAL_AGENT_WEBHOOK_FORWARD=true     receives the webhook bodies the control plane strips and forwards (webhook.forward, one frame <= 9216 bytes or chunks up to 1 MiB),
+#                                      rebuilds them in memory, verifies the sha256 and hands them to the incident detector. Needs LOCAL_AGENT_PROTOCOL_V2=true AND
+#                                      LOCAL_AGENT_INCIDENT_DETECTOR=true (the local consumer). Tighten only: LOCAL_AGENT_WEBHOOK_MAX_BYTES, _MAX_OPEN, _MAX_BUFFERED_BYTES, _ASSEMBLY_MS, _MAX_ENTRIES. LOCAL_AGENT_WEBHOOK_DELIVERY_MS (default 10000, max 14000: how long the final ack waits for the local delivery), _DEDUPE_MS (600000) and _DEDUPE_MAX (1024): resends of a delivered webhookId are acked without reprocessing
+# LOCAL_AGENT_LLM_KEY=true             accepts the virtual key of the AI gateway (config.update llmKey): in memory only, never logged or returned in an ack. Needs LOCAL_AGENT_PROTOCOL_V2=true
+# LOCAL_AGENT_LLM_KEY_FILE=/var/lib/deepdebug/llm-key.json   optional: keep the key across restarts (mode 0600, directory 0700, MUST be outside every workspace)
 # LOCAL_AGENT_CONTENT_DENY_GLOBS=a/,*.x      extra deny globs (they add to the built-in list: .env*, keys, credentials files, secrets/ ...)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepdebug-local-agent",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "DeepDebug Local Agent - AI-powered code debugging assistant",
   "private": false,
   "type": "module",

package/src/incident-detector/README.md

@@ -26,7 +26,8 @@ Flag: `LOCAL_AGENT_INCIDENT_DETECTOR=true` (default **false**; needs `LOCAL_AGEN
 
 Out: `errorHash` (32 hex = sha256 prefix of the normalised FIRST line, Java `computeGroupHash`), `fingerprint` (64 hex, Java
 `IncidentFingerprintGenerator`), `severity`, `service`, `environment`, `count`, `firstSeen`, `lastSeen` (the window), `logCategory`.
-The contract has no field for the stack size or for text: the size is in the local store (`stackBytes`).
+Contract 2.1 adds two optional numbers/labels, sent ONLY when the CP listed `incident.candidate.size-model` in `ready.capabilities`: `stackBytes` (UTF-8 size of the biggest stack of the window,
+saturating at 16 MiB) and `model` (`stack-detector-<agent version>`). There is still no field for text. The size is also in the local store (`stackBytes`).
 Stays: message, stack, everything else, in `LOCAL_AGENT_INCIDENT_STORE_DIR` (default `~/.deepdebug/incidents`).
 
 ## Window semantics (for the control plane, F3-11c)

package/src/incident-detector/aggregator.js

@@ -12,17 +12,20 @@
  *   bounds     at most `maxTracked` hashes at once. Beyond it the least recently seen one is closed (final update if it has one
  *              pending) and counted as evicted. A hash that comes back after its window closed opens a new window.
  *   severity   the highest seen in the window. fingerprint/service/logCategory: those of the first occurrence.
+ *   stackBytes the biggest stack (UTF-8 bytes) seen in the window, saturating at 16 MiB (contract 2.1 (c)); 0 = no stack.
  * Pure: no timers, no I/O. The detector calls tick() on an interval.
  */
 import { maxSeverity } from "./categorize.js";
 
+const MAX_STACK_BYTES = 16 * 1024 * 1024;   // contract 2.1: incident.candidate.stackBytes saturates here
+
 export function createAggregator({ windowMs, flushMs, maxTracked, now = Date.now, onCandidate }) {
     const states = new Map();   // errorHash -> state (insertion order = least recently seen first)
     const stats = { observed: 0, windows: 0, emitted: 0, evicted: 0 };
 
     const snapshot = (s) => ({
         errorHash: s.errorHash, fingerprint: s.fingerprint, severity: s.severity, service: s.service, environment: s.environment,
-        count: s.count, firstSeen: s.firstSeen, lastSeen: s.lastSeen, logCategory: s.logCategory, windowStart: s.windowStart,
+        count: s.count, firstSeen: s.firstSeen, lastSeen: s.lastSeen, logCategory: s.logCategory, windowStart: s.windowStart, stackBytes: s.stackBytes,
     });
     const send = (s, t) => { s.sentCount = s.count; s.lastEmitAt = t; stats.emitted++; onCandidate(snapshot(s)); };
     const close = (s, t) => { states.delete(s.errorHash); if (s.count > s.sentCount) send(s, t); };
@@ -31,7 +34,8 @@ export function createAggregator({ windowMs, flushMs, maxTracked, now = Date.now
         stats,
         get tracked() { return states.size; },
         /** @returns {{opened: boolean, windowStart: number}} opened = this occurrence opened a new window. */
-        observe({ errorHash, fingerprint, severity, service, environment, logCategory, tsMs }) {
+        observe({ errorHash, fingerprint, severity, service, environment, logCategory, tsMs, stackBytes = 0 }) {
+            const size = Number.isFinite(stackBytes) && stackBytes > 0 ? Math.min(Math.trunc(stackBytes), MAX_STACK_BYTES) : 0;
             const t = now();
             stats.observed++;
             const seenAt = Number.isFinite(tsMs) && tsMs >= 0 ? Math.min(tsMs, t) : t;   // never in the future, never before the epoch (the log line is untrusted)
@@ -43,7 +47,7 @@ export function createAggregator({ windowMs, flushMs, maxTracked, now = Date.now
                     stats.evicted++;
                     close(oldest, t);
                 }
-                s = { errorHash, fingerprint, severity, service, environment, logCategory, count: 0, sentCount: 0, firstSeen: seenAt, lastSeen: seenAt, windowStart: t, lastEmitAt: 0 };
+                s = { errorHash, fingerprint, severity, service, environment, logCategory, count: 0, sentCount: 0, stackBytes: size, firstSeen: seenAt, lastSeen: seenAt, windowStart: t, lastEmitAt: 0 };
                 stats.windows++;
                 s.count = 1;
                 states.set(errorHash, s);
@@ -54,6 +58,7 @@ export function createAggregator({ windowMs, flushMs, maxTracked, now = Date.now
             states.set(errorHash, s);
             s.count++;
             s.severity = maxSeverity(s.severity, severity);
+            if (size > s.stackBytes) s.stackBytes = size;   // the biggest stack seen in the window (contract 2.1 (c))
             // firstSeen never changes inside a window (it is part of the window identity), even for an out-of-order line
             if (seenAt > s.lastSeen) s.lastSeen = seenAt;
             if (t - s.lastEmitAt >= flushMs) send(s, t);

package/src/incident-detector/detector.js

@@ -58,7 +58,8 @@ export function createIncidentDetector({ config, emitter, store, audit = null, n
         const environment = config.environment || inferEnvironment(service);
         const logCategory = logCategoryOf(message, stack, extractErrorType(message, stack));
         stats.detected++;
-        const { windowStart } = aggregator.observe({ errorHash, fingerprint, severity, service, environment, logCategory, tsMs: entry.tsMs });
+        const stackBytes = typeof entry.stacktrace === "string" ? Buffer.byteLength(entry.stacktrace) : 0;   // as the source gave it, before the entry cap
+        const { windowStart } = aggregator.observe({ errorHash, fingerprint, severity, service, environment, logCategory, tsMs: entry.tsMs, stackBytes });
         // the detail of the occurrence, tied to its window (the store keeps a few samples per window); resolves when queued
         if (await store.add({ errorHash, fingerprint, service, severity, windowStart, message, stack })) stats.stored++;
     }

package/src/incident-detector/emitter.js

@@ -1,10 +1,10 @@
 /**
  * emitter.js - sends `incident.candidate` frames (F3-11b, contract F3-22: la->cp, metadata only).
  *
- * The payload has exactly the 9 contract fields: errorHash, fingerprint, severity, service, environment, count, firstSeen,
- * lastSeen, logCategory. There is no field for text, a stack, a path or a message, and the session validates every frame against
- * the closed schema before it is written, so even a bug here cannot add one. (The contract has no field for the stack size or the
- * window length either: window = firstSeen..lastSeen; the stack size is in the local store.)
+ * The payload has the 9 contract fields: errorHash, fingerprint, severity, service, environment, count, firstSeen,
+ * lastSeen, logCategory and, ONLY when the CP announced `incident.candidate.size-model` in `ready.capabilities` (contract 2.1 (c)), two more
+ * that carry no text: `stackBytes` (UTF-8 size of the biggest stack of the window) and `model` (detector version, e.g. stack-detector-1.8.0). There is no field for text, a stack, a path or a message, and the session validates every frame against
+ * the closed schema before it is written, so even a bug here cannot add one. (window = firstSeen..lastSeen.)
  *
  *   DLP       service and environment are labels of the customer's own logs; they go through the DLP and a label it would change
  *             (or deny) is not sent at all: the candidate is dropped and counted (`dlp`).
@@ -27,7 +27,11 @@ const RETRY_MS = 5_000;
 const MAX_ATTEMPTS = 5;
 const NON_RETRYABLE_REFUSALS = new Set(["schema_violation", "frame_too_large", "payload_too_large", "unknown_type", "wrong_direction"]);
 
-export function createCandidateEmitter({ session, config, workspaceId = "", env = process.env, audit = null, log = console, now = Date.now, timers = { setTimeout, clearTimeout } }) {
+const SIZE_MODEL_CAPABILITY = "incident.candidate.size-model";
+const MODEL = /^[A-Za-z0-9][A-Za-z0-9._:+-]{0,47}$/;
+const MAX_STACK_BYTES = 16 * 1024 * 1024;
+
+export function createCandidateEmitter({ session, config, workspaceId = "", model = null, env = process.env, audit = null, log = console, now = Date.now, timers = { setTimeout, clearTimeout } }) {
     const warn = (m) => (log.warn || log.log).call(log, m);
     const pending = new Map();   // `${errorHash}|${windowStart}` -> snapshot
     const stats = { submitted: 0, sent: 0, coalesced: 0, droppedFull: 0, droppedDlp: 0, droppedInvalid: 0, droppedGaveUp: 0, droppedStopped: 0, rejected: 0, byCode: {} };
@@ -59,7 +63,13 @@ export function createCandidateEmitter({ session, config, workspaceId = "", env
             const r = protectEgress(label, { env, source: "incident-candidate" });
             if (r.denied || r.text !== label) return null;
         }
-        return { errorHash: s.errorHash, fingerprint: s.fingerprint, severity: s.severity, service, environment, count: s.count, firstSeen: iso(s.firstSeen), lastSeen: iso(s.lastSeen), logCategory: s.logCategory };
+        const payload = { errorHash: s.errorHash, fingerprint: s.fingerprint, severity: s.severity, service, environment, count: s.count, firstSeen: iso(s.firstSeen), lastSeen: iso(s.lastSeen), logCategory: s.logCategory };
+        // contract 2.1 (c): only when the CP said (ready.capabilities) it takes them: a 2.0 CP answers the closed schema with schema_violation
+        if (typeof session.peerHas === "function" && session.peerHas(SIZE_MODEL_CAPABILITY)) {
+            if (Number.isFinite(s.stackBytes)) payload.stackBytes = Math.max(0, Math.min(Math.trunc(s.stackBytes), MAX_STACK_BYTES));
+            if (typeof model === "string" && MODEL.test(model)) payload.model = model;
+        }
+        return payload;
     }
 
     function schedule(ms) {

package/src/incident-detector/index.js

@@ -23,8 +23,8 @@ export function buildSources(config, { stdin = process.stdin } = {}) {
     return sources;
 }
 
-export function installIncidentDetector({ link, workspaceId = "", config, env = process.env, log = console, sources = null }) {
-    const list = sources || buildSources(config);
+export function installIncidentDetector({ link, workspaceId = "", config, env = process.env, log = console, sources = null, extraSources = [], model = null }) {
+    const list = sources || [...buildSources(config), ...extraSources];   // extraSources: push sources owned by someone else (the webhook receiver, F3-12 consumer)
     if (list.length === 0) {
         log.warn("[la-incidents] LOCAL_AGENT_INCIDENT_DETECTOR=true but no source is configured (LOCAL_AGENT_INCIDENT_LOG_FILES, LOCAL_AGENT_INCIDENT_STDIN or LOCAL_AGENT_INCIDENT_LOKI_URL): the detector does not start");
         return null;
@@ -33,7 +33,7 @@ export function installIncidentDetector({ link, workspaceId = "", config, env =
     const audit = createAudit({ file: config.auditFile });
     const store = createDetailStore({ dir: config.storeDir, maxBytes: config.storeMaxBytes, maxQueue: config.storeMaxQueue, messageChars: config.storeMessageChars,
         stackChars: config.storeStackChars, samplesPerWindow: config.samplesPerWindow, env });
-    const emitter = createCandidateEmitter({ session: link.session, config, workspaceId: ws, env, audit, log });
+    const emitter = createCandidateEmitter({ session: link.session, config, workspaceId: ws, model, env, audit, log });
     const detector = createIncidentDetector({ config, emitter, store, audit, sources: list, log });
     const closeLink = link.close.bind(link);
     link.close = () => { void detector.stop().finally(() => { emitter.close(); }); closeLink(); };

package/src/incident-detector/sources/webhook-source.js

@@ -0,0 +1,109 @@
+/**
+ * webhook-source.js - the incident detector as the LOCAL consumer of the webhooks the control plane strips and forwards (F3-12 consumer).
+ *
+ * `webhook.forward` hands the (rebuilt, sha256-verified) body here. It is turned into the same entries every other source produces
+ * ({severity, message, stacktrace, service, tsMs}) and goes through the SAME pipeline (Java rules, DLP-masked local store, candidates with
+ * metadata only): the text of the webhook never leaves this process except into the local store. The ack of the webhook waits for `deliver()`.
+ *
+ *   text/plain          lines, joined into records like a log file (EntryAssembler)
+ *   alertmanager        `alerts[]` with status firing: "alertname: summary", severity label critical -> CRITICAL, error/high/major -> ERROR,
+ *                       anything else WARN (the detector ignores it)
+ *   sentry              `data.event` / `event` (+ `data.issue`): "Type: value" and a stack from the exception frames, `level` as severity,
+ *                       project as service
+ *   other JSON          one log-shaped object (message/msg/level/stack... as in parse.js); a body that does not look like one is `unmapped`
+ * Only SYNTHETIC payloads in the tests: the real shapes of each tool should be confirmed with captured webhooks before relying on them.
+ * Bounded: at most `maxEntries` entries and `maxBytes` of text per webhook. Counters only; never a word of the body in a log.
+ */
+import { EntryAssembler, parseRecord, parseTime } from "../parse.js";
+
+const str = (v) => (typeof v === "string" && v !== "" ? v : undefined);
+
+function fromAlertmanager(o, maxEntries) {
+    const out = [];
+    for (const a of Array.isArray(o.alerts) ? o.alerts : []) {
+        if (out.length >= maxEntries) break;
+        if (!a || typeof a !== "object" || (a.status && a.status !== "firing")) continue;
+        const labels = a.labels && typeof a.labels === "object" ? a.labels : {};
+        const ann = a.annotations && typeof a.annotations === "object" ? a.annotations : {};
+        const name = str(labels.alertname) || "alert";
+        const text = str(ann.summary) || str(ann.description) || "";
+        const sev = String(labels.severity ?? "").toLowerCase();
+        out.push({
+            severity: sev === "critical" ? "CRITICAL" : ["error", "high", "major", "page"].includes(sev) ? "ERROR" : "WARN",
+            message: text ? `${name}: ${text}` : name,
+            stacktrace: null,
+            service: str(labels.service) || str(labels.job) || str(labels.app) || str(labels.namespace) || null,
+            tsMs: parseTime(a.startsAt),
+        });
+    }
+    return out;
+}
+
+function sentryStack(exc) {
+    const values = exc && Array.isArray(exc.values) ? exc.values : [];
+    const v = values[values.length - 1];
+    const frames = v && v.stacktrace && Array.isArray(v.stacktrace.frames) ? v.stacktrace.frames : [];
+    if (frames.length === 0) return null;
+    return frames.slice().reverse().slice(0, 100).map((f) => `    at ${str(f && f.function) || "?"} (${str(f && (f.filename || f.module)) || "?"}:${Number.isFinite(f && f.lineno) ? f.lineno : 0})`).join("\n");
+}
+
+function fromSentry(o) {
+    const data = o.data && typeof o.data === "object" ? o.data : o;
+    const ev = data.event && typeof data.event === "object" ? data.event : data.issue && typeof data.issue === "object" ? data.issue : null;
+    if (!ev) return [];
+    const exc = ev.exception && typeof ev.exception === "object" ? ev.exception : null;
+    const last = exc && Array.isArray(exc.values) ? exc.values[exc.values.length - 1] : null;
+    const head = last && str(last.type) ? `${last.type}${str(last.value) ? `: ${last.value}` : ""}` : str(ev.title) || str(ev.message) || str(ev.culprit);
+    if (!head) return [];
+    const proj = ev.project && typeof ev.project === "object" ? ev.project : null;
+    const ts = typeof ev.timestamp === "number" ? ev.timestamp : ev.datetime || ev.firstSeen;
+    return [{
+        severity: str(ev.level) ? String(ev.level).toUpperCase() : "ERROR",
+        message: head.split("\n")[0],
+        stacktrace: sentryStack(exc),
+        service: str(o.project_name) || str(proj && (proj.slug || proj.name)) || str(ev.project) || null,
+        tsMs: parseTime(ts),
+    }];
+}
+
+/** @returns {{entries:object[], unmapped:boolean}} */
+export function entriesFromWebhook({ source, contentType, body }, { maxEntries = 200, maxBytes = 1048576, maxEntryBytes, maxStackLines } = {}) {
+    const text = new TextDecoder("utf-8").decode(body.length > maxBytes ? body.subarray(0, maxBytes) : body);
+    if (contentType === "text/plain") {
+        const asm = new EntryAssembler({ maxEntryBytes, maxStackLines });
+        const out = [];
+        for (const line of text.split("\n")) { out.push(...asm.push(line.replace(/\r$/, ""))); if (out.length >= maxEntries) break; }
+        out.push(...asm.flush());
+        const entries = out.slice(0, maxEntries);
+        return { entries, unmapped: entries.length === 0 };
+    }
+    let o;
+    try { o = JSON.parse(text); } catch { return { entries: [], unmapped: true }; }
+    if (!o || typeof o !== "object" || Array.isArray(o)) return { entries: [], unmapped: true };
+    let entries = [];
+    if (source === "alertmanager" || Array.isArray(o.alerts)) entries = fromAlertmanager(o, maxEntries);
+    else if (source === "sentry") entries = fromSentry(o);
+    else { const r = parseRecord(text); entries = r ? [r] : []; }
+    return { entries, unmapped: entries.length === 0 };
+}
+
+export function createWebhookSource({ maxEntries = 200, maxBytes = 1048576, maxEntryBytes, maxStackLines, stats = {} } = {}) {
+    let consumer = null;
+    Object.assign(stats, { received: 0, entries: 0, unmapped: 0, ...stats });
+    return {
+        name: "webhook",
+        stats,
+        start(onEntries) { consumer = onEntries; },
+        stop() { consumer = null; },
+        /** The sink of the webhook receiver. Resolves when every entry went through the detector (its detail queued): the ack waits for it. */
+        async deliver(webhook) {
+            if (!consumer) { const e = new Error("webhook source is not started"); e.code = "internal"; throw e; }
+            stats.received++;
+            const { entries, unmapped } = entriesFromWebhook(webhook, { maxEntries, maxBytes, maxEntryBytes, maxStackLines });
+            if (unmapped) { stats.unmapped++; return { entries: 0 }; }
+            stats.entries += entries.length;
+            await consumer(entries);
+            return { entries: entries.length };
+        },
+    };
+}

package/src/la-protocol-v2/contract/CONTRACT_SOURCE.json

@@ -2,15 +2,15 @@
   "repo": "VISIONHAMMER/vh-api-gateway",
   "path": "docs/contracts/la-protocol-v2",
   "branch": "release/qa",
-  "commit": "b9176054337eeabe416117bafd90ce484a71968e",
+  "commit": "c0d6b44a89d2d18a2627493403c06b9caa7d1a96",
   "note": "Copied by scripts/sync-la-protocol-v2-contract.mjs. Do not edit: change the gateway folder and sync again.",
   "files": {
-    "README.md": "93fe7d94f212c36d5402a20cd1397e5236012c6bf1f6bb81546a65033703a88f",
+    "README.md": "e247945f859f777a705c5baebecf2a216462a7c2fe1c30598099c96c88cd432b",
     "ack.schema.json": "d6dfdaa8b1ec2dd47db9e858cd047ca860196ab6b0ad350f8ccb5d2596441ccf",
     "alert.schema.json": "01a8a77840be8ab7901ed7d07c3d68a2295bfaeb638694564e19e60be1747054",
     "approval.decision.schema.json": "a9c7bc74d146465afde1d5830839165a02f232b830b5f6cfd8c8e91fb6da1563",
     "audit.event.schema.json": "e9ceb58ea00077151373955957b8319324de488c80da4063f6d0dcb40a8b3ed0",
-    "config.update.schema.json": "f5318f24230f542c76a3cb996d08f33210c0b2cc2fc55ad73c4f95648582033f",
+    "config.update.schema.json": "432438b0c93ddafa0741e47f99b7357ad5f2b06b606779bf846c282e2f8a5639",
     "content.index.schema.json": "1abc24344435f0f392d5b626c3abb6879d8f9dd2c1d0463840a67634a5caa71e",
     "content.request.schema.json": "440e3675246657e9aae23e51176168bc21c91283b5fcaf6782111a18110bf76e",
     "content.response.schema.json": "c9a66ac9cbbcaec7fc182b3e3fa23b34877bd342592521c7e393779230332231",
@@ -19,24 +19,24 @@
     "error.schema.json": "b1fd663d4a1ea73d88cb575422f15f8c7279001f9385ebb2d5e1889b5d5ef878",
     "file.list.body.schema.json": "dd58ac2af91bbde53e0fd585dc55af0adb01380492d1604f21ed8e972d7ba8d1",
     "heartbeat.schema.json": "8aff84a1ef3ca56bdff8819abb3b0ab01a2547814c2ea2f9ee893cb08f7a08f1",
-    "hello.schema.json": "bd500320f01ff10da49ded6f99c7e8081252019984afb3c178e27003df20b963",
-    "incident.candidate.schema.json": "b292a85917b5958fc6de10a2895732e30a35420385623930c78e47341862dc62",
-    "index.json": "cf8f05e70b6265a169b0117d4577f78b699818eb5091df6cd4c7c7416385582a",
+    "hello.schema.json": "a90a6bf0e9a8a20e4c6edcf2137931cf044846e7924977228275ef648a48934f",
+    "incident.candidate.schema.json": "ffec36aca6916079debc2c6060d093819ea3ea660b57c0c92ac3b541a0e99000",
+    "index.json": "de79c065217e1fa8430c4266ec19fd57df35fc4182eb7c7246b6f1ea03d2630c",
     "job.assign.schema.json": "fdebb4ae98bf38a2c723281c1cf9477f71d877171df9a55b0baeb0b65244f60c",
     "job.cancel.schema.json": "40ef64373283e17306d857c9a40081689786015294b0b88ab8f68f063bd2cfb8",
     "job.event.schema.json": "493d08f9db4f7ffd4a97403ee33ca4a73a65dc8f774d8f18ef0a137fdb5fc470",
     "job.result.schema.json": "9cbc61211482557283b8f4df44e79011ead1abbacdb2d986138199c747edc043",
     "log.stats.schema.json": "4b33b111946a19793a60756793294e90911b06f7050e48821759f2497ec17641",
-    "ready.schema.json": "6e8bd8e1a5ce1b840d35af911ae09b8f58ad9de59eb33cd2b7777859892813f4",
-    "register.schema.json": "e75a4aa9d5d750e1473f71ab2f37d8e9a82fcfab3e8ff1c35118d0c08916e795",
+    "ready.schema.json": "02e51ba5aad3357c9840c14eb45cb86b7aab0c10e349c94c720cda1a0b5b8366",
+    "register.schema.json": "bec30062cf99657a1ecb94bad004f502615901e36bc2b0ba62351ed021e059ac",
     "scan.upload.schema.json": "b1bba86ee362f73afc94c8c216977c12f67f770490e81002d14789397692f23b",
     "scan.uploaded.schema.json": "f4c6aed7b9363b3ce1a9e14f9c4f4fb003bcf104b60acf74421dd0c75fc5d229",
-    "webhook.forward.schema.json": "33d4ee238855339850ff198d1078087f3b2f48c8f290b71def93cc02dd32c985",
-    "vectors/ack.vectors.json": "242ec2b8ff0c748eaaedce63e0015cf5bd9a7092d1055b0670ce6b95403b54b2",
+    "webhook.forward.schema.json": "9ab66adf31386445c2b76930155ffa6874326395d968582d2345ee7fb5b77f82",
+    "vectors/ack.vectors.json": "1756c1169cf5f42c0ab6b1c094071d1f8ccf2fe9efdbc97101e402e93bd65a67",
     "vectors/alert.vectors.json": "0bf179ff390bbecf07a117b80237cb7ac8778864e5780f36d68c8c9a64db8f04",
     "vectors/approval.decision.vectors.json": "338115973bf2c4390d2bb33ce8f4079f3132cd739cd5505e1e873fdc252d2271",
     "vectors/audit.event.vectors.json": "d05c1820103eef041a84eb8b13d9a67a8a5b54b9b54ee3b6e43fd4ef15ed7000",
-    "vectors/config.update.vectors.json": "8a5088d547e3eb4e460b25a5e413caaa02d4402a601340e279166d8c17758e1c",
+    "vectors/config.update.vectors.json": "e61865fad9b4efa808e02877c4352d3720c8069a0b31261701b369d8ae11f9cf",
     "vectors/content.index.vectors.json": "f167db30910989c46f317313d651ca59f9cd9d881d2ea81b84912155d18227b7",
     "vectors/content.request.vectors.json": "fdf0f4d9e19f6480e20e40f4652bf8205da2b113620f8461dfaeb0d61add36a0",
     "vectors/content.response.vectors.json": "cbb47cbf8a9512aa5360eea425f0cdd9064334311d37834dc75bddff07dadc5d",
@@ -44,15 +44,15 @@
     "vectors/error.vectors.json": "f5fd7954f2c1736ee0943eb330c2f85b7fdd7a8959e4f043f9cc9e9bcda39aa5",
     "vectors/file.list.body.vectors.json": "da1dcc5d4ec976853161bef4b3947572f36b5526cbe16b838ac4ef72ddded403",
     "vectors/heartbeat.vectors.json": "cfd2e048139c67aa925f1fa94c05326e75248839645c1a1e4d6d3bb60cafa624",
-    "vectors/hello.vectors.json": "51067dc645a2e9d8116997b36e6f3fe36401d27f3ee3c18de32ec30f8a052c5f",
-    "vectors/incident.candidate.vectors.json": "0dd75ef396bf7b7911d20b3ab220469701f07866bb032ee31af58523c3633ab6",
+    "vectors/hello.vectors.json": "7a50c4e54e6a4ef1227fd7485071bca8ec7b797c3b2907fddda3d8836c3feab6",
+    "vectors/incident.candidate.vectors.json": "a78eb4b103f411f1ec64d9eeb4c39623851e710ac0cc20b4d78b2739b7ff78d5",
     "vectors/job.assign.vectors.json": "e510c2cc6d17238d477429c255d828c0339b504e39a3a50d4b6ca980e262d9ef",
     "vectors/job.cancel.vectors.json": "0fc9f99c8662435e9425389068adf418273489dc73928a21eae1b283256b9bc5",
     "vectors/job.event.vectors.json": "03a2a2435918ba561821916bf4e435f2780210900139ecf68091acac6abf200c",
     "vectors/job.result.vectors.json": "05995fbe65e5357705d75e9b660b517f54c6902069d36b62190b1b79f283e7a5",
     "vectors/log.stats.vectors.json": "a8a67e09ef0f87b81f4028b77427ed7afd809c3f8534b8423a712b2ceef9a27f",
-    "vectors/ready.vectors.json": "a584da17e714a13c3583256773ef0be007660c33c62a456e27568def391e7cef",
-    "vectors/register.vectors.json": "e2a696efc547aa2f7242128d1a860238954f9e9a1330f10b567122d7b3da0365",
+    "vectors/ready.vectors.json": "16327f5e5eccc57a0ec635bcde96116feeeeec7ddbc4b621d4d070738cdc48d5",
+    "vectors/register.vectors.json": "b612e9462b1e2ac198442afccf450f1535daadc4c32d87f6a99b9752c343c486",
     "vectors/scan.upload.vectors.json": "e8a6f73fe91ac58a3222b68cf28124c1254aa4f00c3ef8f472deb7de31cab76e",
     "vectors/scan.uploaded.vectors.json": "7314ea15b1afa7b9625048fb7e245492d8910bc0dae8a52ea62afe2a1e240382",
     "vectors/traces/invalid-agent-mismatch.json": "5f17b867de71c1bcc6c42723acb53a50338c0e491193499ea25c2220ea4fa558",
@@ -76,11 +76,19 @@
     "vectors/traces/invalid-signature-warn-with-enforce-required.json": "71b5b3dc5dce52417173934db1e0de6542ecae5798e87124d54a8017493312e1",
     "vectors/traces/invalid-tenant-mismatch.json": "dcc04ea423bddef20524ead7bfd146a5d9c42fe474c9216dc38c90544d291151",
     "vectors/traces/invalid-type-outside-allowlist.json": "e492d326cfa044d3fc9f7e48dee63a52b715a62ba4867fc5ce21f1d86e3c435f",
+    "vectors/traces/invalid-webhook-chunk-after-last.json": "9a35faaeeafce045a887e643f603ca69950872d62d27d17086513103999aefd6",
+    "vectors/traces/invalid-webhook-chunk-body-hash-changes.json": "7ade576a8dc8e9671383e85fbe6aae414863cbb1cde38737a2cb78efce9c9528",
+    "vectors/traces/invalid-webhook-chunk-last-flag-wrong.json": "8505b5fbbc0a8dc97021a1c02f9883df95f9401bc18eaa2498331b0b6b7d155c",
+    "vectors/traces/invalid-webhook-chunk-non-last-too-short.json": "ff1d64b019c082e7a5c6537fdbf069025a532c764e62c532a24a3b7257f4b6ab",
+    "vectors/traces/invalid-webhook-chunk-out-of-order.json": "b6baa056b4e3347deaf0a4b901a126a3f93d20627faaa3951028bd47894715f4",
+    "vectors/traces/invalid-webhook-chunk-sha-mismatch.json": "1bb79d0e1794cd791625ed2a7eab154e20150c5d7bee7c86aa97f9bf4aaeab6d",
+    "vectors/traces/invalid-webhook-chunk-total-changes.json": "5edf3c1916927f94ef15061a13a6ded8a0168cb0492158f34db8160c0d6bdbe4",
     "vectors/traces/valid-content-chunks-in-order.json": "c5fc301527b062b30c625da2798c7cfab3e3debac29a36f6ec7c699705267ab3",
     "vectors/traces/valid-content-index.json": "9305dc955c4cca1f09158a9c8cf21d9e89d6a6b03646088c547f64a61cd59c30",
     "vectors/traces/valid-handshake-and-job.json": "9aa3c423c496403ca77d63965f1805f0a57ea9f6f8a01351310515b265aeb9cc",
     "vectors/traces/valid-resume-continues-seq.json": "8aa90f24598f8f2d87a5355ec58c3531d16fd11ad41c782f53eca063372b704a",
     "vectors/traces/valid-retransmit-is-idempotent.json": "924e9d296a67f0006c289e7cc978b9529ae1aa03bec2cd331a62f31354a90257",
-    "vectors/webhook.forward.vectors.json": "38d5b53b8fb4ecdb051e2c594afc52eb8b2044e4e6aae6ffb0057fbda33bcd46"
+    "vectors/traces/valid-webhook-chunks-in-order.json": "2e5e6313a7fe9b3f7fea23d6a0c928d6bfef69b2a7179f1578230425f451ada9",
+    "vectors/webhook.forward.vectors.json": "991a677d72a9c698ed3c8d960af532daf8f3158d77a4bea7d08750ccd8693250"
   }
 }

package/src/la-protocol-v2/contract/README.md

@@ -5,13 +5,16 @@ sides. Design: vault `10 Library/Plans/Fase 3 Desenho Tecnico 2026-10-28.md` sec
 implements it behind `deepdebug.agent-ws.protocol-v2.enabled` (default off, F3-05a); the LA side (F3-05b) does not
 exist yet. v1 is untouched. The gateway packages `*.schema.json` + `index.json` from this folder as classpath
 `la-protocol-v2/` (pom resource; both Dockerfiles copy this folder), so this folder stays the only source.
+**Revision 2.1** (`index.json` `revision`, Fase 3, last section): optional LLM key delivery, chunked webhooks, size/model in `incident.candidate`, `ready.capabilities`.
 
 ## Files
 - `envelope.schema.json`: common frame, closed (`additionalProperties:false`). `<type>.schema.json` (22):
   one per allowlisted type, each `$ref`s the envelope and closes `payload`. `defs.schema.json`: shared types.
 - `file.list.body.schema.json` (F3-07c): not a frame type; the schema of the DECODED body of a `content.response` for kind `file.list`
   (below). `vectors/file.list.body.vectors.json` holds its vectors (same format, `schema` names that file).
-- `index.json`: allowlist, direction, signed/control flags, content class per type, and the limits below.
+- `index.json`: allowlist, direction, signed/control flags, content class per type (`none`, `relay`, `transit`, `secret`), the limits below and the contract `revision`.
+- Vector files of a BODY that travels inside a frame (not a frame) are named `*.body.vectors.json` and their schema `*.body.schema.json`; the frame
+  suites skip them (`ProtocolV2ContractTest` checks them against their own schema, `SchemaLaV2ContractTest` does not read them as frames).
 - `vectors/<type>.vectors.json` (+ `cross-type`): valid and invalid messages with `expect` (`valid`, error `code`,
   optional JSON Schema `keyword`, optional session `rule`). `vectors/traces/*.json`: whole sessions for the stateful rules.
 
@@ -30,7 +33,8 @@ ack timeout 5 s, <= 3 retransmissions; handshake steps 10 s; `ping`/`heartbeat`
 (= Redis `la:session` TTL); clock skew <= 60 s. Duplicate detection (gateway, F3-05a): the last 512 `seq`->`msgId` pairs
 per session, in memory (`dedupe-entries`); the 10 min Redis window of the design (`dedupeWindowSeconds` in `index.json`)
 is NOT implemented, a replay older than those 512 frames is `seq_replayed`. CP->LA frames repeat the payload in
-`paramsRaw`, so their effective payload budget is about 20 KiB; larger inputs travel by `ref`.
+`paramsRaw`, so their effective payload budget is about 20 KiB; larger inputs travel by `ref`. Webhook chunking (2.1) has its own limits
+(`webhook*` in `index.json`: 16 KiB raw per chunk, 64 chunks, 1 MiB per webhook, see the last section).
 
 ## State machine
 `AWAIT_REGISTER -> AWAIT_HELLO -> AWAIT_READY -> READY`, after the WS upgrade authenticates (Bearer, as v1).
@@ -45,7 +49,9 @@ is NOT implemented, a replay older than those 512 frames is `seq_replayed`. CP->
   handshake state, `seq` (same seq + same `msgId` = idempotent duplicate, re-ack; same seq + other `msgId` =
   `seq_replayed`; skip = `seq_gap`), chunks (index 0.., `total` constant, `last` iff last index, none after last; then `payload.byteLength` must equal the size of
   the base64-DECODED `payload.data`, else `chunk_inconsistent`: JSON Schema cannot state it, so the vector files carry
-  `expect.rule:"byteLength-decoded"` and both validators apply it).
+  `expect.rule:"byteLength-decoded"` and both validators apply it). Since 2.1 two more stateless rules of the same kind:
+  `webhook-chunk-size` and `llmKey-id-sha256` (last section); `webhook.forward` chunks are also grouped by `payload.webhookId` and the reassembled
+  body must hash to `bodySha256` (`chunk_inconsistent` otherwise).
 - **Errors** (`error{code,retryable}`, then WS close 4400-4499 when fatal): `bad_frame unknown_type schema_violation
   frame_too_large payload_too_large wrong_direction handshake_violation not_ready seq_gap seq_replayed
   chunk_out_of_order chunk_inconsistent tenant_mismatch agent_mismatch params_mismatch signature_mode_insufficient
@@ -64,6 +70,7 @@ Everything is closed: no free-text fields, no extra properties, free strings <=
 hashes, counts). Client content may exist only in three declared fields (`x-content-class`, pinned by the test):
 `content.response.data` (relay, LA->CP, never persisted or logged by the CP), `job.assign.inputs[].inline` and
 `webhook.forward.bodyB64` (transit, CP->LA, `transient:true`, not persisted; `paramsRaw` echoes them).
+Since 2.1 there is one more classified field and it is the only SECRET: `config.update.llmKey.key` (`x-content-class: secret`, see the last section).
 Long non-content strings are marked `x-large-metadata` (`paramsRaw`, `signedPutUrl`, `vhapr1` token). `error.detail` <= 200 chars
 and `audit.event` have no summary text; stack traces, diffs, logs and paths go only through `content.*`.
 
@@ -186,3 +193,96 @@ existing kinds, `ref` convention, ids, envelope and chunking are reused; the cha
   answer is HTTP 501 `not_supported`. That announcement is also how the front/CP discovers that listing exists on a given agent.
 - **Compatibility.** Additive: the kind is added to the `content.request` and `content.index` enums, nothing else changes there. The
   `content.request` payload gained no field. With `deepdebug.content-relay.enabled` off nothing is mapped, as before.
+
+## Revision 2.1 (Fase 3, contract v2.1): LLM key, chunked webhooks, size and model of a candidate
+Decisions of Edu 2026-11-03 (ADR-0017, adenda (c)). **No new frame type** (still 22), every change is additive and optional, and each is gated by a
+capability so a 2.0 peer keeps working unchanged. The gateway code that uses these fields is a later task (G); here only the contract moved.
+
+**Capabilities (negotiation).** The LA announces, in `register` and `hello` `capabilities`: `contract.v2.1` (it has the 2.1 schemas, so it can read the
+new optional `ready.payload.capabilities`), `llm.key` (it handles `config.update.llmKey`) and `webhook.chunked` (it reassembles chunked `webhook.forward`;
+it announces `webhook.forward` too). The CP announces, in `ready.payload.capabilities` (array, <= 32, same name pattern): `incident.candidate.size-model` (it
+accepts `stackBytes` and `model`). Rules: the CP sends `llmKey` only to a session that announced `llm.key`, a chunked webhook only to one that announced
+`webhook.chunked`, and `ready.capabilities` only to one that announced `contract.v2.1` (a 2.0 LA's closed `ready` schema does not know the field, so without
+`contract.v2.1` the `ready` is exactly the 2.0 one); an LA sends `stackBytes`/`model` only if `ready` listed `incident.candidate.size-model` (a 2.0 CP would
+answer the closed schema with `schema_violation`). A name that is absent means 2.0 behaviour.
+One more LA capability, `llm.key.held` (section (e)), tells the CP the LA holds a valid key right now; it is optional and only informs the CP.
+
+### (a) LLM key delivery: `config.update.payload.llmKey`
+`config.update` already carried only flags, a DLP hash, a minimum version, a retention and the data-plane mode: it had no way to hand the LA the virtual
+LiteLLM key (F3-09). `llmKey` is a closed `oneOf`:
+- `{op:"set", keyId, endpoint, key, models[], expiresAt}`, all required. `keyId` is the 64-hex lower-case sha256 of the UTF-8 bytes of `key` (it is
+  LiteLLM's token id and the CP's `la_llm_keys.key_id`; semantic rule `llmKey-id-sha256`: the LA recomputes it and refuses a mismatch). `endpoint` is the AI
+  gateway base URL, `https://` only, host[:port][/path], no credentials, no query, no fragment, <= 256 chars. `key` is 16..256 chars of
+  `[A-Za-z0-9._~+/=-]` (no whitespace, no control character). `models` is 1..32 unique aliases (the scope of the key). `expiresAt` is UTC.
+- `{op:"revoke", keyId}`: names the key by id, never repeats it.
+- A `config.update` that carries `llmKey` carries NOTHING else (`maxProperties: 1`), so the frame can be recognised and redacted as a whole.
+- **The key is a secret.** `x-content-class: secret` on `llmKey.key`; `index.json` marks `config.update` `contentClass: "secret"`. It travels only on the v2
+  channel (TLS plus the Ed25519 signature) and, between gateway instances, only inside the AEAD-sealed relay (F3-04). It appears twice in the frame, in
+  `payload` and in the `paramsRaw` copy: BOTH are secret. The CP never writes it to a log, a metric, a trace, the audit trail, a table or an unsealed Redis
+  value (it keeps it only in the in-memory unacked frame until acked or the session ends). The LA keeps it **only in memory or in a file mode `0600`
+  (directory `0700`) outside every workspace and outside what the content handlers can serve**, never logs it, never puts it in `hello`, `alert`,
+  `audit.event`, `job.event`, `content.response` or an error, and never passes it on a command line.
+- **The ack never returns it.** The answer is the plain `ack` (its payload is only `ackSeq`, `status`, `errorCode`; the contract test pins that no LA->CP
+  frame has a field named `key`, `llmKey` or `keyId`): `accepted`, or `rejected` + `schema_violation` when the LA refuses the key (expired
+  `expiresAt`, `keyId` not the sha256 of `key`).
+- **Rotation.** A `set` with another `keyId` replaces the key the LA holds, atomically (one key per LA); the same `keyId` again is idempotent. The CP should
+  revoke the old key at the AI gateway only after the `accepted` ack of the new one.
+- **Revocation.** The key revoked at the AI gateway is the authoritative revocation; the `revoke` frame only makes the LA drop its copy (delete from memory,
+  unlink and overwrite the file) and stop using it. A `revoke` of an id the LA does not hold is a no-op and is acked `accepted` (it never tells which key it
+  has). The LA also drops the key at `expiresAt`.
+
+### (b) Chunking of `webhook.forward` (CP -> LA)
+2.0 allowed one frame with `bodyB64` <= 12288 chars (9216 raw bytes). That stays: **a body of at most 9216 bytes is sent as ONE frame without `chunk`, exactly
+as in 2.0** (a 2.0 LA reads it). A bigger body (up to **1 MiB**) is chunked, reusing the `content.response` pattern but CP -> LA:
+- Each chunk is a signed `webhook.forward` frame with the envelope `chunk{index,total,last}` (index from 0), its own `seq` and `msgId`, and the same
+  `webhookId`, `source`, `contentType`, **`bodyBytes`** (size of the WHOLE decoded body, 0..1048576) and **`bodySha256`** (sha256 of the whole decoded body,
+  lower-case hex). `bodyBytes` and `bodySha256` are required in a chunked frame and forbidden in an unchunked one (schema `if/then/else` on `chunk`).
+- **Fixed chunk size**: 16384 raw bytes (`bodyB64` <= 21848 chars; twice in the frame with `paramsRaw` it still fits 48 KiB: a vector pins it).
+  `total = max(1, ceil(bodyBytes / 16384))` (<= 64); every non-last chunk has exactly 16384 bytes; the last has `bodyBytes - 16384 * (total - 1)`. That is the
+  stateless rule `webhook-chunk-size` (`chunk_inconsistent` when a frame breaks it), so the LA can size the buffer from the first chunk. A body above
+  9216 bytes is never sent unchunked; a chunked frame with a small body (`total` 1) is valid.
+- **Order and integrity** (reference model, same codes as `content.response`): chunks in index order, `total` constant, `last` iff the last index, none after
+  the last (`chunk_out_of_order` / `chunk_inconsistent`); `bodyBytes`, `bodySha256`, `source`, `contentType` must not change between chunks; on the last
+  chunk the reassembled body must have `bodyBytes` bytes and hash to `bodySha256`, else `chunk_inconsistent`. Each chunk is also authentic on its own (signature).
+- **Acks.** Every chunk is a normal v2 frame: the LA acks each by `seq` (piggyback or `ack{ackSeq,status}`), `accepted` = stored. The `accepted` ack of the
+  LAST chunk means the body was reassembled and its hash verified: that is the ack the CP waits for before answering the webhook (decision: ack AFTER the
+  forward). The LA answers `rejected` + `chunk_inconsistent` / `chunk_out_of_order` / `payload_too_large` / `rate_limited` and drops the assembly; the CP then
+  stops sending chunks of that `webhookId` and treats the webhook as not delivered.
+- **LA limits** (`index.json`): an assembly older than 30 s (`webhookAssemblySeconds`) without its last chunk is dropped; at most 4 open assemblies per session
+  (`webhookMaxOpenAssemblies`; the CP sends one chunked webhook at a time per session) and 4 MiB buffered; beyond that `rejected` + `rate_limited`. The body
+  stays in memory, is never written or logged by the CP, and the LA applies its DLP to it as to any client content.
+- `webhookId` is the group key; a retransmitted chunk (same `seq` and `msgId`) is the existing idempotent duplicate; the same `webhookId` redelivered as a
+  whole is the application's dedup (a deterministic `webhookId` is the consumer's job).
+
+### (c) `incident.candidate`: `stackBytes` and `model`
+Two OPTIONAL fields, no required field added: `stackBytes` (integer 0..16777216: size in bytes of the stack the LA saw; the LA saturates at the cap) and
+`model` (string 1..48, `^[A-Za-z0-9][A-Za-z0-9._:+-]{0,47}$`: detector/parser version, e.g. `stack-detector-1.8.0`; no space, no slash, so no name, path or
+error text fits). The frame still carries no stack, no message and no name. Sent only after `ready` announced `incident.candidate.size-model`.
+
+### (d) `ready.payload.capabilities`
+Optional array (<= 32 capability names). It is what lets (c) be sent safely; it carries no limit and no content. A CP that does not send it is a 2.0 CP, or the
+session did not announce `contract.v2.1`.
+
+### (e) `llm.key.held`: the LA says whether it still has its key
+Problem it solves: an LA that keeps the key only in memory (the default) loses it on restart, but the CP's table still says ACTIVE, and the CP only
+delivers again when the key is close to expiry (< 14 days), so the LA would stay without a key. Rather than the CP guessing, the LA announces it.
+- **Name and place.** The capability string `llm.key.held` (it already matches the `capability` pattern, so no schema enum changes), announced in
+  `register.payload.capabilities` and in `hello.payload.capabilities`, never in `ready.payload.capabilities` (that list is the CP's). It is optional and
+  needs no `contract.v2.1` decision of its own: a CP that does not know it ignores an unknown capability name, as it ignores any other.
+- **Rule for the LA.** It announces `llm.key.held` ONLY when it holds a key that is still valid (`expiresAt` in the future, accepted and
+  `keyId`-verified through `config.update.llmKey`) and that it is IN USE (it is the key its LLM calls would use). No key, an expired key, a revoked key
+  or a key it refused: it does not announce it. The announcement is a snapshot at connect time: `register` and `hello` of one session carry the same
+  answer, and the LA never announces it without also announcing `llm.key` (an LA that cannot receive a key cannot hold one). That dependency is in the
+  schema (`if capabilities contains llm.key.held then it must contain llm.key`, `register` and `hello`), so `llm.key.held` alone is `schema_violation`.
+- **Rule for the CP.** At connect, if the capability is NOT announced (in `register` and `hello`; the CP should treat the key as held only when both
+  say so), the CP delivers a key (mint, then `config.update.llmKey set`) even when an ACTIVE row exists for that agent; the previous key follows the
+  rotation rule of (a) (revoked at the AI gateway only after the `accepted` ack of the new one). If it IS announced, the CP keeps the existing rule:
+  nothing to deliver until the key is within 14 days of `expiresAt`. A 2.0 LA, or a 2.1 LA that does not know the capability, never announces it, so
+  the CP treats it as "holds no key" and delivers one if the channel is on (`llm.key` announced): the safe direction.
+- **Compatible.** Optional and additive: a register/hello without it is valid (2.0, or 2.1 after a restart), and one with it is valid under 2.1 only
+  together with `llm.key`. No frame type, no new field and no new limit. The CP side of this rule is gateway runtime code (a later task, not this contract).
+
+### Compatibility and roll-out order
+Everything is additive and optional: a 2.0 frame is valid under the 2.1 schemas (the vectors of 2.0 are unchanged and still pass), and a 2.1 peer talking to a
+2.0 peer sends nothing the 2.0 peer cannot read, because each new field is gated by a capability the other side announced (above). Roll out the gateway that
+has the 2.1 schemas first (it accepts both shapes), then the LAs. The files changed by 2.1 are listed with their sha256 in the PR; the LA re-syncs exactly those.