deepdebug-local-agent 1.3.0 → 1.5.0

package/test/la-protocol-v2/helpers/content-rig.js

@@ -0,0 +1,94 @@
+// F3-07 test rig: a real V2Session against the ReferenceCp (in memory), the REAL content handler, and temp workspaces on disk.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { ReferenceCp, TENANT, uuid, waitFor } from "./reference-cp.js";
+import { inMemory } from "./la-rig.js";
+import { resolveContentHandlersConfig } from "../../../src/la-protocol-v2/content-handlers/config.js";
+import { ContentRefRegistry } from "../../../src/la-protocol-v2/content-handlers/ref-registry.js";
+import { createContentHandler } from "../../../src/la-protocol-v2/content-handlers/handler.js";
+
+export const ACTOR = { userId: "u-1", role: "member" };
+
+export function tmpDir(prefix = "f307-") {
+    return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+export function write(root, rel, data) {
+    const abs = path.join(root, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, data);
+    return abs;
+}
+
+export function git(root, ...args) {
+    return execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "-c", "commit.gpgsign=false", ...args], { cwd: root, stdio: ["ignore", "pipe", "pipe"] }).toString();
+}
+
+export function initRepo(root) {
+    git(root, "init", "-q", "-b", "main");
+    git(root, "add", "-A");
+    git(root, "commit", "-q", "-m", "init");
+}
+
+/**
+ * @param {object} o
+ * @param {string} [o.dlp]            LOCAL_AGENT_DLP_MODE
+ * @param {object} [o.env]            extra env for the content config and the DLP (LOCAL_AGENT_CONTENT_*, LOCAL_AGENT_DLP_*)
+ * @param {object} [o.workspaces]     { id: {root, tenantId?} }  (default: ws-1 -> a fresh temp dir, ws-2 -> another)
+ * @param {object} [o.cp] [o.la]      options of ReferenceCp / inMemory
+ */
+export async function setup({ dlp = "enforce", env = {}, workspaces, cp: cpOpts, la: laOpts, now } = {}) {
+    const cp = new ReferenceCp(cpOpts);
+    const lenv = inMemory(cp, laOpts).start();
+    await waitFor(() => lenv.session.state === "ready");
+    const dirs = [];
+    const mk = () => { const d = tmpDir(); dirs.push(d); return d; };
+    const wsMap = new Map(Object.entries(workspaces || { "ws-1": { root: mk() }, "ws-2": { root: mk() } }));
+    const fullEnv = { LOCAL_AGENT_CONTENT_HANDLERS: "true", LOCAL_AGENT_DLP_MODE: dlp, ...env };
+    const config = resolveContentHandlersConfig(fullEnv, () => {});
+    const registry = new ContentRefRegistry({ tenantId: TENANT, ttlMs: config.refTtlMs, maxEntries: config.maxRefs, denyGlobs: config.extraDenyGlobs, ...(now ? { now } : {}) });
+    const logs = [];
+    const log = { info: (m) => logs.push(m), log: (m) => logs.push(m), warn: (m) => logs.push(m) };
+    const resolveWorkspace = (id) => {
+        const w = wsMap.get(id);
+        if (!w || (w.tenantId && w.tenantId !== TENANT)) return null;
+        return { root: w.root };
+    };
+    const handler = createContentHandler({ session: lenv.session, tenantId: TENANT, resolveWorkspace, registry, config, env: fullEnv, log, ...(now ? { now } : {}) });
+    lenv.session.setHandler("content.request", (ctx) => handler.handle(ctx));
+    const rig = {
+        cp, ...lenv, handler, registry, config, logs, env: fullEnv, wsMap,
+        root: (id = "ws-1") => wsMap.get(id).root,
+        mint(kind, rel, workspaceId = "ws-1") {
+            const m = registry.mint({ workspaceId, root: wsMap.get(workspaceId).root, kind, rel });
+            return m && m.id;
+        },
+        /** Sends a content.request and waits for the whole answer. */
+        async request({ kind = "file", ref, workspaceId = "ws-1", range, limit, waitMs = 4000 } = {}) {
+            const requestId = uuid();
+            cp.sendData("content.request", { kind, ref, ...(range ? { range } : {}), ...(limit ? { limit } : {}), actor: ACTOR }, { workspaceId, requestId });
+            await waitFor(() => cp.contentRequests.get(requestId)?.done, waitMs);
+            return rig.answer(requestId);
+        },
+        answer(requestId) {
+            const frames = cp.received.filter((f) => f.type === "content.response" && f.requestId === requestId);
+            const first = frames[0];
+            const body = Buffer.concat((cp.contentRequests.get(requestId)?.chunks) || []);
+            return { requestId, frames, status: first?.payload.status, errorCode: first?.payload.errorCode, contentType: first?.payload.contentType,
+                body, text: body.toString("utf8"), chunks: frames.length };
+        },
+        /** Everything the LA ever put on the wire, the audit and the logs, as one string (to prove what never appears in it). */
+        everything() {
+            return JSON.stringify([lenv.wire.toCp, handler.audit.tail(1000), logs]);
+        },
+        async stop() {
+            handler.cancelAll();
+            lenv.session.close();
+            for (const d of dirs) fs.rmSync(d, { recursive: true, force: true });
+        },
+        dirs,
+    };
+    return rig;
+}

