deepdebug-local-agent 1.3.0 → 1.5.0

package/src/la-protocol-v2/contract/log.stats.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.visionhammer.io/la-protocol-v2/log.stats.schema.json",
+  "title": "LA protocol v2: log.stats (la->cp)",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "envelope.schema.json"
+    }
+  ],
+  "properties": {
+    "type": {
+      "const": "log.stats"
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "windowStart": {
+          "$ref": "defs.schema.json#/$defs/ts"
+        },
+        "windowSeconds": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 86400
+        },
+        "counts": {
+          "type": "array",
+          "maxItems": 64,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "category": {
+                "type": "string",
+                "enum": [
+                  "exception",
+                  "timeout",
+                  "http_5xx",
+                  "db",
+                  "oom",
+                  "security",
+                  "other"
+                ]
+              },
+              "count": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              }
+            },
+            "required": [
+              "category",
+              "count"
+            ]
+          }
+        }
+      },
+      "required": [
+        "windowStart",
+        "windowSeconds",
+        "counts"
+      ]
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "chunk": false,
+    "sig": false,
+    "paramsRaw": false,
+    "agentId": true
+  },
+  "required": [
+    "payload",
+    "agentId"
+  ]
+}

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

@@ -0,0 +1,106 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.visionhammer.io/la-protocol-v2/ready.schema.json",
+  "title": "LA protocol v2: ready (cp->la)",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "envelope.schema.json"
+    }
+  ],
+  "properties": {
+    "type": {
+      "const": "ready"
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "protocol": {
+          "const": 2
+        },
+        "sessionId": {
+          "$ref": "defs.schema.json#/$defs/uuid"
+        },
+        "resumed": {
+          "type": "boolean"
+        },
+        "peerLastSeq": {
+          "$ref": "defs.schema.json#/$defs/seq"
+        },
+        "limits": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "maxFrameBytes": {
+              "type": "integer",
+              "minimum": 1024,
+              "maximum": 49152
+            },
+            "chunkRawBytes": {
+              "type": "integer",
+              "minimum": 1024,
+              "maximum": 32768
+            },
+            "maxChunks": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 64
+            },
+            "ackTimeoutMs": {
+              "type": "integer",
+              "minimum": 100,
+              "maximum": 60000
+            },
+            "maxRetries": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 3
+            },
+            "heartbeatSeconds": {
+              "type": "integer",
+              "minimum": 5,
+              "maximum": 300
+            },
+            "contentFirstByteMs": {
+              "type": "integer",
+              "minimum": 100,
+              "maximum": 60000
+            },
+            "contentTotalMs": {
+              "type": "integer",
+              "minimum": 100,
+              "maximum": 120000
+            }
+          },
+          "required": [
+            "maxFrameBytes",
+            "chunkRawBytes",
+            "maxChunks",
+            "ackTimeoutMs",
+            "maxRetries",
+            "heartbeatSeconds"
+          ]
+        }
+      },
+      "required": [
+        "protocol",
+        "sessionId",
+        "resumed",
+        "peerLastSeq",
+        "limits"
+      ]
+    },
+    "seq": {
+      "const": 0
+    },
+    "chunk": false,
+    "sig": true,
+    "paramsRaw": true
+  },
+  "required": [
+    "payload",
+    "sig",
+    "paramsRaw"
+  ]
+}

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

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.visionhammer.io/la-protocol-v2/register.schema.json",
+  "title": "LA protocol v2: register (la->cp)",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "envelope.schema.json"
+    }
+  ],
+  "properties": {
+    "type": {
+      "const": "register"
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "protocol": {
+          "const": 2
+        },
+        "laVersion": {
+          "$ref": "defs.schema.json#/$defs/semver"
+        },
+        "capabilities": {
+          "type": "array",
+          "maxItems": 32,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "defs.schema.json#/$defs/capability"
+          }
+        },
+        "signatureMode": {
+          "$ref": "defs.schema.json#/$defs/signatureMode"
+        },
+        "workspaces": {
+          "type": "array",
+          "maxItems": 64,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "workspaceId": {
+                "$ref": "defs.schema.json#/$defs/workspaceId"
+              },
+              "pathSha256": {
+                "$ref": "defs.schema.json#/$defs/sha256"
+              }
+            },
+            "required": [
+              "workspaceId"
+            ]
+          }
+        },
+        "resume": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "sessionId": {
+              "$ref": "defs.schema.json#/$defs/uuid"
+            },
+            "lastRecvSeq": {
+              "$ref": "defs.schema.json#/$defs/seq"
+            }
+          },
+          "required": [
+            "sessionId",
+            "lastRecvSeq"
+          ]
+        }
+      },
+      "required": [
+        "protocol",
+        "laVersion",
+        "capabilities",
+        "signatureMode",
+        "workspaces"
+      ]
+    },
+    "seq": {
+      "const": 0
+    },
+    "chunk": false,
+    "sig": false,
+    "paramsRaw": false,
+    "agentId": true
+  },
+  "required": [
+    "payload",
+    "agentId"
+  ]
+}

