deepdebug-local-agent 1.8.0 → 1.9.0

package/src/la-protocol-v2/contract/config.update.schema.json

@@ -52,9 +52,93 @@
         },
         "dataPlaneMode": {
           "$ref": "defs.schema.json#/$defs/dataPlaneMode"
+        },
+        "llmKey": {
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "op": {
+                  "const": "set"
+                },
+                "keyId": {
+                  "$ref": "defs.schema.json#/$defs/sha256"
+                },
+                "endpoint": {
+                  "type": "string",
+                  "minLength": 12,
+                  "maxLength": 256,
+                  "pattern": "^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})?$"
+                },
+                "key": {
+                  "type": "string",
+                  "minLength": 16,
+                  "maxLength": 256,
+                  "pattern": "^[A-Za-z0-9._~+/=-]{16,256}$",
+                  "x-content-class": "secret"
+                },
+                "models": {
+                  "type": "array",
+                  "minItems": 1,
+                  "maxItems": 32,
+                  "uniqueItems": true,
+                  "items": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 96,
+                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]{0,95}$"
+                  }
+                },
+                "expiresAt": {
+                  "$ref": "defs.schema.json#/$defs/ts"
+                }
+              },
+              "required": [
+                "op",
+                "keyId",
+                "endpoint",
+                "key",
+                "models",
+                "expiresAt"
+              ]
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "op": {
+                  "const": "revoke"
+                },
+                "keyId": {
+                  "$ref": "defs.schema.json#/$defs/sha256"
+                }
+              },
+              "required": [
+                "op",
+                "keyId"
+              ]
+            }
+          ]
         }
       },
-      "minProperties": 1
+      "minProperties": 1,
+      "if": {
+        "type": "object",
+        "properties": {
+          "llmKey": true
+        },
+        "required": [
+          "llmKey"
+        ]
+      },
+      "then": {
+        "type": "object",
+        "properties": {
+          "llmKey": true
+        },
+        "maxProperties": 1
+      }
     },
     "seq": {
       "type": "integer",

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

@@ -94,7 +94,32 @@
         "clockEpochMs",
         "diskFreeBytes",
         "queueDepth"
-      ]
+      ],
+      "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/incident.candidate.schema.json

@@ -72,6 +72,17 @@
             "security",
             "other"
           ]
+        },
+        "stackBytes": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 16777216
+        },
+        "model": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 48,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:+-]{0,47}$"
         }
       },
       "required": [

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