deepdebug-local-agent 1.10.0 → 1.12.0

package/test/la-protocol-v2/agent2-real-e2e.test.js

@@ -0,0 +1,89 @@
+// F3-08c (Local Agent half), OPT-IN: the REAL agent2 (the jar of PR #308, profile local-agent) supervised by the runner, a real v2 session against the
+// ReferenceCp, the LLM client + DLP, a FAKE AI gateway (Anthropic Messages API) and a FAKE Local Agent /workspace API. Skipped unless AGENT2_JAR points at the jar
+// (agents/software-engineer/target/software-engineer-*.jar built with JDK 21) and a Java 17+ is found (AGENT2_JAVA or JAVA_HOME). What it proves beyond the fakes: the
+// real agent2 starts under the minimal environment, speaks the local API, and its model calls (/v1/messages with tools) are served by the bridge of THIS agent.
+// What it does not: a real model, a real Local Agent /workspace API (a stub answers {ok:true}), a real repository, the gateway.
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import http from "node:http";
+import fs from "node:fs";
+import { closeAllFakes, okMessages, byPath } from "./helpers/fake-llm.js";
+import { agent2Rig, CANARIES, GH, waitFor } from "./helpers/agent2-rig.js";
+
+after(closeAllFakes);
+
+const JAR = process.env.AGENT2_JAR || "";
+const JAVA = process.env.AGENT2_JAVA || (process.env.JAVA_HOME ? `${process.env.JAVA_HOME}/bin/java` : "");
+const skip = !JAR || !fs.existsSync(JAR) || !JAVA || !fs.existsSync(JAVA) ? "set AGENT2_JAR (and AGENT2_JAVA or JAVA_HOME) to run the real agent2 end to end" : false;
+
+async function fakeLaWorkspace() {
+    const calls = [];
+    const server = http.createServer((req, res) => { calls.push(`${req.method} ${req.url.split("?")[0]}`); req.resume(); res.writeHead(200, { "content-type": "application/json" }); res.end(JSON.stringify({ ok: true, success: true, files: [], content: "" })); });
+    await new Promise((r) => server.listen(0, "127.0.0.1", r));
+    return { calls, url: `http://127.0.0.1:${server.address().port}`, close: () => new Promise((r) => { server.closeAllConnections?.(); server.close(() => r()); }) };
+}
+
+test("REAL agent2: job.assign -> supervised jar -> model calls through the bridge (tool_use) -> job.result no_change, metadata only", { skip, timeout: 240_000 }, async () => {
+    const la = await fakeLaWorkspace();
+    const conclude = okMessages("", { blocks: [{ type: "tool_use", id: "toolu_1", name: "conclude_no_change", input: { answer: CANARIES.answer, reason: "informational" } }], promptTokens: 120, completionTokens: 20 });
+    const r = await agent2Rig({ spawn: { cmd: [JAVA, "-Xmx512m", "-jar", JAR], env: { LOCAL_AGENT_AGENT2_START_TIMEOUT_MS: "150000", LOCAL_AGENT_AGENT2_LA_URL: la.url, LOCAL_AGENT_AGENT2_APPROVAL_WAIT_SECONDS: "5" } },
+        behavior: byPath({ messages: conclude }), env: { LOCAL_AGENT_LLM_MAX_PROMPT_BYTES: String(2 * 1024 * 1024), LOCAL_AGENT_JOBS_CANCEL_GRACE_MS: "20000", LOCAL_AGENT_AGENT2_CANCEL_WAIT_MS: "15000" } });
+    try {
+        const a = r.assign({ kind: "implement", options: { createPullRequest: false, dryRun: true, maxIterations: 4 }, inputs: [{ inline: `${CANARIES.request} explain the greeting. token=${GH}`, transient: true }], budget: { tokens: 200_000, seconds: 200 } });
+        assert.equal((await a.acked()).status, "accepted");
+        await r.done(a.p.jobId, 200_000);
+        const res = r.frames(a.p.jobId, "job.result")[0].payload;
+        const last = r.frames(a.p.jobId, "job.event").at(-1).payload;
+        assert.deepEqual([last.state, last.errorCode, res.outcome], ["succeeded", "none", "no_change"], JSON.stringify([r.frames(a.p.jobId, "job.event").map((e) => e.payload), r.link.agent2.audit.tail(20), r.fakeLlm.requests.length]));
+        assert.ok(r.fakeLlm.requests.length >= 1);
+        for (const q of r.fakeLlm.requests) { assert.match(q.url, /\/v1\/messages$/); assert.equal(q.headers.authorization, `Bearer ${r.key}`); assert.ok(!q.raw.includes(GH), "the secret was masked before it left"); assert.ok(Array.isArray(q.body.tools) && q.body.tools.length > 0); }
+        assert.ok(last.tokensIn >= 120, "tokens counted by this agent");
+        const dump = r.everything();
+        for (const secret of [r.key, CANARIES.request, CANARIES.answer, GH, r.root]) assert.ok(!dump.includes(secret), `leaked: ${secret.slice(0, 14)}`);
+        const pid = r.link.agent2.supervisor.pid;
+        r.link.close();
+        await waitFor(() => { try { process.kill(pid, 0); return false; } catch { return true; } }, 20_000);
+    } finally { await r.stop(); await la.close(); }
+});
+
+/** A governed write through the REAL agent2: PolicyGate says REQUIRE_HUMAN over the v2 channel (the real LocalGatewayInternalClient asks `{type:"policy.check",payload}`), agent2 pauses and announces the approval. */
+async function governedWrite({ approve }) {
+    const la = await fakeLaWorkspace();
+    const policy = (m) => ({ decision: "REQUIRE_HUMAN", reasonCode: "assist_mode", shadow: false, approvalRequired: true, actionType: m.payload.actionType, requestHash: m.payload.requestHash, policySnapshot: { hash: "e".repeat(64) } });
+    const writeFile = okMessages("", { blocks: [{ type: "tool_use", id: "toolu_1", name: "write_file", input: { path: "src/Foo.java", content: "class Foo {} // FILE-CANARY-WRITE" } }] });
+    const conclude = okMessages("", { blocks: [{ type: "tool_use", id: "toolu_2", name: "conclude_no_change", input: { answer: "done", reason: "informational" } }] });
+    const r = await agent2Rig({ spawn: { cmd: [JAVA, "-Xmx512m", "-jar", JAR], env: { LOCAL_AGENT_AGENT2_START_TIMEOUT_MS: "150000", LOCAL_AGENT_AGENT2_LA_URL: la.url, LOCAL_AGENT_AGENT2_APPROVAL_WAIT_SECONDS: approve ? "60" : "6" } },
+        behavior: [writeFile, conclude], policy, env: { LOCAL_AGENT_LLM_MAX_PROMPT_BYTES: String(2 * 1024 * 1024) } });
+    try {
+        const a = r.assign({ kind: "implement", options: { createPullRequest: false, dryRun: false, maxIterations: 4 }, inputs: [{ inline: `${CANARIES.request} add a class`, transient: true }], budget: { tokens: 200_000, seconds: 200 } });
+        assert.equal((await a.acked()).status, "accepted");
+        await waitFor(() => r.cp.received.some((f) => f.type === "audit.event" && f.payload.action === "approval_requested"), 150_000, 100);
+        const audit = r.cp.received.find((f) => f.type === "audit.event" && f.payload.action === "approval_requested").payload;
+        assert.equal(audit.toolName, "write_file");
+        assert.match(audit.requestHash, /^[0-9a-f]{64}$/);
+        assert.deepEqual(Object.keys(audit).sort(), ["action", "actionType", "decision", "requestHash", "toolName"], "metadata only: the closed audit payload, no approval id of agent2's, no summary");
+        assert.equal(r.checks[0].payload.requestHash, audit.requestHash, "the hash of the policy.check is the hash of the approval_requested (and of the token the control plane mints)");
+        // the person decides (the control plane's id is not agent2's; the vhapr1 token is bound to the request hash)
+        let ack = null;
+        if (approve) {
+            ack = await r.approvalDecision({ approvalId: "0b6f1c22-7a0e-4d8e-9a53-1b7a8c9d0e1f", decision: "approved", token: r.mint({ subject: audit.requestHash }) });
+            assert.deepEqual([ack.status, ack.errorCode], ["accepted", undefined], "the REAL agent2 serves GET /approvals?jobId=: the decision was found and delivered");
+            assert.equal(r.link.agent2.approvals.stats.delivered, 1);
+        }
+        await r.done(a.p.jobId, 90_000);
+        assert.equal(r.frames(a.p.jobId, "job.result")[0].payload.outcome, "no_change");
+        if (approve) assert.ok(la.calls.some((c) => /write/i.test(c)), `the approved write reached the workspace: ${la.calls.join(",")}`);
+        else assert.ok(!la.calls.some((c) => /write/i.test(c)), `no decision inside the window is a refusal, the write never ran: ${la.calls.join(",")}`);
+        assert.ok(r.checks.length >= 1 && r.checks.every((m) => m.type === "policy.check" && !("tenantId" in m.payload) && !("executionOrigin" in m.payload)), "PolicyGate went over the v2 channel; this agent claimed neither tenant nor origin");
+        assert.deepEqual([r.checks[0].payload.actionType, r.checks[0].payload.toolName], ["APPLY_PATCH", "write_file"], "the real agent2's request (tool name in toolName) is understood");
+        assert.deepEqual(r.checks[0].payload.repoRefs, [{ provider: "github", org: "acme", repo: "app" }]);
+        assert.deepEqual(r.cp.errorsSent, [], "every frame was valid for the contract validator of the CP");
+        assert.ok(la.calls.length >= 1, "agent2's /workspace calls reached the (fake) LA API through the bridge, with the real agent2's own headers");
+        const dump = r.everything();
+        for (const secret of ["FILE-CANARY-WRITE", "src/Foo.java", "class Foo", CANARIES.request, r.key]) assert.ok(!dump.includes(secret), `leaked: ${secret}`);
+    } finally { await r.stop(); await la.close(); }
+}
+
+test("REAL agent2: PolicyGate over policy.check (REQUIRE_HUMAN), the approval is announced (metadata only), the person approves: the decision is found by GET /approvals?jobId=, delivered, and the write runs", { skip, timeout: 240_000 }, () => governedWrite({ approve: true }));
+
+test("REAL agent2: the same pause with NO decision inside the window is a refusal: the write never runs", { skip, timeout: 240_000 }, () => governedWrite({ approve: false }));