package/src/la-protocol-v2/contract/scan.upload.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.visionhammer.io/la-protocol-v2/scan.upload.schema.json",
+  "title": "LA protocol v2: scan.upload (cp->la)",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "envelope.schema.json"
+    }
+  ],
+  "properties": {
+    "type": {
+      "const": "scan.upload"
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "scanId": {
+          "$ref": "defs.schema.json#/$defs/uuid"
+        },
+        "signedPutUrl": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2048,
+          "pattern": "^https://[^\\s]{1,2040}$",
+          "x-large-metadata": true
+        },
+        "maxBytes": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 5368709120
+        },
+        "expiresAt": {
+          "$ref": "defs.schema.json#/$defs/ts"
+        }
+      },
+      "required": [
+        "scanId",
+        "signedPutUrl",
+        "maxBytes",
+        "expiresAt"
+      ]
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "chunk": false,
+    "sig": true,
+    "paramsRaw": true
+  },
+  "required": [
+    "payload",
+    "sig",
+    "paramsRaw"
+  ]
+}

package/src/la-protocol-v2/contract/scan.uploaded.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.visionhammer.io/la-protocol-v2/scan.uploaded.schema.json",
+  "title": "LA protocol v2: scan.uploaded (la->cp)",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "envelope.schema.json"
+    }
+  ],
+  "properties": {
+    "type": {
+      "const": "scan.uploaded"
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "scanId": {
+          "$ref": "defs.schema.json#/$defs/uuid"
+        },
+        "bytes": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 5368709120
+        },
+        "sha256": {
+          "$ref": "defs.schema.json#/$defs/sha256"
+        }
+      },
+      "required": [
+        "scanId",
+        "bytes",
+        "sha256"
+      ]
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "chunk": false,
+    "sig": false,
+    "paramsRaw": false,
+    "agentId": true
+  },
+  "required": [
+    "payload",
+    "agentId"
+  ]
+}

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

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.visionhammer.io/la-protocol-v2/webhook.forward.schema.json",
+  "title": "LA protocol v2: webhook.forward (cp->la)",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "envelope.schema.json"
+    }
+  ],
+  "properties": {
+    "type": {
+      "const": "webhook.forward"
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "webhookId": {
+          "$ref": "defs.schema.json#/$defs/uuid"
+        },
+        "source": {
+          "type": "string",
+          "enum": [
+            "sentry",
+            "alertmanager",
+            "ios",
+            "sonar",
+            "snyk",
+            "other"
+          ]
+        },
+        "contentType": {
+          "type": "string",
+          "enum": [
+            "application/json",
+            "text/plain"
+          ]
+        },
+        "bodyB64": {
+          "type": "string",
+          "minLength": 0,
+          "maxLength": 12288,
+          "pattern": "^[A-Za-z0-9+/]*={0,2}$",
+          "x-content-class": "transit"
+        }
+      },
+      "required": [
+        "webhookId",
+        "source",
+        "contentType",
+        "bodyB64"
+      ]
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "chunk": false,
+    "sig": true,
+    "paramsRaw": true
+  },
+  "required": [
+    "payload",
+    "sig",
+    "paramsRaw"
+  ]
+}

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