package/test/la-protocol-v2/helpers/la-rig.js

@@ -0,0 +1,83 @@
+// A miniature of the v1 tunnel in server.js, around the REAL v2 link: opens a ws to a ReferenceCpServer,
+// hands the socket to the link exactly like server.js does, and records what the v1 handler would get.
+import WebSocket from "ws";
+import { createV2Link } from "../../../src/la-protocol-v2/link.js";
+import { resolveSigningConfig } from "../../../src/utils/request-signing.js";
+import { TENANT, AGENT } from "./reference-cp.js";
+
+export function signingFor(server, mode = "enforce", extraEnv = {}) {
+    return resolveSigningConfig({
+        LOCAL_AGENT_SIGNATURE_MODE: mode,
+        LOCAL_AGENT_SIGNING_PUBLIC_KEYS: `${server.keyId}=${server.publicKeyRaw}`,
+        LOCAL_AGENT_TENANT_ID: TENANT,
+        ...extraEnv,
+    }, { defaultFile: null, fileCfg: {} });
+}
+
+export function startRig(server, { mode = "enforce", sessionOptions = {}, options = {}, fallbackMs = 600_000, tenantId = TENANT, agentId = AGENT } = {}) {
+    const logs = [];
+    const log = { info: (m) => logs.push(m), log: (m) => logs.push(m), warn: (m) => logs.push(m) };
+    const signing = signingFor(server, mode);
+    const link = createV2Link({
+        log, fallbackMs,
+        sessionOptions: {
+            tenantId, agentId, signing, laVersion: "1.3.0", capabilities: ["protocol.v2", "v1.commands", "chunk.base64"],
+            getWorkspaces: () => [{ workspaceId: "ws-1", pathSha256: "ab".repeat(32) }],
+            getHealth: () => ({ diskFreeBytes: 1234 }),
+            options: { handshakeTimeoutMs: 400, ...options },
+            ...sessionOptions,
+        },
+    });
+    const rig = {
+        link, session: link.session, logs, signing,
+        v1Messages: [],          // texts that reached the v1 handler (the tunnel's existing code)
+        inbound: [],             // every text received from the CP, in order
+        legacyRegisters: 0,
+        ws: null,
+        connect() {
+            return new Promise((resolve) => {
+                const ws = new WebSocket(`ws://127.0.0.1:${server.port}/api/v1/agent/ws`, { headers: { Authorization: `Bearer ${server.token}` } });
+                rig.ws = ws;
+                ws.on("open", () => {
+                    const legacy = () => { rig.legacyRegisters++; ws.send(JSON.stringify({ type: "register", tenantId, port: 5055, workspacePath: null })); };
+                    if (!link.begin(ws, legacy)) legacy();
+                    resolve(ws);
+                });
+                ws.on("message", (data, isBinary) => {
+                    const text = data.toString();
+                    if (text === "pong") return;
+                    rig.inbound.push(text);
+                    if (link.handleMessage(ws, text, isBinary)) return;
+                    rig.v1Messages.push(text);
+                });
+                ws.on("close", () => link.onClose(ws));
+                ws.on("error", () => {});
+            });
+        },
+        drop() { rig.ws && rig.ws.terminate(); },
+        async stop() { rig.ws && rig.ws.terminate(); link.close(); },
+    };
+    return rig;
+}
+
+/** No sockets: the session's transport writes straight into a ReferenceCp and the CP's frames straight into the session. */
+import { V2Session } from "../../../src/la-protocol-v2/session.js";
+export function inMemory(cp, { mode = "enforce", tenantId = TENANT, agentId = AGENT, options = {}, sessionOptions = {}, signing } = {}) {
+    const logs = [];
+    const session = new V2Session({
+        tenantId, agentId, signing: signing || signingFor({ keyId: cp.keyId, publicKeyRaw: cp.publicKeyRaw }, mode),
+        laVersion: "1.3.0", capabilities: ["protocol.v2", "v1.commands", "chunk.base64"],
+        getWorkspaces: () => [{ workspaceId: "ws-1", pathSha256: "ab".repeat(32) }],
+        getHealth: () => ({ diskFreeBytes: 1234 }),
+        log: { info: (m) => logs.push(m), warn: (m) => logs.push(m) },
+        options: { handshakeTimeoutMs: 400, ...options }, ...sessionOptions,
+    });
+    const wire = { toLa: [], toCp: [], closed: [], cpClosed: [] };
+    const transport = {
+        send: (t) => { wire.toCp.push(t); cp.feed(t); },
+        close: (c, r) => { wire.closed.push([c, r]); },
+        bufferedAmount: () => 0,
+    };
+    cp.attach((t) => { wire.toLa.push(t); queueMicrotask(() => session.handleText(t, transport)); }, (c, r) => wire.cpClosed.push([c, r]));
+    return { session, transport, wire, logs, start() { session.attach(transport); return this; } };
+}

