deepdebug-local-agent 1.2.0 → 1.4.0

package/test/la-protocol-v2/traces.test.js

@@ -0,0 +1,270 @@
+// F3-05b: the 24 whole-session traces of the contract (F3-22), reproduced in Node. "Traces are language
+// neutral; the LA must reproduce each expect.error." Three things are shown for them:
+//   1. the reference CP (test helper) reproduces every trace: same error at the same frame (so the model the
+//      other tests use is the model of the contract);
+//   2. the two traces whose error is in a CP->LA frame (params_mismatch, tenant_mismatch of the signature)
+//      are reproduced by the REAL LA session, same error at the same frame;
+//   3. for the others (an LA frame that the CP refuses) the LA's own send path refuses to produce the same
+//      frame, with the same code; the valid traces are replayed with the LA as the LA.
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ReferenceCp, uuid, waitFor } from "./helpers/reference-cp.js";
+import { inMemory, signingFor } from "./helpers/la-rig.js";
+import { V2Session } from "../../src/la-protocol-v2/session.js";
+
+const DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "../contract/la-protocol-v2/vectors/traces");
+const traces = fs.readdirSync(DIR).filter((f) => f.endsWith(".json")).sort().map((f) => ({ file: f, name: f.replace(".json", ""), ...JSON.parse(fs.readFileSync(path.join(DIR, f), "utf8")) }));
+
+test("the suite has all 24 traces (20 invalid, 4 valid)", () => {
+    assert.equal(traces.length, 24);
+    assert.equal(traces.filter((t) => t.expect.ok).length, 4);
+});
+
+const textOf = (fr) => {
+    let text = JSON.stringify(fr.frame);
+    if (fr.inflateBytesTo) text += " ".repeat(Math.max(0, fr.inflateBytesTo - Buffer.byteLength(text)));
+    return text;
+};
+
+/** The reference CP in the state the trace starts from (a resumed session when the trace says so). */
+function cpFor(trace) {
+    const s = trace.session;
+    const cp = new ReferenceCp({ tenantId: s.tenantId, agentId: s.agentId, requireEnforce: s.requireEnforce, now: () => Date.parse(s.now) });
+    const ready = trace.frames.map((f) => f.frame).find((f) => f.type === "ready");
+    const reg = trace.frames.map((f) => f.frame).find((f) => f.type === "register");
+    if (ready && ready.payload.resumed) {
+        cp.sessionStarted = true;
+        cp.sessionId = ready.payload.sessionId;
+        cp.laSeq = ready.payload.peerLastSeq;
+        cp.cpSeq = reg.payload.resume.lastRecvSeq;
+    }
+    cp.attach(() => {}, () => {});
+    return cp;
+}
+
+// ------------------------------------------------------------------------------------------ 1. the reference CP
+
+for (const t of traces) {
+    const cpSideError = t.expect.error && t.frames[t.expect.atFrame].dir === "cp->la";
+    test(`reference CP reproduces ${t.name}${cpSideError ? " (n/a: the error is in a CP frame, see 2)" : ""}`, { skip: cpSideError }, () => {
+        const cp = cpFor(t);
+        let failed = null;
+        for (let i = 0; i < t.frames.length && !failed; i++) {
+            const fr = t.frames[i];
+            if (fr.dir === "cp->la") { cp.cpSeq = Math.max(cp.cpSeq, fr.frame.seq); continue; }
+            const r = cp.feed(textOf(fr));
+            if (r) failed = { error: r.code, atFrame: i };
+        }
+        if (t.expect.ok) {
+            assert.equal(failed, null, JSON.stringify(failed));
+            if (t.expect.duplicateFrames) assert.equal(cp.duplicates.length, t.expect.duplicateFrames.length);
+        } else {
+            assert.deepEqual(failed, { error: t.expect.error, atFrame: t.expect.atFrame });
+        }
+    });
+}
+
+// ------------------------------------------------------------------------------------------ 2. errors in CP frames, by the LA
+
+for (const name of ["invalid-params-raw-differs-from-payload", "invalid-sig-tenant-mismatch"]) {
+    test(`the LA reproduces ${name}: ${traces.find((t) => t.name === name).expect.error} at frame ${traces.find((t) => t.name === name).expect.atFrame}`, async () => {
+        const t = traces.find((x) => x.name === name);
+        const cp = new ReferenceCp({ tenantId: t.session.tenantId, agentId: t.session.agentId });
+        // the trace's signatures are placeholders: mode off skips the cryptography, the structural checks still run
+        const env = inMemory(cp, { mode: "off", tenantId: t.session.tenantId, agentId: t.session.agentId });
+        env.session.attach(env.transport);
+        await waitFor(() => env.session.state === "ready");
+        const bad = t.frames[t.expect.atFrame].frame;
+        env.session.setHandler(bad.type, () => ({ accept: true }));
+        env.session.handleText(JSON.stringify(bad), env.transport);
+        await waitFor(() => cp.peerErrors.length > 0);
+        assert.deepEqual(cp.peerErrors, [t.expect.error]);
+        assert.equal(env.session.stats.dataOut, 0);
+        env.session.close();
+    });
+}
+
+// ------------------------------------------------------------------------------------------ 3. the LA never produces them
+
+const LA_FRAMES = (t) => t.frames.map((f, i) => ({ ...f, i })).filter((f) => f.dir === "la->cp");
+
+async function readyLa() {
+    const cp = new ReferenceCp();
+    const env = inMemory(cp).start();
+    await waitFor(() => env.session.state === "ready");
+    return { cp, ...env };
+}
+
+for (const name of ["invalid-chunk-after-last", "invalid-chunk-byte-length-mismatch", "invalid-chunk-last-flag", "invalid-chunk-out-of-order", "invalid-chunk-total-changes", "invalid-payload-above-limit"]) {
+    test(`the LA refuses to send the chunks of ${name}: same code at the same frame`, async () => {
+        const t = traces.find((x) => x.name === name);
+        const { cp, session } = await readyLa();
+        let got = null;
+        for (const fr of LA_FRAMES(t)) {
+            if (fr.frame.type !== "content.response") continue;
+            try {
+                await session.enqueue("content.response", fr.frame.payload, { requestId: fr.frame.requestId, chunk: fr.frame.chunk }).then((h) => h.acked);
+            } catch (e) { got = { error: e.code, atFrame: fr.i }; break; }
+        }
+        // the oversized trace chunk is refused by the schema (payload maxLength), which the CP reports as payload_too_large
+        assert.deepEqual(got, { error: t.expect.error, atFrame: t.expect.atFrame });
+        assert.deepEqual(cp.errorsSent, [], "nothing invalid reached the CP");
+        session.close();
+    });
+}
+
+test("the LA never produces invalid-event-before-ready / invalid-first-frame-not-register: register and hello first, no data before ready", async () => {
+    const cp = new ReferenceCp();
+    const sent = [];
+    const env = inMemory(cp);
+    const swallow = { send: (t) => sent.push(JSON.parse(t)), close() {}, bufferedAmount: () => 0 };
+    env.session.attach(swallow);
+    assert.deepEqual(sent.map((f) => f.type), ["register", "hello"], "the first frame is register, then hello");
+    await assert.rejects(env.session.enqueue("job.event", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", state: "running" }), (e) => e.code === "not_ready");
+    assert.equal(sent.length, 2);
+    env.session.close();
+});
+
+test("the LA never produces invalid-clock-skew: register.ts is the clock of the LA, hello carries clockEpochMs", async () => {
+    const cp = new ReferenceCp();
+    const sent = [];
+    const env = inMemory(cp);
+    env.session.attach({ send: (t) => sent.push(JSON.parse(t)), close() {}, bufferedAmount: () => 0 });
+    assert.ok(Math.abs(Date.parse(sent[0].ts) - Date.now()) < 2000);
+    assert.ok(Math.abs(sent[1].payload.clockEpochMs - Date.now()) < 2000);
+    env.session.close();
+});
+
+test("the LA never produces invalid-signature-warn-with-enforce-required: hello.signatureMode is the real mode, and a CP that requires enforce says so", async () => {
+    const cp = new ReferenceCp({ requireEnforce: true });
+    const env = inMemory(cp, { mode: "warn" }).start();
+    await waitFor(() => cp.errorsSent.length > 0);
+    assert.deepEqual(cp.errorsSent, ["signature_mode_insufficient"]);
+    assert.equal(env.session.state, "await_ready"); // not ready, no data possible
+    assert.equal(cp.hellos.length, 0);
+    env.session.close();
+});
+
+test("the LA never produces invalid-agent-mismatch / invalid-tenant-mismatch: every frame carries the configured ids, never one from a payload", async () => {
+    const { cp, session } = await readyLa();
+    await session.send("job.event", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", state: "running" });
+    for (const f of cp.received) {
+        assert.equal(f.tenantId, cp.tenantId);
+        assert.equal(f.agentId, cp.agentId);
+    }
+    // there is no way to pass an identity to enqueue(); a payload that tries is refused by the closed schema
+    await assert.rejects(session.enqueue("job.event", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", state: "running", tenantId: "99999999-5a4d-4e7b-9c21-0a1b2c3d4e5f" }), (e) => e.code === "schema_violation");
+    session.close();
+});
+
+test("the LA never produces invalid-la-sends-job-assign / invalid-type-outside-allowlist", async () => {
+    const { cp, session } = await readyLa();
+    await assert.rejects(session.enqueue("job.assign", {}), (e) => e.code === "wrong_direction");
+    await assert.rejects(session.enqueue("shell.exec", {}), (e) => e.code === "unknown_type");
+    assert.deepEqual(cp.errorsSent, []);
+    session.close();
+});
+
+test("the LA never produces invalid-seq-gap / invalid-seq-repeated / invalid-resume-restarts-seq: consecutive seq, one msgId per seq, a resume continues", async () => {
+    const { cp, session } = await readyLa();
+    for (let i = 0; i < 4; i++) await session.send("job.event", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", state: "running", iteration: i });
+    assert.deepEqual(cp.received.map((f) => f.seq), [1, 2, 3, 4]);
+    assert.equal(new Set(cp.received.map((f) => f.msgId)).size, 4);
+    assert.deepEqual(cp.errorsSent, []);
+    session.close();
+});
+
+test("the LA never produces invalid-frame-over-48kib: frames are compact JSON and the size is checked before sending", async () => {
+    const { cp, session } = await readyLa();
+    await assert.rejects(session.enqueue("job.event", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", state: "running", phase: "x".repeat(60_000) }), (e) => ["frame_too_large", "payload_too_large", "schema_violation"].includes(e.code));
+    // and the same frame as the trace has it (padded to 50000 bytes) is refused on the way IN as frame_too_large
+    const t = traces.find((x) => x.name === "invalid-frame-over-48kib");
+    const fr = t.frames[t.expect.atFrame];
+    const { transport } = { transport: session.transport };
+    session.handleText(textOf(fr), transport);
+    await waitFor(() => cp.peerErrors.length > 0);
+    assert.deepEqual(cp.peerErrors, ["frame_too_large"]);
+    session.close();
+});
+
+// ------------------------------------------------------------------------------------------ valid traces, LA as the LA
+
+test("valid-handshake-and-job: CP job.assign -> LA acks it (ackSeq 1) and then reports job.event x2 + job.result with seq 1..3", async () => {
+    const t = traces.find((x) => x.name === "valid-handshake-and-job");
+    const cp = new ReferenceCp({ tenantId: t.session.tenantId, agentId: t.session.agentId, requireEnforce: true });
+    const env = inMemory(cp, { tenantId: t.session.tenantId, agentId: t.session.agentId }).start();
+    await waitFor(() => env.session.state === "ready");
+    const assign = t.frames.find((f) => f.frame.type === "job.assign").frame;
+    env.session.setHandler("job.assign", (ctx) => { assert.deepEqual(ctx.params, assign.payload); return { accept: true }; });
+    cp.sendData("job.assign", assign.payload, { workspaceId: assign.workspaceId, requestId: assign.requestId });
+    await waitFor(() => cp.acksFromLa.length === 1);
+    assert.deepEqual(cp.acksFromLa[0], { ackSeq: 1, status: "accepted", errorCode: undefined });
+    for (const fr of LA_FRAMES(t).filter((f) => ["job.event", "job.result"].includes(f.frame.type))) {
+        await env.session.send(fr.frame.type, fr.frame.payload, { workspaceId: fr.frame.workspaceId });
+    }
+    assert.deepEqual(cp.received.map((f) => [f.type, f.seq]), [["job.event", 1], ["job.event", 2], ["job.result", 3]]);
+    assert.deepEqual(cp.errorsSent, []);
+    env.session.close();
+});
+
+test("valid-content-chunks-in-order: the three chunks of the trace go out in order and the CP accepts them", async () => {
+    const t = traces.find((x) => x.name === "valid-content-chunks-in-order");
+    const cp = new ReferenceCp({ tenantId: t.session.tenantId, agentId: t.session.agentId });
+    const env = inMemory(cp, { tenantId: t.session.tenantId, agentId: t.session.agentId }).start();
+    await waitFor(() => env.session.state === "ready");
+    for (const fr of LA_FRAMES(t).filter((f) => f.frame.type === "content.response")) {
+        await env.session.send("content.response", fr.frame.payload, { requestId: fr.frame.requestId, chunk: fr.frame.chunk, workspaceId: fr.frame.workspaceId });
+    }
+    assert.deepEqual(cp.received.map((f) => [f.seq, f.chunk.index]), [[1, 0], [2, 1], [3, 2]]);
+    assert.deepEqual(cp.errorsSent, []);
+    env.session.close();
+});
+
+test("valid-retransmit-is-idempotent: an ack lost -> the same frame again -> the CP re-acks and counts one event", async () => {
+    const cp = new ReferenceCp({ limits: { ackTimeoutMs: 100 } });
+    const env = inMemory(cp).start();
+    await waitFor(() => env.session.state === "ready");
+    cp.dropAcks = 1;
+    await env.session.send("job.event", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", state: "running" });
+    await env.session.send("job.event", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", state: "succeeded" });
+    assert.deepEqual(cp.duplicates, [1]);
+    assert.deepEqual(cp.received.map((f) => f.seq), [1, 2]);
+    assert.deepEqual(cp.errorsSent, []);
+    env.session.close();
+});
+
+test("valid-resume-continues-seq: after a resumed ready the LA continues at peerLastSeq+1", async () => {
+    const t = traces.find((x) => x.name === "valid-resume-continues-seq");
+    const cp = new ReferenceCp({ tenantId: t.session.tenantId, agentId: t.session.agentId });
+    const env = inMemory(cp, { tenantId: t.session.tenantId, agentId: t.session.agentId });
+    // first life: 5 events delivered
+    env.session.attach(env.transport);
+    await waitFor(() => env.session.state === "ready");
+    for (let i = 0; i < 5; i++) await env.session.send("job.event", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", state: "running", iteration: i });
+    // the CP also sent 4 frames
+    env.session.setHandler("job.cancel", () => ({ accept: true }));
+    for (let i = 0; i < 4; i++) cp.sendData("job.cancel", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", reason: "user" });
+    await waitFor(() => env.session.lastRecvSeq === 4);
+    // second life: same session object (the LA process kept it), new connection
+    const t2 = { send: (x) => { env.wire.toCp.push(x); cp.feed(x); }, close() {}, bufferedAmount: () => 0 };
+    env.session.detach(env.transport);
+    cp.attach((x) => queueMicrotask(() => env.session.handleText(x, t2)), () => {});
+    env.session.attach(t2);
+    await waitFor(() => env.session.state === "ready");
+    assert.deepEqual(cp.registers.at(-1).resume, { sessionId: cp.sessionId, lastRecvSeq: 4 });
+    await env.session.send("job.event", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", state: "running", iteration: 5 });
+    assert.equal(cp.received.at(-1).seq, 6, "continues at peerLastSeq + 1");
+    assert.deepEqual(cp.errorsSent, []);
+    env.session.close();
+});
+
+test("V2Session is exported and constructible without side effects (no timers left running)", () => {
+    const cp = new ReferenceCp();
+    const s = new V2Session({ tenantId: cp.tenantId, agentId: cp.agentId, signing: signingFor({ keyId: cp.keyId, publicKeyRaw: cp.publicKeyRaw }), laVersion: "1.3.0" });
+    assert.equal(s.state, "idle");
+    s.close();
+    assert.equal(uuid().length, 36);
+});

package/test/la-protocol-v2/tunnel-e2e.test.js

@@ -0,0 +1,124 @@
+// F3-05b end to end: the real agent process (src/server.js) against the reference CP.
+//  - flag unset / false: the v1 client, nothing of v2 on the wire (characterization; the frames are the v1 ones)
+//  - flag true: v2 handshake with a signed ready, v1 commands still answered on the same connection
+//  - flag true against a gateway without v2: falls back to the v1 register on the same connection
+//  - flag true without an agent id: stays v1
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { ReferenceCpServer, TENANT, AGENT, waitFor } from "./helpers/reference-cp.js";
+import { runAgent } from "./helpers/spawn-agent.js";
+
+const baseEnv = (srv) => ({
+    TENANT_ID: TENANT,
+    LOCAL_AGENT_SIGNATURE_MODE: "enforce",
+    LOCAL_AGENT_SIGNING_PUBLIC_KEYS: `${srv.keyId}=${srv.publicKeyRaw}`,
+});
+
+for (const flag of [undefined, "false", "off", "0", "bogus"]) {
+    test(`flag ${flag === undefined ? "unset" : JSON.stringify(flag)}: the v1 client, exactly: legacy register, no v2 frame, v1 command answered`, async () => {
+        const srv = await new ReferenceCpServer({}).start();
+        try {
+            await runAgent({
+                // everything v2 needs IS configured (UUID tenant, agent id, trusted key): only the flag keeps it off
+                srv, cfg: { authorizationId: AGENT, tenantId: TENANT }, env: { ...baseEnv(srv), LOCAL_AGENT_PROTOCOL_V2: flag },
+                until: async () => {
+                    if (srv.ws && srv.legacy.some((f) => f.type === "register") && !srv.sent) {
+                        srv.sent = true;
+                        srv.ws.send(srv.cp.v1Command("health", {}));
+                    }
+                    return srv.legacy.some((f) => f.command === "health");
+                },
+            });
+            const reg = srv.legacy.find((f) => f.type === "register");
+            assert.deepEqual(Object.keys(reg).sort(), ["port", "tenantId", "type", "workspacePath"]);
+            assert.equal(reg.tenantId, TENANT);
+            const health = srv.legacy.find((f) => f.command === "health");
+            assert.equal(health.status, "ok");
+            assert.equal(srv.cp.rawIn.length, 0, "no v2 frame was ever sent");
+            assert.equal(srv.cp.registers.length, 0);
+            assert.equal(srv.textsFromLa.some((t) => t.includes("schemaVersion")), false);
+        } finally { await srv.stop(); }
+    });
+}
+
+test("flag true: v2 handshake (register, hello, signed ready), no v1 register, and a v1 command is still answered on the same connection", async () => {
+    const srv = await new ReferenceCpServer({ requireEnforce: true }).start();
+    try {
+        await runAgent({
+            srv, cfg: { authorizationId: AGENT, tenantId: TENANT },
+            env: { ...baseEnv(srv), LOCAL_AGENT_PROTOCOL_V2: "true" },
+            until: async () => {
+                if (srv.cp.state === "ready" && !srv.sent) { srv.sent = true; srv.ws.send(srv.cp.v1Command("health", {})); }
+                return srv.legacy.some((f) => f.command === "health");
+            },
+        });
+        assert.equal(srv.connections, 1);
+        const reg = srv.cp.registers[0];
+        assert.equal(reg.protocol, 2);
+        assert.equal(reg.signatureMode, "enforce");
+        assert.match(reg.laVersion, /^\d+\.\d+\.\d+$/);
+        assert.deepEqual(reg.capabilities, ["chunk.base64", "protocol.v2", "v1.commands"]);
+        assert.ok(reg.workspaces.every((w) => /^[0-9a-f]{64}$/.test(w.pathSha256)), "only hashes of paths");
+        assert.equal(JSON.stringify(srv.cp.rawIn).includes("/tmp") || JSON.stringify(srv.cp.rawIn).includes("v2e2e-ws"), false, "no workspace path on the wire");
+        assert.equal(srv.cp.hellos[0].signatureMode, "enforce");
+        assert.equal(srv.legacy.some((f) => f.type === "register"), false, "no v1 register: v2 owns the registration");
+        assert.deepEqual(srv.cp.errorsSent, []);
+        assert.equal(srv.legacy.find((f) => f.command === "health").status, "ok", "v1 command on a v2 connection");
+    } finally { await srv.stop(); }
+});
+
+test("flag true, the CP sends a signed v2 job.cancel: acked `rejected protocol_unsupported` (no handler yet), connection stays up", async () => {
+    const srv = await new ReferenceCpServer({ requireEnforce: true }).start();
+    try {
+        await runAgent({
+            srv, cfg: { authorizationId: AGENT, tenantId: TENANT },
+            env: { ...baseEnv(srv), LOCAL_AGENT_PROTOCOL_V2: "true" },
+            until: async () => {
+                if (srv.cp.state === "ready" && !srv.sent) { srv.sent = true; srv.cp.sendData("job.cancel", { jobId: "c3d4e5f6-a7b8-4c9d-8e0f-2a3b4c5d6e7f", reason: "user" }); }
+                return srv.cp.acksFromLa.length > 0;
+            },
+        });
+        assert.deepEqual(srv.cp.acksFromLa, [{ ackSeq: 1, status: "rejected", errorCode: "protocol_unsupported" }]);
+        assert.deepEqual(srv.cp.errorsSent, []);
+    } finally { await srv.stop(); }
+});
+
+test("flag true against a gateway that does not speak v2: after the handshake timeout the v1 register goes out on the same connection", async () => {
+    const srv = await new ReferenceCpServer({ v2Disabled: true }).start();
+    try {
+        await runAgent({
+            srv, cfg: { authorizationId: AGENT, tenantId: TENANT },
+            env: { ...baseEnv(srv), LOCAL_AGENT_PROTOCOL_V2: "true", LOCAL_AGENT_V2_HANDSHAKE_MS: "300" },
+            until: async () => srv.legacy.some((f) => f.type === "register"),
+        });
+        const reg = srv.legacy.find((f) => f.type === "register");
+        assert.deepEqual(Object.keys(reg).sort(), ["port", "tenantId", "type", "workspacePath"]);
+        assert.equal(srv.connections, 1, "same connection");
+    } finally { await srv.stop(); }
+});
+
+test("flag true without an agent id (no authorizationId): v1 only, nothing of v2 on the wire", async () => {
+    const srv = await new ReferenceCpServer({}).start();
+    try {
+        await runAgent({
+            srv, env: { ...baseEnv(srv), LOCAL_AGENT_PROTOCOL_V2: "true" },
+            until: async () => srv.legacy.some((f) => f.type === "register"),
+        });
+        assert.equal(srv.cp.rawIn.length, 0);
+        assert.ok(srv.legacy.some((f) => f.type === "register"));
+    } finally { await srv.stop(); }
+});
+
+test("flag true with a tenant id that is not a UUID: v1 only", async () => {
+    const srv = await new ReferenceCpServer({}).start();
+    try {
+        await runAgent({
+            srv, cfg: { authorizationId: AGENT },
+            env: { ...baseEnv(srv), TENANT_ID: "tenant-test", LOCAL_AGENT_SIGNATURE_MODE: "off", LOCAL_AGENT_PROTOCOL_V2: "true" },
+            until: async () => srv.legacy.some((f) => f.type === "register"),
+        });
+        assert.equal(srv.cp.rawIn.length, 0);
+    } finally { await srv.stop(); }
+});
+
+test("sanity: waitFor is exported", () => assert.equal(typeof waitFor, "function"));

package/test/ws-channel/allowlist.test.js

@@ -0,0 +1,67 @@
+// Contract tests for the metadata-only outbound allowlist (T4-10).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { validateOutbound, projectResponse, OUTBOUND_SCHEMAS } from '../../src/ws-channel/allowlist.js';
+
+const H = 'a'.repeat(64);
+
+test('contract: every allowed message type validates with a golden example', () => {
+  const golden = [
+    { type: 'register', tenantId: 'tenant-1', port: 5055, workspaceHash: H },
+    { type: 'hello', agentVersion: '1.1.0', protocol: 2, signatureMode: 'enforce', metadataOnly: 'enforce' },
+    { type: 'status', state: 'idle', openWorkspaces: 2, queueDepth: 0, uptimeSeconds: 120 },
+    { type: 'cost', requestId: 'req-1', model: 'claude-sonnet-5-5', tokensIn: 10, tokensOut: 5, costMicros: 1200 },
+    { requestId: 'r1', command: 'health', ok: true, status: 'ok', openWorkspaces: 1 },
+    { requestId: 'r2', command: 'workspace.open', ok: false, errorCode: 'command_error' },
+  ];
+  for (const m of golden) assert.deepEqual(validateOutbound(m).ok, true, JSON.stringify(m));
+});
+
+test('contract: schema set is closed (changing it is a deliberate, reviewed edit)', () => {
+  assert.deepEqual(Object.keys(OUTBOUND_SCHEMAS).sort(), ['cost', 'hello', 'register', 'response', 'status']);
+});
+
+test('rejects unknown types, unknown fields and non-objects', () => {
+  assert.equal(validateOutbound({ type: 'file-content', content: 'x' }).reason, 'unknown-type');
+  assert.equal(validateOutbound({ type: 'status', state: 'idle', content: 'x' }).reason, 'unknown-field');
+  assert.equal(validateOutbound('ping').reason, 'not-an-object');
+  assert.equal(validateOutbound([]).reason, 'not-an-object');
+  assert.equal(validateOutbound({ type: '__proto__' }).reason, 'unknown-type');
+});
+
+test('rejects free text: code, diffs, paths, log lines and chat do not fit any string field', () => {
+  const leaks = ['const x = require("fs");', '--- a/x\n+++ b/x', '/Users/me/project/src/A.java', 'ERROR something failed', 'hello how are you', ''];
+  for (const v of leaks) {
+    assert.equal(validateOutbound({ type: 'register', tenantId: v, port: 1 }).ok, false, JSON.stringify(v));
+    assert.equal(validateOutbound({ type: 'cost', requestId: 'r', model: v }).ok, false);
+    assert.equal(validateOutbound({ requestId: 'r', command: v }).ok, false);
+  }
+  assert.equal(validateOutbound({ type: 'register', tenantId: 't', port: 1, workspaceHash: '/etc/passwd' }).field, 'workspaceHash');
+});
+
+test('rejects nested values, wrong numeric ranges and missing required fields', () => {
+  assert.equal(validateOutbound({ type: 'status', state: { a: 1 } }).ok, false);
+  assert.equal(validateOutbound({ type: 'status', openWorkspaces: -1 }).ok, false);
+  assert.equal(validateOutbound({ type: 'status', openWorkspaces: 1.5 }).ok, false);
+  assert.equal(validateOutbound({ type: 'register', port: 70000, tenantId: 't' }).ok, false);
+  assert.equal(validateOutbound({ type: 'register', port: 5055 }).reason, 'missing-field');
+  assert.equal(validateOutbound({ type: 'status', state: 'unknown-state' }).ok, false);
+});
+
+test('validation reports field names and codes, never the offending value', () => {
+  const secret = 'AKIA_SECRET_VALUE_123 /home/x';
+  const r = validateOutbound({ type: 'register', tenantId: secret, port: 1 });
+  assert.equal(JSON.stringify(r).includes('SECRET'), false);
+});
+
+test('projectResponse strips paths, turns free text into errorCode, rejects content fields', () => {
+  assert.deepEqual(projectResponse('r', 'health', { status: 'ok', workspace: '/home/u/p', openWorkspaces: 1 }).message,
+    { requestId: 'r', command: 'health', status: 'ok', openWorkspaces: 1 });
+  assert.deepEqual(projectResponse('r', 'workspace.open', { ok: true, root: '/home/u/p' }).message,
+    { requestId: 'r', command: 'workspace.open', ok: true });
+  assert.deepEqual(projectResponse('r', 'x', { error: 'ENOENT /home/u/secret.txt' }).message,
+    { requestId: 'r', command: 'x', ok: false, errorCode: 'command_error' });
+  const c = projectResponse('r', 'workspace.file-content', { content: 'code', found: true });
+  assert.equal(c.ok, false);
+  assert.equal(c.field, 'content');
+});

package/test/ws-channel/metadata-guard.test.js

@@ -0,0 +1,104 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createWsMetadataGuard } from '../../src/ws-channel/metadata-guard.js';
+import { resolveWsMetadataConfig } from '../../src/ws-channel/config.js';
+import { createTransitGuard } from '../../src/ws-channel/transit-guard.js';
+
+const capture = () => { const lines = []; return { lines, warn: (m) => lines.push(String(m)), log: (m) => lines.push(String(m)) }; };
+const enforce = { mode: 'enforce' };
+
+test('flag config: default off, enforce, and unrecognised values fail closed', () => {
+  const warn = () => {};
+  assert.equal(resolveWsMetadataConfig({}, warn).mode, 'off');
+  assert.equal(resolveWsMetadataConfig({ LOCAL_AGENT_WS_METADATA_ONLY: '' }, warn).mode, 'off');
+  assert.equal(resolveWsMetadataConfig({ LOCAL_AGENT_WS_METADATA_ONLY: 'off' }, warn).mode, 'off');
+  assert.equal(resolveWsMetadataConfig({ LOCAL_AGENT_WS_METADATA_ONLY: ' ENFORCE ' }, warn).mode, 'enforce');
+  assert.equal(resolveWsMetadataConfig({ LOCAL_AGENT_WS_METADATA_ONLY: 'enfroce' }, warn).mode, 'enforce');
+});
+
+test('flag off: no guard is created and no socket is opened', () => {
+  let socketsOpened = 0;
+  const openSocket = () => { socketsOpened++; };
+  const guard = createWsMetadataGuard({ config: resolveWsMetadataConfig({}) });
+  assert.equal(guard, null);
+  if (guard) openSocket(); // the conditional start point: only reached when the guard exists
+  assert.equal(socketsOpened, 0);
+});
+
+test('legacy content commands are refused before execution, with a metadata-only error', () => {
+  const log = capture();
+  const g = createWsMetadataGuard({ config: enforce, logger: log });
+  for (const cmd of ['workspace.file-content', 'workspace.diff', 'workspace.safe-patch', 'mcp.read-file', 'mcp.execute-command', 'mcp.apply-patch']) {
+    const a = g.admitCommand('req-1', cmd);
+    assert.equal(a.ok, false, cmd);
+    assert.deepEqual(JSON.parse(a.errorFrame), { requestId: 'req-1', command: cmd, ok: false, errorCode: 'blocked_metadata_only' });
+  }
+});
+
+test('health reply carries only metadata (workspace path dropped)', () => {
+  const g = createWsMetadataGuard({ config: enforce, logger: capture() });
+  assert.equal(g.admitCommand('r1', 'health').ok, true);
+  const out = JSON.parse(g.frameResponse('r1', 'health', { status: 'ok', workspace: '/Users/x/client-repo', openWorkspaces: 2 }));
+  assert.deepEqual(out, { requestId: 'r1', command: 'health', status: 'ok', openWorkspaces: 2 });
+});
+
+test('content in a reply is blocked, replaced by an error, and never logged', () => {
+  const log = capture();
+  const g = createWsMetadataGuard({ config: enforce, logger: log });
+  g.admitCommand('r2', 'health');
+  const secret = 'SUPER_SECRET_SOURCE_CODE_LINE';
+  const out = JSON.parse(g.frameResponse('r2', 'health', { status: 'ok', diff: secret }));
+  assert.deepEqual(out, { requestId: 'r2', command: 'health', ok: false, errorCode: 'blocked_metadata_only' });
+  assert.ok(log.lines.some((l) => l.includes('BLOCKED') && l.includes('unknown-field') && l.includes('diff')));
+  assert.equal(log.lines.join('\n').includes(secret), false, 'payload must never be logged');
+  assert.equal(JSON.stringify(out).includes(secret), false);
+});
+
+test('free-text error messages become an errorCode and are not sent', () => {
+  const g = createWsMetadataGuard({ config: enforce, logger: capture() });
+  g.admitCommand('r3', 'workspace.open');
+  const out = JSON.parse(g.frameResponse('r3', 'workspace.open', { error: 'ENOENT: /home/u/secret/file.js' }));
+  assert.deepEqual(out, { requestId: 'r3', command: 'workspace.open', ok: false, errorCode: 'command_error' });
+});
+
+test('spontaneous messages are validated; violations return null (dropped, not queued)', () => {
+  const log = capture();
+  const g = createWsMetadataGuard({ config: enforce, logger: log });
+  assert.ok(g.frameMessage({ type: 'status', state: 'idle', openWorkspaces: 1 }));
+  assert.equal(g.frameMessage({ type: 'chat', text: 'hi' }), null);
+  assert.equal(g.frameMessage({ type: 'register', tenantId: 't', port: 1, workspacePath: '/x' }), null);
+  assert.equal(g.stats.blocked, 2);
+});
+
+test('D17 TTL: reply to an unknown, expired or already-answered request is dropped', () => {
+  let t = 1_000;
+  const transit = createTransitGuard({ now: () => t, limits: { requestTtlMs: 1000 } });
+  const g = createWsMetadataGuard({ config: enforce, transit, logger: capture() });
+  assert.equal(g.frameResponse('never', 'health', { status: 'ok' }), null);
+  g.admitCommand('a', 'health');
+  assert.ok(g.frameResponse('a', 'health', { status: 'ok' }));
+  assert.equal(g.frameResponse('a', 'health', { status: 'ok' }), null, 'single use');
+  g.admitCommand('b', 'health');
+  t += 1500;
+  assert.equal(g.frameResponse('b', 'health', { status: 'ok' }), null, 'expired');
+});
+
+test('D17 limits: message size, rate and in-flight bound', () => {
+  const transit = createTransitGuard({ limits: { rateMax: 2, maxInFlight: 2, maxMessageBytes: 60 } });
+  const g = createWsMetadataGuard({ config: enforce, transit, logger: capture() });
+  assert.equal(g.frameMessage({ type: 'cost', requestId: 'r', model: 'm'.repeat(100) }), null, 'oversize');
+  assert.ok(g.frameMessage({ type: 'status', state: 'idle' }));
+  assert.ok(g.frameMessage({ type: 'status', state: 'busy' }));
+  assert.equal(g.frameMessage({ type: 'status', state: 'idle' }), null, 'rate limited');
+  assert.equal(g.admitCommand('x1', 'health').ok, true);
+  assert.equal(g.admitCommand('x2', 'health').ok, true);
+  assert.equal(g.admitCommand('x3', 'health').ok, false, 'in-flight cap');
+});
+
+test('D17: the guard persists nothing (no fs/network usage in the module)', async () => {
+  const { readFile } = await import('node:fs/promises');
+  for (const f of ['metadata-guard', 'transit-guard', 'allowlist']) {
+    const src = await readFile(new URL(`../../src/ws-channel/${f}.js`, import.meta.url), 'utf8');
+    assert.equal(/node:fs|from "fs"|appendFile|writeFile|node:net|node:http/.test(src), false, f);
+  }
+});