@@ -0,0 +1,90 @@
+/**
+ * contract.js - the CP <-> LA protocol v2 contract (F3-22) as the Local Agent uses it.
+ *
+ * The JSON Schemas, index.json (allowlist, direction, signed/control flags, limits) and the provenance
+ * of the copy are in ./contract (CONTRACT_SOURCE.json: gateway commit + sha256 of every file). Every
+ * frame the Local Agent receives AND every frame it sends is validated here with Ajv (draft 2020-12,
+ * strict). No schema keyword is interpreted by hand and nothing is added to the contract.
+ *
+ * validateFrame(frame) -> { ok } | { ok:false, code, keywords[], rules[] }
+ *   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
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import Ajv2020 from "ajv/dist/2020.js";
+
+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) {
+    const rules = [];
+    if (frame && frame.type === "content.response" && frame.payload && typeof frame.payload.data === "string") {
+        const d = frame.payload.data;
+        if (!BASE64.test(d) || Buffer.from(d, "base64").length !== frame.payload.byteLength) rules.push("byteLength-decoded");
+    }
+    return rules;
+}
+
+let singleton = null;
+
+/** Loads and compiles the contract once per process (about 20 ms). */
+export function loadContract() {
+    if (singleton) return singleton;
+    const index = readJson(path.join(DIR, "index.json"));
+    const ajv = new Ajv2020({ strict: true, allErrors: true });
+    ajv.addKeyword("x-content-class");
+    ajv.addKeyword("x-large-metadata");
+    for (const f of fs.readdirSync(DIR).filter((n) => n.endsWith(".schema.json"))) ajv.addSchema(readJson(path.join(DIR, f)));
+    const validators = new Map();
+    for (const [type, info] of Object.entries(index.types)) {
+        const v = ajv.getSchema(index.baseId + info.schema);
+        if (!v) throw new Error(`contract: no schema for ${type}`);
+        validators.set(type, v);
+    }
+    const defs = readJson(path.join(DIR, "defs.schema.json"));
+    const errorCodes = defs.$defs.errorCode.enum;
+
+    const typeInfo = (type) => (typeof type === "string" && Object.hasOwn(index.types, type) ? index.types[type] : null);
+    const accepts = (info, dir) => info.direction === "both" || info.direction === dir;
+
+    singleton = Object.freeze({
+        index,
+        limits: Object.freeze({ ...index.limits }),
+        errorCodes,
+        typeInfo,
+        /** Types the Local Agent may receive (cp->la, both). */
+        inboundTypes: Object.entries(index.types).filter(([, i]) => accepts(i, "cp->la")).map(([t]) => t),
+        /** Types the Local Agent may send (la->cp, both). */
+        outboundTypes: Object.entries(index.types).filter(([, i]) => accepts(i, "la->cp")).map(([t]) => t),
+        canReceive: (type) => { const i = typeInfo(type); return !!i && accepts(i, "cp->la"); },
+        canSend: (type) => { const i = typeInfo(type); return !!i && accepts(i, "la->cp"); },
+        validateFrame(frame) {
+            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");
+                envelope(frame);
+                return { ok: false, code: "schema_violation", keywords: (envelope.errors || []).map((e) => e.keyword), rules: [] };
+            }
+            const info = typeInfo(frame.type);
+            if (!info) return { ok: false, code: "unknown_type", keywords: ["enum"], rules: [] };
+            const validate = validators.get(frame.type);
+            const schemaOk = validate(frame);
+            if (!schemaOk) {
+                const errs = validate.errors || [];
+                const keywords = errs.map((e) => e.keyword);
+                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 };
+            return { ok: true };
+        },
+    });
+    return singleton;
+}

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

@@ -0,0 +1,34 @@
+/**
+ * errors.js - wire error codes of protocol v2 (defs.schema.json#/$defs/errorCode).
+ *
+ * The close code of a fatal error is 4400 + the position of the code in the schema enum (the gateway
+ * pins the same rule; `timeout` = 4420). Which codes are fatal / retryable mirrors the gateway's
+ * LaV2ErrorCode: a test pins this table against the enum of the copied contract.
+ */
+export const ERROR_CODES = Object.freeze([
+    "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", "clock_skew",
+    "protocol_unsupported", "unauthorized", "agent_offline", "timeout", "rate_limited", "internal",
+]);
+
+// retryable (the peer may repeat the operation unchanged later)
+const RETRYABLE = new Set(["seq_gap", "agent_offline", "timeout", "rate_limited", "internal"]);
+// NOT fatal: the connection stays up after the error frame
+const NON_FATAL = new Set(["protocol_unsupported", "agent_offline", "timeout", "rate_limited", "internal"]);
+
+export const isKnownCode = (code) => ERROR_CODES.includes(code);
+export const isFatal = (code) => isKnownCode(code) && !NON_FATAL.has(code);
+export const isRetryable = (code) => RETRYABLE.has(code);
+export const closeCodeOf = (code) => 4400 + Math.max(0, ERROR_CODES.indexOf(code));
+
+/**
+ * A refusal with a wire code. `message` never carries frame content: only the code and a fixed reason.
+ */
+export class ProtocolError extends Error {
+    constructor(code, reason = "") {
+        super(reason ? `${code}: ${reason}` : code);
+        this.name = "ProtocolError";
+        this.code = isKnownCode(code) ? code : "internal";
+    }
+}

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

@@ -0,0 +1,8 @@
+export { PROTOCOL_V2_FLAG, resolveProtocolV2Config, resolveAgentId } from "./config.js";
+export { loadContract, semanticRules } from "./contract.js";
+export { ERROR_CODES, ProtocolError, closeCodeOf, isFatal, isRetryable } from "./errors.js";
+export { parseStrict } from "./strict-json.js";
+export { ChunkStreamTracker, chunkCount } from "./chunks.js";
+export { V2Session, STATE } from "./session.js";
+export { sendContent, sendContentFailure } from "./content.js";
+export { createV2Link, wsTransport, isV2Frame } from "./link.js";

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

