deepdebug-local-agent 1.3.0 → 1.4.0

package/.github/workflows/deploy-gcp.yml

@@ -1,4 +1,8 @@
-# Deploy local-agent (Node) to GCP Cloud Run (visionhammer) via WIF.
+# Deploy local-agent (Node) to GCP Cloud Run via WIF.
+# QA: project visionhammer (europe-west1 since Plano QA Alvo EU 2026-10-29, same
+# conventions as PROD: deploy-local-agent@ SA of the nonprod project, EU registry,
+# immutable sha-<commit> tag, digest-pinned image-only deploy). PROD: project
+# visionhammer-prod (europe-west1), own WIF pool/deploy SA, digest-pinned deploy.
 # Manual-only: this repo has no develop branch and several active feature
 # branches, so deploys are triggered on demand from the Actions tab. Choose the
 # environment input. Replaces the insptechai Cloud Build path.
@@ -23,14 +27,18 @@ permissions:
   id-token: write
 
 env:
-  GCP_PROJECT: visionhammer
-  # EU migration (PLANO-MIGRACAO-EU-PROD.md): PROD moves to europe-west1. The
-  # region comes from repo variables (PROD_REGION / QA_REGION); today's value
-  # stays the default, so nothing changes until the variable is set.
-  GCP_REGION: ${{ inputs.environment == 'prod' && (vars.PROD_REGION || 'us-central1') || (vars.QA_REGION || 'us-central1') }}
-  WIF_PROVIDER: projects/1009366917257/locations/global/workloadIdentityPools/github-pool/providers/github-provider
-  DEPLOYER_SA: github-deployer@visionhammer.iam.gserviceaccount.com
-  AR_IMAGE: us-central1-docker.pkg.dev/visionhammer/visionhammer-docker/local-agent
+  # PROD lives in visionhammer-prod / europe-west1 (hardcoded: no repo variable
+  # can silently repoint PROD). QA lives in visionhammer / europe-west1 (QA_REGION
+  # only as an escape hatch) with its own deploy SA and the EU registry. The QA
+  # WIF provider is a repo variable so the pool/provider adopted by vh-infra
+  # (live/nonprod/_project) can be flipped without a commit:
+  #   gh variable set QA_WIF_PROVIDER --body projects/1009366917257/locations/global/workloadIdentityPools/<pool>/providers/<provider>
+  GCP_PROJECT: ${{ inputs.environment == 'prod' && 'visionhammer-prod' || 'visionhammer' }}
+  GCP_REGION: ${{ inputs.environment == 'prod' && 'europe-west1' || (vars.QA_REGION || 'europe-west1') }}
+  WIF_PROVIDER: ${{ inputs.environment == 'prod' && 'projects/616585643354/locations/global/workloadIdentityPools/github/providers/github-actions' || (vars.QA_WIF_PROVIDER || 'projects/1009366917257/locations/global/workloadIdentityPools/vh-infra/providers/github-actions') }}
+  DEPLOYER_SA: ${{ inputs.environment == 'prod' && 'deploy-local-agent@visionhammer-prod.iam.gserviceaccount.com' || 'deploy-local-agent@visionhammer.iam.gserviceaccount.com' }}
+  AR_HOST: europe-west1-docker.pkg.dev
+  AR_IMAGE: ${{ inputs.environment == 'prod' && 'europe-west1-docker.pkg.dev/visionhammer-prod/vh-docker/local-agent' || 'europe-west1-docker.pkg.dev/visionhammer/visionhammer-docker-eu/local-agent' }}
 
 jobs:
   deploy:
@@ -51,10 +59,12 @@ jobs:
             fi
             echo "service=deepdebug-local-agent"    >> "$GITHUB_OUTPUT"
             echo "tag=prod-${GITHUB_SHA::8}"         >> "$GITHUB_OUTPUT"
+            echo "image_tag=sha-${GITHUB_SHA}"       >> "$GITHUB_OUTPUT"
             echo "traffic=canary"                    >> "$GITHUB_OUTPUT"
           else
             echo "service=deepdebug-local-agent-qa" >> "$GITHUB_OUTPUT"
             echo "tag=qa-${GITHUB_SHA::8}"           >> "$GITHUB_OUTPUT"
+            echo "image_tag=sha-${GITHUB_SHA}"       >> "$GITHUB_OUTPUT"
             echo "traffic=live"                      >> "$GITHUB_OUTPUT"
           fi
 
@@ -68,35 +78,57 @@ jobs:
         uses: google-github-actions/setup-gcloud@v2
 
       - name: Configure Docker for Artifact Registry
-        run: gcloud auth configure-docker us-central1-docker.pkg.dev --quiet
+        run: gcloud auth configure-docker "$AR_HOST" --quiet
 