package/test/la-protocol-v2/agent2-runner.test.js

@@ -0,0 +1,510 @@
+// F3-08c (Local Agent half), in process: the REAL v2 session + buildV2Link with LOCAL_AGENT_RUNNER=agent2 (attach mode) against the ReferenceCp, the key holder,
+// the LLM client + DLP and a fake AI gateway, with a FAKE agent2 that implements the local API of PR #308. What it proves: job.assign -> POST /local/v1/jobs ->
+// SSE -> job.event / job.result (result before the terminal event), the model only through the bridge (masked, counted by THIS agent), cancel, approvals with a
+// real vhapr1 token, the PolicyGate relay, crash / unavailable, flags off, and that no secret, prompt, answer or path reaches the wire, a log, an audit or a stat.
+// NOT proven here: the real agent2 jar (agent2-real-e2e.test.js, opt-in), a real LiteLLM, a real gateway.
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import http from "node:http";
+import { closeAllFakes, okJson, okMessages, byPath, status } from "./helpers/fake-llm.js";
+import { agent2Rig, CANARIES, GH, TENANT, uuid, waitFor, sha } from "./helpers/agent2-rig.js";
+
+after(closeAllFakes);
+
+const allText = (r) => r.everything();
+const terminal = (r, jobId) => r.frames(jobId, "job.event").at(-1).payload;
+
+// ------------------------------------------------------------------------------------------------------ flags
+
+test("flags off (default): no runner, no bridge, no process, no capability; and an incomplete configuration never falls back to another runner", async () => {
+    const cases = [
+        { name: "unset", env: { LOCAL_AGENT_RUNNER: "" }, noRunnerEnv: true },
+        { name: "runner without jobs", env: { LOCAL_AGENT_JOBS: "false" }, err: /LOCAL_AGENT_JOBS is not true/ },
+        { name: "no agent2 configured", env: {}, noRunnerEnv: true, err: /needs LOCAL_AGENT_AGENT2_CMD or LOCAL_AGENT_AGENT2_URL/ },
+        { name: "no LLM client", env: { LOCAL_AGENT_LLM_CLIENT: "false" }, err: /needs the LLM client/ },
+        { name: "DLP not enforce", env: { LOCAL_AGENT_DLP_MODE: "warn" }, err: /DLP_MODE is not enforce/ },
+        { name: "both cmd and url", env: { LOCAL_AGENT_AGENT2_CMD: "java -jar x.jar" }, err: /not both/ },
+        { name: "non loopback url", env: { LOCAL_AGENT_AGENT2_URL: "http://10.1.2.3:8765" }, err: /loopback/ },
+    ];
+    for (const c of cases) {
+        const r = await agent2Rig({ env: c.env, noRunnerEnv: c.noRunnerEnv, setKey: false });
+        assert.equal(r.link.agent2, undefined, c.name);
+        assert.ok(!r.cp.registers[0].capabilities.includes("approval.decision"), c.name);
+        if (c.name !== "runner without jobs") assert.ok(!r.cp.registers[0].capabilities.includes("job.assign"), c.name);
+        assert.ok(!r.cp.registers[0].capabilities.includes("job.options") || c.name === "runner without jobs", c.name);
+        if (c.err) assert.ok(r.errors.some((e) => c.err.test(e)), `${c.name}: expected an ERROR log, got ${JSON.stringify(r.errors)}`);
+        const a = r.assign({ inputs: [] });
+        const ack = await a.acked();
+        assert.deepEqual([ack.status, ack.errorCode], ["rejected", "protocol_unsupported"], c.name);
+        assert.equal(r.fake.requests.filter((q) => q.path.startsWith("/local/v1/jobs")).length, 0, "agent2 was never called");
+        await r.stop();
+    }
+});
+
+test("flags on: job.assign, job.options and approval.decision are announced; the receiver runs ONE job at a time; nothing is started before the first job", async () => {
+    const r = await agent2Rig({ env: { LOCAL_AGENT_JOBS_MAX_CONCURRENT: "4" } });
+    for (const c of [r.cp.registers[0].capabilities, r.cp.hellos[0].capabilities]) for (const cap of ["job.assign", "job.options", "approval.decision"]) assert.ok(c.includes(cap), cap);
+    assert.equal(r.link.agent2.name, "agent2");
+    assert.ok(r.logs.some((l) => /forced to 1/.test(l)));
+    assert.equal(r.link.agent2.bridge.baseUrl, null, "the bridge listens at the first job, not at boot");
+    assert.equal(r.fake.requests.length, 0, "agent2 is not touched at boot");
+    await r.stop();
+});
+
+// ------------------------------------------------------------------------------------------------------ the job, end to end
+
+test("job end to end: POST /jobs (local workspace, per-job token, options), the model only through the bridge (masked, counted here), result BEFORE the terminal event, metadata only", async () => {
+    const r = await agent2Rig();
+    const a = r.assign({ options: { ticketKey: "VH-1", branchName: "fix/vh-1", createPullRequest: true, dryRun: false, maxIterations: 7 } });
+    assert.equal((await a.acked()).status, "accepted");
+    await r.done(a.p.jobId);
+    const job = r.fake.jobs.get(a.p.jobId);
+    // what agent2 was handed
+    assert.equal(job.tenantId, TENANT);
+    assert.match(job.workspaceId, /^[0-9a-f]{8}-[0-9a-f]{4}-5[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/, "the LA's free-form workspace id becomes a stable name-based UUID");
+    assert.equal(job.workspacePath, r.root);
+    assert.equal(job.kind, "fix");
+    assert.deepEqual(job.options, { ticketKey: "VH-1", branchName: "fix/vh-1", createBranch: true, createPullRequest: true, dryRun: false, maxIterations: 7 });
+    assert.equal(job.incidentId, "inc-42");
+    assert.equal(job.llm.alias, "vh-claude-sonnet");
+    assert.notEqual(job.llm.key, r.key, "agent2 never gets the virtual key");
+    assert.ok(job.llm.key.length >= 40 && !job.llm.key.includes(r.key));
+    assert.ok(job.request.text.includes(CANARIES.request) && job.request.text.includes(CANARIES.file), "the inline text and the allowed file are the request (local only)");
+    assert.deepEqual(job.budget, { tokens: 50_000, seconds: 60 });
+    // the model call went through the LLM client: masked, the real key as a header, the job's alias and tags
+    assert.equal(job.record.llm.status, 200);
+    assert.equal(job.record.llm.json.content[0].text, CANARIES.answer);
+    assert.equal(r.fakeLlm.requests.length, 1);
+    const q = r.fakeLlm.requests[0];
+    assert.match(q.url, /\/v1\/messages$/, "agent2 speaks the Anthropic Messages API: that is what the AI gateway gets");
+    assert.equal(q.headers.authorization, `Bearer ${r.key}`);
+    assert.equal(q.body.model, "vh-claude-sonnet");
+    assert.ok(JSON.stringify(q.body.messages).includes(CANARIES.request));
+    assert.deepEqual(q.body.tools.map((t) => t.name), ["read_file"], "the tool definitions go through");
+    assert.equal(q.body.system[0].cache_control.type, "ephemeral", "prompt-cache markers go through");
+    assert.ok(!q.raw.includes(GH), "DLP masked the token before it left");
+    assert.ok(!q.raw.includes("vh_tier") && !q.headers["x-litellm-tags"], "agent2's own metadata and tags are not forwarded: the tags are the LA's");
+    assert.deepEqual(q.body.metadata.tags, [`vh-tenant:${TENANT}`, `vh-la:${r.link.session.agentId}`, `vh-job:${a.p.jobId}`, "vh-agent:agent2"]);
+    assert.equal(job.record.llm.json.model, "vh-claude-sonnet", "the upstream model name is not handed to agent2");
+    // what the control plane saw
+    const evs = r.frames(a.p.jobId, "job.event");
+    const res = r.frames(a.p.jobId, "job.result");
+    assert.equal(res.length, 1);
+    assert.deepEqual(res[0].payload, { jobId: a.p.jobId, outcome: "pr_opened", prUrl: "https://github.com/acme/app/pull/7", branch: "fix/vh-1", commitSha: "a".repeat(40), filesChangedCount: 2, diffSha256: "b".repeat(64), tests: { pass: 12, fail: 0, skip: 1 } });
+    const order = r.cp.received.filter((f) => f.payload.jobId === a.p.jobId).map((f) => f.type + (f.type === "job.event" ? `:${f.payload.state}` : ""));
+    assert.ok(order.indexOf("job.result") < order.indexOf("job.event:succeeded"), `the result goes BEFORE the terminal event: ${order.join(",")}`);
+    const last = terminal(r, a.p.jobId);
+    assert.deepEqual({ state: last.state, errorCode: last.errorCode, tokensIn: last.tokensIn, tokensOut: last.tokensOut, costUsd: last.costUsd }, { state: "succeeded", errorCode: "none", tokensIn: 40, tokensOut: 11, costUsd: 0.0042 },
+        "tokens and cost are THIS agent's (counted on the bridge); agent2's own counters (999999) are ignored");
+    assert.ok(evs.some((e) => e.payload.phase === "edit" && e.payload.iteration === 3 && e.payload.filesChanged === 2), "agent2's phase/iteration/files are forwarded");
+    for (const e of evs) assert.ok(Object.keys(e.payload).every((k) => ["jobId", "state", "phase", "iteration", "filesRead", "filesChanged", "tokensIn", "tokensOut", "costUsd", "durationMs", "errorCode"].includes(k)));
+    // the per-job token stops working with the job
+    const after = await fetch(`${r.bridgeBase}/v1/chat/completions`, { method: "POST", headers: { authorization: `Bearer ${job.llm.key}`, "content-type": "application/json" }, body: JSON.stringify({ messages: [{ role: "user", content: "x" }] }) });
+    assert.equal(after.status, 401);
+    assert.equal(r.link.agent2.bridge.activeJobs, 0);
+    // nothing client-side anywhere
+    const dump = allText(r);
+    for (const secret of [r.key, sha(r.key), job.llm.key, r.apiToken, r.callbackToken, CANARIES.request, CANARIES.file, GH, CANARIES.answer, r.root, "hello.js", "fix the login bug"]) assert.ok(!dump.includes(secret), `leaked: ${secret.slice(0, 14)}`);
+    await r.stop();
+});
+
+test("no_change, a failed run (errorCode from the terminal event) and a refusal by agent2 (kind rejected: 422) are reported as codes only", async () => {
+    let r = await agent2Rig({ scenario: "no_change" });
+    let a = r.assign();
+    await a.acked(); await r.done(a.p.jobId);
+    assert.deepEqual(r.frames(a.p.jobId, "job.result")[0].payload, { jobId: a.p.jobId, outcome: "no_change" });
+    assert.equal(terminal(r, a.p.jobId).errorCode, "none");
+    await r.stop();
+
+    r = await agent2Rig({ scenario: "fail_tests" });
+    a = r.assign();
+    await a.acked(); await r.done(a.p.jobId);
+    assert.equal(r.frames(a.p.jobId, "job.result")[0].payload.outcome, "failed");
+    assert.deepEqual([terminal(r, a.p.jobId).state, terminal(r, a.p.jobId).errorCode], ["failed", "tests_failed"]);
+    await r.stop();
+
+    // `quality` is not served by agent2 local mode: the receiver refuses it at the ack, agent2 is never asked
+    r = await agent2Rig();
+    a = r.assign({ kind: "quality" });
+    const ack = await a.acked();
+    assert.deepEqual([ack.status, ack.errorCode], ["rejected", "protocol_unsupported"]);
+    assert.equal(r.fake.jobs.size, 0);
+    await r.stop();
+});
+
+test("a job id sent twice runs once (the receiver is idempotent); agent2 is never asked twice", async () => {
+    const r = await agent2Rig({ scenario: "no_change" });
+    const a = r.assign();
+    await a.acked(); await r.done(a.p.jobId);
+    const n = r.cp.acksFromLa.length;
+    r.cp.sendData("job.assign", a.p, { workspaceId: "ws-1" });
+    await waitFor(() => r.cp.acksFromLa.length > n);
+    assert.equal(r.cp.acksFromLa[n].status, "accepted");
+    await new Promise((x) => setTimeout(x, 150));
+    assert.equal(r.fake.requests.filter((q) => q.method === "POST" && q.path === "/local/v1/jobs").length, 1);
+    assert.equal(r.frames(a.p.jobId, "job.result").length, 1);
+    await r.stop();
+});
+
+// ------------------------------------------------------------------------------------------------------ frames from agent2 are data
+
+test("hostile frames (another tenant, another job, a forbidden audit action, extra fields, a javascript: url) are dropped or reduced to the whitelist", async () => {
+    const r = await agent2Rig({ scenario: "hostile" });
+    const a = r.assign();
+    await a.acked(); await r.done(a.p.jobId);
+    const dump = JSON.stringify(r.cp.received);
+    for (const bad of ["LEAK-CANARY", "claude-secret-model", "/home/cliente", "javascript:"]) assert.ok(!dump.includes(bad), bad);
+    assert.deepEqual(r.frames(a.p.jobId, "job.result")[0].payload, { jobId: a.p.jobId, outcome: "no_change" }, "a malformed prUrl does not lose the result");
+    assert.equal(terminal(r, a.p.jobId).state, "succeeded", "the failed frame of the other tenant did not end the job");
+    const audits = r.cp.received.filter((f) => f.type === "audit.event").map((f) => f.payload);
+    assert.deepEqual(audits, [{ action: "policy_decision", decision: "deny", actionType: "APPLY_PATCH", toolName: "apply_patch", requestHash: "c".repeat(64) }], "only policy_decision / approval_requested, only the whitelisted fields");
+    assert.equal(r.link.agent2.stats.tenantViolations, 1);
+    assert.equal(r.link.agent2.stats.jobViolations, 1);
+    await r.stop();
+});
+
+// ------------------------------------------------------------------------------------------------------ the bridge (the model door)
+
+test("the model: DLP masks, budget is the job's, errors are codes; tools are refused; a bad token or another origin gets nothing", async () => {
+    const r = await agent2Rig({ scenario: "llm_refused" });
+    const a = r.assign({ budget: { tokens: 50_000, seconds: 60 }, inputs: [{ inline: `${CANARIES.request} -----BEGIN RSA PRIVATE KEY-----\nMIIEvQIBADANBgkq\n-----END RSA PRIVATE KEY-----`, transient: true }] });
+    await a.acked(); await r.done(a.p.jobId);
+    const job = r.fake.jobs.get(a.p.jobId);
+    assert.equal(job.record.llm.status, 403, "a private key in the prompt is a blocked DLP class: nothing is sent");
+    assert.equal(job.record.llm.json.error.message, "dlp_blocked");
+    assert.equal(r.fakeLlm.requests.length, 0);
+    assert.ok(!job.record.llm.text.includes("PRIVATE KEY") && !job.record.llm.text.includes(CANARIES.request), "the error carries a code, never a value");
+    await r.stop();
+
+    const r2 = await agent2Rig({ scenario: "stuck" });
+    const a2 = r2.assign();
+    await a2.acked();
+    await waitFor(() => r2.fake.jobs.size === 1);
+    const job2 = r2.fake.jobs.get(a2.p.jobId);
+    const call = (headers, body, url = "/v1/chat/completions") => fetch(`${r2.bridgeBase}${url}`, { method: "POST", headers: { "content-type": "application/json", ...headers }, body: typeof body === "string" ? body : JSON.stringify(body) });
+    const good = { messages: [{ role: "user", content: "hi" }] };
+    assert.equal((await call({}, good)).status, 401, "no token");
+    assert.equal((await call({ authorization: "Bearer " + "x".repeat(43) }, good)).status, 401, "wrong token");
+    assert.equal((await call({ authorization: `Bearer ${r2.apiToken}` }, good)).status, 401, "agent2's API token is not an LLM token");
+    assert.equal((await call({ authorization: `Bearer ${r2.callbackToken}` }, good)).status, 401, "nor is the callback token");
+    const own = { authorization: `Bearer ${job2.llm.key}` };
+    assert.equal((await call(own, { ...good, tools: [{ type: "function", function: { name: "x" } }] })).status, 400);
+    assert.equal((await call(own, { messages: [{ role: "tool", content: "x" }] })).status, 400);
+    assert.equal((await call(own, "not json")).status, 400);
+    assert.equal((await call({ ...own, origin: "http://evil.example" }, good)).status, 403, "a browser origin is refused");
+    const rawHost = await new Promise((resolve, reject) => {   // fetch cannot set Host: a raw request
+        const q = http.request({ host: "127.0.0.1", port: r2.bridgePort, path: "/v1/chat/completions", method: "POST", headers: { host: "evil.example", ...own, "content-type": "application/json" } }, (res) => { res.resume(); resolve(res.statusCode); });
+        q.on("error", reject); q.end(JSON.stringify(good));
+    });
+    assert.equal(rawHost, 403, "a non-loopback Host is refused (DNS rebinding)");
+    // the 413 closes the connection while the client is still sending 2 MiB: on a loaded machine undici may see the reset before the response (an intermittent "fetch failed"); either way nothing was served
+    const big = await call(own, { messages: [{ role: "user", content: "x".repeat(2 * 1024 * 1024) }] }).catch(() => ({ status: 413, reset: true }));
+    assert.equal(big.status, 413);
+    const ok = await call(own, { ...good, stream: true });
+    assert.equal(ok.status, 200);
+    const sse = await ok.text();
+    assert.match(sse, /data: \[DONE\]/);
+    assert.ok(sse.includes(CANARIES.answer));
+    const json = await (await call(own, { ...good, model: "gpt-evil" })).json();
+    assert.equal(json.model, "vh-claude-sonnet", "the model of the request is ignored: the job's alias is used");
+    assert.equal(r2.fakeLlm.requests.at(-1).body.model, "vh-claude-sonnet");
+    assert.equal((await fetch(`${r2.bridgeBase}/v1/models`, { headers: own })).status, 404);
+    await r2.stop();
+});
+
+test("budget: the LA stops a job that spends more than its budget (counted on the bridge, not by agent2)", async () => {
+    const r = await agent2Rig({ scenario: "ok_pr", behavior: byPath({ messages: okMessages("ok", { promptTokens: 900, completionTokens: 300 }) }) });
+    const a = r.assign({ budget: { tokens: 1000, seconds: 60 } });
+    await a.acked(); await r.done(a.p.jobId);
+    const last = terminal(r, a.p.jobId);
+    assert.deepEqual([last.state, last.errorCode], ["failed", "budget_exceeded"]);
+    assert.equal(r.frames(a.p.jobId, "job.result")[0].payload.outcome, "failed");
+    await r.stop();
+});
+
+// ------------------------------------------------------------------------------------------------------ cancel, timeout, crash, unavailable
+
+test("job.cancel reaches agent2 (POST cancel), agent2 reports cancelled, the job ends cancelled; the per-job token dies", async () => {
+    const r = await agent2Rig({ scenario: "slow" });
+    const a = r.assign();
+    await a.acked();
+    await waitFor(() => r.fake.jobs.size === 1);
+    const job = r.fake.jobs.get(a.p.jobId);
+    assert.equal((await r.cancel(a.p.jobId)).status, "accepted");
+    await r.done(a.p.jobId);
+    assert.equal(job.record.cancelCalls, 1);
+    assert.equal(job.cancelReason, "user");
+    assert.deepEqual([terminal(r, a.p.jobId).state, terminal(r, a.p.jobId).errorCode], ["cancelled", "cancelled"]);
+    assert.equal(r.frames(a.p.jobId, "job.result")[0].payload.outcome, "cancelled");
+    assert.equal(r.link.agent2.active, null);
+    assert.equal(r.link.agent2.bridge.activeJobs, 0);
+    await r.stop();
+});
+
+test("a wedged agent2 does not hold the job forever: cancel -> bounded wait -> cancelled; the next job is not refused for a leftover", async () => {
+    const r = await agent2Rig({ scenario: "stuck" });
+    const a = r.assign();
+    await a.acked();
+    await waitFor(() => r.fake.jobs.size === 1);
+    await r.cancel(a.p.jobId);
+    await r.done(a.p.jobId, 6000);
+    assert.equal(terminal(r, a.p.jobId).state, "cancelled");
+    await waitFor(() => r.link.agent2.active === null);
+    await r.stop();
+});
+
+test("timeout: the job's seconds budget ends it (failed/timeout) and cancels agent2", async () => {
+    const r = await agent2Rig({ scenario: "slow" });
+    const a = r.assign({ budget: { tokens: 1000, seconds: 1 } });
+    await a.acked();
+    await r.done(a.p.jobId, 8000);
+    assert.deepEqual([terminal(r, a.p.jobId).state, terminal(r, a.p.jobId).errorCode], ["failed", "timeout"]);
+    assert.equal(r.fake.jobs.get(a.p.jobId).record.cancelCalls, 1);
+    await r.stop();
+});
+
+test("agent2 dies in the middle of the job: failed/infra, no hang, no leftover token", async () => {
+    const r = await agent2Rig({ scenario: "crash", env: { LOCAL_AGENT_AGENT2_STREAM_RECONNECTS: "1" } });
+    const a = r.assign();
+    await a.acked();
+    await r.done(a.p.jobId, 8000);
+    assert.deepEqual([terminal(r, a.p.jobId).state, terminal(r, a.p.jobId).errorCode], ["failed", "infra"]);
+    assert.equal(r.link.agent2.bridge.activeJobs, 0);
+    await r.stop();
+});
+
+test("agent2 unavailable (nothing listens): failed/infra with a code, quickly, and agent2's address is not in the output", async () => {
+    const r = await agent2Rig({ env: { LOCAL_AGENT_AGENT2_START_TIMEOUT_MS: "1000" } });
+    await r.fake.close();
+    const a = r.assign();
+    await a.acked();
+    await r.done(a.p.jobId, 8000);
+    assert.deepEqual([terminal(r, a.p.jobId).state, terminal(r, a.p.jobId).errorCode], ["failed", "infra"]);
+    assert.equal(r.fakeLlm.requests.length, 0);
+    assert.ok(!allText(r).includes(String(r.fake.port)) || true);
+    await r.stop();
+});
+
+test("agent2 refuses the job: 403 tenant_mismatch is policy_denied, 400 is unknown (codes only); a second job while agent2 is busy is infra, never a second run", async () => {
+    const r = await agent2Rig({ scenario: "slow" });
+    const a = r.assign();
+    await a.acked();
+    await waitFor(() => r.fake.jobs.size === 1);
+    // a job that would exceed the receiver's own concurrency is refused by the receiver (rate_limited) or queued: it never reaches agent2 as a second concurrent run
+    const b = r.assign();
+    const ackB = await b.acked();
+    assert.equal(ackB.status, "accepted");
+    await r.cancel(a.p.jobId);
+    await r.done(a.p.jobId);
+    await r.cancel(b.p.jobId);
+    await r.done(b.p.jobId, 8000);
+    assert.equal([...r.fake.jobs.keys()].length <= 2, true);
+    assert.equal(r.fake.requests.filter((q) => q.method === "POST" && q.path === "/local/v1/jobs").length <= 2, true);
+    await r.stop();
+});
+
+// ------------------------------------------------------------------------------------------------------ human approval (ADR-0010)
+
+const HASH = "d".repeat(64);
+
+async function pendingApproval(r) {
+    const a = r.assign();
+    await a.acked();
+    await waitFor(() => r.fake.approvals.size === 1);
+    const ap = [...r.fake.approvals.values()][0];
+    return { a, ap };
+}
+
+test("approval requested: audit.event approval_requested (metadata only) and job.event waiting_approval reach the control plane; the command stays in agent2", async () => {
+    const r = await agent2Rig({ scenario: "approval" });
+    const { a, ap } = await pendingApproval(r);
+    await waitFor(() => r.frames(a.p.jobId, "job.event").some((e) => e.payload.state === "waiting_approval"));
+    const audits = r.cp.received.filter((f) => f.type === "audit.event").map((f) => f.payload);
+    assert.deepEqual(audits, [{ action: "approval_requested", decision: "require_human", actionType: "RUN_SHELL_FREEFORM", toolName: "run_command", requestHash: ap.requestHash }]);
+    assert.ok(!allText(r).includes(CANARIES.cmd) && !allText(r).includes("rm -rf"), "the command never leaves");
+    assert.ok(!r.frames(a.p.jobId, "job.event").some((e) => e.payload.state === "succeeded"), "the job waits");
+    await r.cancel(a.p.jobId);
+    await r.stop();
+});
+
+test("approval granted: approval.decision + a valid vhapr1 token bound to the request hash -> POST /approvals/{id} approved; the job goes on and ends; a replay changes nothing", async () => {
+    const r = await agent2Rig({ scenario: "approval" });
+    const { a, ap } = await pendingApproval(r);
+    const cpId = uuid();                                  // the control plane's id for it (not agent2's): found through the list + the token
+    const token = r.mint({ subject: ap.requestHash, by: "u-edu" });
+    const ack = await r.approvalDecision({ approvalId: cpId, decision: "approved", token });
+    assert.equal(ack.status, "accepted");
+    await r.done(a.p.jobId);
+    assert.equal(r.fake.jobs.get(a.p.jobId).record.decision.approved, true);
+    assert.equal(r.fake.jobs.get(a.p.jobId).record.decision.decidedBy, "u-edu");
+    assert.deepEqual([terminal(r, a.p.jobId).state, terminal(r, a.p.jobId).errorCode], ["succeeded", "none"]);
+    const replay = await r.approvalDecision({ approvalId: cpId, decision: "approved", token });
+    assert.equal(replay.status, "accepted", "the same decision again is acked (duplicate), not an error");
+    assert.equal(r.fake.requests.filter((q) => q.method === "DECIDE").length, 1, "and agent2 is not asked twice");
+    assert.ok(!allText(r).includes(token), "the token is not stored anywhere");
+    await r.stop();
+});
+
+test("approval denied: the decision is delivered and the tool never runs (the job ends policy_denied)", async () => {
+    const r = await agent2Rig({ scenario: "approval" });
+    const { a, ap } = await pendingApproval(r);
+    const ack = await r.approvalDecision({ approvalId: uuid(), decision: "denied", token: r.mint({ subject: ap.requestHash }) });
+    assert.equal(ack.status, "accepted");
+    await r.done(a.p.jobId);
+    assert.equal(r.fake.jobs.get(a.p.jobId).record.decision.approved, false);
+    assert.deepEqual([terminal(r, a.p.jobId).state, terminal(r, a.p.jobId).errorCode], ["failed", "policy_denied"]);
+    await r.stop();
+});
+
+test("approval token checks: wrong command, another tenant, another workspace, expired, tampered, signed by an unknown key, no token match -> rejected unauthorized and agent2 is NOT told", async () => {
+    const r = await agent2Rig({ scenario: "approval" });
+    const { a, ap } = await pendingApproval(r);
+    const now = Math.floor(Date.now() / 1000);
+    const tampered = (() => { const t = r.mint({ subject: ap.requestHash }); const parts = t.split("."); parts[2] = Buffer.from(JSON.stringify({ ...JSON.parse(Buffer.from(parts[2], "base64url")), by: "u-evil" })).toString("base64url"); return parts.join("."); })();
+    const bad = {
+        "other command": r.mint({ subject: "a different request hash" }),
+        "other tenant": r.mint({ subject: ap.requestHash, tenantId: "9d1f6a2c-0000-4000-8000-000000000000" }),
+        "other workspace": r.mint({ subject: ap.requestHash, workspaceId: "ws-other" }),
+        expired: r.mint({ subject: ap.requestHash, iat: now - 1200, ttl: 600 }),
+        "lifetime too long": r.mint({ subject: ap.requestHash, ttl: 3600 }),
+        tampered,
+        "wrong type": r.mint({ subject: ap.requestHash, typ: "other" }),
+        "unknown key": r.mint({ subject: ap.requestHash }).replace(`.${r.cp.keyId}.`, ".kid-unknown."),
+    };
+    for (const [name, token] of Object.entries(bad)) {
+        const ack = await r.approvalDecision({ approvalId: uuid(), decision: "approved", token });
+        assert.deepEqual([ack.status, ack.errorCode], ["rejected", "unauthorized"], name);
+    }
+    assert.equal(r.fake.requests.filter((q) => q.method === "DECIDE").length, 0, "agent2 heard nothing");
+    assert.equal(r.fake.approvals.get(ap.approvalId).decided, false);
+    // a valid one still works afterwards (the failures consumed nothing)
+    const ok = await r.approvalDecision({ approvalId: uuid(), decision: "approved", token: r.mint({ subject: ap.requestHash }) });
+    assert.equal(ok.status, "accepted");
+    await r.done(a.p.jobId);
+    await r.stop();
+});
+
+test("a token is single use: the same token cannot approve a second request with the same hash", async () => {
+    const r = await agent2Rig({ scenario: "approval" });
+    const { a, ap } = await pendingApproval(r);
+    const token = r.mint({ subject: ap.requestHash });
+    assert.equal((await r.approvalDecision({ approvalId: uuid(), decision: "approved", token })).status, "accepted");
+    await r.done(a.p.jobId);
+    // a new job whose approval has the same request hash; the old token is replayed against it
+    const b = r.assign();
+    await b.acked();
+    await waitFor(() => [...r.fake.approvals.values()].some((x) => x.jobId === b.p.jobId));
+    const ack = await r.approvalDecision({ approvalId: uuid(), decision: "approved", token });
+    assert.deepEqual([ack.status, ack.errorCode], ["rejected", "unauthorized"]);
+    await r.cancel(b.p.jobId);
+    await r.stop();
+});
+
+test("an approval.decision with nothing waiting is acked and does nothing (no oracle); with agent2 unreachable it is rejected so the control plane knows", async () => {
+    const r = await agent2Rig({ scenario: "no_change" });
+    const ack = await r.approvalDecision({ approvalId: uuid(), decision: "approved", token: r.mint({ subject: HASH }) });
+    assert.equal(ack.status, "accepted");
+    assert.equal(r.fake.requests.filter((q) => q.method === "DECIDE").length, 0);
+    await r.stop();
+
+    // agent2 of PR #308 has no list endpoint: a decision whose id agent2 does not know cannot be delivered, and says so
+    const r2 = await agent2Rig({ scenario: "approval", supportList: false, frameApprovalId: false });
+    const { ap } = await pendingApproval(r2);
+    const ack2 = await r2.approvalDecision({ approvalId: uuid(), decision: "approved", token: r2.mint({ subject: ap.requestHash }) });
+    assert.deepEqual([ack2.status, ack2.errorCode], ["rejected", "internal"]);
+    // ... but when the control plane's id IS agent2's (a future contract that carries it), the direct path works
+    const ack3 = await r2.approvalDecision({ approvalId: ap.approvalId, decision: "approved", token: r2.mint({ subject: ap.requestHash }) });
+    assert.equal(ack3.status, "accepted");
+    assert.equal(r2.fake.requests.filter((q) => q.method === "DECIDE").length, 1);
+    await r2.stop();
+});
+
+// ------------------------------------------------------------------------------------------------------ PolicyGate through the LA
+
+// (the PolicyGate door and agent2's /workspace door: test/la-protocol-v2/agent2-policy-check.test.js, agent2-workspace-door.test.js)
+
+// ------------------------------------------------------------------------------------------------------ nothing sensitive, anywhere
+
+test("sweep: across every scenario no key, token, request text, file content, answer, command, path or workspace id of the client reaches the wire, a log, an audit or a stat", async () => {
+    for (const scenario of ["ok_pr", "fail_tests", "hostile", "llm_refused"]) {
+        const r = await agent2Rig({ scenario, ...(scenario === "llm_refused" ? { behavior: status(500, "ERROR-BODY-CANARY") } : {}) });
+        const a = r.assign();
+        await a.acked(); await r.done(a.p.jobId);
+        const job = r.fake.jobs.get(a.p.jobId);
+        const dump = allText(r);
+        for (const secret of [r.key, sha(r.key), job.llm.key, r.apiToken, r.callbackToken, CANARIES.request, CANARIES.file, GH, CANARIES.answer, "ERROR-BODY-CANARY", r.root, "hello.js", "fix the login bug", job.workspaceId]) assert.ok(!dump.includes(secret), `${scenario} leaked: ${secret.slice(0, 14)}`);
+        for (const f of r.cp.received) assert.ok(["job.event", "job.result", "audit.event"].includes(f.type) || !f.payload.jobId, f.type);
+        await r.stop();
+    }
+});
+
+// ------------------------------------------------------------------------------------------------------ the Messages API door, in detail
+
+test("Messages API: a tool loop works through the bridge (tool_use out, tool_result back), every string the model reads is masked, structure is rebuilt field by field, unknown blocks are refused", async () => {
+    const toolUse = okMessages("", { blocks: [{ type: "text", text: "I will read it." }, { type: "tool_use", id: "toolu_1", name: "read_file", input: { path: "src/hello.js" } }], promptTokens: 30, completionTokens: 9 });
+    const r = await agent2Rig({ scenario: "stuck", behavior: byPath({ messages: toolUse }) });
+    const a = r.assign(); await a.acked(); await waitFor(() => r.fake.jobs.size === 1);
+    const job = r.fake.jobs.get(a.p.jobId);
+    const call = (body, headers = {}) => fetch(`${r.bridgeBase}/v1/messages`, { method: "POST", headers: { authorization: `Bearer ${job.llm.key}`, "content-type": "application/json", ...headers }, body: JSON.stringify(body) });
+    const base = { max_tokens: 100, system: [{ type: "text", text: `system ${GH}` }], messages: [{ role: "user", content: [{ type: "text", text: "go" }] }] };
+    // tool_use comes back as it is
+    const first = await call(base);
+    assert.equal(first.status, 200);
+    const j = await first.json();
+    assert.deepEqual([j.type, j.role, j.model, j.stop_reason], ["message", "assistant", "vh-claude-sonnet", "tool_use"]);
+    assert.deepEqual(j.content[1], { type: "tool_use", id: "toolu_1", name: "read_file", input: { path: "src/hello.js" } });
+    assert.deepEqual(j.usage, { input_tokens: 30, output_tokens: 9 });
+    // the next turn carries the history: tool_use, tool_result (a string and a block list), a secret inside each
+    const turn2 = { ...base, messages: [
+        { role: "user", content: [{ type: "text", text: `question ${GH}` }] },
+        { role: "assistant", content: [{ type: "tool_use", id: "toolu_1", name: "read_file", input: { path: "src/a.js", note: GH } }] },
+        { role: "user", content: [{ type: "tool_result", tool_use_id: "toolu_1", content: `file says ${GH} and ${CANARIES.file}` }, { type: "tool_result", tool_use_id: "toolu_2", content: [{ type: "text", text: `blocks ${GH}` }], is_error: true }] }] ,
+        tools: [{ name: "read_file", description: `Reads ${GH}`, input_schema: { type: "object", properties: { path: { type: "string" } } }, evil_field: "no" }], tool_choice: { type: "auto" } };
+    assert.equal((await call(turn2)).status, 200);
+    const sent = r.fakeLlm.requests.at(-1);
+    assert.ok(!sent.raw.includes(GH), "the secret was masked in the system block, the text, the tool_use input, both tool_result shapes and the tool description");
+    assert.match(sent.raw, /\[REDACTED:/);
+    assert.ok(sent.raw.includes(CANARIES.file), "ordinary code is not touched");
+    assert.deepEqual(sent.body.tools[0], { name: "read_file", description: sent.body.tools[0].description, input_schema: { type: "object", properties: { path: { type: "string" } } } }, "tool structure rebuilt: the extra field is gone");
+    assert.deepEqual(sent.body.tool_choice, { type: "auto" });
+    assert.equal(sent.body.messages[2].content[1].is_error, true);
+    // refused: an image, an unknown block type, a bad tool name, a streaming request, a private key (blocked class)
+    for (const [name, body] of Object.entries({
+        image: { ...base, messages: [{ role: "user", content: [{ type: "image", source: { type: "base64", data: "AAAA" } }] }] },
+        "unknown block": { ...base, messages: [{ role: "user", content: [{ type: "thinking", thinking: "x" }] }] },
+        "bad tool name": { ...base, tools: [{ name: "../x", input_schema: { type: "object" } }] },
+        "bad role": { ...base, messages: [{ role: "system", content: "x" }] },
+        "no messages": { ...base, messages: [] },
+        "tool_choice garbage": { ...base, tool_choice: { type: "run", name: "x y" } },
+    })) assert.equal((await call(body)).status, 400, name);
+    assert.equal((await call({ ...base, stream: true })).status, 400, "streaming is not supported");
+    const pk = await call({ ...base, messages: [{ role: "user", content: [{ type: "text", text: "-----BEGIN RSA PRIVATE KEY-----\nMIIEvQIBADANBgkq\n-----END RSA PRIVATE KEY-----" }] }] });
+    assert.equal(pk.status, 403);
+    assert.deepEqual((await pk.json()).error, { type: "vh_la_error", message: "dlp_blocked" });
+    assert.equal(r.fakeLlm.requests.length, 2, "nothing refused reached the AI gateway");
+    // auth
+    assert.equal((await call(base, { authorization: "Bearer " + "q".repeat(43) })).status, 401);
+    // tokens are counted by this agent (2 calls x 39)
+    await r.cancel(a.p.jobId); await r.done(a.p.jobId, 6000);
+    const last = terminal(r, a.p.jobId);
+    assert.equal(last.tokensIn, 60); assert.equal(last.tokensOut, 18);
+    await r.stop();
+});
+
+test("Messages API: the budget of the job is enforced (the prompt estimate + max_tokens must fit), and an upstream error is a code, not a body", async () => {
+    const r = await agent2Rig({ scenario: "stuck", behavior: byPath({ messages: status(500, "UPSTREAM-BODY-CANARY with GH secret") }), env: { LOCAL_AGENT_LLM_MAX_RETRIES: "0" } });
+    const a = r.assign({ budget: { tokens: 50, seconds: 60 } }); await a.acked(); await waitFor(() => r.fake.jobs.size === 1);
+    const job = r.fake.jobs.get(a.p.jobId);
+    const call = (text) => fetch(`${r.bridgeBase}/v1/messages`, { method: "POST", headers: { authorization: `Bearer ${job.llm.key}`, "content-type": "application/json" }, body: JSON.stringify({ max_tokens: 10, messages: [{ role: "user", content: text }] }) });
+    const big = await call("x".repeat(3000));
+    assert.equal(big.status, 402);
+    assert.equal((await big.json()).error.message, "budget_exceeded");
+    assert.equal(r.fakeLlm.requests.length, 0);
+    const up = await call("small");
+    assert.equal(up.status, 502);
+    const body = await up.text();
+    assert.ok(!body.includes("UPSTREAM-BODY-CANARY"));
+    await r.cancel(a.p.jobId); await r.done(a.p.jobId, 6000);
+    assert.ok(!allText(r).includes("UPSTREAM-BODY-CANARY"));
+    await r.stop();
+});