deepdebug-local-agent 1.9.0 → 1.11.0

package/test/la-protocol-v2/helpers/fake-agent2-cli.js

@@ -0,0 +1,22 @@
+// The fake agent2 as a PROCESS (spawn-mode tests): reads the same environment the real agent2 reads (AGENT2_LOCAL_PORT, AGENT2_LOCAL_API_TOKEN,
+// AGENT2_LOCAL_TENANT_ID, AGENT2_LLM_BASE_URL, AGENT2_LA_CALLBACK_URL/TOKEN). argv: --scenario=<name>; --die-on-start exits at once; --hang never serves; --die-on-job exits when a job arrives.
+// GET /local/v1/_env (debug) reports the environment it was started with so the tests can pin the allowlist.
+import { startFakeAgent2 } from "./fake-agent2.js";
+
+const arg = (n) => process.argv.find((a) => a.startsWith(`--${n}=`))?.split("=")[1];
+const has = (n) => process.argv.includes(`--${n}`);
+
+// `node --test` also loads every file under test/: without the environment of a started agent2 this file is a no-op
+if (!process.env.AGENT2_LOCAL_API_TOKEN && !has("die-on-start")) process.exit(0);
+if (has("die-on-start")) process.exit(3);
+if (has("hang")) { setInterval(() => {}, 1 << 30); } else {
+    const f = await startFakeAgent2({
+        token: process.env.AGENT2_LOCAL_API_TOKEN, tenantId: process.env.AGENT2_LOCAL_TENANT_ID, port: Number(process.env.AGENT2_LOCAL_PORT), scenario: arg("scenario") || "ok_pr",
+        llmBase: () => process.env.AGENT2_LLM_BASE_URL, callbackUrl: () => process.env.AGENT2_LA_CALLBACK_URL, callbackToken: () => process.env.AGENT2_LA_CALLBACK_TOKEN,
+        workspaceUrl: () => process.env.AGENT2_LA_WORKSPACE_URL, workspaceToken: () => process.env.AGENT2_LA_WORKSPACE_TOKEN,
+        onCrash: () => process.exit(1),
+        supportList: !has("no-list"),
+    });
+    void f;
+    if (has("die-on-job")) setInterval(() => { if (f.jobs.size) process.exit(1); }, 20);
+}

package/test/la-protocol-v2/helpers/fake-agent2.js