-      - name: Build & push image (multi-stage Node Dockerfile)
+      # QA and PROD: immutable tag sha-<full SHA> (a re-run of the same SHA fails
+      # the push by design); the deploy references the pushed DIGEST, not the tag.
+      - name: Build & push image (immutable sha tag, resolve digest)
         run: |
-          IMG="${AR_IMAGE}:${{ steps.vars.outputs.tag }}"
-          docker build --platform=linux/amd64 -t "$IMG" .
-          docker push "$IMG"
-          echo "IMG=$IMG" >> "$GITHUB_ENV"
+          TAGGED="${AR_IMAGE}:${{ steps.vars.outputs.image_tag }}"
+          docker build --platform=linux/amd64 -t "$TAGGED" .
+          docker push "$TAGGED"
+          DIGEST="$(docker inspect --format='{{index .RepoDigests 0}}' "$TAGGED")"
+          case "$DIGEST" in
+            "${AR_IMAGE}@sha256:"*) ;;
+            *) echo "::error::Unexpected digest reference: $DIGEST"; exit 1 ;;
+          esac
+          echo "IMG=$DIGEST" >> "$GITHUB_ENV"
 
-      - name: Deploy to Cloud Run (image only; preserves env/secrets)
+      - name: Deploy to Cloud Run (QA, image only by digest, live)
+        if: inputs.environment != 'prod'
         run: |
-          # PROD lands at 0% traffic behind a tag (canary); verify the tagged
-          # URL, then promote with `gcloud run services update-traffic`.
-          # QA keeps deploying live. Mirrors vh-api-gateway deploy-gcp.yml.
+          # QA (europe-west1) keeps deploying live. The service is Terraform-owned
+          # (vh-infra live/nonprod/qa/20-services: env, secrets, Filestore mount,
+          # min=max=1), so this is an image-only `services update` on the `app`
+          # container: never --set-env-vars / --update-env-vars / scaling flags.
+          # Service-level flags BEFORE --container.
           #
           # --vpc-egress is pinned: gcloud 572 flipped the template to
           # all-traffic on an image-only update; with no Cloud NAT that cuts
           # the service's internet egress.
-          EXTRA=""
-          if [ "${{ steps.vars.outputs.traffic }}" = "canary" ]; then
-            EXTRA="--no-traffic --tag ${{ steps.vars.outputs.tag }}"
-          fi
-          gcloud run deploy "${{ steps.vars.outputs.service }}" \
+          gcloud run services update "${{ steps.vars.outputs.service }}" \
+            --project "$GCP_PROJECT" \
+            --region "$GCP_REGION" \
+            --vpc-egress=private-ranges-only \
+            --quiet \
+            --container=app \
+            --image="$IMG"
+
+      # PROD: `services update` with image only (Terraform owns env/secrets, so
+      # no --set-env-vars). Singleton service (min=max=1): the revision lands at
+      # 0% behind a tag; promote with `gcloud run services update-traffic`
+      # (--to-revisions) once the tagged revision is verified.
+      - name: Deploy to Cloud Run (PROD, digest, canary)
+        if: inputs.environment == 'prod'
+        run: |
+          gcloud run services update "${{ steps.vars.outputs.service }}" \
             --image "$IMG" \
             --project "$GCP_PROJECT" \
             --region "$GCP_REGION" \
             --vpc-egress=private-ranges-only \
-            $EXTRA \
+            --no-traffic --tag "${{ steps.vars.outputs.tag }}" \
             --quiet
 
       - name: Summary
-        run: echo "Deployed **${{ steps.vars.outputs.service }}** with \`$IMG\`" >> "$GITHUB_STEP_SUMMARY"
+        run: |
+          echo "Deployed **${{ steps.vars.outputs.service }}** (${GCP_PROJECT}/${GCP_REGION}) with \`$IMG\`" >> "$GITHUB_STEP_SUMMARY"

package/CHANGELOG.md

@@ -8,6 +8,12 @@ platform side does not sign commands yet.
 
 ### Added (opt-in, off by default)
 
+- **`LOCAL_AGENT_PROTOCOL_V2=true`** (F3-05b, default off). The Local Agent side of the CP <-> LA protocol v2:
+  register/hello/ready with resume, seq/ack/retransmission, chunking of `content.response`, allowlist, every
+  frame validated against the gateway's JSON Schemas, Ed25519 check of signed CP frames, `signatureMode` in
+  `hello`. Falls back to the v1 register on the same connection when the gateway does not speak v2; v1 commands
+  keep working. Transport only: no content handlers yet. See `docs/la-protocol-v2.md`. No behaviour change when off.
+
 - **`LOCAL_AGENT_WS_METADATA_ONLY=off|enforce`** (T4-10, D17, D19). `enforce`
   restricts the outbound WS channel to allowlisted metadata (ids, hashes,
   counts, state, cost), refuses legacy content commands and denies

package/docs/la-protocol-v2.md