package/test/la-protocol-v2/helpers/reference-cp.js

@@ -0,0 +1,349 @@
+// Reference control plane for the tests of protocol v2 (F3-05b). NOT product code and NOT the gateway: a
+// small Node model of the CP side that applies the rules of the contract README in the same order as the
+// gateway's LaV2Session (size, parse, allowlist, schema, tenant, agent, direction, state, seq, chunks),
+// signs its frames like AgentRequestSigner (VH-AGENT-SIG-V1, method WS, path = type) and keeps a session
+// across connections so resume can be exercised. What it proves is limited by that: see the note
+// "Fase 3 F3-05b" (interoperability with the real LaV2Session is a separate test, test/interop).
+import crypto from "node:crypto";
+import { WebSocketServer } from "ws";
+import { loadContract } from "../../../src/la-protocol-v2/contract.js";
+import { canonicalString, sha256Hex } from "../../../src/utils/request-signing.js";
+import { parseStrict } from "../../../src/la-protocol-v2/strict-json.js";
+import { closeCodeOf, isFatal, isRetryable } from "../../../src/la-protocol-v2/errors.js";
+
+export const TENANT = "3f2b8c1e-5a4d-4e7b-9c21-0a1b2c3d4e5f";
+export const AGENT = "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d";
+export const uuid = () => crypto.randomUUID();
+
+export function newKeyPair() {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync("ed25519");
+    const raw = publicKey.export({ format: "der", type: "spki" }).subarray(-32).toString("base64");
+    return { privateKey, publicKeyRaw: raw };
+}
+
+const DEFAULT_LIMITS = { maxFrameBytes: 49152, chunkRawBytes: 32768, maxChunks: 64, ackTimeoutMs: 5000, maxRetries: 3,
+    heartbeatSeconds: 30, contentFirstByteMs: 10000, contentTotalMs: 30000 };
+
+export class ReferenceCp {
+    constructor({ tenantId = TENANT, agentId = AGENT, privateKey, publicKeyRaw, keyId = "vh-cp-test", requireEnforce = false,
+        now = Date.now, limits = {}, workspaceId = "", skewSeconds = 60 } = {}) {
+        this.publicKeyRaw = publicKeyRaw;
+        this.contract = loadContract();
+        if (!privateKey) ({ privateKey, publicKeyRaw: this.publicKeyRaw } = newKeyPair());
+        Object.assign(this, { tenantId, agentId, privateKey, keyId, requireEnforce, now, skewSeconds, workspaceId });
+        this.limits = { ...DEFAULT_LIMITS, ...limits };
+        this.sessionId = uuid();
+        this.laSeq = 0; this.cpSeq = 0;
+        this.ring = new Map();
+        this.unacked = new Map();
+        this.chunkStates = new Map();
+        this.state = "await_register";
+        this.reattached = false;
+        this.resume = null;
+        this.sendFn = () => {}; this.closeFn = () => {};
+        // observations
+        this.received = [];       // LA data frames accepted, in order
+        this.duplicates = [];     // seq of duplicate frames re-acked
+        this.errorsSent = [];     // codes sent to the LA
+        this.peerErrors = [];     // error frames the LA sent us
+        this.acksFromLa = [];
+        this.registers = [];
+        this.hellos = [];
+        this.rawIn = [];
+        this.dropAcks = 0;        // do not ack the next n accepted LA data frames (simulates lost acks)
+        this.silent = false;      // do not ack anything
+        this.ackDelayMs = 0;      // answer acks late (slow consumer)
+        this.onReceived = () => {};
+        this.contentRequests = new Map(); // requestId -> {chunks:[], done}
+    }
+
+    /** A new connection of the same agent (resume candidate). */
+    attach(send, close) {
+        this.sendFn = send; this.closeFn = close;
+        for (const u of this.unacked.values()) clearTimeout(u.timer);
+        this.state = "await_register";
+        this.reattached = this.sessionStarted === true;
+        this.resume = null;
+    }
+
+    detach() {
+        for (const u of this.unacked.values()) { clearTimeout(u.timer); u.timer = null; }
+        this.sendFn = () => {};
+    }
+
+    // ------------------------------------------------------------------ inbound (LA -> CP)
+
+    /** @returns {null | {code:string}} the refusal (error frame already sent, close done when fatal) */
+    feed(text) {
+        this.rawIn.push(text);
+        const r = this.#process(text);
+        if (r) {
+            this.errorsSent.push(r.code);
+            this.#sendError(r.code, r.refSeq, r.refMsgId);
+            if (isFatal(r.code)) { this.closeFn(closeCodeOf(r.code), r.code); this.detach(); }
+        }
+        return r;
+    }
+
+    #process(text) {
+        const L = this.limits;
+        if (Buffer.byteLength(text, "utf8") > L.maxFrameBytes) return { code: "frame_too_large" };
+        let m;
+        try { m = parseStrict(text); } catch { return { code: "bad_frame" }; }
+        if (m === null || typeof m !== "object" || Array.isArray(m)) return { code: "bad_frame" };
+        const info = this.contract.typeInfo(m.type);
+        if (!info) return { code: "unknown_type" };
+        const v = this.contract.validateFrame(m);
+        if (!v.ok) return { code: v.code };
+        if (m.tenantId !== this.tenantId) return { code: "tenant_mismatch" };
+        if (m.agentId !== this.agentId) return { code: "agent_mismatch" };
+        if (info.direction === "cp->la") return { code: "wrong_direction" };
+        if (this.state === "await_register") return m.type === "register" ? this.#onRegister(m) : { code: "handshake_violation" };
+        if (this.state === "await_hello") return m.type === "hello" ? this.#onHello(m) : { code: "not_ready" };
+        if (m.type === "register" || m.type === "hello") return { code: "handshake_violation" };
+        if (info.control) {
+            if (m.type === "ack") this.#onAck(m);
+            else if (m.type === "error") this.peerErrors.push(m.payload.code);
+            return null;
+        }
+        return this.#onData(m);
+    }
+
+    #onRegister(m) {
+        const skew = Math.abs(Date.parse(m.ts) - this.now()) / 1000;
+        if (skew > this.skewSeconds) return { code: "clock_skew" };
+        this.registers.push(m.payload);
+        this.resume = m.payload.resume || null;
+        this.state = "await_hello";
+        return null;
+    }
+
+    #onHello(m) {
+        if (this.requireEnforce && m.payload.signatureMode !== "enforce") return { code: "signature_mode_insufficient" };
+        this.hellos.push(m.payload);
+        const resumed = !!(this.reattached && this.resume && this.resume.sessionId === this.sessionId && this.resume.lastRecvSeq <= this.cpSeq);
+        if (this.reattached && !resumed) this.#reset();
+        this.reattached = false;
+        this.sessionStarted = true;
+        if (resumed) this.#ackUpTo(this.resume.lastRecvSeq);
+        this.#sendReady(resumed);
+        this.state = "ready";
+        if (resumed) for (const u of this.unacked.values()) { u.retries = 0; this.#transmit(u); }
+        return null;
+    }
+
+    #reset() {
+        for (const u of this.unacked.values()) clearTimeout(u.timer);
+        this.unacked.clear(); this.ring.clear(); this.chunkStates.clear();
+        this.laSeq = 0; this.cpSeq = 0; this.sessionId = uuid();
+    }
+
+    #onAck(m) {
+        this.acksFromLa.push({ ackSeq: m.payload.ackSeq, status: m.payload.status, errorCode: m.payload.errorCode });
+        if (m.payload.ackSeq > this.cpSeq) return;
+        if (m.payload.status === "rejected") {
+            this.#ackUpTo(m.payload.ackSeq - 1);
+            const u = this.unacked.get(m.payload.ackSeq);
+            if (u) { clearTimeout(u.timer); this.unacked.delete(m.payload.ackSeq); }
+        } else this.#ackUpTo(m.payload.ackSeq);
+    }
+
+    #ackUpTo(n) {
+        for (const [seq, u] of this.unacked) { if (seq > n) break; clearTimeout(u.timer); this.unacked.delete(seq); }
+    }
+
+    #onData(m) {
+        const { seq, msgId } = m;
+        if (seq <= this.laSeq) {
+            if (this.ring.get(seq) === msgId) { this.duplicates.push(seq); if (!this.silent) this.#sendAck(seq, "duplicate"); return null; }
+            return { code: "seq_replayed", refSeq: seq, refMsgId: msgId };
+        }
+        if (seq !== this.laSeq + 1) return { code: "seq_gap", refSeq: seq, refMsgId: msgId };
+        if (m.type === "content.response") {
+            const bad = this.#chunkRule(m);
+            if (bad) return { code: bad, refSeq: seq, refMsgId: msgId };
+        }
+        this.laSeq = seq;
+        this.ring.set(seq, msgId);
+        while (this.ring.size > 512) this.ring.delete(this.ring.keys().next().value);
+        if (m.ack !== undefined) this.#ackUpTo(m.ack);
+        this.received.push(m);
+        if (m.type === "content.response") {
+            const c = this.contentRequests.get(m.requestId) || { chunks: [], done: false };
+            c.chunks.push(Buffer.from(m.payload.data, "base64"));
+            if (m.chunk.last) c.done = true;
+            this.contentRequests.set(m.requestId, c);
+        }
+        if (this.dropAcks > 0) this.dropAcks--;
+        else if (!this.silent) {
+            if (this.ackDelayMs > 0) setTimeout(() => this.#sendAck(seq, "accepted"), this.ackDelayMs);
+            else this.#sendAck(seq, "accepted");
+        }
+        this.onReceived(m);
+        return null;
+    }
+
+    #chunkRule(m) {
+        const { index, total, last } = m.chunk;
+        const st = this.chunkStates.get(m.requestId);
+        if (st && st.done) return "chunk_out_of_order";
+        if (st && st.total !== total) return "chunk_inconsistent";
+        if (index !== (st ? st.next : 0)) return "chunk_out_of_order";
+        if (last !== (index === total - 1)) return "chunk_inconsistent";
+        this.chunkStates.set(m.requestId, { total, next: index + 1, done: last });
+        return null;
+    }
+
+    // ------------------------------------------------------------------ outbound (CP -> LA)
+
+    #envelope(type, seq, requestId, workspaceId) {
+        return { schemaVersion: 2, type, msgId: uuid(), seq, tenantId: this.tenantId, agentId: this.agentId, workspaceId,
+            ts: new Date(this.now()).toISOString(), ...(requestId ? { requestId } : {}) };
+    }
+
+    #sign(frame, type, payload, workspaceId) {
+        const raw = JSON.stringify(payload);
+        const timestamp = String(Math.floor(this.now() / 1000));
+        const nonce = crypto.randomBytes(18).toString("base64url");
+        const canonical = canonicalString({ method: "WS", pathAndQuery: type, bodySha256: sha256Hex(Buffer.from(raw, "utf8")),
+            tenantId: this.tenantId, workspaceId, timestamp, nonce });
+        const signature = crypto.sign(null, Buffer.from(canonical, "utf8"), this.privateKey).toString("base64");
+        frame.paramsRaw = raw;
+        frame.sig = { keyId: this.keyId, timestamp, nonce, tenantId: this.tenantId, workspaceId, signature };
+        frame.payload = payload;
+    }
+
+    #sendReady(resumed) {
+        const f = this.#envelope("ready", 0, null, this.workspaceId);
+        this.#sign(f, "ready", { protocol: 2, sessionId: this.sessionId, resumed, peerLastSeq: this.laSeq, limits: { ...this.limits } }, this.workspaceId);
+        this.sendFn(JSON.stringify(f));
+    }
+
+    #sendAck(ackSeq, status, errorCode) {
+        const f = this.#envelope("ack", 0, null, "");
+        f.payload = { ackSeq, status, ...(errorCode ? { errorCode } : {}) };
+        this.sendFn(JSON.stringify(f));
+    }
+
+    #sendError(code, refSeq, refMsgId) {
+        const f = this.#envelope("error", 0, null, "");
+        f.payload = { code, retryable: isRetryable(code), ...(refSeq ? { refSeq } : {}), ...(refMsgId ? { refMsgId } : {}), ...(isFatal(code) ? { closeCode: closeCodeOf(code) } : {}) };
+        this.sendFn(JSON.stringify(f));
+    }
+
+    /** Sends a CP->LA data frame (job.assign, content.request, ...). Retransmitted (re-signed) until acked. */
+    sendData(type, payload, { workspaceId = this.workspaceId, requestId } = {}) {
+        const seq = ++this.cpSeq;
+        const u = { seq, type, payload, workspaceId, requestId, msgId: uuid(), retries: 0, timer: null };
+        this.unacked.set(seq, u);
+        this.#transmit(u);
+        return seq;
+    }
+
+    #transmit(u) {
+        const f = this.#envelope(u.type, u.seq, u.requestId, u.workspaceId);
+        f.msgId = u.msgId;
+        if (this.laSeq > 0) f.ack = this.laSeq;
+        this.#sign(f, u.type, u.payload, u.workspaceId);
+        this.sendFn(JSON.stringify(f));
+        clearTimeout(u.timer);
+        u.timer = setTimeout(() => {
+            if (!this.unacked.has(u.seq)) return;
+            if (u.retries >= this.limits.maxRetries) { this.timedOut = true; this.closeFn(closeCodeOf("timeout"), "ack_timeout"); this.detach(); return; }
+            u.retries++; this.retransmits = (this.retransmits || 0) + 1;
+            this.#transmit(u);
+        }, this.limits.ackTimeoutMs);
+        u.timer.unref?.();
+    }
+
+    /** A signed v1 command envelope ({requestId, command, params, paramsRaw, sig}) as the v1 gateway sends it. */
+    v1Command(command, params = {}) {
+        const f = { requestId: uuid(), command, params };
+        const raw = JSON.stringify(params);
+        const timestamp = String(Math.floor(this.now() / 1000));
+        const nonce = crypto.randomBytes(18).toString("base64url");
+        const canonical = canonicalString({ method: "WS", pathAndQuery: command, bodySha256: sha256Hex(Buffer.from(raw, "utf8")),
+            tenantId: this.tenantId, workspaceId: this.workspaceId, timestamp, nonce });
+        f.paramsRaw = raw;
+        f.sig = { keyId: this.keyId, timestamp, nonce, tenantId: this.tenantId, workspaceId: this.workspaceId,
+            signature: crypto.sign(null, Buffer.from(canonical, "utf8"), this.privateKey).toString("base64") };
+        return JSON.stringify(f);
+    }
+
+    /** Sends exactly this frame (for the tests that need an invalid CP frame). */
+    sendRaw(text) { this.sendFn(text); }
+    frameWith(type, payload, over = {}) {
+        const seq = ++this.cpSeq;
+        const f = this.#envelope(type, seq, over.requestId, this.workspaceId);
+        this.#sign(f, type, payload, this.workspaceId);
+        return Object.assign(f, over.frame || {});
+    }
+}
+
+/** A WebSocket server in front of one ReferenceCp (one agent). Authorization: Bearer <token>. */
+export class ReferenceCpServer {
+    constructor(opts = {}) {
+        this.cp = new ReferenceCp(opts);
+        this.privateKey = this.cp.privateKey;
+        this.publicKeyRaw = this.cp.publicKeyRaw;
+        this.keyId = this.cp.keyId;
+        this.token = opts.token || "tok";
+        this.connections = 0;
+        this.textsFromLa = [];   // everything the LA sent that was not a v2 frame (pings, legacy register, v1 answers)
+        this.legacy = [];        // parsed JSON frames of v1 shape
+        this.v2Disabled = !!opts.v2Disabled;      // behave like a gateway without v2: ignore v2 frames
+        this.refuseV2 = !!opts.refuseV2;          // answer the v2 register with error protocol_unsupported
+        this.closes = [];
+    }
+
+    async start() {
+        this.wss = new WebSocketServer({ host: "127.0.0.1", port: 0 });
+        await new Promise((r) => this.wss.on("listening", r));
+        this.port = this.wss.address().port;
+        this.wss.on("connection", (ws, req) => {
+            if (req.headers.authorization !== `Bearer ${this.token}`) { ws.close(1008, "unauthorized"); return; }
+            this.connections++;
+            this.ws = ws;
+            if (!this.v2Disabled) this.cp.attach((t) => { if (ws.readyState === 1) ws.send(t); }, (code, reason) => ws.close(code, reason));
+            ws.on("message", (d, isBinary) => {
+                const text = d.toString();
+                if (text === "ping") { ws.send("pong"); return; }
+                let o = null;
+                try { o = JSON.parse(text); } catch { /* not json */ }
+                if (o && o.schemaVersion !== undefined) {
+                    if (this.v2Disabled) return;
+                    if (this.refuseV2) { // like the gateway: the connection is v1 from now on; the v2 frames after the register are ignored
+                        if (o.type === "register") ws.send(JSON.stringify({ schemaVersion: 2, type: "error", msgId: uuid(), seq: 0, tenantId: this.cp.tenantId, agentId: this.cp.agentId,
+                            workspaceId: "", ts: new Date().toISOString(), payload: { code: "protocol_unsupported", retryable: false } }));
+                        return;
+                    }
+                    this.cp.feed(text);
+                } else {
+                    this.textsFromLa.push(text);
+                    if (o) this.legacy.push(o);
+                }
+                void isBinary;
+            });
+            ws.on("close", (code) => { this.closes.push(code); this.cp.detach(); });
+        });
+        return this;
+    }
+
+    get url() { return `http://127.0.0.1:${this.port}`; }
+    kill() { this.ws && this.ws.terminate(); }
+    async stop() {
+        for (const c of this.wss.clients) c.terminate();
+        this.cp.detach();
+        await new Promise((r) => this.wss.close(r));
+    }
+}
+
+export async function waitFor(cond, ms = 4000, step = 10) {
+    const t0 = Date.now();
+    while (Date.now() - t0 < ms) {
+        const v = await cond();
+        if (v) return v;
+        await new Promise((r) => setTimeout(r, step));
+    }
+    throw new Error(`waitFor timed out after ${ms} ms: ${cond.toString().slice(0, 120)}`);
+}