@@ -0,0 +1,280 @@
+// A FAKE agent2 (F3-08c): implements the local API of PR #308 (docs/runbooks/local-agent-api.md of visionhammer-agents) closely enough to test the Local Agent's runner:
+// bearer auth, closed JSON bodies, 409 busy, idempotent re-assign, SSE of closed frames that replays from the start and ends after job.result, cancel, approvals
+// (detail, decide, and the LIST endpoint that #308 does not have yet - switch it off with `supportList:false`). It is NOT the real agent2: what it proves is limited
+// by that (the real jar is exercised by test/la-protocol-v2/agent2-real-e2e.test.js when AGENT2_JAR points at one).
+// A scenario is `async (job, h) => void`; h talks back through the bridge exactly as agent2 does (LLM with the per-job key, PolicyGate relay with the callback token).
+import http from "node:http";
+import crypto from "node:crypto";
+
+const JOB_FIELDS = new Set(["jobId", "tenantId", "workspaceId", "kind", "repoRef", "policy", "budget", "llm", "options", "incidentId", "request", "workspacePath"]);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+export const SCENARIOS = {
+    /** one LLM call, an edit, a PR */
+    async ok_pr(job, h) {
+        h.event({ state: "running", phase: "context", iteration: 0, filesRead: 2 });
+        const r = await h.llm([{ role: "system", content: "You are agent2." }, { role: "user", content: job.request.text }]);
+        job.record.llm = r;
+        h.event({ state: "running", phase: "edit", iteration: 3, filesRead: 5, filesChanged: 2, tokensIn: 999999, tokensOut: 999999, costUsd: 99 });   // agent2's own counters must be ignored
+        await sleep(160);   // longer than the progress coalescing window of the tests, so this frame is not folded into the terminal one
+        h.event({ state: "succeeded", phase: "done", errorCode: "none", iteration: 3, filesChanged: 2 });
+        h.result({ 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 } });
+    },
+    async no_change(job, h) {
+        h.event({ state: "running", phase: "plan", iteration: 1 });
+        h.event({ state: "succeeded", phase: "done", errorCode: "none" });
+        h.result({ outcome: "no_change" });
+    },
+    async fail_tests(job, h) {
+        h.event({ state: "running", phase: "validate", iteration: 2 });
+        h.event({ state: "failed", phase: "validate", errorCode: "tests_failed" });
+        h.result({ outcome: "failed" });
+    },
+    /** asks a person; goes on only when approved */
+    async approval(job, h) {
+        h.event({ state: "running", phase: "edit", iteration: 1 });
+        const a = h.requestApproval({ actionType: "RUN_SHELL_FREEFORM", toolName: "run_command", requestHash: job.record.requestHash || crypto.createHash("sha256").update("rm -rf build").digest("hex"), summary: "SECRET-COMMAND-CANARY rm -rf /home/cliente/build" });
+        job.record.approvalId = a.approvalId;
+        const d = await a.decision;
+        job.record.decision = d;
+        h.event({ state: "running", phase: "edit", iteration: 2 });
+        if (d && d.approved) { h.event({ state: "succeeded", phase: "done", errorCode: "none" }); h.result({ outcome: "no_change" }); }
+        else { h.event({ state: "failed", errorCode: "policy_denied" }); h.result({ outcome: "failed" }); }
+    },
+    /** runs until cancelled, then reports `cancelled` like agent2 does */
+    async slow(job, h) {
+        h.event({ state: "running", phase: "plan", iteration: 1 });
+        await h.cancelled;
+        h.event({ state: "cancelled", errorCode: "cancelled" });
+        h.result({ outcome: "cancelled" });
+    },
+    /** runs until cancelled and never answers (a wedged agent2) */
+    async stuck(job, h) { h.event({ state: "running", phase: "plan" }); await new Promise(() => {}); },
+    /** a governed action, asked EXACTLY like PR #308 does (LocalGatewayInternalClient + LocalPolicyCheck): `{type:"policy.check",payload}`, the tool name from the guard's `model` */
+    async policy(job, h) {
+        h.event({ state: "running", phase: "edit" });
+        job.record.policy = await h.policyCheck({ actionType: "APPLY_PATCH", tool: "apply_patch" });
+        job.record.policyOtherShape = await h.policyRaw({ method: "POST", path: "/api/v1/internal/policy/evaluate", body: { actionType: "APPLY_PATCH" } });   // the hosted shape: not accepted
+        h.event({ state: "succeeded", phase: "done", errorCode: "none" });
+        h.result({ outcome: "no_change" });
+    },
+    /** the same, with what a compromised or buggy agent2 could add on top: claims about who it is, paths, URLs. The bridge must drop them */
+    async policy_check(job, h) {
+        h.event({ state: "running", phase: "edit" });
+        job.record.policy = await h.policyCheck({ actionType: "APPLY_PATCH", tool: "apply_patch", incident: "inc-42",
+            extra: { tenantId: "11111111-1111-4111-8111-111111111111", workspaceId: job.workspaceId, agent: "software-engineer", executionOrigin: "hosted", diffFiles: ["src/SECRET-PATH-CANARY.js"], allowedFiles: ["src/SECRET-PATH-CANARY.js"],
+                repoUrl: "https://github.com/acme/app.git", repoUrls: ["https://github.com/acme/app.git"] } });
+        h.event({ state: "succeeded", phase: "done", errorCode: "none" });
+        h.result({ outcome: "no_change" });
+    },
+    /** what agent2 must NOT get away with: another job, another repository, bad shapes, in one run (results in job.record.bad) */
+    async policy_hostile(job, h) {
+        h.event({ state: "running", phase: "edit" });
+        const bad = {};
+        bad.otherJob = await h.policyCheck({ actionType: "APPLY_PATCH", payload: { jobId: crypto.randomUUID() } });
+        bad.otherRepo = await h.policyCheck({ actionType: "APPLY_PATCH", payload: { repoRefs: [{ provider: "github", org: "acme", repo: "other" }] } });
+        bad.twoRepos = await h.policyCheck({ actionType: "APPLY_PATCH", payload: { repoRefs: [{ provider: "github", org: "acme", repo: "app" }, { provider: "github", org: "acme", repo: "lib" }] } });
+        bad.repoExtraKey = await h.policyCheck({ actionType: "APPLY_PATCH", payload: { repoRefs: [{ provider: "github", org: "acme", repo: "app", url: "https://x" }] } });
+        bad.noHash = await h.policyCheck({ actionType: "APPLY_PATCH", payload: { requestHash: undefined } });
+        bad.badHash = await h.policyCheck({ actionType: "APPLY_PATCH", payload: { requestHash: "NOT-A-HASH" } });
+        bad.badAction = await h.policyCheck({ actionType: "APPLY PATCH" });
+        bad.badTool = await h.policyCheck({ actionType: "APPLY_PATCH", payload: { toolName: "write file /etc/passwd" } });
+        bad.payloadArray = await h.policyRaw({ type: "policy.check", payload: [1] });
+        bad.noPayload = await h.policyRaw({ type: "policy.check" });
+        bad.extraTop = await h.policyRaw({ type: "policy.check", payload: {}, tenantId: "x" });
+        bad.otherType = await h.policyRaw({ type: "audit.event", payload: {} });
+        job.record.bad = bad;
+        h.event({ state: "succeeded", phase: "done", errorCode: "none" });
+        h.result({ outcome: "no_change" });
+    },
+    /** reads and writes files of the workspace through the LA /workspace API, as agent2 does (read_file, write_file) */
+    async workspace(job, h) {
+        h.event({ state: "running", phase: "edit" });
+        job.record.read = await h.workspace("GET", "/workspace/file-content?path=src%2Fhello.js");
+        job.record.write = await h.workspace("POST", "/workspace/write-file", { path: "src/out.txt", content: "written by agent2 through the bridge" });
+        job.record.noToken = await h.workspace("GET", "/workspace/file-content?path=src%2Fhello.js", undefined, { tokenOverride: "" });
+        job.record.badToken = await h.workspace("GET", "/workspace/file-content?path=src%2Fhello.js", undefined, { tokenOverride: "z".repeat(43) });
+        job.record.otherApi = await h.workspace("POST", "/setup/run-command", { command: "id" }).catch(() => null);
+        h.event({ state: "succeeded", phase: "done", errorCode: "none" });
+        h.result({ outcome: "no_change" });
+    },
+    /** the model refuses (budget / DLP): agent2 maps it to its own failure */
+    async llm_refused(job, h) {
+        const r = await h.llm([{ role: "user", content: job.request.text }]);
+        job.record.llm = r;
+        h.event({ state: "failed", errorCode: "llm_error" });
+        h.result({ outcome: "failed" });
+    },
+    /** frames of another tenant / job / a forbidden audit action, mixed with good ones */
+    async hostile(job, h) {
+        h.raw({ type: "job.event", tenantId: "9d1f6a2c-0000-4000-8000-000000000000", payload: { jobId: job.jobId, state: "failed", errorCode: "unknown" } });
+        h.raw({ type: "job.event", payload: { jobId: crypto.randomUUID(), state: "failed" } });
+        h.raw({ type: "audit.event", payload: { action: "config_applied", decision: "allow" } });
+        h.raw({ type: "audit.event", payload: { action: "policy_decision", decision: "deny", actionType: "APPLY_PATCH", toolName: "apply_patch", requestHash: "c".repeat(64), prompt: "LEAK-CANARY-PROMPT" } });
+        h.event({ state: "running", phase: "edit", model: "claude-secret-model", message: "LEAK-CANARY-MESSAGE", path: "/home/cliente/x" });
+        h.event({ state: "succeeded", phase: "done", errorCode: "none" });
+        h.result({ outcome: "no_change", prUrl: "javascript:alert(1)" });
+    },
+    /** exits mid-job (spawn mode: the process dies; in-process: the server vanishes) */
+    async crash(job, h) { h.event({ state: "running", phase: "plan" }); await sleep(50); h.crash(); },
+};
+
+export async function startFakeAgent2({ token, tenantId, scenario = "ok_pr", port = 0, llmBase = null, callbackUrl = null, callbackToken = null, workspaceUrl = null, workspaceToken = null, supportList = true, frameApprovalId = true, healthDelayMs = 0, onCrash = null } = {}) {
+    const jobs = new Map();
+    const approvals = new Map();
+    const requests = [];
+    const sockets = new Set();
+    let current = null;
+    const sc = typeof scenario === "function" ? scenario : SCENARIOS[scenario];
+    let scenarioName = scenario;
+
+    const json = (res, status, body) => { const t = JSON.stringify(body); res.writeHead(status, { "content-type": "application/json", "content-length": Buffer.byteLength(t) }); res.end(t); };
+    const auth = (req) => req.headers.authorization === `Bearer ${token}`;
+    const body = (req) => new Promise((resolve) => { const c = []; req.on("data", (x) => c.push(x)); req.on("end", () => { try { resolve(JSON.parse(Buffer.concat(c).toString("utf8") || "null")); } catch { resolve(undefined); } }); });
+
+    function makeJob(b) {
+        const job = { ...b, frames: [], listeners: new Set(), done: false, seq: 0, record: {}, cancelRequested: false, cancelReason: null };
+        job.cancelled = new Promise((r) => { job.onCancel = r; });
+        const push = (type, payload, over = {}) => {
+            const f = { seq: ++job.seq, type, tenantId: b.tenantId, workspaceId: b.workspaceId, payload, ...over };
+            if (over.drop) for (const k of over.drop) delete f[k];
+            job.frames.push(f);
+            for (const l of job.listeners) l(f);
+            if (type === "job.result") { job.done = true; for (const l of job.listeners) l(null); }
+        };
+        const h = {
+            event: (p) => push("job.event", { jobId: b.jobId, ...p }),
+            result: (p) => push("job.result", { jobId: b.jobId, ...p }),
+            audit: (p) => push("audit.event", p),
+            raw: ({ type, tenantId: t, payload }) => { const f = { seq: ++job.seq, type, ...(t ? { tenantId: t } : { tenantId: b.tenantId }), workspaceId: b.workspaceId, payload }; job.frames.push(f); for (const l of job.listeners) l(f); },
+            cancelled: job.cancelled,
+            requestApproval({ actionType, toolName, requestHash, summary }) {
+                const approvalId = crypto.randomUUID();
+                let resolve;
+                const decision = new Promise((r) => { resolve = r; });
+                const p = { approvalId, jobId: b.jobId, actionType, toolName, summary, requestHash, expiresAt: new Date(Date.now() + 600_000).toISOString(), resolve, decided: false };
+                approvals.set(approvalId, p);
+                push("audit.event", { action: "approval_requested", decision: "require_human", actionType, toolName, requestHash, ...(frameApprovalId ? { approvalId } : {}) });   // PR #308 puts its own id in both frames (loopback only)
+                push("job.event", { jobId: b.jobId, state: "waiting_approval", ...(frameApprovalId ? { approvalId } : {}) });
+                return { approvalId, decision };
+            },
+            /** One model turn like agent2's ClaudeApiClient does it (Anthropic Messages API, tools, content blocks, its own metadata); `over.api:"chat"` = the OpenAI-shaped route. */
+            async llm(messages, over = {}) {
+                const { api = "messages", ...rest } = over;
+                const sys = messages.filter((m) => m.role === "system").map((m) => ({ type: "text", text: m.content, cache_control: { type: "ephemeral" } }));
+                const turns = messages.filter((m) => m.role !== "system").map((m) => ({ role: m.role, content: [{ type: "text", text: m.content }] }));
+                const body = api === "chat" ? { model: b.llm.alias, messages, max_tokens: 512, temperature: 0, metadata: { vh_tier: "x" }, ...rest }
+                    : { model: b.llm.alias, max_tokens: 512, ...(sys.length ? { system: sys } : {}), messages: turns, tools: [{ name: "read_file", description: "Reads a file", input_schema: { type: "object", properties: { path: { type: "string" } } } }], metadata: { vh_tier: "reasoning" }, ...rest };
+                const res = await fetch(`${llmBase()}/${api === "chat" ? "chat/completions" : "messages"}`, { method: "POST", headers: { authorization: `Bearer ${b.llm.key}`, "content-type": "application/json", "x-litellm-tags": "tenant:x" }, body: JSON.stringify(body) });
+                const text = await res.text();
+                let j = null; try { j = JSON.parse(text); } catch { /* keep null */ }
+                return { status: res.status, json: j, text };
+            },
+            /** POST /agent2/cp-request with exactly this JSON body (any shape: for the negative cases) */
+            async policyRaw(bodyObj, { tokenOverride } = {}) {
+                const res = await fetch(`${callbackUrl()}/agent2/cp-request`, { method: "POST", headers: { authorization: `Bearer ${tokenOverride ?? callbackToken()}`, "content-type": "application/json" }, body: JSON.stringify(bodyObj) });
+                const text = await res.text();
+                let j = null; try { j = JSON.parse(text); } catch { /* keep null */ }
+                return { status: res.status, json: j };
+            },
+            /** The request of PR #308's LocalGatewayInternalClient, byte for byte in shape: `{type:"policy.check", payload:{actionType, requestHash, toolName?, modelAlias, incidentId?, jobId, repoRefs}}`
+             *  (LocalPolicyCheck.checkPayload: the repo comes from the job, the hash from the guard's context). `payload` overrides fields (undefined removes one), `extra` adds fields. */
+            async policyCheck({ actionType, tool, incident, payload = {}, extra = {}, tokenOverride }) {
+                const requestHash = crypto.createHash("sha256").update(`${b.jobId}|${actionType}|${tool ?? ""}`).digest("hex");
+                const base = { actionType, requestHash, ...(tool ? { toolName: tool } : {}), modelAlias: b.llm.alias, ...((incident ?? b.incidentId) ? { incidentId: incident ?? b.incidentId } : {}), jobId: b.jobId,
+                    repoRefs: [{ provider: b.repoRef.provider, org: b.repoRef.org, repo: b.repoRef.repo }] };
+                const merged = { ...base, ...payload, ...extra };
+                for (const k of Object.keys(merged)) if (merged[k] === undefined) delete merged[k];
+                const r = await h.policyRaw({ type: "policy.check", payload: merged }, { tokenOverride });
+                r.requestHash = merged.requestHash;
+                return r;
+            },
+            /** a call to the LA /workspace API the way agent2 makes it: at AGENT2_LA_WORKSPACE_URL (the bridge) with X-Agent-Token = AGENT2_LA_WORKSPACE_TOKEN, no signature of its own */
+            async workspace(method, pathAndQuery, bodyObj, { tokenOverride, headers = {} } = {}) {
+                const t = tokenOverride === undefined ? (workspaceToken ? workspaceToken() : callbackToken()) : tokenOverride;
+                const res = await fetch(`${(workspaceUrl ? workspaceUrl() : callbackUrl())}${pathAndQuery}`, { method, headers: { ...(t ? { "x-agent-token": t } : {}), ...(bodyObj !== undefined ? { "content-type": "application/json" } : {}), ...headers }, ...(bodyObj !== undefined ? { body: JSON.stringify(bodyObj) } : {}) });
+                const text = await res.text();
+                let j = null; try { j = JSON.parse(text); } catch { /* keep null */ }
+                return { status: res.status, json: j, text };
+            },
+            crash() { if (onCrash) onCrash(); else { for (const s of sockets) s.destroy(); server.close(); } },
+        };
+        job.h = h;
+        return job;
+    }
+
+    const server = http.createServer(async (req, res) => {
+        const url = new URL(req.url, "http://x");
+        const p = url.pathname;
+        requests.push({ method: req.method, path: p });
+        if (req.method === "GET" && p === "/local/v1/health") { if (healthDelayMs) await sleep(healthDelayMs); return json(res, 200, { status: "up", mode: "local", busy: !!(current && !current.done) }); }
+        if (req.method === "GET" && p === "/local/v1/_env") return json(res, 200, { keys: Object.keys(process.env), values: process.env });   // debug route of the CLI wrapper only
+        if (!auth(req)) return json(res, 401, { error: "unauthorized" });
+        let m;
+        if (req.method === "POST" && p === "/local/v1/jobs") {
+            const b = await body(req);
+            if (!b || typeof b !== "object" || Array.isArray(b)) return json(res, 400, { error: "invalid_body" });
+            for (const k of Object.keys(b)) if (!JOB_FIELDS.has(k)) return json(res, 400, { error: "invalid_body" });
+            if (b.tenantId !== tenantId) return json(res, 403, { error: "tenant_mismatch" });
+            if (b.kind === "quality") return json(res, 422, { error: "unsupported_kind" });
+            if (!/^vh-/.test(b.llm?.alias || "")) return json(res, 400, { error: "invalid", field: "llm.alias" });
+            if (jobs.has(b.jobId)) return json(res, 202, { jobId: b.jobId, state: "running", created: false });
+            if (current && !current.done) return json(res, 409, { error: "busy" });
+            const job = makeJob(b);
+            jobs.set(b.jobId, job);
+            current = job;
+            Promise.resolve().then(() => (sc || SCENARIOS.ok_pr)(job, job.h)).catch(() => {});
+            return json(res, 202, { jobId: b.jobId, state: "running", created: true });
+        }
+        if ((m = p.match(/^\/local\/v1\/jobs\/([^/]+)\/events$/)) && req.method === "GET") {
+            const job = jobs.get(m[1]);
+            if (!job) return json(res, 404, { error: "unknown_job" });
+            res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store" });
+            const write = (f) => res.write(`event: frame\ndata: ${JSON.stringify(f)}\n\n`);
+            for (const f of job.frames) write(f);
+            if (job.done) return res.end();
+            const l = (f) => { if (f === null) { res.end(); job.listeners.delete(l); } else write(f); };
+            job.listeners.add(l);
+            req.on("close", () => job.listeners.delete(l));
+            return;
+        }
+        if ((m = p.match(/^\/local\/v1\/jobs\/([^/]+)\/cancel$/)) && req.method === "POST") {
+            const job = jobs.get(m[1]);
+            const b = await body(req);
+            if (job) { job.cancelRequested = true; job.cancelReason = b?.reason ?? null; job.record.cancelCalls = (job.record.cancelCalls || 0) + 1; job.onCancel(); }
+            return json(res, 202, { jobId: m[1], state: job?.done ? "finished" : "cancelling" });
+        }
+        if ((m = p.match(/^\/local\/v1\/jobs\/([^/]+)$/)) && req.method === "GET") { const job = jobs.get(m[1]); return job ? json(res, 200, { jobId: m[1], state: job.done ? "finished" : "running" }) : json(res, 404, { error: "unknown_job" }); }
+        if (req.method === "GET" && p === "/local/v1/approvals") {
+            if (!supportList) return json(res, 404, { error: "not_found" });
+            requests.push({ method: "LIST", path: p, query: url.search });
+            const only = url.searchParams.get("jobId");
+            return json(res, 200, { approvals: [...approvals.values()].filter((a) => !a.decided && (!only || a.jobId === only)).map(({ approvalId, jobId, actionType, toolName, requestHash, expiresAt }) => ({ approvalId, jobId, actionType, toolName, requestHash, expiresAt })) });
+        }
+        if ((m = p.match(/^\/local\/v1\/approvals\/([^/]+)$/))) {
+            const a = approvals.get(m[1]);
+            if (req.method === "GET") return a && !a.decided ? json(res, 200, { approvalId: a.approvalId, jobId: a.jobId, actionType: a.actionType, toolName: a.toolName, summary: a.summary, requestHash: a.requestHash, expiresAt: a.expiresAt }) : json(res, 404, { error: "unknown_approval" });
+            if (req.method === "POST") {
+                const b = await body(req);
+                if (!a) return json(res, 404, { error: "unknown_approval" });
+                if (a.decided) return json(res, 409, { error: "already_decided" });
+                if (!b || !["approved", "denied"].includes(b.decision)) return json(res, 400, { error: "invalid_body" });
+                a.decided = true;
+                a.decidedBy = b.decidedBy;
+                requests.push({ method: "DECIDE", path: p, decision: b.decision, decidedBy: b.decidedBy });
+                a.resolve({ approved: b.decision === "approved", decidedBy: b.decidedBy });
+                return json(res, 200, { approvalId: a.approvalId, decision: b.decision });
+            }
+        }
+        return json(res, 404, { error: "not_found" });
+    });
+    server.on("connection", (s) => { sockets.add(s); s.on("close", () => sockets.delete(s)); });
+    await new Promise((r) => server.listen(port, "127.0.0.1", r));
+    const actualPort = server.address().port;
+    return {
+        port: actualPort, baseUrl: `http://127.0.0.1:${actualPort}`, jobs, approvals, requests,
+        get current() { return current; },
+        set scenario(s) { scenarioName = s; },
+        async close() { for (const s of sockets) s.destroy(); await new Promise((r) => server.close(() => r())); },
+    };
+}