@@ -0,0 +1,68 @@
+# Protocol v2 on the Local Agent (F3-05b)
+
+The Local Agent side of the CP <-> LA WebSocket protocol v2. The contract is owned by the gateway
+(`docs/contracts/la-protocol-v2` of vh-api-gateway, F3-22); this repo keeps a verified copy in
+`src/la-protocol-v2/contract/` (`CONTRACT_SOURCE.json` records the gateway commit and the sha256 of every
+file; `npm test` fails if a copy was edited). Update it with `node scripts/sync-la-protocol-v2-contract.mjs
+<gateway contract dir> --commit <sha>`; never edit the copy.
+
+## Flag
+
+`LOCAL_AGENT_PROTOCOL_V2=true` (default **off**; unset, empty or unrecognised = off). With it off the tunnel in
+`src/server.js` is the v1 client, byte for byte: no v2 module (nor Ajv, nor the schemas) is loaded.
+
+It also needs `TENANT_ID` to be a UUID and the agent id (`authorizationId` of `~/.deepdebug/config.json`, or
+`LOCAL_AGENT_ID`); without them v2 stays off with a warning. Tuning (clamped): `LOCAL_AGENT_V2_MAX_IN_FLIGHT`
+(frames unacked, default 8), `LOCAL_AGENT_V2_HANDSHAKE_MS` (wait for `ready`, default 10000).
+
+## What it does
+
+- **Handshake.** On each socket: `register` (`protocol:2`, version, capabilities, `signatureMode`, workspaces as
+  `{workspaceId, pathSha256}`, `resume{sessionId,lastRecvSeq}` when it has a session) then `hello`. The gateway
+  answers a signed `ready` (`sessionId`, `resumed`, `peerLastSeq`, limits). Paths never leave the machine, only hashes.
+- **Fallback to v1** on the same connection: no `ready` in 10 s, or `error protocol_unsupported`. The v1
+  register is then sent, and v2 is not offered again for 10 min. A refusal that v1 would not fix
+  (`signature_mode_insufficient`, `clock_skew`, ...) does not fall back.
+- **Signatures.** Every signed CP->LA frame (`ready` included) is checked like a v1 command: `paramsRaw` must equal
+  `payload` (duplicate keys refused), `sig` must be bound to the frame's tenant and workspace, and the Ed25519
+  signature must verify with the trusted keys (`VH-AGENT-SIG-V1`, method `WS`, path = type). `enforce` refuses,
+  `warn` logs and goes on, `off` does not verify. `hello.signatureMode` reports the real mode; the gateway
+  refuses `hybrid`/`client` tenants that are not in `enforce`.
+- **Validation of everything.** Each received and each sent frame is validated with Ajv (2020-12, strict) against
+  the closed schemas, after the allowlist (21 types; direction checked) and the size limit (48 KiB). A refusal is an
+  `error` frame with the wire code only (never an echo of the content) and, for fatal codes, a WS close
+  `4400 + position of the code` (`timeout` = 4420).
+- **Numbering and acks.** `seq` per direction from 1, `ack` piggybacked, an `ack` frame per accepted data frame
+  (`duplicate` for a retransmission, never executed twice: the last 512 `seq`->`msgId` pairs are kept).
+  A frame with no handler is acked `rejected protocol_unsupported`.
+- **Sending.** At most N frames unacked (the rest wait in a bounded queue, 256), retransmitted after
+  `ackTimeoutMs` (same bytes: same seq and msgId), at most 3 times, then `timeout` to the caller and the socket
+  is closed 4420 (the frame is kept for the resume). A `heartbeat` frame every `heartbeatSeconds`; the text `ping`
+  of v1 stays as liveness.
+- **Resume.** The session survives a dropped socket for 120 s (the gateway keeps it 90 s, same instance only).
+  `resumed:false` restarts both numberings at 1 and fails the frames that were in flight (`agent_offline`).
+- **Chunking** (`src/la-protocol-v2/content.js`): `sendContent(session, {requestId, source})` splits a `Buffer` (or
+  `{size, read}`, read lazily) into `content.response` chunks of at most 32 KiB raw (43692 base64 chars, frame
+  under 48 KiB), at most 64 per response (2 MiB), `chunk{index,total,last}`, `byteLength` = decoded size. The
+  chunk rules of the contract are enforced on what is sent; a stream cannot continue across a reset.
+- **v1 commands on a v2 connection** (decision of 2026-10-29: transition, v1 is decommissioned later). A frame
+  without `schemaVersion` is not a v2 frame: it goes to the existing v1 handler (`handleWsCommand`), which
+  answers in the v1 shape. **The gateway (F3-05a) still refuses to send v1 commands to a v2 agent
+  (`protocol_mismatch`)**: this is ready on the LA side, but it will only be exercised once the gateway sends them.
+
+## What it does NOT do
+
+No handler of `content.request` (F3-07), no DLP on what is sent (F3-09, must run before `sendContent` is
+called), no log/incident detector (F3-11b), no `job.assign` runtime (F3-08). Those frames are acked
+`rejected protocol_unsupported`. `sha256` of `content.response` is not sent (the contract does not say what it covers).
+
+## Tests
+
+`npm test` (node:test), all in `test/la-protocol-v2/`:
+`contract.test.js` (all 134 vectors of F3-22, valid and invalid, plus the drift check), `traces.test.js` (the 24
+traces), `session-inbound.test.js`, `session-outbound.test.js`, `link.test.js`, `tunnel-e2e.test.js` (the real
+`src/server.js` against a reference CP; flag off = v1 frames). The reference CP (`test/la-protocol-v2/helpers/reference-cp.js`)
+is a Node model of the gateway rules, not the gateway.
+
+**Interoperability with the real gateway session** (`LaV2Session`, Java, real Reactor Netty socket on loopback, real
+Ed25519 signer): `tools/interop/` (`README.md`). Not part of `npm test` (needs a gateway checkout, JDK 21, Maven).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepdebug-local-agent",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "DeepDebug Local Agent - AI-powered code debugging assistant",
   "private": false,
   "type": "module",
