deepdebug-local-agent 1.7.0 → 1.9.0

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

@@ -1,5 +1,6 @@
 {
   "protocol": 2,
+  "revision": "2.1",
   "baseId": "https://schemas.visionhammer.io/la-protocol-v2/",
   "limits": {
     "maxFrameBytes": 49152,
@@ -12,7 +13,13 @@
     "heartbeatSeconds": 30,
     "sessionDeadSeconds": 90,
     "dedupeWindowSeconds": 600,
-    "clockSkewSeconds": 60
+    "clockSkewSeconds": 60,
+    "webhookChunkRawBytes": 16384,
+    "webhookMaxChunks": 64,
+    "webhookMaxBytes": 1048576,
+    "webhookSingleFrameRawBytes": 9216,
+    "webhookAssemblySeconds": 30,
+    "webhookMaxOpenAssemblies": 4
   },
   "types": {
     "register": {
@@ -118,7 +125,7 @@
       "direction": "cp->la",
       "control": false,
       "signed": true,
-      "contentClass": "none"
+      "contentClass": "secret"
     },
     "scan.upload": {
       "schema": "scan.upload.schema.json",

package/src/la-protocol-v2/contract/ready.schema.json

@@ -81,6 +81,14 @@
             "maxRetries",
             "heartbeatSeconds"
           ]
+        },
+        "capabilities": {
+          "type": "array",
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "defs.schema.json#/$defs/capability"
+          }
         }
       },
       "required": [

package/src/la-protocol-v2/contract/register.schema.json

@@ -75,7 +75,32 @@
         "capabilities",
         "signatureMode",
         "workspaces"
-      ]
+      ],
+      "if": {
+        "properties": {
+          "capabilities": {
+            "type": "array",
+            "maxItems": 32,
+            "contains": {
+              "const": "llm.key.held"
+            }
+          }
+        },
+        "required": [
+          "capabilities"
+        ]
+      },
+      "then": {
+        "properties": {
+          "capabilities": {
+            "type": "array",
+            "maxItems": 32,
+            "contains": {
+              "const": "llm.key"
+            }
+          }
+        }
+      }
     },
     "seq": {
       "const": 0

package/src/la-protocol-v2/contract/webhook.forward.schema.json

@@ -40,9 +40,17 @@
         "bodyB64": {
           "type": "string",
           "minLength": 0,
-          "maxLength": 12288,
+          "maxLength": 21848,
           "pattern": "^[A-Za-z0-9+/]*={0,2}$",
           "x-content-class": "transit"
+        },
+        "bodyBytes": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 1048576
+        },
+        "bodySha256": {
+          "$ref": "defs.schema.json#/$defs/sha256"
         }
       },
       "required": [
@@ -57,7 +65,7 @@
       "minimum": 1,
       "maximum": 9007199254740991
     },
-    "chunk": false,
+    "chunk": true,
     "sig": true,
     "paramsRaw": true
   },
@@ -65,5 +73,66 @@
     "payload",
     "sig",
     "paramsRaw"
-  ]
+  ],
+  "if": {
+    "type": "object",
+    "properties": {
+      "chunk": true
+    },
+    "required": [
+      "chunk"
+    ]
+  },
+  "then": {
+    "type": "object",
+    "properties": {
+      "payload": {
+        "type": "object",
+        "properties": {
+          "bodyBytes": true,
+          "bodySha256": true
+        },
+        "required": [
+          "bodyBytes",
+          "bodySha256"
+        ]
+      }
+    }
+  },
+  "else": {
+    "type": "object",
+    "properties": {
+      "payload": {
+        "type": "object",
+        "properties": {
+          "bodyB64": {
+            "type": "string",
+            "maxLength": 12288
+          }
+        },
+        "not": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "bodyBytes": true
+              },
+              "required": [
+                "bodyBytes"
+              ]
+            },
+            {
+              "type": "object",
+              "properties": {
+                "bodySha256": true
+              },
+              "required": [
+                "bodySha256"
+              ]
+            }
+          ]
+        }
+      }
+    }
+  }
 }

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