@@ -0,0 +1,93 @@
+/**
+ * link.js - glue between the v1 WS tunnel in server.js and the v2 session (F3-05b).
+ *
+ * The tunnel keeps owning the socket, the reconnect loop, the text `ping` and every v1 command. With
+ * LOCAL_AGENT_PROTOCOL_V2=true it asks the link, per connection:
+ *   begin(ws, legacyRegister)  -> true: v2 negotiation started (register + hello); the legacy register is sent
+ *                                 later ONLY if the gateway does not speak v2 (no `ready` in handshakeTimeoutMs,
+ *                                 or `error protocol_unsupported`); false: nothing to do, send the legacy register now
+ *   handleMessage(ws, data)    -> true when the frame was a v2 frame (consumed); false: it is a v1 command (or noise)
+ *                                 and the tunnel runs its existing handler. v1 commands keep working on a v2
+ *                                 connection (Edu 2026-10-29: transition; v1 is decommissioned later)
+ *   onClose(ws)                -> the session survives for a resume
+ * After a fallback the link stays on v1 for `fallbackMs` (a gateway without v2 would otherwise cost 10 s per reconnect).
+ */
+import { V2Session } from "./session.js";
+
+/** Adapts a `ws` WebSocket to the transport the session writes to. */
+export function wsTransport(ws) {
+    return {
+        send: (text) => { if (ws.readyState === 1) ws.send(text); },
+        close: (code, reason) => { try { ws.close(code, String(reason).slice(0, 100)); } catch { /* already closed */ } },
+        bufferedAmount: () => ws.bufferedAmount || 0,
+    };
+}
+
+/** v2 frames are the JSON objects that carry `schemaVersion`; a v1 command has `command` and no `schemaVersion`. */
+export function isV2Frame(text, maxFrameBytes) {
+    if (text.length > maxFrameBytes) return /"schemaVersion"/.test(text.slice(0, 1024)); // too big to be valid, but still a v2 attempt
+    if (text.charCodeAt(0) !== 0x7b) return false;
+    try {
+        const o = JSON.parse(text);
+        return o !== null && typeof o === "object" && !Array.isArray(o) && Object.hasOwn(o, "schemaVersion");
+    } catch {
+        return false;
+    }
+}
+
+export function createV2Link({ sessionOptions, log = console, now = Date.now, fallbackMs = 600_000 }) {
+    const session = new V2Session({ ...sessionOptions, log: { info: (m) => (log.info || log.log).call(log, m), warn: (m) => log.warn(m) }, now });
+    let current = null;     // { ws, transport, mode: 'negotiating' | 'v2' | 'v1' }
+    let fallbackUntil = 0;
+
+    const toV1 = (conn, legacyRegister, why) => {
+        if (current !== conn || conn.mode === "v1") return;
+        conn.mode = "v1";
+        fallbackUntil = now() + fallbackMs;
+        session.abandon();
+        log.warn(`[la-v2] gateway does not speak protocol v2 (${why}); using v1 on this connection`);
+        legacyRegister();
+    };
+
+    session.on("ready", () => { if (current && current.mode === "negotiating") current.mode = "v2"; });
+
+    return {
+        session,
+        /** @returns {boolean} true when v2 negotiation owns the registration of this connection */
+        begin(ws, legacyRegister) {
+            if (now() < fallbackUntil) return false;
+            const conn = { ws, transport: wsTransport(ws), mode: "negotiating" };
+            current = conn;
+            session.removeAllListeners("handshake-timeout");
+            session.removeAllListeners("unsupported");
+            session.removeAllListeners("rejected");
+            session.once("handshake-timeout", () => toV1(conn, legacyRegister, "no ready in time"));
+            session.once("unsupported", () => toV1(conn, legacyRegister, "protocol_unsupported"));
+            session.on("rejected", (code) => log.warn(`[la-v2] gateway refused the v2 handshake: ${code}`));
+            try {
+                session.attach(conn.transport);
+            } catch (e) {
+                log.warn(`[la-v2] could not start the handshake (${e.code || "internal"}); using v1`);
+                current = null;
+                return false;
+            }
+            return true;
+        },
+        handleMessage(ws, text, isBinary = false) {
+            const conn = current;
+            if (!conn || conn.ws !== ws || conn.mode === "v1") return false;
+            if (isBinary) { session.handleText("", conn.transport, true); return true; }
+            if (!isV2Frame(text, session.limits.maxFrameBytes)) return false;
+            session.handleText(text, conn.transport);
+            return true;
+        },
+        onClose(ws) {
+            const conn = current;
+            if (!conn || conn.ws !== ws) return;
+            current = null;
+            if (conn.mode !== "v1") session.detach(conn.transport);
+        },
+        get mode() { return current ? current.mode : null; },
+        close() { session.close(); current = null; },
+    };
+}