@@ -34,6 +34,7 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.39.0",
     "@modelcontextprotocol/sdk": "^1.0.4",
+    "ajv": "^8.20.0",
     "body-parser": "^1.20.3",
     "chokidar": "^3.6.0",
     "cors": "^2.8.5",

package/scripts/sync-la-protocol-v2-contract.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// scripts/sync-la-protocol-v2-contract.mjs - copies the CP <-> LA protocol v2 contract (F3-22) from a
+// vh-api-gateway checkout into this repo and records where it came from.
+//
+//   node scripts/sync-la-protocol-v2-contract.mjs <gateway-contract-dir> --commit <sha> [--tip <sha>]
+//
+// <gateway-contract-dir> is docs/contracts/la-protocol-v2 of vh-api-gateway (a worktree of release/qa, or
+// the output of `git archive`). The gateway folder stays the only source of truth: never edit the copies.
+//   src/la-protocol-v2/contract/   *.schema.json + index.json (shipped: the runtime validates against them)
+//   test/contract/la-protocol-v2/  vectors/ (valid + invalid messages, traces) used by the tests
+//   src/la-protocol-v2/contract/CONTRACT_SOURCE.json   commit + sha256 of every copied file (a test fails on drift)
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const args = process.argv.slice(2);
+const src = args.find((a) => !a.startsWith("--"));
+const opt = (name) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : undefined; };
+const commit = opt("commit");
+if (!src || !commit || !/^[0-9a-f]{40}$/.test(commit)) {
+    console.error("usage: sync-la-protocol-v2-contract.mjs <gateway docs/contracts/la-protocol-v2> --commit <40-hex sha> [--tip <sha>]");
+    process.exit(2);
+}
+const sha256 = (buf) => crypto.createHash("sha256").update(buf).digest("hex");
+const runtimeDir = path.join(ROOT, "src/la-protocol-v2/contract");
+const vectorsDir = path.join(ROOT, "test/contract/la-protocol-v2");
+fs.rmSync(vectorsDir, { recursive: true, force: true });
+fs.mkdirSync(runtimeDir, { recursive: true });
+fs.mkdirSync(vectorsDir, { recursive: true });
+
+const files = {};
+for (const name of fs.readdirSync(src).filter((n) => n.endsWith(".schema.json") || n === "index.json" || n === "README.md")) {
+    const buf = fs.readFileSync(path.join(src, name));
+    fs.writeFileSync(path.join(runtimeDir, name), buf);
+    files[name] = sha256(buf);
+}
+function copyTree(from, to, rel) {
+    fs.mkdirSync(to, { recursive: true });
+    for (const e of fs.readdirSync(from, { withFileTypes: true })) {
+        if (e.isDirectory()) { copyTree(path.join(from, e.name), path.join(to, e.name), `${rel}/${e.name}`); continue; }
+        const buf = fs.readFileSync(path.join(from, e.name));
+        fs.writeFileSync(path.join(to, e.name), buf);
+        files[`${rel}/${e.name}`] = sha256(buf);
+    }
+}
+copyTree(path.join(src, "vectors"), path.join(vectorsDir, "vectors"), "vectors");
+fs.writeFileSync(path.join(runtimeDir, "CONTRACT_SOURCE.json"), JSON.stringify({
+    repo: "VISIONHAMMER/vh-api-gateway",
+    path: "docs/contracts/la-protocol-v2",
+    branch: "release/qa",
+    commit,
+    ...(opt("tip") ? { branchTip: opt("tip") } : {}),
+    note: "Copied by scripts/sync-la-protocol-v2-contract.mjs. Do not edit: change the gateway folder and sync again.",
+    files,
+}, null, 2) + "\n");
+console.log(`synced ${Object.keys(files).length} files from ${commit.slice(0, 8)}`);

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

