deepdebug-local-agent 1.9.0 → 1.11.0

package/src/la-protocol-v2/contract/job.assign.schema.json

@@ -184,6 +184,37 @@
               }
             ]
           }
+        },
+        "options": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Optional (revision 2.1, capability job.options): how to run the job. Absent = the Local Agent's own defaults. Sent only to a Local Agent that announced job.options; none of these fields is content (a ticket id, a branch name, flags and a counter).",
+          "properties": {
+            "ticketKey": {
+              "$ref": "defs.schema.json#/$defs/shortId"
+            },
+            "branchName": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 255,
+              "pattern": "^(?!.*\\.\\.)(?!.*//)(?!.*/\\.)(?!.*[./]$)(?!.*\\.lock(/|$))[A-Za-z0-9_][A-Za-z0-9_./-]{0,254}$"
+            },
+            "createBranch": {
+              "type": "boolean"
+            },
+            "createPullRequest": {
+              "type": "boolean"
+            },
+            "dryRun": {
+              "type": "boolean"
+            },
+            "maxIterations": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 100
+            }
+          },
+          "minProperties": 1
         }
       },
       "required": [

package/src/la-protocol-v2/contract/policy.check.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.visionhammer.io/la-protocol-v2/policy.check.schema.json",
+  "title": "LA protocol v2: policy.check (la->cp)",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "envelope.schema.json"
+    }
+  ],
+  "properties": {
+    "type": {
+      "const": "policy.check"
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "actionType": {
+          "$ref": "defs.schema.json#/$defs/shortId"
+        },
+        "toolName": {
+          "$ref": "defs.schema.json#/$defs/shortId"
+        },
+        "requestHash": {
+          "$ref": "defs.schema.json#/$defs/sha256"
+        },
+        "repoRefs": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 8,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "provider": {
+                "type": "string",
+                "enum": [
+                  "github",
+                  "gitlab",
+                  "bitbucket",
+                  "azure",
+                  "other"
+                ]
+              },
+              "org": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 100,
+                "pattern": "^[A-Za-z0-9_.-]{1,100}$"
+              },
+              "repo": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 100,
+                "pattern": "^[A-Za-z0-9_.-]{1,100}$"
+              }
+            },
+            "required": [
+              "provider",
+              "org",
+              "repo"
+            ]
+          }
+        },
+        "incidentId": {
+          "$ref": "defs.schema.json#/$defs/shortId"
+        },
+        "jobId": {
+          "$ref": "defs.schema.json#/$defs/uuid"
+        },
+        "modelAlias": {
+          "$ref": "defs.schema.json#/$defs/shortId"
+        }
+      },
+      "required": [
+        "actionType",
+        "requestHash"
+      ]
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "chunk": false,
+    "sig": false,
+    "paramsRaw": false,
+    "requestId": true,
+    "agentId": true
+  },
+  "required": [
+    "payload",
+    "requestId",
+    "agentId"
+  ]
+}

package/src/la-protocol-v2/contract/policy.decision.schema.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.visionhammer.io/la-protocol-v2/policy.decision.schema.json",
+  "title": "LA protocol v2: policy.decision (cp->la)",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "envelope.schema.json"
+    }
+  ],
+  "properties": {
+    "type": {
+      "const": "policy.decision"
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "decision": {
+          "type": "string",
+          "enum": [
+            "ALLOW",
+            "DENY",
+            "REQUIRE_HUMAN"
+          ]
+        },
+        "reasonCode": {
+          "type": "string",
+          "minLength": 2,
+          "maxLength": 48,
+          "pattern": "^[a-z][a-z0-9_]{1,47}$"
+        },
+        "shadow": {
+          "type": "boolean"
+        },
+        "approvalRequired": {
+          "type": "boolean"
+        },
+        "actionType": {
+          "$ref": "defs.schema.json#/$defs/shortId"
+        },
+        "effectiveMode": {
+          "$ref": "defs.schema.json#/$defs/operationMode"
+        },
+        "requestHash": {
+          "$ref": "defs.schema.json#/$defs/sha256"
+        },
+        "policySnapshot": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "hash": {
+              "$ref": "defs.schema.json#/$defs/sha256"
+            }
+          },
+          "required": [
+            "hash"
+          ]
+        }
+      },
+      "required": [
+        "decision",
+        "reasonCode",
+        "shadow",
+        "approvalRequired",
+        "actionType",
+        "requestHash",
+        "policySnapshot"
+      ],
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "decision": {
+                "const": "REQUIRE_HUMAN"
+              },
+              "shadow": {
+                "const": false
+              }
+            },
+            "required": [
+              "decision",
+              "shadow"
+            ]
+          },
+          "then": {
+            "properties": {
+              "approvalRequired": {
+                "const": true
+              }
+            }
+          },
+          "else": {
+            "properties": {
+              "approvalRequired": {
+                "const": false
+              }
+            }
+          }
+        }
+      ]
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "chunk": false,
+    "sig": true,
+    "paramsRaw": true,
+    "requestId": true
+  },
+  "required": [
+    "payload",
+    "sig",
+    "paramsRaw",
+    "requestId"
+  ]
+}

