deepdebug-local-agent 1.2.0 → 1.4.0

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

@@ -0,0 +1,103 @@
+# Gateway <-> Local Agent WebSocket protocol v2 (contract, F3-22)
+
+Machine-readable contract for the control-plane (CP, gateway) <-> Local Agent (LA) channel, shared by both
+sides. Design: vault `10 Library/Plans/Fase 3 Desenho Tecnico 2026-10-28.md` sec. 4.2. Status: the gateway
+implements it behind `deepdebug.agent-ws.protocol-v2.enabled` (default off, F3-05a); the LA side (F3-05b) does not
+exist yet. v1 is untouched. The gateway packages `*.schema.json` + `index.json` from this folder as classpath
+`la-protocol-v2/` (pom resource; both Dockerfiles copy this folder), so this folder stays the only source.
+
+## Files
+- `envelope.schema.json`: common frame, closed (`additionalProperties:false`). `<type>.schema.json` (21):
+  one per allowlisted type, each `$ref`s the envelope and closes `payload`. `defs.schema.json`: shared types.
+- `index.json`: allowlist, direction, signed/control flags, content class per type, and the limits below.
+- `vectors/<type>.vectors.json` (+ `cross-type`): valid and invalid messages with `expect` (`valid`, error `code`,
+  optional JSON Schema `keyword`, optional session `rule`). `vectors/traces/*.json`: whole sessions for the stateful rules.
+
+## Envelope
+`{schemaVersion:2, type, msgId(uuid), seq, ack?, requestId?, tenantId, agentId?, workspaceId, ts, chunk?, paramsRaw?, sig?, payload}`.
+CP->LA frames carry `paramsRaw` (the exact signed JSON, which must equal `payload`) and `sig` (Ed25519, same
+`VH-AGENT-SIG-V1` canonical as v1); LA->CP frames carry `agentId` (required in EVERY LA->CP frame, `ack` and `error` included: the gateway refuses one without it as
+`agent_mismatch`; the per-type schemas of `ack`/`error` require it for both directions, and the gateway always sets it on its own)
+and never a signature (F3-X3 may add one).
+`ack` = highest contiguous `seq` received from the peer, piggybacked on any frame. The design's flat fields
+live under `payload`; its `reqId` is `requestId`; `chunkNo,last` is `chunk{index,total,last}` (index from 0).
+
+## Limits (index.json)
+Frame <= 48 KiB UTF-8; chunk <= 32 KiB raw (43692 base64 chars); <= 64 chunks (2 MiB per response);
+ack timeout 5 s, <= 3 retransmissions; handshake steps 10 s; `ping`/`heartbeat` 30 s, session dead after 90 s
+(= Redis `la:session` TTL); clock skew <= 60 s. Duplicate detection (gateway, F3-05a): the last 512 `seq`->`msgId` pairs
+per session, in memory (`dedupe-entries`); the 10 min Redis window of the design (`dedupeWindowSeconds` in `index.json`)
+is NOT implemented, a replay older than those 512 frames is `seq_replayed`. CP->LA frames repeat the payload in
+`paramsRaw`, so their effective payload budget is about 20 KiB; larger inputs travel by `ref`.
+
+## State machine
+`AWAIT_REGISTER -> AWAIT_HELLO -> AWAIT_READY -> READY`, after the WS upgrade authenticates (Bearer, as v1).
+1. LA sends `register` (`protocol:2`, version, capabilities, `signatureMode`, `workspaces[]` with `pathSha256`,
+   optional `resume{sessionId,lastRecvSeq}`). 2. LA sends `hello` (state: `signatureMode`, Graphify, disk, queue, clock).
+3. CP validates (tenant, agent, skew, `signatureMode=enforce` when the tenant is `hybrid`/`client`) and answers
+   `ready{sessionId, resumed, peerLastSeq, limits}`. Handshake and control frames (`register hello ready ack error`)
+   use `seq 0`; every other frame has `seq` 1.. consecutive per direction. Text `ping`/`pong` stays as liveness.
+- **Resume:** with `resume` and a live Redis session the CP answers `resumed:true`; the LA continues at
+  `peerLastSeq+1` and re-sends unacked frames; otherwise `resumed:false`, both restart at 1 and in-flight requests fail.
+- **Rules (reference model in `ProtocolV2ContractTest`, same order):** size, allowlist, schema, tenant/agent, direction,
+  handshake state, `seq` (same seq + same `msgId` = idempotent duplicate, re-ack; same seq + other `msgId` =
+  `seq_replayed`; skip = `seq_gap`), chunks (index 0.., `total` constant, `last` iff last index, none after last; then `payload.byteLength` must equal the size of
+  the base64-DECODED `payload.data`, else `chunk_inconsistent`: JSON Schema cannot state it, so the vector files carry
+  `expect.rule:"byteLength-decoded"` and both validators apply it).
+- **Errors** (`error{code,retryable}`, then WS close 4400-4499 when fatal): `bad_frame unknown_type schema_violation
+  frame_too_large payload_too_large wrong_direction handshake_violation not_ready seq_gap seq_replayed
+  chunk_out_of_order chunk_inconsistent tenant_mismatch agent_mismatch params_mismatch signature_mode_insufficient
+  clock_skew protocol_unsupported unauthorized agent_offline timeout rate_limited internal`.
+- **Timeouts:** `content.request` 10 s to first chunk, 30 s total, then `timeout`; v1-style commands keep 120 s.
+
+## Compatibility with v1
+Same endpoint, auth and signature. A v2 LA sends the `register` above; a gateway with v2 off (the default) ignores
+it (it has no `requestId`/`workspacePath`) and the LA, with no `ready` in 10 s, falls back to the legacy
+`{type:"register",tenantId,port,workspacePath}` and v1 commands. A v2 gateway treats a frame without `schemaVersion`
+as v1 for that session. v1 command names are not v2 types (`mcp.execute-command` is rejected). v2 needs a CP
+signing key: without one the gateway does not negotiate v2.
+
+## What never goes in the envelope
+Everything is closed: no free-text fields, no extra properties, free strings <= 512 chars (identifiers, enums,
+hashes, counts). Client content may exist only in three declared fields (`x-content-class`, pinned by the test):
+`content.response.data` (relay, LA->CP, never persisted or logged by the CP), `job.assign.inputs[].inline` and
+`webhook.forward.bodyB64` (transit, CP->LA, `transient:true`, not persisted; `paramsRaw` echoes them).
+Long non-content strings are marked `x-large-metadata` (`paramsRaw`, `signedPutUrl`, `vhapr1` token). `error.detail` <= 200 chars
+and `audit.event` have no summary text; stack traces, diffs, logs and paths go only through `content.*`.
+
+## Verify
+- Java (gateway, runs in `mvn test`): `mvn -o test -Dtest=ProtocolV2ContractTest` (JDK 21).
+- Node (LA, F3-05b; Ajv 2020, no LA code needed): `cd docs/contracts/la-protocol-v2 && npm i --no-save ajv@8 &&
+  node tools/validate-vectors.cjs`. Traces are language-neutral; the LA must reproduce each `expect.error`.
+- Changing a schema = change the vectors in the same PR; adding a type = update `index.json` and the envelope enum.
+
+## Gateway behaviour (F3-05a) and gaps the code revealed
+Each frame is checked in the order of the Rules (size, parse with duplicate keys refused, allowlist, schema, tenant,
+agent, direction, state, seq, chunks); `error` frames carry the wire code only, never the content. CP->LA frames are
+built from the unsigned payload and validated against these schemas before they are written, so the CP cannot send a field the
+schema does not know. That runtime check covers the data frames sent through the API (`job.*`, `content.request`, ...); the
+handshake and control frames (`ready`, `ack`, `error`) are assembled by fixed code and are NOT schema-checked at runtime: the
+test transport validates every frame the session writes, and the tests fail on a violation.
+A fatal error closes the socket with 4400 + the position of its code in the `errorCode` enum (a test pins the order; `timeout` = 4420). Resume works only on the same gateway instance (state is in memory, 90 s); elsewhere `resumed:false`. Not done in
+F3-05a: relaying a v2 stream between gateway instances, the HTTP relay (F3-06), LA handlers (F3-05b/07). Gaps, for
+F3-05b to confirm (none changes a schema):
+1. **`byteLength` is the decoded size of `data`**; the gateway refuses a chunk where it differs (`chunk_inconsistent`).
+   The F3-22 vectors had 27 for a 26-byte payload and a `max-size-chunk` that decoded to 32769 bytes (fixed in F3-05a); the
+   above-limit vectors still disagreed and a non-canonical 43693-char `data` was in use: all fixed, and
+   `ProtocolV2ContractTest` now fails on any vector or trace whose `byteLength` differs from the decoded size.
+2. **`content.request` is acked implicitly by its first `content.response`**, also when the request timed out or was
+   cancelled meanwhile. The ack timeout is 5 s but the first chunk may take 10 s: an LA that is slow to start must
+   send an explicit `ack` (`accepted`) first, else the request is sent again (same seq and msgId) up to 3 times.
+3. **Retransmissions are re-signed**: same `seq` and `msgId`, new `sig.nonce`/`timestamp` (the LA keeps a nonce LRU
+   and a 60 s skew). The LA must dedupe by `seq`+`msgId` and re-ack, never execute twice.
+4. **No window in `ready.limits` and no `content.cancel` type.** The gateway bounds each request with a queue of
+   `maxChunksInFlight` (16): a consumer that falls further behind loses that request (`rate_limited`) while the
+   chunks still in flight are validated, acked and dropped. Cancelling a request cannot stop the LA; a cancel
+   message (or a window in `ready.limits`) is a contract change for later.
+5. `content.response.sha256` has no stated scope (chunk or whole content); the gateway passes it through unchecked.
+6. After 3 unanswered retransmissions the gateway closes with 4420 (`timeout`) and keeps the frame for a resume; the
+   LA must reconnect with `resume` to receive it. A silent connection (no frame and no text `ping` for 90 s) is closed
+   the same way.
+7. v1 commands are refused for an LA that speaks v2 (`protocol_mismatch`): until F3-06/07 move the callers, a v2 LA
+   cannot serve `sendCommand`, so the LA must stay on v1 for tenants whose flows still use v1 commands.
+

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

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.visionhammer.io/la-protocol-v2/ack.schema.json",
+  "title": "LA protocol v2: ack (both)",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "envelope.schema.json"
+    }
+  ],
+  "properties": {
+    "type": {
+      "const": "ack"
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "ackSeq": {
+          "$ref": "defs.schema.json#/$defs/seq"
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "accepted",
+            "duplicate",
+            "rejected"
+          ]
+        },
+        "errorCode": {
+          "$ref": "defs.schema.json#/$defs/errorCode"
+        }
+      },
+      "required": [
+        "ackSeq",
+        "status"
+      ]
+    },
+    "seq": {
+      "const": 0
+    },
+    "chunk": false,
+    "sig": false,
+    "paramsRaw": false,
+    "agentId": true
+  },
+  "required": [
+    "payload",
+    "agentId"
+  ]
+}

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

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.visionhammer.io/la-protocol-v2/alert.schema.json",
+  "title": "LA protocol v2: alert (la->cp)",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "envelope.schema.json"
+    }
+  ],
+  "properties": {
+    "type": {
+      "const": "alert"
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "code": {
+          "type": "string",
+          "enum": [
+            "la_degraded",
+            "index_stale",
+            "disk_low",
+            "signature_warn",
+            "queue_full",
+            "clock_skew"
+          ]
+        },
+        "severity": {
+          "type": "string",
+          "enum": [
+            "warning",
+            "critical"
+          ]
+        },
+        "value": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        }
+      },
+      "required": [
+        "code",
+        "severity"
+      ]
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "chunk": false,
+    "sig": false,
+    "paramsRaw": false,
+    "agentId": true
+  },
+  "required": [
+    "payload",
+    "agentId"
+  ]
+}