@@ -0,0 +1,45 @@
+/**
+ * chunks.js - the chunk rules of protocol v2 (README of the contract: "chunks") for ONE direction.
+ *
+ * A `content.response` is a stream of frames with the same requestId: chunk.index 0.., chunk.total constant,
+ * chunk.last true only on the last index, nothing after last, every payload.data at most chunkRawBytes
+ * decoded. The Local Agent applies them to what it SENDS (so it can never emit a stream the gateway would
+ * refuse with a fatal error); the same class is how the tests check the traces.
+ */
+const MAX_STREAMS = 256;
+
+/** How many chunks a payload of `size` bytes needs. An empty payload is still one (empty) chunk. */
+export function chunkCount(size, chunkRawBytes) {
+    return Math.max(1, Math.ceil(size / chunkRawBytes));
+}
+
+export class ChunkStreamTracker {
+    constructor({ chunkRawBytes = 32768, maxChunks = 64 } = {}) {
+        this.chunkRawBytes = chunkRawBytes;
+        this.maxChunks = maxChunks;
+        this.streams = new Map(); // requestId -> { total, next, done }
+    }
+
+    /**
+     * Checks one chunk against the stream state and, when it is fine, records it.
+     * @returns {null | "chunk_out_of_order" | "chunk_inconsistent"}
+     */
+    accept(requestId, chunk, decodedBytes) {
+        const { index, total, last } = chunk;
+        const st = this.streams.get(requestId);
+        if (st && st.done) return "chunk_out_of_order";
+        if (st && st.total !== total) return "chunk_inconsistent";
+        if (total > this.maxChunks) return "chunk_inconsistent";
+        const expected = st ? st.next : 0;
+        if (index !== expected) return "chunk_out_of_order";
+        if (last !== (index === total - 1)) return "chunk_inconsistent";
+        if (decodedBytes > this.chunkRawBytes) return "chunk_inconsistent";
+        this.streams.delete(requestId);
+        this.streams.set(requestId, { total, next: index + 1, done: last });
+        while (this.streams.size > MAX_STREAMS) this.streams.delete(this.streams.keys().next().value);
+        return null;
+    }
+
+    forget(requestId) { this.streams.delete(requestId); }
+    clear() { this.streams.clear(); }
+}

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

@@ -0,0 +1,27 @@
+/**
+ * config.js - LOCAL_AGENT_PROTOCOL_V2 flag (F3-05b).
+ *
+ *   false (default)  the WS tunnel is the v1 client, byte for byte: no v2 module is loaded.
+ *   true             the tunnel offers protocol v2 first (register/hello/ready, see session.js) and
+ *                    falls back to the v1 register on the SAME connection when the gateway does not
+ *                    answer `ready` or answers `protocol_unsupported`.
+ *
+ * Unset/empty/unrecognised = false (an unknown value must never switch the transport).
+ */
+export const PROTOCOL_V2_FLAG = "LOCAL_AGENT_PROTOCOL_V2";
+
+const TRUE = new Set(["true", "1", "yes", "on"]);
+const FALSE = new Set(["", "false", "0", "no", "off"]);
+
+export function resolveProtocolV2Config(env = process.env, warn = console.warn) {
+    const raw = String(env[PROTOCOL_V2_FLAG] ?? "").trim().toLowerCase();
+    if (TRUE.has(raw)) return { enabled: true };
+    if (!FALSE.has(raw)) warn(`[la-v2] unrecognised ${PROTOCOL_V2_FLAG} value; protocol v2 stays off`);
+    return { enabled: false };
+}
+
+/** The per-machine authorization id the gateway checks as `agentId` (config.json `authorizationId`). */
+export function resolveAgentId(env = process.env, fileCfg = {}) {
+    const raw = String(env.LOCAL_AGENT_ID || fileCfg.authorizationId || "").trim().toLowerCase();
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(raw) ? raw : null;
+}

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

