deepdebug-local-agent 1.9.0 → 1.11.0

package/src/la-protocol-v2/jobs/agent2/policy-check.js

@@ -0,0 +1,170 @@
+/**
+ * policy-check.js - the PolicyGate relay of the agent2 bridge over the v2 channel (contract 2.2, F3-08c, Local Agent half).
+ *
+ * agent2 (profile local-agent, PR #308: LocalGatewayInternalClient) asks `POST <bridge>/agent2/cp-request {"type":"policy.check","payload":{...}}`: the payload is already the
+ * CLOSED `policy.check` payload of the contract (actionType, requestHash, toolName?, modelAlias?, incidentId?, jobId, repoRefs?). This module checks it again (agent2 is another
+ * process: its words are data), pins what this agent knows better than agent2 (the job, its repository, its model alias), sends it as a `policy.check` frame (LA -> CP, unsigned:
+ * the authenticated session IS the identity), waits for the CP's signed `policy.decision` (matched by the envelope `requestId` AND the `requestHash`) and gives agent2 back the
+ * decision payload as the contract defines it (`decision`, `reasonCode`, `shadow`, `approvalRequired`, `actionType`, `requestHash`, `policySnapshot.hash`, `effectiveMode`?).
+ *
+ * What this agent does NOT say: the tenant, the agent and the origin. The CP derives all three from the session (the closed schema would refuse them), so a
+ * process on this machine cannot claim another tenant or another origin, and there is no bearer of the platform on the customer's host. Anything else agent2 puts in the
+ * payload is dropped (counted). What goes in the frame: action type, tool name, the request hash agent2 computed (the one of its `approval_requested`), the job's repository as
+ * {provider, org, repo} (never a URL, a branch, a path, a command or a diff), the job id, the incident id and the model alias.
+ *
+ * Fail closed, always: no session / capability not negotiated (`ready` did not list `policy.check`) / a payload that is not a valid question / a job or repository that is not the
+ * running job's / frame refused / acked `rejected` / no decision in `timeoutMs` / a decision that is not a complete answer to what was asked = a DENY (an HTTP error agent2 turns
+ * into a DENY) with a reason code. A late or unknown decision is ignored and counted. Nothing of a request is logged or audited beyond ids hashed by the caller, counters and codes.
+ */
+import crypto from "node:crypto";
+
+const SHORT_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const NAME = /^[A-Za-z0-9_.-]{1,100}$/;
+const REASON = /^[a-z][a-z0-9_]{1,47}$/;
+const PROVIDERS = new Set(["github", "gitlab", "bitbucket", "azure", "other"]);
+const DECISIONS = new Set(["ALLOW", "DENY", "REQUIRE_HUMAN"]);
+const MODES = new Set(["observe", "assist", "autonomous", "none"]);
+const CHECK_KEYS = new Set(["actionType", "requestHash", "toolName", "repoRefs", "incidentId", "jobId", "modelAlias"]);
+const MAX_REPOS = 8;
+const MAX_PENDING = 16;
+
+const isShort = (v) => typeof v === "string" && SHORT_ID.test(v);
+const refOf = (r) => (r && typeof r === "object" && !Array.isArray(r) && PROVIDERS.has(r.provider) && typeof r.org === "string" && NAME.test(r.org) && typeof r.repo === "string" && NAME.test(r.repo)
+    ? { provider: r.provider, org: r.org, repo: r.repo } : null);
+const sameRef = (a, b) => a.provider === b.provider && a.org === b.org && a.repo === b.repo;
+
+/**
+ * agent2's `policy.check` payload -> the payload this agent sends. @returns {{payload:object, dropped:number}|{error:string, status:number}}
+ * Pinned from the running job (never from agent2): `jobId`, `repoRefs` (the job's repository; what agent2 names must BE that repository), `modelAlias`.
+ */
+export function normalizePolicyCheck(p, job) {
+    if (!p || typeof p !== "object" || Array.isArray(p)) return { error: "bad_request", status: 400 };
+    if (!isShort(p.actionType)) return { error: "bad_action_type", status: 400 };
+    if (typeof p.requestHash !== "string" || !SHA256.test(p.requestHash)) return { error: "bad_request_hash", status: 400 };
+    if (p.toolName !== undefined && !isShort(p.toolName)) return { error: "bad_tool_name", status: 400 };
+    if (p.incidentId !== undefined && !isShort(p.incidentId)) return { error: "bad_incident_id", status: 400 };
+    if (p.modelAlias !== undefined && !isShort(p.modelAlias)) return { error: "bad_model_alias", status: 400 };
+    if (p.jobId !== undefined && (typeof p.jobId !== "string" || p.jobId !== job.jobId)) return { error: "job_mismatch", status: 403 };
+    const jobRef = refOf(job.repoRef);
+    if (p.repoRefs !== undefined) {
+        if (!Array.isArray(p.repoRefs) || p.repoRefs.length < 1 || p.repoRefs.length > MAX_REPOS) return { error: "bad_repo_refs", status: 400 };
+        for (const r of p.repoRefs) {
+            const ref = refOf(r);
+            if (!ref || Object.keys(r).length !== 3) return { error: "bad_repo_refs", status: 400 };
+            if (!jobRef || !sameRef(ref, jobRef)) return { error: "repo_mismatch", status: 403 };   // a repository that is not the job's is not asked about here
+        }
+    }
+    let dropped = 0;
+    for (const k of Object.keys(p)) if (!CHECK_KEYS.has(k)) dropped++;
+    const incidentId = isShort(p.incidentId) ? p.incidentId : isShort(job.incidentId) ? job.incidentId : undefined;
+    return {
+        dropped,
+        payload: {
+            actionType: p.actionType, requestHash: p.requestHash,
+            ...(p.toolName ? { toolName: p.toolName } : {}),
+            ...(jobRef ? { repoRefs: [jobRef] } : {}),
+            ...(incidentId ? { incidentId } : {}),
+            ...(UUID.test(String(job.jobId)) ? { jobId: job.jobId } : {}),
+            ...(isShort(job.alias) ? { modelAlias: job.alias } : {}),
+        },
+    };
+}
+
+/** The signed `policy.decision` payload, checked once more as a complete and consistent answer to `asked`; null when it is not. Only the contract's fields come out. */
+export function decisionBody(p, asked) {
+    if (!p || typeof p !== "object" || !DECISIONS.has(p.decision)) return null;
+    if (typeof p.shadow !== "boolean" || typeof p.approvalRequired !== "boolean") return null;
+    if (p.approvalRequired !== (p.decision === "REQUIRE_HUMAN" && !p.shadow)) return null;   // the contract pins this equivalence
+    if (typeof p.reasonCode !== "string" || !REASON.test(p.reasonCode)) return null;
+    if (p.requestHash !== asked.requestHash || !isShort(p.actionType)) return null;
+    if (!p.policySnapshot || typeof p.policySnapshot.hash !== "string" || !SHA256.test(p.policySnapshot.hash)) return null;
+    return { decision: p.decision, reasonCode: p.reasonCode, shadow: p.shadow, approvalRequired: p.approvalRequired, actionType: p.actionType, requestHash: p.requestHash,
+        ...(MODES.has(p.effectiveMode) ? { effectiveMode: p.effectiveMode } : {}), policySnapshot: { hash: p.policySnapshot.hash } };
+}
+
+/**
+ * @param {object} o
+ * @param {()=>object|null} o.getSession  the v2 session (late-bound)
+ * @param {number} [o.timeoutMs]          10 s = `policyCheckTimeoutMs` of the contract
+ * @returns {{relay:Function, handleDecision:Function, stats:object, readonly pending:number, close:Function}}
+ */
+export function createPolicyCheckRelay({ getSession, timeoutMs = 10_000, log = console, now = Date.now, randomUuid = () => crypto.randomUUID(), audit = null }) {
+    const pending = new Map();   // requestId -> { requestHash, actionType, resolve, timer }
+    const stats = { sent: 0, decided: 0, allow: 0, deny: 0, requireHuman: 0, shadow: 0, unavailable: 0, late: 0, mismatch: 0, invalid: 0, dropped: 0, byReason: {} };
+    const note = (event, extra) => { try { audit?.record({ event, ...extra }); } catch { /* the audit never breaks the data path */ } };
+    const warn = (m) => (log.warn || log.log).call(log, m);
+    void now;
+
+    const unavailable = (reason, status = 503) => {
+        stats.unavailable++; stats.byReason[reason] = (stats.byReason[reason] || 0) + 1;
+        return { status, json: { decision: "DENY", shadow: false, approvalRequired: false, reasonCode: "gate_unavailable", error: reason } };
+    };
+
+    function count(p) {
+        stats.decided++;
+        if (p.decision === "ALLOW") stats.allow++; else if (p.decision === "DENY") stats.deny++; else stats.requireHuman++;
+        if (p.shadow) stats.shadow++;
+        stats.byReason[p.reasonCode] = (stats.byReason[p.reasonCode] || 0) + 1;
+    }
+
+    function settle(requestId, result) {
+        const e = pending.get(requestId);
+        if (!e) return;
+        pending.delete(requestId);
+        clearTimeout(e.timer);
+        e.resolve(result);
+    }
+
+    return {
+        stats,
+        get pending() { return pending.size; },
+        /** the bridge's policyRelay: ({check, job}) -> {status, json}; `check` = the payload of agent2's `policy.check`; never throws */
+        async relay({ check, job }) {
+            const session = getSession();
+            if (!session || session.state !== "ready" || typeof session.peerHas !== "function") return unavailable("no_session");
+            if (!session.peerHas("policy.check")) return unavailable("not_negotiated");   // the CP did not list the capability in `ready`: it would not answer
+            if (pending.size >= MAX_PENDING) return unavailable("busy", 429);
+            const built = normalizePolicyCheck(check, job);
+            if (built.error) return unavailable(built.error, built.status);
+            stats.dropped += built.dropped;
+            const requestId = randomUuid();
+            return new Promise((resolve) => {
+                const timer = setTimeout(() => { settle(requestId, unavailable("timeout", 504)); note("policy_check_timeout", {}); }, timeoutMs);
+                if (timer.unref) timer.unref();
+                pending.set(requestId, { requestHash: built.payload.requestHash, actionType: built.payload.actionType, resolve, timer });
+                session.enqueue("policy.check", built.payload, { requestId, workspaceId: job.workspaceId }).then((h) => {
+                    stats.sent++;
+                    // the CP may refuse the frame (ack `rejected`: a stray check of a CP with the feature off, say): that is the answer, no decision will come
+                    h.acked.catch((e) => { settle(requestId, unavailable(e && typeof e.code === "string" ? `rejected_${e.code}`.slice(0, 40) : "rejected")); });
+                }, (e) => settle(requestId, unavailable(e && typeof e.code === "string" ? `send_${e.code}`.slice(0, 40) : "send_failed")));
+            });
+        },
+        /** session handler of `policy.decision` (the session already checked schema, signature, tenant and sequence) */
+        handleDecision(ctx) {
+            const e = ctx.requestId ? pending.get(ctx.requestId) : null;
+            if (!e) { stats.late++; note("policy_decision_unknown", {}); return { accept: true }; }   // late (timed out already) or never asked: dropped, acked
+            const p = ctx.params;
+            if (p.requestHash !== e.requestHash) {   // not the answer to what was asked: never read as one
+                stats.mismatch++;
+                warn("[la-agent2] a policy.decision did not match its policy.check; the action is denied");
+                note("policy_decision_mismatch", {});
+                settle(ctx.requestId, unavailable("decision_mismatch", 502));
+                return { accept: true };
+            }
+            const body = decisionBody(p, e);
+            if (!body) {   // the session checked the schema; this is the second look: an answer that is not complete and consistent is never read as one
+                stats.invalid++;
+                note("policy_decision_invalid", {});
+                settle(ctx.requestId, unavailable("decision_invalid", 502));
+                return { accept: true };
+            }
+            count(body);
+            settle(ctx.requestId, { status: 200, json: body });
+            return { accept: true };
+        },
+        /** the session is gone: nothing will answer */
+        close() { for (const id of [...pending.keys()]) settle(id, unavailable("closed")); },
+    };
+}

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