package/src/la-protocol-v2/contract/approval.decision.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.visionhammer.io/la-protocol-v2/approval.decision.schema.json",
+  "title": "LA protocol v2: approval.decision (cp->la)",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "envelope.schema.json"
+    }
+  ],
+  "properties": {
+    "type": {
+      "const": "approval.decision"
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "approvalId": {
+          "$ref": "defs.schema.json#/$defs/uuid"
+        },
+        "decision": {
+          "type": "string",
+          "enum": [
+            "approved",
+            "denied"
+          ]
+        },
+        "token": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 4096,
+          "pattern": "^vhapr1\\.[A-Za-z0-9_-]{1,64}\\.[A-Za-z0-9_-]{1,2048}\\.[A-Za-z0-9_-]{1,512}$",
+          "x-large-metadata": true
+        }
+      },
+      "required": [
+        "approvalId",
+        "decision",
+        "token"
+      ]
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "chunk": false,
+    "sig": true,
+    "paramsRaw": true
+  },
+  "required": [
+    "payload",
+    "sig",
+    "paramsRaw"
+  ]
+}

package/src/la-protocol-v2/contract/audit.event.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.visionhammer.io/la-protocol-v2/audit.event.schema.json",
+  "title": "LA protocol v2: audit.event (la->cp)",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "envelope.schema.json"
+    }
+  ],
+  "properties": {
+    "type": {
+      "const": "audit.event"
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "action": {
+          "type": "string",
+          "enum": [
+            "policy_decision",
+            "approval_requested",
+            "redaction",
+            "content_served",
+            "config_applied"
+          ]
+        },
+        "decision": {
+          "type": "string",
+          "enum": [
+            "allow",
+            "deny",
+            "require_human",
+            "n/a"
+          ]
+        },
+        "actionType": {
+          "$ref": "defs.schema.json#/$defs/shortId"
+        },
+        "toolName": {
+          "$ref": "defs.schema.json#/$defs/shortId"
+        },
+        "requestHash": {
+          "$ref": "defs.schema.json#/$defs/sha256"
+        },
+        "redactionSummary": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "rules": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 100000
+            },
+            "matches": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 100000000
+            }
+          },
+          "required": [
+            "rules",
+            "matches"
+          ]
+        }
+      },
+      "required": [
+        "action"
+      ]
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "chunk": false,
+    "sig": false,
+    "paramsRaw": false,
+    "agentId": true
+  },
+  "required": [
+    "payload",
+    "agentId"
+  ]
+}

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