package/test/la-protocol-v2/helpers/fake-la-api.js

@@ -0,0 +1,29 @@
+// A stand-in for the Local Agent's own HTTP API with the REAL perimeter of src/server.js in front of two trivial routes: the same auth middleware (utils/agent-auth.js), the same body
+// parser hook and the same signature middleware (utils/request-signing.js, LOCAL_AGENT_SIGNATURE_MODE=enforce by default). What it proves is that a request is accepted or refused by
+// the real checks; the routes are not the real /workspace handlers (the real server is exercised by agent2-workspace-real-server.test.js).
+import http from "node:http";
+import express from "express";
+import bodyParser from "body-parser";
+import { createAuthMiddleware, resolveAuthConfig, allowedOrigins } from "../../../src/utils/agent-auth.js";
+import { createSignatureMiddleware, resolveSigningConfig, captureRawBody } from "../../../src/utils/request-signing.js";
+
+export async function startFakeLaApi({ env = {}, keyId, publicKeyRaw, port = 0 } = {}) {
+    const requests = [];
+    const app = express();
+    app.use(createAuthMiddleware(resolveAuthConfig(env), allowedOrigins(env)));
+    app.use(bodyParser.json({ limit: "50mb", verify: captureRawBody }));
+    app.use(createSignatureMiddleware(resolveSigningConfig({ LOCAL_AGENT_SIGNATURE_MODE: "enforce", ...env, LOCAL_AGENT_SIGNING_PUBLIC_KEYS: `${keyId}=${publicKeyRaw}`, LOCAL_AGENT_SIGNING_KEYS_FILE: "/nonexistent" }, { defaultFile: null })));
+    const note = (req, extra = {}) => requests.push({ method: req.method, url: req.originalUrl, headers: { ...req.headers }, signature: req.vhSignature, body: req.body, ...extra });
+    app.get("/workspace/file-content", (req, res) => { note(req); res.json({ ok: true, content: "// hello from the LA", root: req.headers["x-workspace-root"] || null }); });
+    app.post("/workspace/write-file", (req, res) => { note(req); res.json({ ok: true, written: req.body && req.body.path }); });
+    app.post("/workspace/echo", (req, res) => { note(req); res.json({ ok: true, bytes: JSON.stringify(req.body || {}).length }); });
+    app.delete("/workspace/thing", (req, res) => { note(req); res.json({ ok: true }); });
+    app.get("/workspace/slow", (req, res) => { note(req); setTimeout(() => res.json({ ok: true }), 300); });
+    app.post("/setup/run-command", (req, res) => { note(req); res.json({ ok: true, ran: true }); });   // must never be reachable through the bridge
+    const server = http.createServer(app);
+    const sockets = new Set();
+    server.on("connection", (s) => { sockets.add(s); s.on("close", () => sockets.delete(s)); });
+    await new Promise((r) => server.listen(port, "127.0.0.1", r));
+    const p = server.address().port;
+    return { port: p, url: `http://127.0.0.1:${p}`, requests, async close() { for (const s of sockets) s.destroy(); await new Promise((r) => server.close(() => r())); } };
+}