@@ -0,0 +1,258 @@
+/**
+ * runner.js - the `agent2` Runner (F3-08c, Local Agent half): the packaged agent loop (agent2, profile local-agent) runs the job NEXT TO this agent, on the
+ * customer's side; the control plane only assigns the job and receives metadata. Selected with LOCAL_AGENT_RUNNER=agent2 (runtime.js); see
+ * docs/la-agent2-runner.md.
+ *
+ *   job.assign (+options) --> POST /local/v1/jobs of agent2         the workspace is the LOCAL one, the request text is the job's `inline` inputs (and the
+ *                                                                   allowed files named by `ref`), the "LLM key" agent2 receives is a per-job token of the
+ *                                                                   loopback bridge (bridge.js), never the virtual key
+ *   GET /local/v1/jobs/{id}/events (SSE) --> job.event / job.result  only whitelisted metadata (frames.js); phase/iteration/files go through the manager's
+ *                                                                   progress, so tokens and cost are THIS agent's (counted on the bridge), the result is
+ *                                                                   sent BEFORE the terminal event (manager), `waiting_approval` while a person decides
+ *   audit.event approval_requested --> the control plane             actionType, toolName, requestHash only; the command or file list stays in agent2
+ *   policy question (bridge) --> policy.check / policy.decision      over the v2 channel; the control plane derives tenant, agent and origin from the session (policy-check.js)
+ *   agent2's /workspace calls (bridge) --> this agent's /workspace   vouched for by this agent, so the signature check can stay on (bridge.js)
+ *   approval.decision --> POST /local/v1/approvals/{id}              after the token check (approvals.js)
+ *   job.cancel / timeout --> POST /local/v1/jobs/{id}/cancel
+ *
+ * One job at a time (agent2 refuses a second with 409; runtime.js forces LOCAL_AGENT_JOBS_MAX_CONCURRENT=1 for this runner). Failure codes only: agent2
+ * unavailable / crashed / stream lost = `infra`; agent2 refusing the job = `policy_denied` (403) or `unknown`.
+ *
+ * Never in a log, an audit, a stat or an error: the request text, a file, an answer, the per-job token, the API token, the workspace path. Ids are
+ * hashed (short), everything else is a counter or a code.
+ */
+import crypto from "node:crypto";
+import { createAudit, short } from "../../content-handlers/audit.js";
+import { ProtocolError } from "../../errors.js";
+import { createAgent2Bridge } from "./bridge.js";
+import { createAgent2Supervisor, Agent2UnavailableError } from "./supervisor.js";
+import { createApprovalDecider } from "./approvals.js";
+import { normalizeFrame } from "./frames.js";
+import { createPolicyCheckRelay } from "./policy-check.js";
+import { internalSignatureHeaders } from "../../../utils/request-signing.js";
+import { internalAuthHeaders, resolveAuthConfig } from "../../../utils/agent-auth.js";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const RETRYABLE = new Set(["rate_limited", "not_ready"]);
+const utf8 = new TextEncoder();
+const defaultSleep = (ms) => new Promise((r) => { const t = setTimeout(r, ms); if (t.unref) t.unref(); });
+
+/** agent2's API wants UUID workspace ids; the Local Agent's are free-form strings ("default", "ws-1"): a stable name-based UUID stands in for those. */
+export function workspaceUuid(tenantId, workspaceId) {
+    if (UUID.test(String(workspaceId))) return workspaceId;
+    const h = crypto.createHash("sha256").update(`vh-la-workspace:${tenantId}:${workspaceId}`).digest();
+    h[6] = (h[6] & 0x0f) | 0x50;   // version 5 layout
+    h[8] = (h[8] & 0x3f) | 0x80;
+    const x = h.subarray(0, 16).toString("hex");
+    return `${x.slice(0, 8)}-${x.slice(8, 12)}-${x.slice(12, 16)}-${x.slice(16, 20)}-${x.slice(20, 32)}`;
+}
+
+function truncateBytes(text, max) {
+    const b = utf8.encode(text);
+    if (b.length <= max) return text;
+    return new TextDecoder("utf-8", { fatal: false }).decode(b.subarray(0, max)).replace(/�+$/, "");
+}
+
+const HTTP_TO_JOB = Object.freeze({ 403: "policy_denied", 401: "infra", 409: "infra" });
+
+/**
+ * @param {object} o
+ * @param {object} o.config                          resolveAgent2RunnerConfig() (enabled)
+ * @param {string} o.tenantId
+ * @param {(workspaceId:string)=>string|null} o.resolveWorkspaceRoot
+ * @param {()=>object} o.getSession                  the v2 session (late-bound: the link does not exist yet when the runner is built)
+ * @param {{keys:Map}} o.signing                     the trusted platform keys (approval tokens)
+ * @param {Function} [o.policyRelay]                 ({body, job}) => Promise<{status, json}>; TEST SEAM. Default: the policy.check relay over the v2 session (no session / no answer = DENY)
+ */
+export function createAgent2Runner({ config, tenantId, resolveWorkspaceRoot, getSession, signing, env = process.env, log = console, policyRelay = null, fetchImpl, spawnImpl, now = Date.now, sleep = defaultSleep, rssOf, audit = null }) {
+    const tenant = String(tenantId).toLowerCase();
+    const auditor = audit || createAudit({ now });
+    const warn = (m) => (log.warn || log.log).call(log, m);
+    const note = (event, extra) => { try { auditor.record({ event, ...extra }); } catch { /* the audit never breaks the data path */ } };
+    const policyCheck = createPolicyCheckRelay({ getSession, timeoutMs: config.policyCheckTimeoutMs, log, now, audit: auditor });
+    const authCfg = resolveAuthConfig(env);
+    // the hop agent2 -> bridge -> this agent's own API: the internal marker of this process (what the WS tunnel uses for its own hops) + the signed identity it stands for
+    // (tenant and the running job's workspace) + X-Agent-Token when this agent has one. agent2 holds none of it.
+    const workspace = { url: config.laUrl, maxBodyBytes: config.maxWorkspaceBodyBytes, timeoutMs: config.workspaceTimeoutMs,
+        headers: ({ tenantId: t, workspaceId }) => ({ ...internalAuthHeaders(authCfg), ...internalSignatureHeaders(), "X-VH-Tenant-Id": t, "X-VH-Workspace-Id": workspaceId }) };
+    const bridge = createAgent2Bridge({ port: config.bridgePort, maxBodyBytes: config.maxBodyBytes, policyRelay: policyRelay || policyCheck.relay, tenantId: tenant, log, now, workspace });
+    const supervisor = createAgent2Supervisor({ config, tenantId: tenant, bridge, env, log, now, sleep, ...(fetchImpl ? { fetchImpl } : {}), ...(spawnImpl ? { spawnImpl } : {}), ...(rssOf ? { rssOf } : {}) });
+    const approvals = createApprovalDecider({ api: supervisor.api, signing, tenantId: tenant, now, audit: auditor, log });
+    const stats = { jobs: 0, ok: 0, failed: 0, cancelled: 0, busy: 0, framesDropped: 0, tenantViolations: 0, jobViolations: 0, auditForwarded: 0, auditGivenUp: 0, streamReconnects: 0, byCode: {} };
+    let active = null;   // { jobId, workspaceId }
+
+    async function forwardAudit(payload, workspaceId, jobShort) {
+        const session = getSession();
+        for (let i = 0; ; i++) {
+            try { const h = await session.enqueue("audit.event", payload, { workspaceId }); h.acked.catch(() => {}); stats.auditForwarded++; return; } catch (e) {
+                const code = e instanceof ProtocolError ? e.code : "internal";
+                if (!RETRYABLE.has(code) || i >= config.auditForwardRetries) { stats.auditGivenUp++; note("audit_forward_given_up", { jobShort, code, tries: i + 1 }); return; }
+                await sleep(config.auditForwardRetryMs);
+            }
+        }
+    }
+
+    async function requestText(job, ctx) {
+        const parts = [];
+        for (const i of job.inputs || []) {
+            if (typeof i.inline === "string") parts.push(i.inline);
+            else if (typeof i.ref === "string") {
+                const r = await ctx.readFile(i.ref, { maxBytes: config.maxRefFileBytes });
+                if (r && r.ok && typeof r.text === "string") parts.push(r.text);
+            }
+        }
+        let text = parts.join("\n\n").trim();
+        if (!text) text = `${job.kind === "implement" ? "Implement the requested change in this repository." : "Investigate and fix the reported problem in this repository."}${job.incidentRef?.id ? ` Incident ${job.incidentRef.id}.` : ""}`;
+        return truncateBytes(text, config.maxRequestTextBytes);
+    }
+
+    function jobBody(job, root, text, token) {
+        const o = job.options || {};
+        const options = {};
+        for (const k of ["ticketKey", "branchName", "createBranch", "createPullRequest", "dryRun", "maxIterations"]) if (o[k] !== undefined) options[k] = o[k];
+        return {
+            jobId: job.jobId, tenantId: tenant, workspaceId: workspaceUuid(tenant, job.workspaceId), kind: job.kind,
+            repoRef: job.repoRef, policy: job.policy, budget: { tokens: job.budget.tokens, seconds: job.budget.seconds },
+            llm: { alias: job.llm.alias, key: token },
+            ...(Object.keys(options).length ? { options } : {}),
+            ...(job.incidentRef?.id ? { incidentId: job.incidentRef.id } : {}),
+            request: { text }, workspacePath: root,
+        };
+    }
+
+    const failed = (errorCode) => { stats.failed++; stats.byCode[errorCode] = (stats.byCode[errorCode] || 0) + 1; return { outcome: "failed", errorCode }; };
+
+    async function start(job, ctx) {
+        stats.jobs++;
+        const jobShort = short(job.jobId);
+        if (active) { stats.busy++; note("job_refused_busy", { jobShort }); return failed("infra"); }
+        active = { jobId: job.jobId, workspaceId: job.workspaceId };
+        const evAc = new AbortController();
+        let proxyToken = null;
+        let cancelTimer = null;
+        let onDown = null;
+        let sendCancel = null;
+        try {
+            const root = resolveWorkspaceRoot(job.workspaceId);
+            if (!root) return failed("infra");
+            try {
+                const { baseUrl } = await bridge.listen();
+                if (config.mode === "attach" && config.callbackToken) bridge.setCallbackToken(config.callbackToken);
+                void baseUrl;
+                await supervisor.ensureReady();
+            } catch (e) {
+                note("agent2_unavailable", { jobShort, code: e instanceof Agent2UnavailableError ? e.code : "bridge", mode: config.mode });
+                return failed("infra");
+            }
+            if (ctx.signal.aborted) return { outcome: "cancelled" };
+            proxyToken = bridge.registerJob({ jobId: job.jobId, alias: job.llm.alias, llm: ctx.llm, workspaceId: job.workspaceId, incidentId: job.incidentRef?.id, root, repoRef: job.repoRef });
+            const text = await requestText(job, ctx);
+            try {
+                await supervisor.api.postJob(jobBody(job, root, text, proxyToken), ctx.signal);
+            } catch (e) {
+                note("agent2_job_refused", { jobShort, code: e && e.code, status: e && e.status, field: e && e.field });
+                if (ctx.signal.aborted) return { outcome: "cancelled" };
+                return failed(HTTP_TO_JOB[e && e.status] || (e && (e.status === 400 || e.status === 422) ? "unknown" : "infra"));
+            }
+            ctx.progress({ phase: "context" });
+
+            // ---- cancellation: the job's signal reaches agent2, which reports `cancelled` itself; we wait for that for a while, then let go
+            let cancelSent = false;
+            sendCancel = () => {
+                if (cancelSent) return;
+                cancelSent = true;
+                supervisor.api.cancel(job.jobId, "user").catch(() => {});
+                cancelTimer = setTimeout(() => evAc.abort(), config.cancelWaitMs);
+                if (cancelTimer.unref) cancelTimer.unref();
+            };
+            if (ctx.signal.aborted) sendCancel(); else ctx.signal.addEventListener("abort", sendCancel, { once: true });
+            active.sendCancel = sendCancel;
+            onDown = () => evAc.abort();
+            supervisor.on("down", onDown);   // agent2 died: nothing more will come
+
+            // ---- the event stream (replays from the start on a reconnect: skip what was handled)
+            const st = { lastSeq: 0, result: null, terminal: null, waiting: false, forwards: [] };
+            const handle = (raw) => {
+                const f = normalizeFrame(raw, { tenantId: tenant, jobId: job.jobId });
+                if (!f) { stats.framesDropped++; return; }
+                if (f.violation) { if (f.violation === "tenant") stats.tenantViolations++; else stats.jobViolations++; note("frame_dropped", { jobShort, why: f.violation }); return; }
+                if (f.seq <= st.lastSeq) return;
+                st.lastSeq = f.seq;
+                if (f.type === "job.event") {
+                    if (f.terminal) { st.terminal = f.payload; return; }
+                    const waiting = f.payload.state === "waiting_approval";
+                    st.waiting = waiting;
+                    ctx.progress({ ...(f.payload.phase ? { phase: f.payload.phase } : {}), ...(f.payload.iteration !== undefined ? { iteration: f.payload.iteration } : {}),
+                        ...(f.payload.filesRead !== undefined ? { filesRead: f.payload.filesRead } : {}), ...(f.payload.filesChanged !== undefined ? { filesChanged: f.payload.filesChanged } : {}), waitingApproval: waiting });
+                } else if (f.type === "job.result") {
+                    st.result = f.payload;
+                } else if (f.type === "audit.event") {
+                    if (f.payload.action === "approval_requested") {
+                        note("approval_requested", { jobShort, actionType: f.payload.actionType, toolName: f.payload.toolName, hinted: !!f.approvalHint });
+                        if (f.approvalHint) approvals.noteRequested(job.jobId, f.approvalHint);
+                    }
+                    st.forwards.push(forwardAudit(f.payload, job.workspaceId, jobShort));
+                }
+            };
+            let reconnects = 0;
+            for (;;) {
+                try { await supervisor.api.events(job.jobId, { signal: evAc.signal, onFrame: handle }); } catch (e) {
+                    if (evAc.signal.aborted || ctx.signal.aborted && (e && e.code === "cancelled")) break;
+                    if (supervisor.state !== "ready") break;
+                    if (e && (e.code === "not_found" || e.code === "unauthorized")) break;
+                }
+                if (st.result || evAc.signal.aborted) break;
+                if (supervisor.state !== "ready" || reconnects >= config.streamReconnects) break;
+                reconnects++; stats.streamReconnects++;
+                await sleep(250 * reconnects);
+            }
+            await Promise.allSettled(st.forwards);
+
+            // ---- the outcome
+            const r = st.result;
+            const t = st.terminal;
+            if (!r) {
+                if (ctx.signal.aborted) return { outcome: "cancelled" };
+                return failed("infra");
+            }
+            if (r.outcome === "failed") {
+                const code = t && t.errorCode && !["none", "cancelled"].includes(t.errorCode) ? t.errorCode : "unknown";
+                return failed(code);
+            }
+            if (r.outcome === "cancelled") { stats.cancelled++; return { outcome: "cancelled" }; }
+            stats.ok++;
+            return { outcome: r.outcome, ...(r.prUrl ? { prUrl: r.prUrl } : {}), ...(r.branch ? { branch: r.branch } : {}), ...(r.commitSha ? { commitSha: r.commitSha } : {}),
+                ...(r.filesChangedCount !== undefined ? { filesChangedCount: r.filesChangedCount } : {}), ...(r.diffSha256 ? { diffSha256: r.diffSha256 } : {}), ...(r.tests ? { tests: r.tests } : {}) };
+        } finally {
+            if (cancelTimer) clearTimeout(cancelTimer);
+            if (onDown) supervisor.off("down", onDown);
+            if (sendCancel) ctx.signal.removeEventListener("abort", sendCancel);
+            try { evAc.abort(); } catch { /* done */ }
+            approvals.forgetJob(job.jobId);
+            if (proxyToken) bridge.revokeJob(job.jobId);   // the per-job "key" stops working the moment the job is over
+            if (active && active.jobId === job.jobId) active = null;
+        }
+    }
+
+    return {
+        name: "agent2",
+        kinds: ["fix", "implement"],       // `quality` is not served by agent2 local mode (422 there): the manager acks it protocol_unsupported
+        needsLlm: true,
+        supportsOptions: true,
+        start,
+        cancel(jobId) {
+            if (active && active.jobId === jobId && active.sendCancel) active.sendCancel();
+        },
+        /** session handler of `approval.decision` (runtime.js registers it) */
+        async handleApprovalDecision(ctx) {
+            const p = ctx.params;
+            if (active && ctx.workspaceId && ctx.workspaceId !== active.workspaceId) { note("approval_decision_other_workspace", {}); return { reject: "unauthorized" }; }
+            return approvals.decide(p, active ? { jobId: active.jobId, workspaceId: active.workspaceId } : null);
+        },
+        /** session handler of `policy.decision` (runtime.js registers it): the answer to a policy.check the bridge asked */
+        handlePolicyDecision(ctx) { return policyCheck.handleDecision(ctx); },
+        async close() { policyCheck.close(); await Promise.allSettled([supervisor.stop(), bridge.close()]); },
+        stats, audit: auditor, bridge, supervisor, approvals, policyCheck,
+        get active() { return active ? active.jobId : null; },
+    };
+}