@@ -0,0 +1,73 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.visionhammer.io/la-protocol-v2/config.update.schema.json",
+  "title": "LA protocol v2: config.update (cp->la)",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "envelope.schema.json"
+    }
+  ],
+  "properties": {
+    "type": {
+      "const": "config.update"
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "flags": {
+          "type": "array",
+          "maxItems": 64,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "name": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 64,
+                "pattern": "^[a-z0-9]+([._-][a-z0-9]+)*$"
+              },
+              "enabled": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "name",
+              "enabled"
+            ]
+          }
+        },
+        "dlpRulesetSha256": {
+          "$ref": "defs.schema.json#/$defs/sha256"
+        },
+        "minLaVersion": {
+          "$ref": "defs.schema.json#/$defs/semver"
+        },
+        "retentionDays": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 3650
+        },
+        "dataPlaneMode": {
+          "$ref": "defs.schema.json#/$defs/dataPlaneMode"
+        }
+      },
+      "minProperties": 1
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "chunk": false,
+    "sig": true,
+    "paramsRaw": true
+  },
+  "required": [
+    "payload",
+    "sig",
+    "paramsRaw"
+  ]
+}

package/src/la-protocol-v2/contract/content.request.schema.json

@@ -0,0 +1,110 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.visionhammer.io/la-protocol-v2/content.request.schema.json",
+  "title": "LA protocol v2: content.request (cp->la)",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "envelope.schema.json"
+    }
+  ],
+  "properties": {
+    "type": {
+      "const": "content.request"
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": [
+            "incident.detail",
+            "incident.stack",
+            "file",
+            "diff",
+            "log.window",
+            "log.groups",
+            "chat.session",
+            "wiki.page",
+            "job.stream",
+            "job.timeline",
+            "approval.detail",
+            "report"
+          ]
+        },
+        "ref": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 512,
+          "pattern": "^[^\\u0000-\\u001f]{1,512}$"
+        },
+        "range": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "offset": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 2097152
+            },
+            "length": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 2097152
+            }
+          },
+          "required": [
+            "offset",
+            "length"
+          ]
+        },
+        "limit": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1000
+        },
+        "actor": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "userId": {
+              "$ref": "defs.schema.json#/$defs/shortId"
+            },
+            "role": {
+              "type": "string",
+              "enum": [
+                "viewer",
+                "member",
+                "admin",
+                "root"
+              ]
+            }
+          },
+          "required": [
+            "userId",
+            "role"
+          ]
+        }
+      },
+      "required": [
+        "kind",
+        "ref",
+        "actor"
+      ]
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "chunk": false,
+    "sig": true,
+    "paramsRaw": true
+  },
+  "required": [
+    "payload",
+    "sig",
+    "paramsRaw"
+  ]
+}