package/test/la-protocol-v2/helpers/fake-llm.js

@@ -0,0 +1,75 @@
+// A fake OpenAI-compatible server (chat/completions, JSON and SSE) on 127.0.0.1, plus the fetch that points the https endpoint of the key at it.
+// It records what it was sent (method, url, headers, parsed body) so the tests can prove what left the agent and what did not.
+import http from "node:http";
+import crypto from "node:crypto";
+
+export const sha = (s) => crypto.createHash("sha256").update(Buffer.from(s, "utf8")).digest("hex");
+export const mkKey = (tag = "A") => `sk-CANARY-LLMKEY-${tag}-${crypto.randomBytes(12).toString("hex")}`;
+export const FUTURE = (ms = 3_600_000) => new Date(Date.now() + ms).toISOString();
+export const keySet = (key, over = {}) => ({ op: "set", keyId: sha(key), endpoint: "https://ai.visionhammer.io/litellm", key, models: ["vh-claude-sonnet", "vh-embed"], expiresAt: FUTURE(), ...over });
+
+export const okJson = (content = "ok", { promptTokens = 12, completionTokens = 5, cost, model = "vh-claude-sonnet" } = {}) => (req, res) => {
+    const body = JSON.stringify({ id: "cmpl-1", object: "chat.completion", model, choices: [{ index: 0, message: { role: "assistant", content }, finish_reason: "stop" }], usage: { prompt_tokens: promptTokens, completion_tokens: completionTokens, total_tokens: promptTokens + completionTokens } });
+    res.writeHead(200, { "content-type": "application/json", ...(cost !== undefined ? { "x-litellm-response-cost": String(cost) } : {}) });
+    res.end(body);
+};
+
+/** The Anthropic Messages API answer (what LiteLLM returns on /v1/messages): text, or tool_use blocks. */
+export const okMessages = (content = "ok", { promptTokens = 12, completionTokens = 5, cost, model = "claude-upstream-model", blocks } = {}) => (req, res) => {
+    const body = JSON.stringify({ id: "msg_1", type: "message", role: "assistant", model, content: blocks || [{ type: "text", text: content }], stop_reason: blocks ? "tool_use" : "end_turn", stop_sequence: null,
+        usage: { input_tokens: promptTokens, output_tokens: completionTokens } });
+    res.writeHead(200, { "content-type": "application/json", ...(cost !== undefined ? { "x-litellm-response-cost": String(cost) } : {}) });
+    res.end(body);
+};
+
+/** One behavior per API: /v1/messages -> `messages`, anything else (chat/completions) -> `chat`. */
+export const byPath = ({ chat = okJson(), messages = okMessages() } = {}) => (req, res, entry) => (/\/messages$/.test(req.url) ? messages(req, res, entry) : chat(req, res, entry));
+
+export const okSse = (deltas, { promptTokens = 20, completionTokens = 7, gapMs = 0 } = {}) => async (req, res) => {
+    res.writeHead(200, { "content-type": "text/event-stream" });
+    for (const d of deltas) {
+        res.write(`data: ${JSON.stringify({ choices: [{ index: 0, delta: { content: d } }] })}\n\n`);
+        if (gapMs) await new Promise((r) => setTimeout(r, gapMs));
+    }
+    res.write(`data: ${JSON.stringify({ choices: [{ index: 0, delta: {}, finish_reason: "stop" }] })}\n\n`);
+    res.write(`data: ${JSON.stringify({ choices: [], usage: { prompt_tokens: promptTokens, completion_tokens: completionTokens } })}\n\n`);
+    res.end("data: [DONE]\n\n");
+};
+
+export const status = (code, body = "") => (req, res) => { res.writeHead(code, { "content-type": "application/json" }); res.end(body); };
+
+/** @param {Function|Function[]} behavior one handler for every request, or a list used in order (the last one repeats) */
+const OPEN = new Set();
+/** Closes every fake server a failed test left open (so a red test never hangs the run). */
+export async function closeAllFakes() { await Promise.all([...OPEN].map((f) => f.close())); }
+
+export async function startFakeLlm(behavior = okJson()) {
+    const requests = [];
+    let list = Array.isArray(behavior) ? behavior : [behavior];
+    const sockets = new Set();
+    const server = http.createServer((req, res) => {
+        const chunks = [];
+        req.on("data", (c) => chunks.push(c));
+        req.on("end", () => {
+            const raw = Buffer.concat(chunks).toString("utf8");
+            let body = null;
+            try { body = JSON.parse(raw); } catch { /* keep null */ }
+            const entry = { method: req.method, url: req.url, headers: req.headers, raw, body };
+            requests.push(entry);
+            const h = list[Math.min(requests.length - 1, list.length - 1)];
+            Promise.resolve(h(req, res, entry)).catch(() => { try { res.destroy(); } catch { /* gone */ } });
+        });
+    });
+    server.on("connection", (s) => { sockets.add(s); s.on("close", () => sockets.delete(s)); });
+    await new Promise((r) => server.listen(0, "127.0.0.1", r));
+    const port = server.address().port;
+    const fake = {
+        port, requests,
+        set(b) { list = Array.isArray(b) ? b : [b]; },
+        /** the fetch the holder uses: the https origin of the key's endpoint is pointed at this server, everything else is untouched */
+        fetchImpl: (url, init) => fetch(String(url).replace(/^https:\/\/[^/]+/, `http://127.0.0.1:${port}`), init),
+        async close() { OPEN.delete(fake); for (const s of sockets) s.destroy(); await new Promise((r) => server.close(r)); },
+    };
+    OPEN.add(fake);
+    return fake;
+}

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

