deepdebug-local-agent 1.8.0 → 1.10.0

package/src/la-protocol-v2/llm-key/store.js

@@ -0,0 +1,183 @@
+/**
+ * store.js - the virtual LLM key of the AI gateway, as the Local Agent holds it (F3-09 consumer, contract 2.1 (a)).
+ *
+ * ONE key per agent (= per tenant: the holder belongs to one link). `set` with another keyId replaces it atomically, the same keyId
+ * again is idempotent, `revoke` drops the copy (an unknown id is a no-op: it never tells which key is held). The key is dropped by itself
+ * at `expiresAt`.
+ *
+ * Where it lives: in a private field of this object (never a property: JSON.stringify, util.inspect, structuredClone and a heap
+ * snapshot of enumerable state do not show it) and, when `file` is configured, in a file mode 0600 inside a 0700 directory that is NOT
+ * under any workspace root. Revocation overwrites the file with zeros before unlinking it.
+ * Never: logged, put in an ack, an audit record, a metric, an error message, a command line or a URL. `describe()` returns metadata only
+ * (models, expiry, whether a key is held); the key leaves this object only through `request()`, as an Authorization header.
+ *
+ * There is NO LLM client in the Local Agent today (the thinking happens in vh-agents via vh-litellm). `request()` is the hook a future
+ * client uses: same https endpoint the control plane gave, redirects refused, the caller cannot choose another host or header.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+const ENDPOINT = /^https:\/\/[A-Za-z0-9]([A-Za-z0-9.-]{0,251}[A-Za-z0-9])?(:[0-9]{1,5})?(\/[A-Za-z0-9._~/-]{0,200})?$/;
+const KEY = /^[A-Za-z0-9._~+/=-]{16,256}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const PATH_AND_QUERY = /^\/(?!\/)[A-Za-z0-9._~!$&'()*+,;=:@%/?-]{0,2000}$/;
+const MAX_TIMER_MS = 2 ** 31 - 1;
+
+export class LlmKeyError extends Error {
+    constructor(code) { super(code); this.name = "LlmKeyError"; this.code = code; }   // codes only: "no_key" | "expired" | "bad_path"
+}
+
+const sha256Hex = (s) => crypto.createHash("sha256").update(Buffer.from(s, "utf8")).digest("hex");
+
+/** realpath of the deepest existing ancestor + the part that does not exist yet (symlinks of the existing part are resolved). */
+function realish(p) {
+    const rest = [];
+    let cur = path.resolve(p);
+    for (;;) {
+        try { return path.join(fs.realpathSync(cur), ...rest.reverse()); } catch { /* does not exist: go up */ }
+        const up = path.dirname(cur);
+        if (up === cur) return path.join(cur, ...rest.reverse());
+        rest.push(path.basename(cur));
+        cur = up;
+    }
+}
+
+/** Is `file` inside any of `roots`? (both sides resolved through symlinks, also when the file's directory does not exist yet) */
+export function insideAny(file, roots) {
+    const f = realish(path.dirname(file));
+    return roots.some((r) => {
+        if (!r) return false;
+        const rel = path.relative(realish(r), f);
+        return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+    });
+}
+
+export function createLlmKeyHolder({ file = null, workspaceRoots = () => [], now = Date.now, timers = { setTimeout, clearTimeout }, audit = null, log = console } = {}) {
+    let held = null;            // { keyId, endpoint, models, expiresAt, expiresMs, key }
+    let timer = null;
+    let fileOk = !!file;
+    const stats = { set: 0, replaced: 0, revoked: 0, revokeUnknown: 0, expired: 0, refused: 0, requests: 0, persistErrors: 0 };
+    const warn = (m) => (log.warn || log.log).call(log, m);
+    const note = (event, extra = {}) => { try { audit?.record({ event, ...extra }); } catch { /* the audit never breaks the data path */ } };
+
+    if (file && insideAny(file, workspaceRoots())) {
+        fileOk = false;
+        warn("[la-llm-key] LOCAL_AGENT_LLM_KEY_FILE is inside a workspace: the key stays in memory only");
+    }
+
+    function disarm() { if (timer) { timers.clearTimeout(timer); timer = null; } }
+    function arm() {
+        disarm();
+        if (!held) return;
+        const left = held.expiresMs - now();
+        timer = timers.setTimeout(() => { timer = null; if (held && held.expiresMs <= now()) { drop(); stats.expired++; note("llm_key_expired"); } else arm(); }, Math.max(0, Math.min(left, MAX_TIMER_MS)));
+        if (timer && typeof timer.unref === "function") timer.unref();
+    }
+
+    function wipeFile() {
+        if (!file || !fileOk) return;
+        try {
+            const size = fs.statSync(file).size;
+            const fd = fs.openSync(file, "r+");
+            try { fs.writeSync(fd, Buffer.alloc(size)); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+        } catch { /* nothing to overwrite */ }
+        try { fs.unlinkSync(file); } catch { /* already gone */ }
+    }
+
+    function persist(entry) {
+        if (!file || !fileOk) return;
+        try {
+            fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+            const tmp = `${file}.${process.pid}.tmp`;
+            const body = JSON.stringify({ v: 1, keyId: entry.keyId, endpoint: entry.endpoint, models: entry.models, expiresAt: entry.expiresAt, key: entry.key });
+            fs.writeFileSync(tmp, body, { mode: 0o600 });
+            fs.chmodSync(tmp, 0o600);
+            fs.renameSync(tmp, file);
+        } catch {
+            stats.persistErrors++;
+            warn("[la-llm-key] the key could not be written to its file; it stays in memory only");   // never the path, never the error text
+        }
+    }
+
+    function drop() { held = null; disarm(); wipeFile(); }
+
+    /** @returns {boolean} true = a usable key is held (also drops an expired one). */
+    function active() {
+        if (!held) return false;
+        if (held.expiresMs <= now()) { drop(); stats.expired++; note("llm_key_expired"); return false; }
+        return true;
+    }
+
+    const holder = {
+        stats,
+        /**
+         * The 2.1 `llmKey.set` already validated by the schema; this re-checks what the schema cannot (id = sha256(key), expiry in the future)
+         * and what a bug could break (shapes), so the holder is safe on its own.
+         * @returns {{ok:true, replaced:boolean} | {ok:false, code:"schema_violation"}}
+         */
+        set({ keyId, endpoint, key, models, expiresAt }) {
+            const expiresMs = Date.parse(expiresAt);
+            const shapesOk = SHA256.test(keyId) && typeof endpoint === "string" && ENDPOINT.test(endpoint) && typeof key === "string" && KEY.test(key)
+                && Array.isArray(models) && models.length >= 1 && models.length <= 32 && models.every((m) => typeof m === "string" && m.length > 0 && m.length <= 96) && Number.isFinite(expiresMs);
+            if (!shapesOk || sha256Hex(key) !== keyId || expiresMs <= now()) { stats.refused++; note("llm_key_refused"); return { ok: false, code: "schema_violation" }; }
+            const replaced = !!held && held.keyId !== keyId;
+            held = { keyId, endpoint: endpoint.replace(/\/+$/, ""), models: Object.freeze([...models]), expiresAt, expiresMs, key };
+            persist(held);
+            arm();
+            if (replaced) stats.replaced++;
+            stats.set++;
+            note("llm_key_set", { models: models.length, replaced });
+            return { ok: true, replaced };
+        },
+        /** @returns {{ok:true, dropped:boolean}} an id the holder does not have is a no-op (acked `accepted` all the same). */
+        revoke(keyId) {
+            if (held && typeof keyId === "string" && held.keyId === keyId) { drop(); stats.revoked++; note("llm_key_revoked"); return { ok: true, dropped: true }; }
+            stats.revokeUnknown++;
+            return { ok: true, dropped: false };
+        },
+        /** Loads the key file left by a previous run (when `file` is set): kept only when it is private, valid and not expired. */
+        load() {
+            if (!file || !fileOk) return false;
+            try {
+                const st = fs.statSync(file);
+                if (!st.isFile() || (st.mode & 0o077) !== 0 || st.size > 4096) { wipeFile(); return false; }   // readable by others or odd: never trusted
+                const o = JSON.parse(fs.readFileSync(file, "utf8"));
+                if (!o || o.v !== 1) { wipeFile(); return false; }
+                const r = holder.set({ keyId: o.keyId, endpoint: o.endpoint, key: o.key, models: o.models, expiresAt: o.expiresAt });
+                if (!r.ok) { wipeFile(); return false; }
+                stats.set--; // a reload is not a new delivery
+                return true;
+            } catch { return false; }
+        },
+        /**
+         * F3-10: does this reference (`job.assign.llm.keyRef`) name the key held right now? Compares in constant time and answers a boolean only:
+         * the id never leaves the holder. A reference is the key id or its first 8..64 hex characters (the `key_short` the control plane logs).
+         */
+        matches(ref) {
+            if (!active() || typeof ref !== "string" || !/^[0-9a-f]{8,64}$/.test(ref)) return false;
+            const a = Buffer.from(held.keyId.slice(0, ref.length));
+            const b = Buffer.from(ref);
+            return a.length === b.length && crypto.timingSafeEqual(a, b);
+        },
+        /** Metadata only. */
+        describe() { return active() ? { held: true, models: [...held.models], expiresAt: held.expiresAt } : { held: false }; },
+        get held() { return active(); },
+        /**
+         * The one way out for the key: an authorized request to the AI gateway the control plane named. `pathAndQuery` starts with one "/",
+         * the host is never the caller's choice, `authorization` from the caller is replaced, redirects are refused (a 3xx would carry the header elsewhere).
+         */
+        async request(pathAndQuery, init = {}, { fetchImpl = globalThis.fetch } = {}) {
+            if (!active()) throw new LlmKeyError(held ? "expired" : "no_key");
+            if (typeof pathAndQuery !== "string" || !PATH_AND_QUERY.test(pathAndQuery) || pathAndQuery.split("?")[0].split("/").includes("..")) throw new LlmKeyError("bad_path");
+            const url = held.endpoint + pathAndQuery;
+            if (new URL(url).origin !== new URL(held.endpoint).origin) throw new LlmKeyError("bad_path");
+            const headers = new Headers(init.headers || {});
+            headers.set("authorization", `Bearer ${held.key}`);
+            stats.requests++;
+            return fetchImpl(url, { ...init, headers, redirect: "error" });
+        },
+        close() { disarm(); held = null; },   // process shutdown: memory only; a key FILE is kept for the next start
+    };
+    return holder;
+}

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

@@ -8,6 +8,11 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createV2Link } from "./link.js";
 import { resolveContentHandlersConfig } from "./content-handlers/config.js";