package/src/la-protocol-v2/jobs/agent2/api-client.js

@@ -0,0 +1,150 @@
+/**
+ * api-client.js - the Local Agent's client of agent2's local API (`/local/v1`, visionhammer-agents docs/runbooks/local-agent-api.md, PR #308).
+ *
+ * Loopback + `Authorization: Bearer <AGENT2_LOCAL_API_TOKEN>`. Errors are CODES (and, for a validation error, the NAME of the field): the body of a
+ * response is parsed, never echoed, never logged. The event stream (`GET /jobs/{id}/events`) is Server-Sent Events whose `frame` events carry the closed
+ * F3-08b frames (job.event / job.result / audit.event: ids, enums, counters).
+ */
+export class Agent2ApiError extends Error {
+    constructor(code, { status = 0, field } = {}) {
+        super(code);   // the message is the code, never free text from a response
+        this.name = "Agent2ApiError";
+        this.code = code;
+        this.status = status;
+        if (field) this.field = field;
+    }
+}
+
+const CODE = /^[a-z][a-z0-9_]{0,39}$/;
+const FIELD = /^[A-Za-z][A-Za-z0-9_.[\]]{0,59}$/;
+const MAX_JSON_BYTES = 1024 * 1024;
+const MAX_SSE_LINE_BYTES = 256 * 1024;
+
+async function readJson(res, maxBytes = MAX_JSON_BYTES) {
+    if (!res.body || typeof res.body.getReader !== "function") return null;
+    const reader = res.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        total += value.byteLength;
+        if (total > maxBytes) { try { await reader.cancel(); } catch { /* gone */ } throw new Agent2ApiError("response_too_large", { status: res.status }); }
+        chunks.push(Buffer.from(value.buffer, value.byteOffset, value.byteLength));
+    }
+    if (total === 0) return null;
+    try { return JSON.parse(Buffer.concat(chunks).toString("utf8")); } catch { return undefined; }
+}
+
+export function createAgent2Api({ getTarget, requestTimeoutMs = 10_000, fetchImpl = (...a) => globalThis.fetch(...a) }) {
+    /** getTarget() -> { baseUrl, token } of the agent2 that is up now (the token changes at every start of a supervised process). */
+    async function call(method, path, { body, signal, timeoutMs = requestTimeoutMs, auth = true } = {}) {
+        const { baseUrl, token } = getTarget();
+        const ac = new AbortController();
+        let timedOut = false;
+        const timer = setTimeout(() => { timedOut = true; ac.abort(); }, timeoutMs);
+        const onAbort = () => ac.abort();
+        if (signal) { if (signal.aborted) { clearTimeout(timer); throw new Agent2ApiError("cancelled"); } signal.addEventListener("abort", onAbort, { once: true }); }
+        try {
+            const res = await fetchImpl(`${baseUrl}/local/v1${path}`, {
+                method,
+                headers: { accept: "application/json", ...(auth ? { authorization: `Bearer ${token}` } : {}), ...(body !== undefined ? { "content-type": "application/json" } : {}) },
+                ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+                signal: ac.signal,
+            });
+            const json = await readJson(res);
+            if (res.status >= 200 && res.status < 300) return { status: res.status, json: json ?? {} };
+            const code = json && typeof json.error === "string" && CODE.test(json.error) ? json.error : res.status === 401 ? "unauthorized" : res.status === 404 ? "not_found" : res.status === 409 ? "conflict" : "http_error";
+            const field = json && typeof json.field === "string" && FIELD.test(json.field) ? json.field : undefined;
+            throw new Agent2ApiError(code, { status: res.status, field });
+        } catch (e) {
+            if (e instanceof Agent2ApiError) throw e;
+            throw new Agent2ApiError(signal?.aborted ? "cancelled" : timedOut ? "timeout" : "unreachable");
+        } finally {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+        }
+    }
+
+    return {
+        /** GET /health (no token). true when agent2 answers `status: up`. */
+        async health(signal) {
+            try { const r = await call("GET", "/health", { auth: false, timeoutMs: Math.min(requestTimeoutMs, 3_000), signal }); return !!r.json && r.json.status === "up"; } catch { return false; }
+        },
+        async postJob(body, signal) { return (await call("POST", "/jobs", { body, signal })).json; },
+        async cancel(jobId, reason = "user", signal) { return (await call("POST", `/jobs/${encodeURIComponent(jobId)}/cancel`, { body: { reason }, signal })).json; },
+        async jobState(jobId, signal) { return (await call("GET", `/jobs/${encodeURIComponent(jobId)}`, { signal })).json; },
+        /**
+         * Pending approvals of agent2 for ONE job: `GET /approvals?jobId=` -> [{approvalId, jobId, requestHash, actionType, toolName, expiresAt}] (an array, or
+         * `{approvals:[...]}`). The way this agent learns the id agent2 gave an approval it announced in `audit.event approval_requested` (which carries no id).
+         * Not in PR #308 as first merged (404 there): the caller falls back to the detail route.
+         */
+        async listApprovals({ jobId, signal } = {}) {
+            const q = jobId ? `?jobId=${encodeURIComponent(jobId)}` : "";
+            const j = (await call("GET", `/approvals${q}`, { signal })).json;
+            return Array.isArray(j) ? j : Array.isArray(j?.approvals) ? j.approvals : [];
+        },
+        async approvalDetail(approvalId, signal) { return (await call("GET", `/approvals/${encodeURIComponent(approvalId)}`, { signal })).json; },
+        async decide(approvalId, decision, decidedBy, signal) {
+            return (await call("POST", `/approvals/${encodeURIComponent(approvalId)}`, { body: { decision, ...(decidedBy ? { decidedBy } : {}) }, signal })).json;
+        },
+
+        /**
+         * Reads the SSE of a job: `onFrame(frame)` for every `frame` event (already JSON-parsed). Resolves `{ ended: true }` when the server ends the stream,
+         * rejects with Agent2ApiError on a non-200, a broken stream or an abort. The stream replays from the start: the caller skips what it already handled.
+         */
+        async events(jobId, { signal, onFrame, idleMs = 0 }) {
+            const { baseUrl, token } = getTarget();
+            const ac = new AbortController();
+            let idle = null;
+            const arm = () => { if (!idleMs) return; clearTimeout(idle); idle = setTimeout(() => ac.abort(), idleMs); };
+            const onAbort = () => ac.abort();
+            if (signal) { if (signal.aborted) throw new Agent2ApiError("cancelled"); signal.addEventListener("abort", onAbort, { once: true }); }
+            let res;
+            try {
+                arm();
+                res = await fetchImpl(`${baseUrl}/local/v1/jobs/${encodeURIComponent(jobId)}/events`, { method: "GET", headers: { accept: "text/event-stream", authorization: `Bearer ${token}` }, signal: ac.signal });
+                if (res.status !== 200) { try { await res.body?.cancel(); } catch { /* gone */ } throw new Agent2ApiError(res.status === 404 ? "not_found" : res.status === 401 ? "unauthorized" : "http_error", { status: res.status }); }
+                if (!res.body || typeof res.body.getReader !== "function") throw new Agent2ApiError("bad_response");
+                const reader = res.body.getReader();
+                const dec = new TextDecoder("utf-8");
+                let buf = "";
+                let event = "message";
+                let data = [];
+                const dispatch = () => {
+                    if (event === "frame" && data.length) {
+                        let frame;
+                        try { frame = JSON.parse(data.join("\n")); } catch { frame = undefined; }
+                        if (frame !== undefined) onFrame(frame);
+                    }
+                    event = "message"; data = [];
+                };
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done) break;
+                    arm();
+                    buf += dec.decode(value, { stream: true });
+                    if (buf.length > MAX_SSE_LINE_BYTES * 2) throw new Agent2ApiError("bad_response");
+                    let nl;
+                    while ((nl = buf.search(/\r?\n/)) >= 0) {
+                        const line = buf.slice(0, nl);
+                        buf = buf.slice(buf[nl] === "\r" ? nl + 2 : nl + 1);
+                        if (line === "") dispatch();
+                        else if (line.startsWith("event:")) event = line.slice(6).trim();
+                        else if (line.startsWith("data:")) data.push(line.slice(5).replace(/^ /, ""));
+                        // comments (`:`), `id:` and `retry:` are ignored
+                    }
+                }
+                if (buf.trim() === "" ) dispatch();
+                return { ended: true };
+            } catch (e) {
+                if (e instanceof Agent2ApiError) throw e;
+                throw new Agent2ApiError(signal?.aborted ? "cancelled" : "stream_broken");
+            } finally {
+                clearTimeout(idle);
+                signal?.removeEventListener("abort", onAbort);
+                try { ac.abort(); } catch { /* done */ }
+            }
+        },
+    };
+}

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