@@ -54,6 +54,7 @@ export class ReferenceCp {
         this.dropAcks = 0;        // do not ack the next n accepted LA data frames (simulates lost acks)
         this.silent = false;      // do not ack anything
         this.rejectData = [];     // F3-07b: error codes, consumed one per LA data frame: the frame is acked `rejected` with that code (not stored)
+        this.rejectTypes = {};    // F3-08c: { "<frame type>": "<error code>" }: every LA data frame of that type is acked `rejected` with that code (not stored)
         this.rejectedFrames = []; // [type, code] of the frames acked `rejected`
         this.ackDelayMs = 0;      // answer acks late (slow consumer)
         this.onReceived = () => {};
@@ -170,8 +171,8 @@ export class ReferenceCp {
         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);
-        if (this.rejectData.length > 0) { // the gateway's non-fatal answer: the seq is consumed, the frame is not stored
-            const code = this.rejectData.shift();
+        if (this.rejectData.length > 0 || this.rejectTypes[m.type]) { // the gateway's non-fatal answer: the seq is consumed, the frame is not stored
+            const code = this.rejectTypes[m.type] || this.rejectData.shift();
             this.rejectedFrames.push([m.type, code]);
             this.#sendAck(seq, "rejected", code);
             return null;
@@ -225,7 +226,9 @@ export class ReferenceCp {
     #sendReady(resumed) {
         const f = this.#envelope("ready", 0, null, this.workspaceId);
         const announced = (this.registers.at(-1) || {}).capabilities || [];
-        const caps = this.capabilities.length > 0 && announced.includes("contract.v2.1") ? { capabilities: [...this.capabilities] } : {};
+        // like the gateway: `policy.check` (2.2) is listed only for an LA that announced it, and everything 2.1+ only for an LA that announced contract.v2.1
+        const listed = this.capabilities.filter((c) => c !== "policy.check" || announced.includes("policy.check"));
+        const caps = listed.length > 0 && announced.includes("contract.v2.1") ? { capabilities: listed } : {};
         this.#sign(f, "ready", { protocol: 2, sessionId: this.sessionId, resumed, peerLastSeq: this.laSeq, limits: { ...this.limits }, ...caps }, this.workspaceId);
         this.sendFn(JSON.stringify(f));
     }

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

@@ -18,14 +18,15 @@ export async function runAgent({ srv, root = DEFAULT_ROOT, env = {}, cfg, until,
         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;
+    const base = { ...process.env };
+    delete base.LOCAL_AGENT_TOKEN;   // the developer's own token never leaks into a test; a test that wants one passes it in `env`
+    const full = { ...base, PORT: String(await freePort()), GATEWAY_URL: srv.url, AUTH_TOKEN: srv.token, WORKSPACE_ROOT: ws, HOME: home, ...env };
     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;
+            if (until && (await until({ child }))) break;
             await new Promise((r) => setTimeout(r, 50));
         }
     } finally {

package/test/la-protocol-v2/helpers/supervisor-exit-script.js

@@ -0,0 +1,15 @@
+// A tiny stand-in for "the Local Agent exits": starts a supervisor (spawn mode) with the fake agent2 CLI as the child, prints the child's pid and exits NORMALLY with process.exit().
+// Used by agent2-orphan.test.js to prove the child does not outlive an orderly exit of its supervisor. argv: <cli> <pidfile>
+import { createAgent2Supervisor } from "../../../src/la-protocol-v2/jobs/agent2/supervisor.js";
+import { resolveAgent2RunnerConfig } from "../../../src/la-protocol-v2/jobs/agent2/config.js";
+import net from "node:net";
+
+const [, , cli, pidFile] = process.argv;
+// `node --test` also loads every file under test/: without its arguments this file is a no-op
+if (!cli || !pidFile) process.exit(0);
+const port = await new Promise((res) => { const s = net.createServer().listen(0, "127.0.0.1", () => { const p = s.address().port; s.close(() => res(p)); }); });
+const config = resolveAgent2RunnerConfig({ LOCAL_AGENT_RUNNER: "agent2", LOCAL_AGENT_AGENT2_CMD: JSON.stringify([process.execPath, cli, "--scenario=slow"]), LOCAL_AGENT_AGENT2_PORT: String(port), LOCAL_AGENT_AGENT2_PIDFILE: pidFile, LOCAL_AGENT_AGENT2_START_TIMEOUT_MS: "8000" });
+const sup = createAgent2Supervisor({ config, tenantId: "3f2b8c1e-5a4d-4e7b-9c21-0a1b2c3d4e5f", bridge: { listen: async () => ({ baseUrl: "http://127.0.0.1:1" }), setCallbackToken() {} }, env: { PATH: process.env.PATH, HOME: process.env.HOME }, log: { warn() {}, info() {} } });
+await sup.ensureReady();
+console.log(`CHILD_PID=${sup.pid}`);
+process.exit(0);