deepdebug-local-agent 1.10.0 → 1.11.0

package/src/la-protocol-v2/jobs/agent2/bridge.js

@@ -0,0 +1,299 @@
+/**
+ * bridge.js - the loopback door agent2 uses to reach the outside world through THIS agent (F3-08c, Local Agent half).
+ *
+ *   POST /v1/messages (also /messages)   the LLM, Anthropic Messages API with tools: what the packaged agent loop speaks (ClaudeApiClient), so agent2's
+ *       `AGENT2_LLM_BASE_URL` points at `<bridge>/v1`. The bearer is a PER-JOB token minted by the runner (memory only, revoked when the job ends); the virtual
+ *       key of the AI gateway is never given to agent2: the request is handed to the job's `ctx.llm.messages`, i.e. the LLM client of this agent, which masks
+ *       EVERY string the model will read with the DLP (enforce, no opt-out: system, text, tool_use input, tool_result, tool descriptions), counts tokens and
+ *       cost into the job, applies the job's budget/alias/tags and calls the AI gateway through the key holder. `model` and `metadata` in the request are
+ *       ignored: the job's alias and this agent's tags are used. Not streaming.
+ *   POST /v1/chat/completions (also /chat/completions)   the same for an OpenAI-shaped, text-only caller (`ctx.llm.chat`); `tools` are refused there.
+ *   POST /agent2/cp-request   the PolicyGate door: `{"type":"policy.check","payload":{actionType, requestHash, toolName?, modelAlias?, incidentId?, jobId, repoRefs?}}` (what agent2's
+ *       LocalGatewayInternalClient sends; bearer = the callback token of the running agent2), EXACTLY that shape and nothing else (any other body, e.g. the hosted
+ *       `{method,path,body}`, is 403 path_not_allowed). The question goes to the control plane as a `policy.check` frame over the v2 channel (policy-check.js) and the answer is
+ *       the signed `policy.decision` payload (200), in the contract's field names. This agent does NOT say who is asking (tenant, agent and `executionOrigin=local-agent` are
+ *       derived by the control plane from the authenticated session): the payload is rebuilt from a whitelist, the job id and the repository are the RUNNING job's, and a
+ *       tenant/origin/agent claim in it is dropped. Without a relay, or when the channel cannot answer, the answer is a 4xx/5xx DENY and agent2 blocks every governed action
+ *       (fail closed).
+ *   ANY /workspace/...   agent2's door to this agent's own `/workspace` API (read_file, write_file, exec, ...). The LA verifies a platform signature on its API
+ *       (LOCAL_AGENT_SIGNATURE_MODE=enforce, default) that agent2 cannot make, so THIS bridge, which agent2 can only reach with the callback token, forwards the request
+ *       to the API on agent2's behalf and vouches for it with the process-local internal marker (the same one the WS tunnel uses for its own hops), the tenant
+ *       and the running job's workspace; the API's X-Agent-Token is added here, so agent2 never holds it. The signature check stays ON: a request that does
+ *       not come through this bridge is still refused 401. Only `/workspace/` paths, no `..`, no encoded characters, one body cap.
+ *
+ * Perimeter: bound to 127.0.0.1, requests from a loopback socket only, a `Host` that is loopback, no `Origin` (a browser), constant-time token comparison,
+ * body cap, JSON only. What it never does: log a body, an answer, a token or a path; echo a request value in an error (codes only).
+ */
+import http from "node:http";
+import crypto from "node:crypto";
+import path from "node:path";
+
+const LLM_STATUS = Object.freeze({
+    bad_request: 400, dlp_blocked: 403, dlp_denied: 403, dlp_not_enforced: 403, model_not_allowed: 403, prompt_too_large: 413,
+    no_key: 401, key_expired: 401, key_rejected: 401, budget_exceeded: 402, rate_limited: 429, busy: 429, timeout: 504,
+    network_error: 502, upstream_error: 502, response_too_large: 502, bad_response: 502, cancelled: 409, internal: 500,
+});
+const ROLES = new Set(["system", "user", "assistant"]);
+export const POLICY_CHECK_TYPE = "policy.check";
+
+function safeEqual(a, b) {
+    const x = crypto.createHash("sha256").update(String(a)).digest();
+    const y = crypto.createHash("sha256").update(String(b)).digest();
+    return crypto.timingSafeEqual(x, y) && String(a).length === String(b).length;
+}
+
+const isLoopbackAddr = (a) => { const s = String(a || "").replace(/^::ffff:/, ""); return s === "::1" || /^127\./.test(s); };
+const isLoopbackHost = (h) => /^(127\.\d{1,3}\.\d{1,3}\.\d{1,3}|localhost|\[::1\])(:\d{1,5})?$/.test(String(h || ""));
+
+/**
+ * @param {object} o
+ * @param {number} [o.port]   0 = any free port
+ * @param {number} o.maxBodyBytes
+ * @param {(args:{check:object, job:{jobId:string, workspaceId:string, alias:string, incidentId?:string, repoRef?:object}}) => Promise<{status:number, json:object}>} [o.policyRelay]  null = no relay (503)
+ * @param {string} o.tenantId  the ONE tenant this agent serves (vouched for in the /workspace hop; never put in a policy request)
+ * @param {{url:string, headers:(job:object)=>object, maxBodyBytes?:number, timeoutMs?:number}|null} [o.workspace]  the LA's own /workspace API: base URL (loopback) and the headers
+ *        that make the hop authentic (internal marker + X-Agent-Token); null = the /workspace door is closed (404)
+ */
+export function createAgent2Bridge({ port = 0, maxBodyBytes, policyRelay = null, tenantId, log = console, now = Date.now, workspace = null }) {
+    const jobs = new Map();        // token -> { jobId, alias, llm, workspaceId, incidentId?, root?, inflight }
+    const byJob = new Map();       // jobId -> token
+    let callbackToken = null;
+    let server = null;
+    let listening = null;
+    let baseUrl = null;
+    const stats = { llmCalls: 0, llmErrors: 0, llmUnauthorized: 0, relayCalls: 0, relayRefused: 0, relayErrors: 0, wsForwarded: 0, wsRefused: 0, wsErrors: 0, rejectedPerimeter: 0, byCode: {} };
+    const bump = (k) => { stats.byCode[k] = (stats.byCode[k] || 0) + 1; };
+    const warn = (m) => (log.warn || log.log).call(log, m);
+
+    const send = (res, status, json, headers = {}) => {
+        const text = JSON.stringify(json);
+        res.writeHead(status, { "content-type": "application/json", "content-length": Buffer.byteLength(text), "cache-control": "no-store", ...headers });
+        res.end(text);
+    };
+    const fail = (res, status, code) => { bump(code); send(res, status, { error: { message: code, type: "vh_la_error", code } }, status === 413 ? { connection: "close" } : {}); };
+
+    function readBody(req) {
+        return new Promise((resolve, reject) => {
+            const chunks = [];
+            let total = 0;
+            let over = false;
+            req.on("data", (c) => {
+                total += c.length;
+                if (total > maxBodyBytes) {
+                    if (!over) { over = true; chunks.length = 0; reject(Object.assign(new Error("too_large"), { code: "payload_too_large" })); }   // nothing is kept; the rest is read and thrown away so the 413 can be delivered
+                    return;
+                }
+                if (!over) chunks.push(c);
+            });
+            req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+            req.on("error", () => reject(Object.assign(new Error("read"), { code: "bad_request" })));
+        });
+    }
+
+    const bearer = (req) => { const h = req.headers.authorization; return typeof h === "string" && /^Bearer\s+\S{16,512}$/i.test(h) ? h.replace(/^Bearer\s+/i, "") : null; };
+
+    function findJob(token) {
+        if (!token) return null;
+        for (const [t, rec] of jobs) if (safeEqual(t, token)) return rec;   // compares against every token: no early exit on a prefix
+        return null;
+    }
+
+    async function llm(req, res) {
+        const rec = findJob(bearer(req));
+        if (!rec) { stats.llmUnauthorized++; return fail(res, 401, "unauthorized"); }
+        let body;
+        try {
+            if (!/^application\/json\b/i.test(String(req.headers["content-type"] || ""))) return fail(res, 415, "unsupported_media_type");
+            body = JSON.parse(await readBody(req));
+        } catch (e) { return fail(res, e && e.code === "payload_too_large" ? 413 : 400, e && e.code === "payload_too_large" ? "payload_too_large" : "bad_request"); }
+        if (!body || typeof body !== "object" || Array.isArray(body)) return fail(res, 400, "bad_request");
+        if (body.tools !== undefined || body.functions !== undefined || body.tool_choice !== undefined || body.function_call !== undefined) return fail(res, 400, "tools_unsupported");
+        const msgs = body.messages;
+        if (!Array.isArray(msgs) || msgs.length < 1 || !msgs.every((m) => m && typeof m === "object" && ROLES.has(m.role) && typeof m.content === "string")) return fail(res, 400, "bad_request");
+        if (body.n !== undefined && body.n !== 1) return fail(res, 400, "bad_request");
+        const stream = body.stream === true;
+        const maxTokens = Number.isSafeInteger(body.max_tokens) && body.max_tokens > 0 ? body.max_tokens : Number.isSafeInteger(body.max_completion_tokens) && body.max_completion_tokens > 0 ? body.max_completion_tokens : undefined;
+        const temperature = typeof body.temperature === "number" && Number.isFinite(body.temperature) && body.temperature >= 0 && body.temperature <= 2 ? body.temperature : undefined;
+        if (rec.inflight >= 2) return fail(res, 429, "busy");
+        rec.inflight++;
+        stats.llmCalls++;
+        try {
+            const r = await rec.llm.chat({ messages: msgs.map((m) => ({ role: m.role, content: m.content })), ...(maxTokens ? { maxTokens } : {}), ...(temperature !== undefined ? { temperature } : {}) });
+            const usage = { prompt_tokens: r.usage.promptTokens, completion_tokens: r.usage.completionTokens, total_tokens: r.usage.promptTokens + r.usage.completionTokens };
+            const created = Math.floor(now() / 1000);
+            const id = `chatcmpl-${crypto.randomBytes(8).toString("hex")}`;
+            const model = rec.alias;
+            const finish = r.finishReason || "stop";
+            if (!stream) return send(res, 200, { id, object: "chat.completion", created, model, choices: [{ index: 0, message: { role: "assistant", content: r.text }, finish_reason: finish }], usage });
+            res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store" });
+            res.write(`data: ${JSON.stringify({ id, object: "chat.completion.chunk", created, model, choices: [{ index: 0, delta: { role: "assistant", content: r.text }, finish_reason: null }] })}\n\n`);
+            res.write(`data: ${JSON.stringify({ id, object: "chat.completion.chunk", created, model, choices: [{ index: 0, delta: {}, finish_reason: finish }], usage })}\n\n`);
+            res.end("data: [DONE]\n\n");
+        } catch (e) {
+            stats.llmErrors++;
+            const code = e && typeof e.code === "string" && Object.hasOwn(LLM_STATUS, e.code) ? e.code : "internal";
+            fail(res, LLM_STATUS[code], code);
+        } finally {
+            rec.inflight--;
+        }
+    }
+
+    /** Anthropic Messages API. Errors keep the Messages shape ({type:"error", error:{type, message}}) with a code as the message. */
+    async function messagesRoute(req, res) {
+        const anthropicFail = (status, code) => { bump(code); send(res, status, { type: "error", error: { type: "vh_la_error", message: code } }, status === 413 ? { connection: "close" } : {}); };
+        const rec = findJob(bearer(req));
+        if (!rec) { stats.llmUnauthorized++; return anthropicFail(401, "unauthorized"); }
+        let body;
+        try {
+            if (!/^application\/json\b/i.test(String(req.headers["content-type"] || ""))) return anthropicFail(415, "unsupported_media_type");
+            body = JSON.parse(await readBody(req));
+        } catch (e) { return e && e.code === "payload_too_large" ? anthropicFail(413, "payload_too_large") : anthropicFail(400, "bad_request"); }
+        if (!body || typeof body !== "object" || Array.isArray(body)) return anthropicFail(400, "bad_request");
+        if (body.stream === true) return anthropicFail(400, "stream_unsupported");
+        if (!Array.isArray(body.messages)) return anthropicFail(400, "bad_request");
+        const maxTokens = Number.isSafeInteger(body.max_tokens) && body.max_tokens > 0 ? body.max_tokens : undefined;
+        const temperature = typeof body.temperature === "number" && Number.isFinite(body.temperature) ? body.temperature : undefined;
+        if (rec.inflight >= 2) return anthropicFail(429, "busy");
+        rec.inflight++;
+        stats.llmCalls++;
+        try {
+            const r = await rec.llm.messages({ messages: body.messages, ...(body.system !== undefined ? { system: body.system } : {}), ...(body.tools !== undefined ? { tools: body.tools } : {}),
+                ...(body.tool_choice !== undefined ? { toolChoice: body.tool_choice } : {}), ...(maxTokens ? { maxTokens } : {}), ...(temperature !== undefined ? { temperature } : {}) });
+            send(res, 200, { ...r.message, model: rec.alias });
+        } catch (e) {
+            stats.llmErrors++;
+            const code = e && typeof e.code === "string" && Object.hasOwn(LLM_STATUS, e.code) ? e.code : "internal";
+            anthropicFail(LLM_STATUS[code], code);
+        } finally {
+            rec.inflight--;
+        }
+    }
+
+    async function cpRequest(req, res) {
+        if (!callbackToken || !bearer(req) || !safeEqual(bearer(req), callbackToken)) { stats.relayRefused++; return fail(res, 401, "unauthorized"); }
+        let body;
+        try { body = JSON.parse(await readBody(req)); } catch (e) { return fail(res, e && e.code === "payload_too_large" ? 413 : 400, e && e.code === "payload_too_large" ? "payload_too_large" : "bad_request"); }
+        if (!body || typeof body !== "object" || Array.isArray(body)) return fail(res, 400, "bad_request");
+        if (Object.keys(body).length !== 2 || body.type !== POLICY_CHECK_TYPE || !body.payload || typeof body.payload !== "object" || Array.isArray(body.payload)) { stats.relayRefused++; return fail(res, 403, "path_not_allowed"); }
+        const active = [...jobs.values()][0];
+        if (!active) { stats.relayRefused++; return fail(res, 409, "no_active_job"); }
+        if (!policyRelay) { stats.relayRefused++; return fail(res, 503, "policy_relay_unavailable"); }
+        stats.relayCalls++;
+        try {
+            // the relay rebuilds the question from a whitelist and pins the job, its repository and its alias: agent2's own claims about who it is are never carried
+            const out = await policyRelay({ check: body.payload, job: { jobId: active.jobId, workspaceId: active.workspaceId, alias: active.alias, ...(active.incidentId ? { incidentId: active.incidentId } : {}),
+                ...(active.repoRef ? { repoRef: active.repoRef } : {}) } });
+            const status = Number.isInteger(out?.status) && out.status >= 200 && out.status < 600 ? out.status : 502;
+            send(res, status, out?.json && typeof out.json === "object" ? out.json : { error: "bad_response" });
+        } catch { stats.relayErrors++; fail(res, 502, "policy_relay_failed"); }
+    }
+
+    const WS_PATH = /^\/workspace(?:\/[A-Za-z0-9._~-]+)+\/?$/;
+    const WS_METHODS = new Set(["GET", "POST", "PUT", "DELETE"]);
+    const FORWARD_REQ_HEADERS = ["content-type", "accept"];
+    const sameRoot = (a, b) => typeof a === "string" && typeof b === "string" && a.trim() !== "" && path.resolve(a.trim()) === path.resolve(b);
+    const FORWARD_RES_HEADERS = ["content-type", "cache-control"];
+
+    /** agent2 -> this agent's /workspace API, vouched for by this agent (see the header). */
+    function workspaceRoute(req, res) {
+        const presented = typeof req.headers["x-agent-token"] === "string" ? req.headers["x-agent-token"] : bearer(req);
+        if (!workspace) { stats.wsRefused++; return fail(res, 404, "not_found"); }
+        if (!callbackToken || !presented || !safeEqual(presented, callbackToken)) { stats.wsRefused++; return fail(res, 401, "unauthorized"); }
+        if (!WS_METHODS.has(req.method)) { stats.wsRefused++; return fail(res, 405, "method_not_allowed"); }
+        const raw = String(req.url || "");
+        const q = raw.indexOf("?");
+        const pathOnly = q >= 0 ? raw.slice(0, q) : raw;
+        const query = q >= 0 ? raw.slice(q) : "";
+        if (!WS_PATH.test(pathOnly) || pathOnly.split("/").some((seg) => seg === "." || seg === "..") || /[\u0000-\u001f\u007f#]/.test(query)) { stats.wsRefused++; return fail(res, 403, "path_not_allowed"); }
+        const active = [...jobs.values()][0];
+        if (!active) { stats.wsRefused++; return fail(res, 409, "no_active_job"); }
+        // agent2 acts on the workspace of ITS job: the root header it sends must be that root (it is added when it sends none); the id header is the job's, not agent2's
+        const claimed = req.headers["x-workspace-root"];
+        if (claimed !== undefined && !sameRoot(Array.isArray(claimed) ? claimed[0] : claimed, active.root)) { stats.wsRefused++; return fail(res, 403, "workspace_mismatch"); }
+        const cap = workspace.maxBodyBytes || 16 * 1024 * 1024;
+        const declared = Number(req.headers["content-length"]);
+        if (Number.isFinite(declared) && declared > cap) { stats.wsRefused++; return fail(res, 413, "payload_too_large"); }
+        const chunks = [];
+        let total = 0;
+        let over = false;
+        req.on("data", (c) => { total += c.length; if (total > cap) { over = true; chunks.length = 0; } else if (!over) chunks.push(c); });
+        req.on("error", () => { try { fail(res, 400, "bad_request"); } catch { /* gone */ } });
+        req.on("end", () => {
+            if (over) { stats.wsRefused++; return fail(res, 413, "payload_too_large"); }
+            const body = Buffer.concat(chunks);
+            const headers = {};
+            for (const h of FORWARD_REQ_HEADERS) if (typeof req.headers[h] === "string") headers[h] = req.headers[h];
+            if (active.root) headers["x-workspace-root"] = active.root;
+            headers["x-workspace-id"] = active.workspaceId;
+            Object.assign(headers, workspace.headers({ jobId: active.jobId, workspaceId: active.workspaceId, tenantId }));   // internal marker, tenant, workspace, X-Agent-Token: ours, not agent2's
+            if (body.length > 0 || req.method === "POST" || req.method === "PUT") headers["content-length"] = String(body.length);
+            stats.wsForwarded++;
+            let up;
+            try {
+                const u = new URL(workspace.url);
+                up = http.request({ host: u.hostname.replace(/^\[|\]$/g, ""), port: u.port || 80, method: req.method, path: raw, headers, agent: false, timeout: workspace.timeoutMs || 15 * 60_000 }, (r) => {
+                    const out = {};
+                    for (const h of FORWARD_RES_HEADERS) if (typeof r.headers[h] === "string") out[h] = r.headers[h];
+                    if (typeof r.headers["content-length"] === "string") out["content-length"] = r.headers["content-length"];
+                    res.writeHead(r.statusCode || 502, out);
+                    r.pipe(res);
+                    r.on("error", () => { try { res.destroy(); } catch { /* gone */ } });
+                });
+            } catch { stats.wsErrors++; return fail(res, 502, "workspace_unreachable"); }
+            up.on("timeout", () => { up.destroy(); });
+            up.on("error", () => { stats.wsErrors++; if (!res.headersSent) fail(res, 502, "workspace_unreachable"); else { try { res.destroy(); } catch { /* gone */ } } });
+            res.on("close", () => { if (!up.destroyed) up.destroy(); });
+            up.end(body);
+        });
+    }
+
+    function handler(req, res) {
+        // perimeter first: nothing below runs for a request that does not come from this host's own processes
+        if (!isLoopbackAddr(req.socket.remoteAddress) || !isLoopbackHost(req.headers.host) || req.headers.origin !== undefined) { stats.rejectedPerimeter++; return fail(res, 403, "forbidden"); }
+        const url = String(req.url || "").split("?")[0];
+        if (req.method === "POST" && (url === "/v1/chat/completions" || url === "/chat/completions")) return void llm(req, res).catch(() => { try { fail(res, 500, "internal"); } catch { /* gone */ } });
+        if (req.method === "POST" && (url === "/v1/messages" || url === "/messages")) return void messagesRoute(req, res).catch(() => { try { fail(res, 500, "internal"); } catch { /* gone */ } });
+        if (req.method === "POST" && url === "/agent2/cp-request") return void cpRequest(req, res).catch(() => { try { fail(res, 500, "internal"); } catch { /* gone */ } });
+        if (url === "/workspace" || url.startsWith("/workspace/")) return workspaceRoute(req, res);
+        return fail(res, 404, "not_found");
+    }
+
+    return {
+        stats,
+        get baseUrl() { return baseUrl; },
+        get activeJobs() { return jobs.size; },
+        /** Starts listening once (idempotent). */
+        listen() {
+            if (listening) return listening;
+            listening = new Promise((resolve, reject) => {
+                server = http.createServer(handler);
+                server.requestTimeout = 180_000;
+                server.headersTimeout = 10_000;
+                server.on("error", (e) => { listening = null; reject(e); });
+                server.listen(port, "127.0.0.1", () => { baseUrl = `http://127.0.0.1:${server.address().port}`; resolve({ baseUrl, port: server.address().port }); });
+            });
+            return listening;
+        },
+        setCallbackToken(t) { callbackToken = typeof t === "string" && t.length >= 32 ? t : null; },
+        /** The token agent2 presents as its "LLM key" for this job (random, memory only). `llm` = the job's ctx.llm ({chat, messages}). */
+        registerJob({ jobId, alias, llm, workspaceId, incidentId, root, repoRef }) {
+            const token = crypto.randomBytes(32).toString("base64url");
+            const old = byJob.get(jobId);
+            if (old) jobs.delete(old);
+            jobs.set(token, { jobId, alias, llm, workspaceId, ...(incidentId ? { incidentId } : {}), ...(root ? { root } : {}), ...(repoRef ? { repoRef } : {}), inflight: 0 });
+            byJob.set(jobId, token);
+            return token;
+        },
+        revokeJob(jobId) {
+            const t = byJob.get(jobId);
+            if (t) jobs.delete(t);
+            byJob.delete(jobId);
+        },
+        async close() {
+            jobs.clear(); byJob.clear(); callbackToken = null;
+            const s = server;
+            server = null; listening = null; baseUrl = null;
+            if (s) { if (s.closeAllConnections) s.closeAllConnections(); await new Promise((r) => s.close(() => r())); }
+        },
+    };
+}

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

@@ -0,0 +1,128 @@
+/**
+ * config.js - LOCAL_AGENT_RUNNER=agent2 and the limits of the agent2 runner (F3-08c, Local Agent half).
+ *
+ *   unset / anything else (default)  nothing of this folder is loaded: no process, no listener, no capability.
+ *   agent2                           the runner of the job.assign receiver is the packaged agent2 (`visionhammer-agents`, profile local-agent) that runs
+ *                                    NEXT TO this agent. It needs, all of them: LOCAL_AGENT_PROTOCOL_V2=true, LOCAL_AGENT_JOBS=true, LOCAL_AGENT_LLM_KEY=true,
+ *                                    LOCAL_AGENT_LLM_CLIENT=true and LOCAL_AGENT_DLP_MODE=enforce (runtime.js refuses, and says so, when one is missing), plus
+ *                                    ONE way to reach agent2:
+ *                                      LOCAL_AGENT_AGENT2_CMD   this agent starts and supervises it (JSON array `["java","-jar","/opt/agent2.jar"]`, or a plain
+ *                                                               command split on spaces; never run through a shell)
+ *                                      LOCAL_AGENT_AGENT2_URL   agent2 already runs (sidecar / compose); loopback http only. Needs LOCAL_AGENT_AGENT2_TOKEN
+ *                                                               (the AGENT2_LOCAL_API_TOKEN it was started with, >= 32 chars) and LOCAL_AGENT_AGENT2_BRIDGE_PORT
+ *                                                               (the port of the loopback bridge; the sidecar's AGENT2_LLM_BASE_URL points at it)
+ *
+ * Every number is clamped: a bad value falls back to the default, never to "unlimited".
+ */
+export const RUNNER_FLAG = "LOCAL_AGENT_RUNNER";
+
+const KIB = 1024;
+const MIB = 1024 * KIB;
+
+function int(raw, def, min, max) {
+    const n = Number.parseInt(String(raw ?? ""), 10);
+    return Number.isFinite(n) && n >= min && n <= max ? n : def;
+}
+
+/** True when LOCAL_AGENT_RUNNER selects the agent2 runner. */
+export function agent2RunnerRequested(env = process.env) {
+    return String(env[RUNNER_FLAG] ?? "").trim().toLowerCase() === "agent2";
+}
+
+/** `["a","b"]` (JSON) or `a b` (split on whitespace). Never a shell string: no quoting, no expansion. */
+export function parseCommand(raw) {
+    const s = String(raw ?? "").trim();
+    if (!s) return null;
+    if (s.startsWith("[")) {
+        try {
+            const a = JSON.parse(s);
+            return Array.isArray(a) && a.length > 0 && a.length <= 64 && a.every((x) => typeof x === "string" && x.length > 0 && x.length <= 4096 && !x.includes("\0")) ? a : null;
+        } catch { return null; }
+    }
+    const parts = s.split(/\s+/).filter(Boolean);
+    return parts.length > 0 && parts.length <= 64 && parts.every((x) => !x.includes("\0")) ? parts : null;
+}
+
+const LOOPBACK_HOST = /^(127\.\d{1,3}\.\d{1,3}\.\d{1,3}|localhost|\[::1\])$/;
+
+/** Loopback `http://host:port` (no path, no credentials) or null. */
+export function loopbackBase(raw) {
+    try {
+        const u = new URL(String(raw ?? "").trim());
+        if (u.protocol !== "http:" || u.username || u.password || !LOOPBACK_HOST.test(u.hostname) || (u.pathname !== "/" && u.pathname !== "") || u.search || u.hash) return null;
+        return `http://${u.host}`;
+    } catch { return null; }
+}
+
+/** `https://host[:port][/base]` or loopback `http`, no credentials, no query. */
+export function relayBase(raw) {
+    try {
+        const u = new URL(String(raw ?? "").trim());
+        if (u.username || u.password || u.search || u.hash) return null;
+        if (u.protocol === "https:" || (u.protocol === "http:" && LOOPBACK_HOST.test(u.hostname))) return `${u.protocol}//${u.host}${u.pathname.replace(/\/+$/, "")}`;
+        return null;
+    } catch { return null; }
+}
+
+const PASSTHROUGH_NAME = /^[A-Z][A-Z0-9_]{1,63}$/;
+
+/**
+ * @returns {{enabled:false, error?:string} | {enabled:true, mode:"spawn"|"attach", ...}}
+ */
+export function resolveAgent2RunnerConfig(env = process.env, warn = console.warn) {
+    const raw = String(env[RUNNER_FLAG] ?? "").trim().toLowerCase();
+    if (raw !== "agent2") {
+        if (raw && !["smoke", "false", "0", "no", "off"].includes(raw)) warn(`[la-agent2] unrecognised ${RUNNER_FLAG} value; the agent2 runner stays off`);
+        return { enabled: false };
+    }
+    const cmd = parseCommand(env.LOCAL_AGENT_AGENT2_CMD);
+    const urlRaw = String(env.LOCAL_AGENT_AGENT2_URL ?? "").trim();
+    if (String(env.LOCAL_AGENT_AGENT2_CMD ?? "").trim() && !cmd) return { enabled: false, error: "LOCAL_AGENT_AGENT2_CMD is not a JSON array of strings or a plain command" };
+    if (cmd && urlRaw) return { enabled: false, error: "set LOCAL_AGENT_AGENT2_CMD (this agent starts agent2) OR LOCAL_AGENT_AGENT2_URL (agent2 already runs), not both" };
+    if (!cmd && !urlRaw) return { enabled: false, error: "LOCAL_AGENT_RUNNER=agent2 needs LOCAL_AGENT_AGENT2_CMD or LOCAL_AGENT_AGENT2_URL" };
+
+    const pass = [];
+    for (const n of String(env.LOCAL_AGENT_AGENT2_ENV_PASSTHROUGH ?? "").split(/[,\s]+/).filter(Boolean)) {
+        if (PASSTHROUGH_NAME.test(n)) pass.push(n); else warn("[la-agent2] LOCAL_AGENT_AGENT2_ENV_PASSTHROUGH: an entry is not a plain variable name; ignored");
+    }
+    // F3-08c (Edu 2026-11-04): the PolicyGate is asked over the v2 channel (`policy.check`), not over HTTP with a platform bearer. The old pair is ignored, loudly.
+    if (String(env.LOCAL_AGENT_AGENT2_POLICY_URL ?? "").trim() || String(env.LOCAL_AGENT_AGENT2_POLICY_TOKEN ?? "").trim()) {
+        warn("[la-agent2] LOCAL_AGENT_AGENT2_POLICY_URL / _POLICY_TOKEN are ignored: the PolicyGate is asked over the v2 channel (policy.check). No platform credential belongs on this machine");
+    }
+    const common = {
+        enabled: true,
+        passthrough: pass,
+        laUrl: loopbackBase(env.LOCAL_AGENT_AGENT2_LA_URL) || `http://127.0.0.1:${int(env.LOCAL_AGENT_PORT ?? env.PORT, 5055, 1, 65535)}`,   // this agent's own API: the bridge forwards agent2's /workspace calls to it, signed for agent2
+        maxWorkspaceBodyBytes: int(env.LOCAL_AGENT_AGENT2_WORKSPACE_MAX_BODY_BYTES, 16 * MIB, 4 * KIB, 256 * MIB),   // one /workspace request body (write_file, safe-patch, ...)
+        workspaceTimeoutMs: int(env.LOCAL_AGENT_AGENT2_WORKSPACE_TIMEOUT_MS, 15 * 60_000, 1_000, 3_600_000),     // one /workspace call (exec and tests can be long)
+        policyCheckTimeoutMs: int(env.LOCAL_AGENT_AGENT2_POLICY_TIMEOUT_MS, 10_000, 1_000, 60_000),             // policy.check -> policy.decision; none in time = DENY (the contract says 10 s)
+        pidFile: String(env.LOCAL_AGENT_AGENT2_PIDFILE ?? "").trim() || null,                                   // spawn mode: where the child's pid is kept so a restart of THIS agent can end an orphan (default: ~/.deepdebug/agent2-runner.pid)
+        bridgePort: int(env.LOCAL_AGENT_AGENT2_BRIDGE_PORT, 0, 0, 65535),                               // 0 = any free port (spawn mode); attach mode needs a fixed one
+        startTimeoutMs: int(env.LOCAL_AGENT_AGENT2_START_TIMEOUT_MS, 90_000, 1_000, 600_000),
+        healthIntervalMs: int(env.LOCAL_AGENT_AGENT2_HEALTH_INTERVAL_MS, 15_000, 100, 300_000),
+        healthFailures: int(env.LOCAL_AGENT_AGENT2_HEALTH_FAILURES, 3, 1, 20),                           // consecutive failed probes before the process is killed (spawn) / marked down (attach)
+        maxRestarts: int(env.LOCAL_AGENT_AGENT2_MAX_RESTARTS, 3, 0, 20),                                 // restarts inside restartWindowMs; beyond it agent2 is `unavailable` until the window passes
+        restartWindowMs: int(env.LOCAL_AGENT_AGENT2_RESTART_WINDOW_MS, 600_000, 1_000, 86_400_000),
+        restartBackoffMs: int(env.LOCAL_AGENT_AGENT2_RESTART_BACKOFF_MS, 1_000, 0, 60_000),
+        maxHeapMb: int(env.LOCAL_AGENT_AGENT2_MAX_HEAP_MB, 0, 0, 262_144),                              // spawn: JAVA_TOOL_OPTIONS=-Xmx<n>m (0 = leave it to the command)
+        maxRssBytes: int(env.LOCAL_AGENT_AGENT2_MAX_RSS_BYTES, 0, 0, Number.MAX_SAFE_INTEGER),          // spawn: killed (and restarted at the next job) above it; 0 = off
+        stopGraceMs: int(env.LOCAL_AGENT_AGENT2_STOP_GRACE_MS, 5_000, 100, 60_000),
+        requestTimeoutMs: int(env.LOCAL_AGENT_AGENT2_REQUEST_TIMEOUT_MS, 10_000, 100, 120_000),          // one call to the local API (not the event stream)
+        streamReconnects: int(env.LOCAL_AGENT_AGENT2_STREAM_RECONNECTS, 3, 0, 20),
+        maxBodyBytes: int(env.LOCAL_AGENT_AGENT2_MAX_BODY_BYTES, MIB, 4 * KIB, 8 * MIB),                 // bridge: one LLM request body
+        maxRequestTextBytes: int(env.LOCAL_AGENT_AGENT2_MAX_REQUEST_BYTES, 64 * KIB, KIB, MIB),          // the text handed to agent2 as the job's request
+        maxRefFileBytes: int(env.LOCAL_AGENT_AGENT2_MAX_REF_FILE_BYTES, 32 * KIB, KIB, MIB),
+        approvalWaitSeconds: int(env.LOCAL_AGENT_AGENT2_APPROVAL_WAIT_SECONDS, 0, 0, 3_600),            // 0 = agent2's own default (600)
+        cancelWaitMs: int(env.LOCAL_AGENT_AGENT2_CANCEL_WAIT_MS, 8_000, 1_000, 120_000),               // after a cancel/timeout: how long the runner waits for agent2 to report `cancelled` before it lets go of the job (keep it below LOCAL_AGENT_JOBS_CANCEL_GRACE_MS, 10 s: the next job needs agent2 free)
+        auditForwardRetries: int(env.LOCAL_AGENT_AGENT2_AUDIT_RETRIES, 10, 0, 100),
+        auditForwardRetryMs: int(env.LOCAL_AGENT_AGENT2_AUDIT_RETRY_MS, 500, 10, 10_000),
+    };
+    if (cmd) return { ...common, mode: "spawn", cmd, apiPort: int(env.LOCAL_AGENT_AGENT2_PORT, 8765, 1, 65535) };
+    const base = loopbackBase(urlRaw);
+    if (!base) return { enabled: false, error: "LOCAL_AGENT_AGENT2_URL must be a loopback http URL (agent2 runs next to this agent: same host, same pod or same network namespace)" };
+    const token = String(env.LOCAL_AGENT_AGENT2_TOKEN ?? "").trim();
+    if (token.length < 32) return { enabled: false, error: "LOCAL_AGENT_AGENT2_URL needs LOCAL_AGENT_AGENT2_TOKEN (>= 32 chars, the AGENT2_LOCAL_API_TOKEN agent2 was started with)" };
+    if (!common.bridgePort) return { enabled: false, error: "LOCAL_AGENT_AGENT2_URL needs LOCAL_AGENT_AGENT2_BRIDGE_PORT (the fixed loopback port agent2's AGENT2_LLM_BASE_URL and AGENT2_LA_CALLBACK_URL point at)" };
+    const callbackToken = String(env.LOCAL_AGENT_AGENT2_CALLBACK_TOKEN ?? "").trim();   // the AGENT2_LA_CALLBACK_TOKEN the sidecar was started with (the PolicyGate relay); without it the relay answers 401
+    return { ...common, mode: "attach", url: base, token, callbackToken: callbackToken.length >= 32 ? callbackToken : null };
+}

package/src/la-protocol-v2/jobs/agent2/frames.js

@@ -0,0 +1,61 @@
+/**
+ * frames.js - what the Local Agent accepts from agent2's event stream (`GET /local/v1/jobs/{id}/events`, F3-08b frames) before anything goes to the control
+ * plane. agent2 is a separate process: its frames are DATA, checked against the same closed shapes the contract has, from the same whitelists. A frame of
+ * another tenant or job is dropped (and counted); a field that is not in the whitelist is dropped; a value out of range is dropped. The result is a plain
+ * object that cannot carry text, a path, a model name or a prompt.
+ *
+ * One thing is kept for THIS agent only and never goes to the control plane (its schema is closed): the `approvalId` agent2 puts in `approval_requested` (PR #308), returned beside
+ * the payload as `approvalHint` so the approval decider can find the approval a later `approval.decision` is about.
+ *
+ * What is NOT taken from agent2: token counts and cost (this agent counts them itself, on the LLM bridge - agent2 is not the authority on its own spending).
+ */
+import { JOB_ERROR_CODES, resultPayload } from "../events.js";
+
+const STATES = new Set(["queued", "running", "waiting_approval", "succeeded", "failed", "cancelled"]);
+const TERMINAL = new Set(["succeeded", "failed", "cancelled"]);
+const PHASES = new Set(["init", "context", "plan", "edit", "validate", "pr", "done"]);
+const AUDIT_ACTIONS = new Set(["policy_decision", "approval_requested"]);   // the others (redaction, content_served, config_applied) are this agent's to say
+const AUDIT_DECISIONS = new Set(["allow", "deny", "require_human", "n/a"]);
+const SHORT_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const UUID_LOWER = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const isCount = (v) => Number.isSafeInteger(v) && v >= 0;
+
+/**
+ * @returns {null | {violation:"tenant"|"job"} | {type:"job.event"|"job.result"|"audit.event", seq:number, payload:object, approvalHint?:{approvalId:string, requestHash:string}}}
+ */
+export function normalizeFrame(frame, { tenantId, jobId }) {
+    if (!frame || typeof frame !== "object" || Array.isArray(frame)) return null;
+    if (!Number.isSafeInteger(frame.seq) || frame.seq < 1) return null;
+    if (typeof frame.tenantId === "string" && frame.tenantId.toLowerCase() !== String(tenantId).toLowerCase()) return { violation: "tenant" };
+    const p = frame.payload;
+    if (!p || typeof p !== "object" || Array.isArray(p)) return null;
+    if (frame.type === "job.event") {
+        if (p.jobId !== jobId) return { violation: "job" };
+        if (!STATES.has(p.state)) return null;
+        const out = { jobId, state: p.state };
+        if (PHASES.has(p.phase)) out.phase = p.phase;
+        if (Number.isInteger(p.iteration) && p.iteration >= 0 && p.iteration <= 1000) out.iteration = p.iteration;
+        for (const k of ["filesRead", "filesChanged"]) if (isCount(p[k])) out[k] = p[k];
+        if (JOB_ERROR_CODES.includes(p.errorCode)) out.errorCode = p.errorCode;
+        return { type: "job.event", seq: frame.seq, payload: out, terminal: TERMINAL.has(p.state) };
+    }
+    if (frame.type === "job.result") {
+        if (p.jobId !== jobId) return { violation: "job" };
+        const outcome = ["pr_opened", "no_change", "failed", "cancelled"].includes(p.outcome) ? p.outcome : null;
+        if (!outcome) return null;
+        const r = resultPayload(jobId, outcome, p);
+        return { type: "job.result", seq: frame.seq, payload: r };
+    }
+    if (frame.type === "audit.event") {
+        if (!AUDIT_ACTIONS.has(p.action)) return null;
+        const out = { action: p.action };
+        if (AUDIT_DECISIONS.has(p.decision)) out.decision = p.decision;
+        if (typeof p.actionType === "string" && SHORT_ID.test(p.actionType)) out.actionType = p.actionType;
+        if (typeof p.toolName === "string" && SHORT_ID.test(p.toolName)) out.toolName = p.toolName;
+        if (typeof p.requestHash === "string" && SHA256.test(p.requestHash)) out.requestHash = p.requestHash;
+        const hint = out.action === "approval_requested" && typeof p.approvalId === "string" && UUID_LOWER.test(p.approvalId) && out.requestHash ? { approvalHint: { approvalId: p.approvalId, requestHash: out.requestHash } } : {};
+        return { type: "audit.event", seq: frame.seq, payload: out, ...hint };
+    }
+    return null;
+}