package/src/la-protocol-v2/contract/content.response.schema.json

@@ -0,0 +1,90 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.visionhammer.io/la-protocol-v2/content.response.schema.json",
+  "title": "LA protocol v2: content.response (la->cp)",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "envelope.schema.json"
+    }
+  ],
+  "properties": {
+    "type": {
+      "const": "content.response"
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "ok",
+            "error",
+            "not_found",
+            "forbidden"
+          ]
+        },
+        "errorCode": {
+          "$ref": "defs.schema.json#/$defs/errorCode"
+        },
+        "contentType": {
+          "type": "string",
+          "enum": [
+            "text/plain",
+            "text/markdown",
+            "text/x-diff",
+            "application/json",
+            "application/zip",
+            "application/octet-stream"
+          ]
+        },
+        "encoding": {
+          "const": "base64"
+        },
+        "data": {
+          "type": "string",
+          "minLength": 0,
+          "maxLength": 43692,
+          "pattern": "^[A-Za-z0-9+/]*={0,2}$",
+          "x-content-class": "relay"
+        },
+        "byteLength": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 32768
+        },
+        "totalBytes": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2097152
+        },
+        "sha256": {
+          "$ref": "defs.schema.json#/$defs/sha256"
+        }
+      },
+      "required": [
+        "status",
+        "encoding",
+        "data",
+        "byteLength"
+      ]
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "sig": false,
+    "paramsRaw": false,
+    "chunk": true,
+    "requestId": true,
+    "agentId": true
+  },
+  "required": [
+    "payload",
+    "chunk",
+    "requestId",
+    "agentId"
+  ]
+}