@@ -0,0 +1,114 @@
+/**
+ * approvals.js - `approval.decision` (CP -> LA, signed frame) to `POST /local/v1/approvals/{id}` of agent2 (F3-08c, ADR-0010, Local Agent half).
+ *
+ * The control plane decided (a person clicked); this agent only passes the decision on AFTER checking, on top of the session's signature check of the
+ * frame, the `vhapr1` token of the payload (src/utils/approval-token.js: Ed25519 over the platform key, tenant, workspace, <= 15 min, single use):
+ *   - the token must be bound to THIS approval: its `sha256` is the SHA-256 of the approval's `requestHash` (the hash agent2 announced in
+ *     `audit.event approval_requested`) - a token minted for another action does not approve this one;
+ *   - the approval must belong to the job running now;
+ *   - the token is consumed only after agent2 took the decision (a transient failure can be retried by the control plane with the same token).
+ * Nothing is decided on a doubt: an unknown approval, a bad token or an unreachable agent2 leaves agent2 waiting, and agent2's own window then refuses
+ * (no decision = refusal, the tool never runs).
+ *
+ * How the approval is found: the id in `approval.decision` is the control plane's, and `audit.event approval_requested` carries no id. agent2's pending list FOR THIS JOB
+ * (`GET /local/v1/approvals?jobId=`) gives the candidates ({approvalId, requestHash, ...}) and the token picks the one it is bound to (its `sha256` is the SHA-256 of the
+ * candidate's requestHash). An agent2 without the list (404) is asked for the CP's id directly (`GET /approvals/{id}`: the case where the two ids are the same). Without
+ * either, the decision cannot be delivered and the approval expires as a refusal.
+ */
+import crypto from "node:crypto";
+import { verifyApprovalToken } from "../../../utils/approval-token.js";
+
+const SHORT_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/;
+const DIFFERENT_COMMAND = "approval token is for a different command";
+const REMEMBER = 4096;
+
+/** What the token's `sha256` must equal: the SHA-256 of this string. (Proposal for the gateway: mint with `command = requestHash`.) */
+export const approvalSubject = (requestHash) => String(requestHash ?? "");
+
+export function createApprovalDecider({ api, signing, tenantId, now = Date.now, audit = null, log = console }) {
+    const hints = new Map();        // jobId -> Map(approvalId -> requestHash): what agent2's own `approval_requested` frames told us (this agent only; the control plane never sees the id)
+    const decided = new Map();      // approvalId -> true (bounded): a repeated frame is acked and not delivered twice
+    const usedJti = new Set();
+    const stats = { received: 0, delivered: 0, duplicate: 0, noJob: 0, unmatched: 0, unauthorized: 0, deliveryFailed: 0 };
+    const note = (event, extra) => { try { audit?.record({ event, ...extra }); } catch { /* the audit never breaks the data path */ } };
+    const remember = (set, v) => { set.add ? set.add(v) : set.set(v, true); const m = set; if (m.size > REMEMBER) m.delete(m.keys().next().value); };
+    const sh = (v) => crypto.createHash("sha256").update(String(v ?? "")).digest("hex").slice(0, 16);
+
+    return {
+        stats,
+        /** agent2 announced an approval (frame `audit.event approval_requested` with its id): remembered for this job, bounded. Only a fallback: the pending list stays the authority. */
+        noteRequested(jobId, { approvalId, requestHash }) {
+            let m = hints.get(jobId);
+            if (!m) { m = new Map(); hints.set(jobId, m); if (hints.size > 8) hints.delete(hints.keys().next().value); }
+            m.set(approvalId, requestHash);
+            if (m.size > 32) m.delete(m.keys().next().value);
+        },
+        forgetJob(jobId) { hints.delete(jobId); },
+        /**
+         * @param {{approvalId:string, decision:"approved"|"denied", token:string}} p   the validated payload (the session checked schema and signature)
+         * @param {{jobId:string, workspaceId:string}|null} active                         the job running now
+         * @returns {Promise<{accept:true}|{reject:string}>}
+         */
+        async decide(p, active) {
+            stats.received++;
+            const idShort = sh(p.approvalId);
+            if (decided.has(p.approvalId)) { stats.duplicate++; note("approval_decision_duplicate", { approvalShort: idShort }); return { accept: true }; }
+            if (!active) { stats.noJob++; note("approval_decision_no_job", { approvalShort: idShort }); return { accept: true }; }   // nothing waits for it: acked, no oracle
+            // The id in `approval.decision` is the control plane's; agent2 gave the approval its own. The pending list of THIS job (`GET /approvals?jobId=`) is how this agent
+            // learns the candidates; the vhapr1 token then picks the one it is bound to. An agent2 without the list (404) is asked for the CP's id directly (the case where
+            // the two ids are the same).
+            let candidates = [];
+            let listed = false;   // agent2 told us what is pending (an empty answer is "nothing waits": the approval is gone)
+            try {
+                candidates = await api.listApprovals({ jobId: active.jobId });
+                listed = true;
+            } catch (e) {
+                if (e && (e.status === 404 || e.code === "not_found" || e.code === "http_error")) {
+                    const told = hints.get(active.jobId);
+                    if (told && told.size > 0) {
+                        // no list in this agent2: the approvals it announced for this job (its own ids); the token below still has to match one, and agent2 refuses a decision on one that is gone
+                        candidates = [...told].map(([approvalId, requestHash]) => ({ approvalId, requestHash, jobId: active.jobId }));
+                        listed = true;
+                    } else try {
+                        const d = await api.approvalDetail(p.approvalId);
+                        if (d && typeof d === "object") { candidates = [d]; listed = true; }
+                    } catch (e2) {
+                        if (!(e2 && (e2.status === 404 || e2.code === "not_found"))) { stats.deliveryFailed++; note("approval_decision_failed", { approvalShort: idShort, code: e2 && e2.code }); return { reject: "rate_limited" }; }
+                    }
+                } else { stats.deliveryFailed++; note("approval_decision_failed", { approvalShort: idShort, code: e && e.code }); return { reject: "rate_limited" }; }
+            }
+            candidates = candidates.filter((c) => c && typeof c.approvalId === "string" && typeof c.requestHash === "string" && (c.jobId === undefined || c.jobId === active.jobId));
+            if (candidates.length === 0) {
+                stats.unmatched++;
+                note("approval_decision_unmatched", { approvalShort: idShort, listed });
+                // listed and empty: nothing waits any more (decided, expired, job over) - acked. Not listed: this agent could not even ask agent2
+                // (no `GET /approvals` there): the decision is NOT delivered and the control plane is told, instead of a silent "accepted"
+                return listed ? { accept: true } : { reject: "internal" };
+            }
+            let match = null;
+            let verdict = null;
+            for (const c of candidates) {
+                const v = verifyApprovalToken(p.token, { subject: approvalSubject(c.requestHash), keys: signing.keys, identity: { tenantId, workspaceId: active.workspaceId }, requestTenantId: tenantId, nonces: null, now });
+                if (v.ok) { match = c; verdict = v; break; }
+                if (v.reason !== DIFFERENT_COMMAND) { stats.unauthorized++; note("approval_decision_unauthorized", { approvalShort: idShort, reason: String(v.reason).replace(/'[^']*'/g, "'?'").slice(0, 60) }); return { reject: "unauthorized" }; }
+            }
+            if (!match) { stats.unauthorized++; note("approval_decision_unauthorized", { approvalShort: idShort, reason: "different command" }); return { reject: "unauthorized" }; }
+            if (usedJti.has(verdict.jti)) { stats.unauthorized++; note("approval_decision_unauthorized", { approvalShort: idShort, reason: "already used" }); return { reject: "unauthorized" }; }
+            const by = typeof verdict.approvedBy === "string" && SHORT_ID.test(verdict.approvedBy) ? verdict.approvedBy : undefined;
+            try {
+                await api.decide(match.approvalId, p.decision, by);
+            } catch (e) {
+                // already decided / gone (the window ran out): nothing more to do, and the token is spent either way
+                if (e && (e.status === 404 || e.status === 409 || e.code === "already_decided" || e.code === "unknown_approval")) { remember(usedJti, verdict.jti); remember(decided, p.approvalId); note("approval_decision_late", { approvalShort: idShort, code: e.code }); return { accept: true }; }
+                stats.deliveryFailed++;
+                note("approval_decision_failed", { approvalShort: idShort, code: e && e.code });
+                return { reject: "rate_limited" };   // the token was not consumed: the control plane may send it again
+            }
+            remember(usedJti, verdict.jti);
+            remember(decided, p.approvalId);
+            stats.delivered++;
+            note("approval_decision_delivered", { approvalShort: idShort, decision: p.decision });
+            return { accept: true };
+        },
+    };
+}