@@ -0,0 +1,57 @@
+/**
+ * content.js - sends content to the control plane as a stream of `content.response` chunks (the relay of
+ * the design: never persisted or logged by the CP). TRANSPORT ONLY: no handler of `content.request` lives
+ * here (F3-07) and nothing here decides what may leave the machine (DLP is F3-09, before this is called).
+ *
+ * Rules (contract): <= 32 KiB raw per chunk (43692 base64 chars, frame <= 48 KiB), <= 64 chunks (2 MiB per
+ * response), chunk.index from 0, total constant, last only on the final one, byteLength = decoded size.
+ * Each chunk is its own data frame: numbered, acked, retransmitted. At most `maxInFlight` chunks are in
+ * flight and the next one is not even read until a slot opens (bounded memory for any size).
+ */
+import { ProtocolError } from "./errors.js";
+import { chunkCount } from "./chunks.js";
+
+/**
+ * @param {import("./session.js").V2Session} session
+ * @param {object} o
+ * @param {string} o.requestId           the content.request being answered (lower-case UUID)
+ * @param {Buffer | {size:number, read:(offset:number, length:number)=>Promise<Buffer>}} o.source
+ * @param {string} [o.contentType]       one of the contract's content types
+ * @param {string} [o.workspaceId]
+ * @param {AbortSignal} [o.signal]       abort stops reading and drops the chunks still waiting for a slot
+ * @returns {Promise<{chunks:number, bytes:number}>} resolves when the last chunk was acked
+ */
+export async function sendContent(session, { requestId, source, contentType = "application/octet-stream", workspaceId, signal }) {
+    const size = Buffer.isBuffer(source) ? source.length : source.size;
+    if (!Number.isSafeInteger(size) || size < 0) throw new ProtocolError("internal", "source size");
+    const { chunkRawBytes, maxChunks } = session.limits;
+    const total = chunkCount(size, chunkRawBytes);
+    if (total > maxChunks) throw new ProtocolError("payload_too_large", "response above the chunk limit");
+    const acks = [];
+    try {
+        for (let index = 0; index < total; index++) {
+            if (signal && signal.aborted) throw new ProtocolError("agent_offline", "cancelled");
+            const offset = index * chunkRawBytes;
+            const length = Math.min(chunkRawBytes, size - offset);
+            const bytes = Buffer.isBuffer(source) ? source.subarray(offset, offset + length) : await source.read(offset, length);
+            if (!Buffer.isBuffer(bytes) || bytes.length !== length) throw new ProtocolError("internal", "source returned a wrong length");
+            const h = await session.enqueue("content.response", {
+                status: "ok", contentType, encoding: "base64", data: bytes.toString("base64"), byteLength: length, totalBytes: size,
+            }, { requestId, workspaceId, chunk: { index, total, last: index === total - 1 } });
+            acks.push(h.acked);
+        }
+    } catch (e) {
+        session.cancelWaiting(requestId);
+        for (const a of acks) a.catch(() => {});
+        throw e;
+    }
+    await Promise.all(acks);
+    return { chunks: total, bytes: size };
+}
+
+/** A failed answer: one empty chunk with the status (error | not_found | forbidden) and a wire error code. */
+export async function sendContentFailure(session, { requestId, status = "error", errorCode = "internal", workspaceId }) {
+    await session.send("content.response", {
+        status, errorCode, encoding: "base64", data: "", byteLength: 0,
+    }, { requestId, workspaceId, chunk: { index: 0, total: 1, last: true } });
+}

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