@@ -10,8 +10,10 @@
  *   unknown_type       `type` is not in the allowlist (index.json)
  *   schema_violation   the frame does not satisfy the closed schema of its type
  *   payload_too_large  ... because a string under /payload is above its maxLength (same rule as the gateway)
- *   chunk_inconsistent content.response whose byteLength differs from the decoded size of data
+ *   chunk_inconsistent content.response whose byteLength differs from the decoded size of data; webhook.forward chunk of the wrong size (2.1)
+ *   (rule llmKey-id-sha256 of 2.1 is a schema_violation: the keyId is not the sha256 of the key)
  */
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -21,16 +23,52 @@ const DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "contract");
 const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
 const readJson = (p) => JSON.parse(fs.readFileSync(p, "utf8"));
 
-/** Rules JSON Schema cannot state (README of the contract): byteLength == size of the decoded `data`. */
-export function semanticRules(frame) {
+/** The base64 alphabet with padding, canonical form (no whitespace, length multiple of 4). */
+export const isCanonicalBase64 = (s) => typeof s === "string" && BASE64.test(s);
+const decodedLength = (s) => (isCanonicalBase64(s) ? Buffer.from(s, "base64").length : -1);
+
+/**
+ * Contract 2.1, rule `webhook-chunk-size`: a chunked webhook.forward has total == max(1, ceil(bodyBytes / chunkRaw)), a non-last chunk
+ * decodes to exactly chunkRaw bytes and the last one to bodyBytes - chunkRaw * (total - 1). Stateless (one frame).
+ * @returns {boolean} true when the frame BREAKS the rule
+ */
+export function webhookChunkSizeViolation(payload, chunk, chunkRaw = 16384) {
+    if (!payload || !chunk || typeof payload.bodyB64 !== "string" || !Number.isSafeInteger(payload.bodyBytes)) return false;
+    const { index, total } = chunk;
+    const expectedTotal = Math.max(1, Math.ceil(payload.bodyBytes / chunkRaw));
+    const expectedSize = index < total - 1 ? chunkRaw : payload.bodyBytes - chunkRaw * (total - 1);
+    return total !== expectedTotal || index >= total || decodedLength(payload.bodyB64) !== expectedSize;
+}
+
+/** Contract 2.1, rule `llmKey-id-sha256`: llmKey (op set) keyId == lower-case hex sha256 of the UTF-8 bytes of key. @returns {boolean} true when it BREAKS the rule */
+export function llmKeyIdMismatch(llmKey) {
+    if (!llmKey || llmKey.op !== "set" || typeof llmKey.key !== "string") return false;
+    return crypto.createHash("sha256").update(Buffer.from(llmKey.key, "utf8")).digest("hex") !== llmKey.keyId;
+}
+
+/** Rule -> wire code (the `code` the vectors expect). */
+export const RULE_CODES = Object.freeze({ "byteLength-decoded": "chunk_inconsistent", "webhook-chunk-size": "chunk_inconsistent", "llmKey-id-sha256": "schema_violation" });
+
+/**
+ * Rules JSON Schema cannot state (README of the contract): byteLength == size of the decoded `data` (content.response), and since 2.1
+ * `webhook-chunk-size` and `llmKey-id-sha256`. `skip` names rules the caller applies itself later (the session defers the two 2.1
+ * rules to the handlers: they are answered with a non-fatal `rejected` ack, in the order of the reference model: state first).
+ */
+export function semanticRules(frame, { skip = [] } = {}) {
     const rules = [];
-    if (frame && frame.type === "content.response" && frame.payload && typeof frame.payload.data === "string") {
+    const on = (name) => !skip.includes(name);
+    if (frame && frame.type === "content.response" && frame.payload && typeof frame.payload.data === "string" && on("byteLength-decoded")) {
         const d = frame.payload.data;
         if (!BASE64.test(d) || Buffer.from(d, "base64").length !== frame.payload.byteLength) rules.push("byteLength-decoded");
     }
+    if (frame && frame.type === "webhook.forward" && frame.chunk && on("webhook-chunk-size")
+        && webhookChunkSizeViolation(frame.payload, frame.chunk, loadLimits().webhookChunkRawBytes)) rules.push("webhook-chunk-size");
+    if (frame && frame.type === "config.update" && frame.payload && on("llmKey-id-sha256") && llmKeyIdMismatch(frame.payload.llmKey)) rules.push("llmKey-id-sha256");
     return rules;
 }
 
+const loadLimits = () => loadContract().limits;
+
 let singleton = null;
 
 /** Loads and compiles the contract once per process (about 20 ms). */
@@ -73,7 +111,7 @@ export function loadContract() {
             if (!v) throw new Error(`contract: no schema ${schemaFile}`);
             return v(value) === true;
         },
-        validateFrame(frame) {
+        validateFrame(frame, { skipRules = [] } = {}) {
             if (frame === null || typeof frame !== "object" || typeof frame.type !== "string") {
                 // no `type` at all (a v1 command frame, say): the envelope says what is missing
                 const envelope = ajv.getSchema(index.baseId + "envelope.schema.json");
@@ -90,8 +128,8 @@ export function loadContract() {
                 const tooLong = errs.some((e) => e.keyword === "maxLength" && String(e.instancePath).startsWith("/payload"));
                 return { ok: false, code: tooLong ? "payload_too_large" : "schema_violation", keywords, rules: [] };
             }
-            const rules = semanticRules(frame);
-            if (rules.length) return { ok: false, code: "chunk_inconsistent", keywords: [], rules };
+            const rules = semanticRules(frame, { skip: skipRules });
+            if (rules.length) return { ok: false, code: RULE_CODES[rules[0]] || "chunk_inconsistent", keywords: [], rules };
             return { ok: true };
         },
     });

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

@@ -0,0 +1,29 @@
+/**
+ * config.js - LOCAL_AGENT_LLM_KEY flag and limits of the LLM key holder (F3-09 consumer, contract 2.1 (a)).
+ *
+ *   false (default)  `config.update` keeps being acked `rejected protocol_unsupported`, the capability `llm.key` is NOT announced, so
+ *                    the control plane never sends a key: nothing of this folder is loaded.
+ *   true             the agent handles `config.update.llmKey` (set / revoke) and keeps the virtual key of the AI gateway IN MEMORY.
+ *                    Needs LOCAL_AGENT_PROTOCOL_V2=true as well (without a v2 session nobody sends a key: the flag does nothing).
+ *
+ *   LOCAL_AGENT_LLM_KEY_FILE   optional absolute path of a file (mode 0600, directory 0700) where the key survives a restart. It must be
+ *                              OUTSIDE every workspace (a workspace is what the content handlers may serve). Unset = memory only.
+ * Unset/empty/unrecognised = false (an unknown value must never open the door to a key).
+ */
+import path from "node:path";
+
+export const LLM_KEY_FLAG = "LOCAL_AGENT_LLM_KEY";
+
+const TRUE = new Set(["true", "1", "yes", "on"]);
+const FALSE = new Set(["", "false", "0", "no", "off"]);
+
+export function resolveLlmKeyConfig(env = process.env, warn = console.warn) {
+    const raw = String(env[LLM_KEY_FLAG] ?? "").trim().toLowerCase();
+    if (!TRUE.has(raw)) {
+        if (!FALSE.has(raw)) warn(`[la-llm-key] unrecognised ${LLM_KEY_FLAG} value; the LLM key handler stays off`);
+        return { enabled: false };
+    }
+    let file = String(env.LOCAL_AGENT_LLM_KEY_FILE ?? "").trim() || null;
+    if (file && !path.isAbsolute(file)) { warn("[la-llm-key] LOCAL_AGENT_LLM_KEY_FILE must be an absolute path; the key stays in memory only"); file = null; }
+    return { enabled: true, file: file ? path.normalize(file) : null };
+}

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

@@ -0,0 +1,33 @@
+/**
+ * handler.js - `config.update` with `llmKey` (F3-09 consumer, contract 2.1 (a)). Registered by install.js only with
+ * LOCAL_AGENT_LLM_KEY=true. The frame was already validated against the closed schema (a frame that carries `llmKey` carries nothing else);
+ * the session defers the rule `llmKey-id-sha256` to here, so a wrong id is a non-fatal `rejected schema_violation`, as the README says.
+ *
+ *   set     accepted | rejected schema_violation (id is not the sha256 of the key, key already expired)
+ *   revoke  accepted (also for an id this agent does not hold: it never says which key it has)
+ *   others  a `config.update` WITHOUT llmKey (flags, dlp hash, ...) is what it was before: rejected protocol_unsupported
+ * The answer is the plain ack: it never carries the key, the id or any text. Nothing here logs a value of the frame.
+ */
+import { llmKeyIdMismatch } from "../contract.js";
+
+export function createLlmKeyHandler({ holder }) {
+    const stats = { frames: 0, set: 0, revoke: 0, rejected: 0, other: 0 };
+    return {
+        stats,
+        handle(ctx) {
+            stats.frames++;
+            const k = ctx.params && ctx.params.llmKey;
+            if (!k) { stats.other++; return { reject: "protocol_unsupported" }; }
+            if (k.op === "revoke") { stats.revoke++; holder.revoke(k.keyId); return { accept: true }; }
+            if (k.op === "set") {
+                if (llmKeyIdMismatch(k)) { stats.rejected++; return { reject: "schema_violation" }; }
+                const r = holder.set(k);
+                if (!r.ok) { stats.rejected++; return { reject: r.code }; }
+                stats.set++;
+                return { accept: true };
+            }
+            stats.rejected++;
+            return { reject: "schema_violation" };
+        },
+    };
+}

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

@@ -0,0 +1,21 @@
+/**
+ * install.js - puts the LLM key holder on a v2 link (F3-09 consumer). Called by runtime.js only when LOCAL_AGENT_LLM_KEY=true and v2 is on.
+ * Returns link.llm = { holder, handler, request(path, init) }.
+ */
+import { createAudit } from "../content-handlers/audit.js";
+import { createLlmKeyHolder } from "./store.js";
+import { createLlmKeyHandler } from "./handler.js";
+
+export const LLM_KEY_CAPABILITIES = Object.freeze(["llm.key"]);
+
+export function installLlmKey({ link, config, workspaceRoots = () => [], log = console, now = Date.now }) {
+    const audit = createAudit({});   // ring only: a key event never goes to a file the operator did not ask for
+    const holder = createLlmKeyHolder({ file: config.file, workspaceRoots, now, audit, log });
+    holder.load();
+    const handler = createLlmKeyHandler({ holder });
+    link.session.setHandler("config.update", (ctx) => handler.handle(ctx));
+    const closeLink = link.close.bind(link);
+    link.close = () => { holder.close(); closeLink(); };
+    link.llm = { holder, handler, audit, request: (p, init, opts) => holder.request(p, init, opts) };
+    return link.llm;
+}

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

@@ -0,0 +1,173 @@
+/**
+ * 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; }
+        },
+        /** 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,9 @@ 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 { 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}$/;
@@ -56,6 +59,24 @@ export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWo
         }
     }
     const contentCaps = contentCfg.enabled ? ["content.diff", "content.file", "content.file.list"] : []; // content.file.list: F3-07c, how the front finds out what exists (the gateway only sends file.list to agents that announce it)
+    // 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));
+    // 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));
+    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"] : [];
+    // 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: {
@@ -65,7 +86,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],
+            capabilities: ["protocol.v2", "v1.commands", "chunk.base64", ...contentCaps, ...incidentCaps, ...webhookCaps, ...llmCaps, ...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 || ""),
@@ -87,5 +111,24 @@ 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 });
+    }
+    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, 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;
 }