+import { resolveLlmKeyConfig } from "./llm-key/config.js";
+import { resolveWebhookConfig } from "./webhooks/config.js";
+import { resolveLlmClientConfig } from "./llm/config.js";
+import { resolveJobsConfig } from "./jobs/config.js";
+import { loadContract } from "./contract.js";
 
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const WORKSPACE_ID = /^[A-Za-z0-9_.-]{0,64}$/;
@@ -35,7 +40,7 @@ async function diskFreeBytes(dir) {
 /**
  * @returns {Promise} the link, or null (with a warning) when v2 cannot run here: then the tunnel is the plain v1 client.
  */
-export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWorkspaceRoot, log = console, env = process.env }) {
+export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWorkspaceRoot, log = console, env = process.env, jobRunner = null, onJobResult = null, llmFetch = undefined }) {
     const tenant = String(tenantId || "").toLowerCase();
     if (!UUID.test(tenant)) { log.warn("[la-v2] off: the tenant id is not a UUID"); return null; }
     if (!agentId) { log.warn("[la-v2] off: no agent id (authorizationId in ~/.deepdebug/config.json or LOCAL_AGENT_ID)"); return null; }
@@ -59,8 +64,44 @@ export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWo
     // F3-11b: incident detector (logs -> incident.candidate, metadata only), behind LOCAL_AGENT_INCIDENT_DETECTOR (default off: nothing below changes anything)
     const { resolveIncidentDetectorConfig } = await import("../incident-detector/config.js");
     const incidentCfg = resolveIncidentDetectorConfig(env, (m) => log.warn(m));
-    const hasIncidentSource = incidentCfg.enabled && (incidentCfg.files.length > 0 || incidentCfg.stdin || !!incidentCfg.loki);
+    // F3-12 consumer: webhook.forward receiver, behind LOCAL_AGENT_WEBHOOK_FORWARD (default off). The incident detector is its local consumer:
+    // without it there is nobody to hand a webhook to, so the handler is NOT registered and no webhook capability is announced.
+    let webhookCfg = resolveWebhookConfig(env, (m) => log.warn(m), loadContract().limits);
+    if (webhookCfg.enabled && !incidentCfg.enabled) {
+        (log.error || log.warn).call(log, "[la-webhook] ERROR: LOCAL_AGENT_WEBHOOK_FORWARD=true but LOCAL_AGENT_INCIDENT_DETECTOR is not true: there is no local consumer, the webhook receiver is NOT registered and no webhook capability is announced");
+        webhookCfg = { enabled: false };
+    }
+    // F3-09 consumer: virtual LLM key of the AI gateway (config.update.llmKey), behind LOCAL_AGENT_LLM_KEY (default off)
+    const llmCfg = resolveLlmKeyConfig(env, (m) => log.warn(m));
+    // F3-10: LLM client (LOCAL_AGENT_LLM_CLIENT) and job.assign receiver (LOCAL_AGENT_JOBS), both default off. Both need DLP enforce (no opt-out);
+    // the client needs the key holder; the receiver needs a runner (and the client unless the runner says it does not think).
+    const dlpEnforce = async () => (await import("../dlp/index.js")).dlpConfigFromEnv(env).mode === "enforce";
+    const err = (m) => (log.error || log.warn).call(log, m);
+    let llmClientCfg = resolveLlmClientConfig(env, (m) => log.warn(m));
+    if (llmClientCfg.enabled && !llmCfg.enabled) { err("[la-llm] ERROR: LOCAL_AGENT_LLM_CLIENT=true but LOCAL_AGENT_LLM_KEY is not true: there is no key holder, the LLM client is NOT installed"); llmClientCfg = { enabled: false }; }
+    if (llmClientCfg.enabled && !(await dlpEnforce())) { err("[la-llm] ERROR: LOCAL_AGENT_LLM_CLIENT=true but LOCAL_AGENT_DLP_MODE is not enforce: prompts would leave this machine unmasked, the LLM client is NOT installed"); llmClientCfg = { enabled: false }; }
+    let jobsCfg = resolveJobsConfig(env, (m) => log.warn(m));
+    let runner = null;
+    if (jobsCfg.enabled) {
+        const { validateRunner } = await import("./jobs/manager.js");
+        const given = jobRunner && validateRunner(jobRunner) ? jobRunner : null;
+        const needsLlm = given ? given.needsLlm !== false : jobsCfg.runner === "smoke";
+        if (jobRunner && !given) err("[la-jobs] ERROR: the runner passed to buildV2Link does not implement start()/cancel(); it is ignored");
+        if (!given && !jobsCfg.runner) { err("[la-jobs] ERROR: LOCAL_AGENT_JOBS=true but there is no runner (LOCAL_AGENT_JOBS_RUNNER=smoke or an injected one): job.assign is NOT registered"); jobsCfg = { enabled: false }; }
+        else if (!(await dlpEnforce())) { err("[la-jobs] ERROR: LOCAL_AGENT_JOBS=true but LOCAL_AGENT_DLP_MODE is not enforce: job.assign is NOT registered and no job capability is announced"); jobsCfg = { enabled: false }; }
+        else if (needsLlm && !llmClientCfg.enabled) { err("[la-jobs] ERROR: LOCAL_AGENT_JOBS=true with a runner that needs the LLM client, but the client is not installed (LOCAL_AGENT_LLM_CLIENT, LOCAL_AGENT_LLM_KEY, DLP enforce): job.assign is NOT registered"); jobsCfg = { enabled: false }; }
+        else runner = given;
+    }
+    const hasIncidentSource = incidentCfg.enabled && (incidentCfg.files.length > 0 || incidentCfg.stdin || !!incidentCfg.loki || webhookCfg.enabled);
     const incidentCaps = hasIncidentSource ? ["incident.candidate"] : [];
+    const webhookCaps = webhookCfg.enabled ? ["webhook.forward", "webhook.chunked"] : [];
+    const llmCaps = llmCfg.enabled ? ["llm.key"] : [];
+    const jobCaps = jobsCfg.enabled ? ["job.assign"] : [];   // F3-10: this agent runs jobs (the CP sends job.assign only to a session that announced it)
+    // F3-10 (contract 2.1): `job.options` = the runner understands job.assign `options` (dryRun, createPullRequest, ...). Only a runner that declared supportsOptions
+    // (the smoke runner does); an injected one that did not never gets options, and the CP, without this capability, refuses a dry run instead of sending it.
+    const jobOptionCaps = jobsCfg.enabled && (runner ? runner.supportsOptions === true : jobsCfg.runner === "smoke") ? ["job.options"] : [];
+    // contract 2.1: announced only when a 2.1 feature is on, so with every flag off register/hello are exactly what they were
+    const v21Caps = webhookCaps.length || llmCaps.length || incidentCaps.length ? ["contract.v2.1"] : [];
     const link = createV2Link({
         log,
         sessionOptions: {
@@ -70,7 +111,10 @@ export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWo
             signing,
             laVersion: agentVersion(),
             // only what this build implements: the transport, the handshake and the v1 commands on the same connection
-            capabilities: ["protocol.v2", "v1.commands", "chunk.base64", ...contentCaps, ...incidentCaps],
+            capabilities: ["protocol.v2", "v1.commands", "chunk.base64", ...contentCaps, ...incidentCaps, ...webhookCaps, ...llmCaps, ...jobCaps, ...jobOptionCaps, ...v21Caps],
+            // contract 2.1 (e): `llm.key.held` is a snapshot taken at every connect (register and hello alike): announced only while the holder has a
+            // valid, unexpired key (a revoked or expired one is not announced from the next connection on). `link` is assigned below, before any attach.
+            dynamicCapabilities: () => (llmCfg.enabled && link.llm && link.llm.holder.held ? ["llm.key.held"] : []),
             getWorkspaces: () => {
                 const open = (wsManager?.list?.() || []).map((w) => ({
                     workspaceId: String(w.id || ""),
@@ -92,9 +136,32 @@ export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWo
         const { installContentHandlers } = await import("./content-handlers/install.js");
         installContentHandlers({ link, tenantId: tenant, wsManager, getWorkspaceRoot, config: contentCfg, env, log });
     }
+    if (llmCfg.enabled) {
+        const { installLlmKey } = await import("./llm-key/install.js");
+        const roots = () => [getWorkspaceRoot(), ...(wsManager?.list?.() || []).map((w) => w && w.root)].filter(Boolean);
+        installLlmKey({ link, config: llmCfg, workspaceRoots: roots, log });
+    }
+    if (llmClientCfg.enabled) {
+        const { installLlmClient } = await import("./llm/install.js");
+        installLlmClient({ link, config: llmClientCfg, tenantId: tenant, agentId, env, ...(llmFetch ? { fetchImpl: llmFetch } : {}) });
+    }
+    if (jobsCfg.enabled) {
+        const { installJobs } = await import("./jobs/install.js");
+        installJobs({ link, tenantId: tenant, wsManager, getWorkspaceRoot, config: jobsCfg, env, log, runner, onResult: onJobResult });
+    }
+    let webhookSource = null;
+    if (webhookCfg.enabled) {
+        const { createWebhookSource } = await import("../incident-detector/sources/webhook-source.js");
+        webhookSource = createWebhookSource({ maxEntries: webhookCfg.maxEntries, maxBytes: webhookCfg.maxBodyBytes, maxEntryBytes: incidentCfg.maxEntryBytes, maxStackLines: incidentCfg.maxStackLines });
+    }
     if (incidentCfg.enabled) {
         const { installIncidentDetector } = await import("../incident-detector/index.js");
-        installIncidentDetector({ link, workspaceId: WORKSPACE_ID.test(identityWs) ? identityWs : "", config: incidentCfg, env, log });
+        installIncidentDetector({ link, workspaceId: WORKSPACE_ID.test(identityWs) ? identityWs : "", config: incidentCfg, env, log, extraSources: webhookSource ? [webhookSource] : [], model: `stack-detector-${agentVersion()}` });
+    }
+    if (webhookSource) {
+        const { installWebhookReceiver } = await import("./webhooks/install.js");
+        const receiver = installWebhookReceiver({ link, config: webhookCfg });
+        receiver.setSink((webhook) => webhookSource.deliver(webhook));
     }
     return link;
 }

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),
+    };
+}