@@ -0,0 +1,81 @@
+{
+  "repo": "VISIONHAMMER/vh-api-gateway",
+  "path": "docs/contracts/la-protocol-v2",
+  "branch": "release/qa",
+  "commit": "b090144e19b1da0182554553b18f321452f03bd6",
+  "branchTip": "7043f75e3ed1b201e2c958fd52f721b5a1177efe",
+  "note": "Copied by scripts/sync-la-protocol-v2-contract.mjs. Do not edit: change the gateway folder and sync again.",
+  "files": {
+    "README.md": "41dd3cbceccb487ca30da5838841f04d8abffcc81c31424da833114ab646b291",
+    "ack.schema.json": "d6dfdaa8b1ec2dd47db9e858cd047ca860196ab6b0ad350f8ccb5d2596441ccf",
+    "alert.schema.json": "01a8a77840be8ab7901ed7d07c3d68a2295bfaeb638694564e19e60be1747054",
+    "approval.decision.schema.json": "a9c7bc74d146465afde1d5830839165a02f232b830b5f6cfd8c8e91fb6da1563",
+    "audit.event.schema.json": "e9ceb58ea00077151373955957b8319324de488c80da4063f6d0dcb40a8b3ed0",
+    "config.update.schema.json": "f5318f24230f542c76a3cb996d08f33210c0b2cc2fc55ad73c4f95648582033f",
+    "content.request.schema.json": "9966b55ec051832ac93ee43e9cd226e4f0efaeb49741947bfc48193e40e00a32",
+    "content.response.schema.json": "c9a66ac9cbbcaec7fc182b3e3fa23b34877bd342592521c7e393779230332231",
+    "defs.schema.json": "f19fd27fd103d8da02de4506c086263c6236250c5c127aa3aab41833a90b743a",
+    "envelope.schema.json": "670fb26c7d532475da144185e5100b3a2ffe0d267451b1ef9debadf31b33ab79",
+    "error.schema.json": "b1fd663d4a1ea73d88cb575422f15f8c7279001f9385ebb2d5e1889b5d5ef878",
+    "heartbeat.schema.json": "8aff84a1ef3ca56bdff8819abb3b0ab01a2547814c2ea2f9ee893cb08f7a08f1",
+    "hello.schema.json": "bd500320f01ff10da49ded6f99c7e8081252019984afb3c178e27003df20b963",
+    "incident.candidate.schema.json": "b292a85917b5958fc6de10a2895732e30a35420385623930c78e47341862dc62",
+    "index.json": "55543ecf492b1ffe2b9a78075890ee05518d3539fbcaeb04e8b2da8ff37c9130",
+    "job.assign.schema.json": "fdebb4ae98bf38a2c723281c1cf9477f71d877171df9a55b0baeb0b65244f60c",
+    "job.cancel.schema.json": "40ef64373283e17306d857c9a40081689786015294b0b88ab8f68f063bd2cfb8",
+    "job.event.schema.json": "493d08f9db4f7ffd4a97403ee33ca4a73a65dc8f774d8f18ef0a137fdb5fc470",
+    "job.result.schema.json": "9cbc61211482557283b8f4df44e79011ead1abbacdb2d986138199c747edc043",
+    "log.stats.schema.json": "4b33b111946a19793a60756793294e90911b06f7050e48821759f2497ec17641",
+    "ready.schema.json": "6e8bd8e1a5ce1b840d35af911ae09b8f58ad9de59eb33cd2b7777859892813f4",
+    "register.schema.json": "e75a4aa9d5d750e1473f71ab2f37d8e9a82fcfab3e8ff1c35118d0c08916e795",
+    "scan.upload.schema.json": "b1bba86ee362f73afc94c8c216977c12f67f770490e81002d14789397692f23b",
+    "scan.uploaded.schema.json": "f4c6aed7b9363b3ce1a9e14f9c4f4fb003bcf104b60acf74421dd0c75fc5d229",
+    "webhook.forward.schema.json": "33d4ee238855339850ff198d1078087f3b2f48c8f290b71def93cc02dd32c985",
+    "vectors/ack.vectors.json": "242ec2b8ff0c748eaaedce63e0015cf5bd9a7092d1055b0670ce6b95403b54b2",
+    "vectors/alert.vectors.json": "0bf179ff390bbecf07a117b80237cb7ac8778864e5780f36d68c8c9a64db8f04",
+    "vectors/approval.decision.vectors.json": "338115973bf2c4390d2bb33ce8f4079f3132cd739cd5505e1e873fdc252d2271",
+    "vectors/audit.event.vectors.json": "d05c1820103eef041a84eb8b13d9a67a8a5b54b9b54ee3b6e43fd4ef15ed7000",
+    "vectors/config.update.vectors.json": "8a5088d547e3eb4e460b25a5e413caaa02d4402a601340e279166d8c17758e1c",
+    "vectors/content.request.vectors.json": "6922748edfc630ce881a1b79d24827de03f849e05c441ef7eecc684bf2238e58",
+    "vectors/content.response.vectors.json": "35ef18edbcec24c029781e97d60dcb0b9111697fa3a5a2a8dfd159744e7f8258",
+    "vectors/cross-type.vectors.json": "f7ed403d3e3f53150b715a5423fde1bed708e8c6245709ed4ad74389dc8c3307",
+    "vectors/error.vectors.json": "f5fd7954f2c1736ee0943eb330c2f85b7fdd7a8959e4f043f9cc9e9bcda39aa5",
+    "vectors/heartbeat.vectors.json": "cfd2e048139c67aa925f1fa94c05326e75248839645c1a1e4d6d3bb60cafa624",
+    "vectors/hello.vectors.json": "51067dc645a2e9d8116997b36e6f3fe36401d27f3ee3c18de32ec30f8a052c5f",
+    "vectors/incident.candidate.vectors.json": "0dd75ef396bf7b7911d20b3ab220469701f07866bb032ee31af58523c3633ab6",
+    "vectors/job.assign.vectors.json": "e510c2cc6d17238d477429c255d828c0339b504e39a3a50d4b6ca980e262d9ef",
+    "vectors/job.cancel.vectors.json": "0fc9f99c8662435e9425389068adf418273489dc73928a21eae1b283256b9bc5",
+    "vectors/job.event.vectors.json": "03a2a2435918ba561821916bf4e435f2780210900139ecf68091acac6abf200c",
+    "vectors/job.result.vectors.json": "05995fbe65e5357705d75e9b660b517f54c6902069d36b62190b1b79f283e7a5",
+    "vectors/log.stats.vectors.json": "a8a67e09ef0f87b81f4028b77427ed7afd809c3f8534b8423a712b2ceef9a27f",
+    "vectors/ready.vectors.json": "a584da17e714a13c3583256773ef0be007660c33c62a456e27568def391e7cef",
+    "vectors/register.vectors.json": "e2a696efc547aa2f7242128d1a860238954f9e9a1330f10b567122d7b3da0365",
+    "vectors/scan.upload.vectors.json": "e8a6f73fe91ac58a3222b68cf28124c1254aa4f00c3ef8f472deb7de31cab76e",
+    "vectors/scan.uploaded.vectors.json": "7314ea15b1afa7b9625048fb7e245492d8910bc0dae8a52ea62afe2a1e240382",
+    "vectors/traces/invalid-agent-mismatch.json": "5f17b867de71c1bcc6c42723acb53a50338c0e491193499ea25c2220ea4fa558",
+    "vectors/traces/invalid-chunk-after-last.json": "0dcc3f3cce605a490d65e96592668381fa9a191d908a26ede998717494eb2f2e",
+    "vectors/traces/invalid-chunk-byte-length-mismatch.json": "d328ad05b22d3abaf0497ee8482a07a08ac90a4ede94edf754e8962ca8ea201e",
+    "vectors/traces/invalid-chunk-last-flag.json": "6c59a361313e966999ec25c80733758d86befb5f3607528634a148291844d212",
+    "vectors/traces/invalid-chunk-out-of-order.json": "c6560290755d86b524316823d32fcbd1420c170b13e198813c3b7e7b7f32ecb6",
+    "vectors/traces/invalid-chunk-total-changes.json": "9b7ade197252275725bc0754e40eadc12a289c063fed13a2905c55583a27a767",
+    "vectors/traces/invalid-clock-skew.json": "de16e0bd72e08bb03d44d5f2f04a238dcd38447ff1690f8acfe712ca3fe2028b",
+    "vectors/traces/invalid-event-before-ready.json": "17081f197fab5f4490b15a088f2bce620921007b5fdd7ed63bd988899d674883",
+    "vectors/traces/invalid-first-frame-not-register.json": "cf41c2d0e67f6df382790dab13bb9e49db99a34a88c1f9d108214be5df1e4ea3",
+    "vectors/traces/invalid-frame-over-48kib.json": "912e37c9a326ad92284ba22af752269cb5dd52ed06cdc22b17fd3b74a8423734",
+    "vectors/traces/invalid-la-sends-job-assign.json": "4ce5313e125e2afa920e923c2b5b524f627f47d06961a250a8dc642b79225252",
+    "vectors/traces/invalid-params-raw-differs-from-payload.json": "1220630372c78a41d77b2653b8f9025cb87d601c199adb03edbf007e6e727ad1",
+    "vectors/traces/invalid-payload-above-limit.json": "99f3834cfea69bc6ffa169bd6a2ed915377331205f8e991ceacbf21b3525fe96",
+    "vectors/traces/invalid-resume-restarts-seq.json": "795964093051511c00538f88774956b471a35338b92a0a180bedb33d460f2d83",
+    "vectors/traces/invalid-seq-gap.json": "9c85719b07cb7309752ffaa33b6c6cb1b278c45cd72e21dbc788c56af5e4502f",
+    "vectors/traces/invalid-seq-repeated.json": "4a4dd18d5b9de61a6cec735229b7991d6de4f3598acd7b16541eaca44be4556d",
+    "vectors/traces/invalid-sig-tenant-mismatch.json": "5d8895cbc9c1b91be31a851d009d1f2b832f9735c3713b131ac9837c90b4a8e7",
+    "vectors/traces/invalid-signature-warn-with-enforce-required.json": "71b5b3dc5dce52417173934db1e0de6542ecae5798e87124d54a8017493312e1",
+    "vectors/traces/invalid-tenant-mismatch.json": "dcc04ea423bddef20524ead7bfd146a5d9c42fe474c9216dc38c90544d291151",
+    "vectors/traces/invalid-type-outside-allowlist.json": "e492d326cfa044d3fc9f7e48dee63a52b715a62ba4867fc5ce21f1d86e3c435f",
+    "vectors/traces/valid-content-chunks-in-order.json": "c5fc301527b062b30c625da2798c7cfab3e3debac29a36f6ec7c699705267ab3",
+    "vectors/traces/valid-handshake-and-job.json": "9aa3c423c496403ca77d63965f1805f0a57ea9f6f8a01351310515b265aeb9cc",
+    "vectors/traces/valid-resume-continues-seq.json": "8aa90f24598f8f2d87a5355ec58c3531d16fd11ad41c782f53eca063372b704a",
+    "vectors/traces/valid-retransmit-is-idempotent.json": "924e9d296a67f0006c289e7cc978b9529ae1aa03bec2cd331a62f31354a90257",
+    "vectors/webhook.forward.vectors.json": "38d5b53b8fb4ecdb051e2c594afc52eb8b2044e4e6aae6ffb0057fbda33bcd46"
+  }
+}

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.
+