package/test/la-protocol-v2/helpers/spawn-agent.js

@@ -0,0 +1,36 @@
+// Boots the REAL agent (src/server.js of `root`) against a ReferenceCpServer and returns what it did.
+// Used by the flag-off characterization and by the end-to-end test of the v2 tunnel.
+import net from "node:net";
+import os from "node:os";
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+export const DEFAULT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+export const freePort = () => new Promise((res) => { const s = net.createServer().listen(0, "127.0.0.1", () => { const p = s.address().port; s.close(() => res(p)); }); });
+
+export async function runAgent({ srv, root = DEFAULT_ROOT, env = {}, cfg, until, ms = 20000, prepare }) {
+    const ws = fs.mkdtempSync(path.join(os.tmpdir(), "v2e2e-ws-"));
+    if (prepare) await prepare(ws); // F3-07: put files / a git repo in the workspace before the agent starts
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), "v2e2e-home-"));
+    if (cfg) {
+        fs.mkdirSync(path.join(home, ".deepdebug"));
+        fs.writeFileSync(path.join(home, ".deepdebug", "config.json"), JSON.stringify(cfg));
+    }
+    const full = { ...process.env, PORT: String(await freePort()), GATEWAY_URL: srv.url, AUTH_TOKEN: srv.token, WORKSPACE_ROOT: ws, HOME: home, ...env };
+    delete full.LOCAL_AGENT_TOKEN;
+    for (const k of Object.keys(full)) if (full[k] === undefined) delete full[k];
+    const child = spawn(process.execPath, ["src/server.js"], { cwd: root, env: full, stdio: "ignore" });
+    try {
+        const deadline = Date.now() + ms;
+        while (Date.now() < deadline) {
+            if (until && (await until())) break;
+            await new Promise((r) => setTimeout(r, 50));
+        }
+    } finally {
+        child.kill("SIGKILL");
+        fs.rmSync(ws, { recursive: true, force: true });
+        fs.rmSync(home, { recursive: true, force: true });
+    }
+}