deepdebug-local-agent 1.10.0 → 1.12.0

package/src/la-protocol-v2/jobs/workspace-materializer.js

@@ -0,0 +1,244 @@
+/**
+ * workspace-materializer.js - LA-2 (ADR-0014 Design A, chat on the Local Agent). A `job.assign` names a workspace by id and a `repoRef`
+ * {provider, org, repo, branch}. When this agent does not serve that workspace yet, it can CLONE IT ITSELF, into its own cache, with the customer's OWN
+ * credentials (credential helper / ssh-agent / GH_TOKEN of this process, or a local token file read by GIT_ASKPASS). The platform never sends a token and
+ * never sees one; it only names the repository.
+ *
+ *   LOCAL_AGENT_JOBS_AUTO_WORKSPACE=true   (default OFF) turns it on. Needs LOCAL_AGENT_JOBS (the manager that calls it).
+ *   LOCAL_AGENT_ALLOWED_REPOS              `host/org/repo` or `host/org/*`, separated by comma/space/newline; LOCAL_AGENT_ALLOWED_REPOS_FILE adds a file
+ *                                          (one entry per line, `#` comments). ONLY the customer decides this list: it is never taken from the control plane.
+ *                                          Empty = nothing is materialized (fail closed).
+ *   LOCAL_AGENT_WORKSPACE_CACHE            where clones live (default ~/.deepdebug/workspaces)
+ *   LOCAL_AGENT_GIT_TOKEN_FILE             optional: a file with a token that a GIT_ASKPASS script cats (POSIX). Absent = the machine's own helper/ssh.
+ *   LOCAL_AGENT_WORKSPACE_CLONE_TIMEOUT_MS (default 300000), LOCAL_AGENT_WORKSPACE_MAX_BYTES (default 2 GiB, a clone above it is removed)
+ *
+ * Rules: one clone at a time on this agent and one clone per workspace id (a second job for the same id awaits the first); URL built here from the closed
+ * provider list and the validated org/repo (never from outside text, never with credentials); `execFile` with an array; the tenant is the SESSION's
+ * (wsManager.open(.., {tenantId})); a directory of another tenant, a symlink in the cache or a foreign directory is refused; nothing of git's stderr, of a path
+ * or of the allowlist is thrown, logged or audited (codes and short hashes only). An existing clone is fetched and fast-forwarded only when clean: local work
+ * of a previous job is never reset.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { readWorkspaceSidecar, isSafeToRemove } from "../../utils/open-gate.js";
+import { short } from "../content-handlers/audit.js";
+import { gitEnv, ensureAskpassScript, runGit } from "./git-exec.js";
+
+export const MATERIALIZE_FLAG = "LOCAL_AGENT_JOBS_AUTO_WORKSPACE";
+const TRUE = new Set(["true", "1", "yes", "on"]);
+const MIB = 1024 * 1024;
+const WS_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+const SEG = /^[A-Za-z0-9_.-]{1,100}$/;
+const BRANCH = /^[A-Za-z0-9_./-]{1,255}$/;
+const HOSTS = Object.freeze({ github: "github.com", gitlab: "gitlab.com", bitbucket: "bitbucket.org" });   // azure/other: no known host, not materializable
+const ENTRY = /^([a-z0-9.-]+)\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+|\*)$/;
+
+function int(raw, def, min, max) { const n = Number.parseInt(String(raw ?? ""), 10); return Number.isFinite(n) && n >= min && n <= max ? n : def; }
+
+/** An error with a code and the job error code `infra`; the message is generic (the manager never reads it anyway). */
+export class MaterializeError extends Error {
+    constructor(code) { super(`workspace not available (${code})`); this.name = "MaterializeError"; this.code = code; this.jobErrorCode = "infra"; }
+}
+
+/** Parses the allowlist text. Returns { exact:Set<"host/org/repo">, orgs:Set<"host/org">, invalid:number } (lower case). */
+export function parseAllowlist(text) {
+    const exact = new Set();
+    const orgs = new Set();
+    let invalid = 0;
+    for (const raw of String(text || "").split(/[\s,]+/)) {
+        const e = raw.trim().toLowerCase();
+        if (!e || e.startsWith("#")) continue;
+        const m = ENTRY.exec(e);
+        if (!m || m[2] === "." || m[2] === ".." || m[3] === "." || m[3] === "..") { invalid++; continue; }
+        if (m[3] === "*") orgs.add(`${m[1]}/${m[2]}`); else exact.add(`${m[1]}/${m[2]}/${m[3]}`);
+    }
+    return { exact, orgs, invalid };
+}
+
+function readAllowlistText(env) {
+    let text = String(env.LOCAL_AGENT_ALLOWED_REPOS ?? "");
+    const file = String(env.LOCAL_AGENT_ALLOWED_REPOS_FILE ?? "").trim();
+    if (file) {
+        try { text += "\n" + fs.readFileSync(file, "utf8").split(/\r?\n/).filter((l) => !l.trim().startsWith("#")).join("\n"); } catch { /* unreadable file = no entries from it (fail closed) */ }
+    }
+    return text;
+}
+
+/** { enabled:false } unless LOCAL_AGENT_JOBS_AUTO_WORKSPACE is true. */
+export function resolveMaterializeConfig(env = process.env, warn = console.warn) {
+    if (!TRUE.has(String(env[MATERIALIZE_FLAG] ?? "").trim().toLowerCase())) return { enabled: false };
+    const allow = parseAllowlist(readAllowlistText(env));
+    if (allow.invalid) warn(`[la-workspace] ${allow.invalid} invalid LOCAL_AGENT_ALLOWED_REPOS entr${allow.invalid === 1 ? "y" : "ies"} ignored`);
+    if (!allow.exact.size && !allow.orgs.size) warn("[la-workspace] LOCAL_AGENT_ALLOWED_REPOS is empty: no workspace will be materialized");
+    const tokenFile = String(env.LOCAL_AGENT_GIT_TOKEN_FILE ?? "").trim() || null;
+    return {
+        enabled: true,
+        allow,
+        cacheDir: path.resolve(String(env.LOCAL_AGENT_WORKSPACE_CACHE ?? "").trim() || path.join(os.homedir(), ".deepdebug", "workspaces")),
+        tokenFile: tokenFile ? path.resolve(tokenFile) : null,
+        cloneTimeoutMs: int(env.LOCAL_AGENT_WORKSPACE_CLONE_TIMEOUT_MS, 300_000, 1_000, 3_600_000),
+        gitTimeoutMs: int(env.LOCAL_AGENT_WORKSPACE_GIT_TIMEOUT_MS, 60_000, 1_000, 600_000),
+        maxBytes: int(env.LOCAL_AGENT_WORKSPACE_MAX_BYTES, 2048 * MIB, MIB, 64 * 1024 * MIB),
+        depth: int(env.LOCAL_AGENT_WORKSPACE_CLONE_DEPTH, 50, 1, 10_000),
+    };
+}
+
+/** Validates a repoRef and builds { host, org, repo, branch, key, url } or null. The url has NO credentials and is only https. */
+export function repoTarget(repoRef) {
+    if (!repoRef || typeof repoRef !== "object") return null;
+    const host = HOSTS[repoRef.provider];
+    const { org, repo, branch } = repoRef;
+    if (!host || typeof org !== "string" || typeof repo !== "string" || typeof branch !== "string") return null;
+    if (!SEG.test(org) || !SEG.test(repo) || org === "." || org === ".." || repo === "." || repo === "..") return null;
+    if (!BRANCH.test(branch) || branch.startsWith("-") || branch.startsWith("/") || branch.endsWith("/") || branch.endsWith(".lock") || branch.includes("..") || branch.includes("//") || branch.includes("/.")) return null;
+    return { host, org, repo, branch, key: `${host}/${org.toLowerCase()}/${repo.toLowerCase()}`, orgKey: `${host}/${org.toLowerCase()}`, url: `https://${host}/${org}/${repo}.git` };
+}
+
+/** Bounded, symlink-safe size of a directory (lstat, no following). Returns bytes counted up to `limit`+1. */
+function dirBytes(dir, limit) {
+    let total = 0;
+    const stack = [dir];
+    while (stack.length) {
+        const d = stack.pop();
+        let ents;
+        try { ents = fs.readdirSync(d, { withFileTypes: true }); } catch { continue; }
+        for (const e of ents) {
+            const p = path.join(d, e.name);
+            if (e.isDirectory()) stack.push(p);
+            else { try { total += fs.lstatSync(p).size; } catch { /* vanished */ } }
+            if (total > limit) return total;
+        }
+    }
+    return total;
+}
+
+/**
+ * @param {object} o
+ * @param {object} o.config         resolveMaterializeConfig() (enabled)
+ * @param {string} o.tenantId       the SESSION's tenant
+ * @param {object} o.wsManager      open(id, dir, {tenantId}), list()
+ * @param {object} [o.audit]        { record(entry) } - codes and short hashes only
+ * @param {object} [o.env]
+ * @param {object} [o.seams]        TESTS ONLY: { remoteUrl(target) => string, gitConfig: string[] (e.g. protocol.file.allow=always), runGit }
+ */
+export function createWorkspaceMaterializer({ config, tenantId, wsManager, audit: auditIn = null, env = process.env, log = console, seams = {} }) {
+    let audit = auditIn;
+    const tenant = String(tenantId).toLowerCase();
+    const git = seams.runGit || runGit;
+    const stats = { admitted: 0, refused: {}, cloned: 0, reused: 0, failed: {} };
+    const inflight = new Map();   // workspaceId -> Promise<{root}>
+    let chain = Promise.resolve();   // one clone/fetch at a time on this agent
+    const note = (event, extra) => { try { audit?.record({ event, ...extra }); } catch { /* the audit never breaks the data path */ } };
+    const refuse = (why, extra) => { stats.refused[why] = (stats.refused[why] || 0) + 1; note("workspace_refused", { why, ...extra }); return null; };
+
+    const cacheReal = () => { try { fs.mkdirSync(config.cacheDir, { recursive: true, mode: 0o700 }); return fs.realpathSync(config.cacheDir); } catch { return null; } };
+    const allowed = (t) => config.allow.exact.has(t.key) || config.allow.orgs.has(t.orgKey);
+    const tokenUsable = () => { if (!config.tokenFile) return true; try { fs.accessSync(config.tokenFile, fs.constants.R_OK); return fs.statSync(config.tokenFile).isFile(); } catch { return false; } };
+    const listed = (id) => (wsManager?.list?.() || []).find((w) => w && w.id === id);
+
+    /**
+     * Synchronous admission (inside the 5 s ack): may this workspace be materialized for this job? true = the manager accepts the job and calls ensure()
+     * from inside it. false = the job is refused `unauthorized` with an audit CODE. Never touches the network.
+     */
+    function admit(workspaceId, repoRef) {
+        const base = { workspaceShort: short(workspaceId) };
+        if (typeof workspaceId !== "string" || !WS_ID.test(workspaceId) || workspaceId === "default") return !!refuse("bad_workspace_id", base);
+        if (listed(workspaceId)) return !!refuse("already_open_elsewhere", base);   // served (the resolver decided) or another tenant's: never replaced
+        const t = repoTarget(repoRef);
+        if (!t) return !!refuse("bad_repo_ref", base);
+        if (!allowed(t)) return !!refuse("repo_not_allowed", { ...base, repoShort: short(t.key) });
+        if (!tokenUsable()) return !!refuse("credential_unavailable", base);   // a configured token file that cannot be read: a clear refusal now, not a failed clone later
+        const root = cacheReal();
+        if (!root) return !!refuse("cache_unavailable", base);
+        const dir = path.join(root, workspaceId);
+        let st = null;
+        try { st = fs.lstatSync(dir); } catch { st = null; }
+        if (st) {
+            if (st.isSymbolicLink() || !st.isDirectory()) return !!refuse("cache_entry_unsafe", base);
+            const sc = readWorkspaceSidecar(dir);
+            if (!sc || sc.id !== workspaceId) return !!refuse("foreign_directory", base);
+            if (!sc.tenantId || sc.tenantId.toLowerCase() !== tenant) return !!refuse("tenant_mismatch", base);
+        }
+        stats.admitted++;
+        return true;
+    }
+
+    async function doEnsure(workspaceId, repoRef, signal) {
+        const t = repoTarget(repoRef);
+        const ws = short(workspaceId);
+        const fail = (code) => { stats.failed[code] = (stats.failed[code] || 0) + 1; note("workspace_failed", { code, workspaceShort: ws }); throw new MaterializeError(code); };
+        if (!t || !allowed(t) || !WS_ID.test(workspaceId)) fail("repo_not_allowed");   // defence in depth: ensure() re-checks what admit() checked
+        const root = cacheReal();
+        if (!root) fail("cache_unavailable");
+        const dir = path.join(root, workspaceId);
+        if (!isSafeToRemove(root, dir)) fail("cache_entry_unsafe");
+        let askpass = null;
+        if (config.tokenFile) {
+            if (!tokenUsable()) fail("credential_unavailable");
+            try { askpass = ensureAskpassScript(root); } catch { fail("cache_unavailable"); }
+        }
+        const env2 = gitEnv(env, { askpass, tokenFile: config.tokenFile });
+        const extraConfig = seams.gitConfig || [];
+        const remote = seams.remoteUrl ? seams.remoteUrl(t) : t.url;
+        let st = null;
+        try { st = fs.lstatSync(dir); } catch { st = null; }
+        if (st) {
+            if (st.isSymbolicLink() || !st.isDirectory()) fail("cache_entry_unsafe");
+            const sc = readWorkspaceSidecar(dir);
+            if (!sc || sc.id !== workspaceId) fail("foreign_directory");
+            if (!sc.tenantId || sc.tenantId.toLowerCase() !== tenant) fail("tenant_mismatch");
+            // existing clone: fetch the branch; move only a CLEAN tree (the previous job's local work is never reset)
+            const f = await git(["fetch", "--depth", String(config.depth), "--no-tags", "--", "origin", t.branch], { cwd: dir, env: env2, timeoutMs: config.gitTimeoutMs, signal, extraConfig });
+            if (!f.ok) fail(f.code === "failed" ? "fetch_failed" : f.code);
+            const dirty = await git(["status", "--porcelain"], { cwd: dir, env: env2, timeoutMs: config.gitTimeoutMs, signal, extraConfig });
+            if (dirty.ok && dirty.stdout.trim() === "") {
+                const co = await git(["checkout", "--quiet", t.branch, "--"], { cwd: dir, env: env2, timeoutMs: config.gitTimeoutMs, signal, extraConfig });
+                if (co.ok) await git(["merge", "--ff-only", "--quiet", "FETCH_HEAD"], { cwd: dir, env: env2, timeoutMs: config.gitTimeoutMs, signal, extraConfig });
+            } else note("workspace_kept_dirty", { workspaceShort: ws });
+            stats.reused++;
+        } else {
+            const tmp = path.join(root, `.tmp-${workspaceId}-${crypto.randomBytes(4).toString("hex")}`);
+            let ok = false;
+            try {
+                const c = await git(["clone", "--branch", t.branch, "--single-branch", "--depth", String(config.depth), "--no-tags", "--", remote, tmp], { env: env2, cwd: root, timeoutMs: config.cloneTimeoutMs, signal, extraConfig });
+                if (!c.ok) fail(c.code === "failed" ? "clone_failed" : c.code);
+                if (dirBytes(tmp, config.maxBytes) > config.maxBytes) fail("too_large");
+                // the remote of the clone is the credential-free URL we built; nothing else was ever written to its config
+                fs.renameSync(tmp, dir);
+                ok = true;
+            } finally {
+                if (!ok) { try { if (isSafeToRemove(root, tmp)) fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* best effort */ } }
+            }
+            stats.cloned++;
+        }
+        try { await wsManager.open(workspaceId, dir, { tenantId: tenant }); } catch {
+            if (!st) { try { if (isSafeToRemove(root, dir)) fs.rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ } }   // a fresh clone that could not be registered must not stay as a "foreign" directory
+            fail("open_failed");
+        }
+        note("workspace_ready", { workspaceShort: ws, repoShort: short(t.key), reused: !!st });
+        return { root: dir };
+    }
+
+    return {
+        stats, config,
+        /** The job manager hands its audit in (one trail for jobs and workspaces). */
+        bindAudit(a) { if (!audit) audit = a; },
+        admit,
+        /**
+         * Clone (or refresh) and register the workspace. Called by the job manager from inside the job; resolves { root } or throws MaterializeError (job `failed`, `infra`).
+         * One clone at a time; a second call for the same id shares the first one's promise.
+         */
+        ensure(workspaceId, repoRef, signal) {
+            const running = inflight.get(workspaceId);
+            if (running) return running;
+            const p = chain.then(() => { if (signal && signal.aborted) throw new MaterializeError("aborted"); return doEnsure(workspaceId, repoRef, signal); });
+            chain = p.catch(() => {});
+            inflight.set(workspaceId, p);
+            const clear = () => { if (inflight.get(workspaceId) === p) inflight.delete(workspaceId); };
+            p.then(clear, clear);
+            return p;
+        },
+    };
+}

package/src/la-protocol-v2/llm/client.js

@@ -38,6 +38,8 @@ export class LlmClientError extends Error {
 }
 
 const MODEL = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,95}$/;
+const TOOL_NAME = /^[A-Za-z0-9_.-]{1,64}$/;
+const TOOL_ID = /^[A-Za-z0-9_-]{1,64}$/;
 const ROLES = new Set(["system", "user", "assistant"]);
 const COST_HEADER = "x-litellm-response-cost";
 const MAX_SSE_LINE_BYTES = 256 * 1024;
@@ -111,7 +113,7 @@ export function createLlmClient({ holder, config, tenantId, agentId, env = proce
         try {
             let res;
             try {
-                res = await holder.request(config.path, { method: "POST", headers: { "content-type": "application/json", accept: o.stream ? "text/event-stream" : "application/json" }, body: bodyText, signal: ac.signal }, fetchImpl ? { fetchImpl } : undefined);
+                res = await holder.request(o.path || config.path, { method: "POST", headers: { "content-type": "application/json", accept: o.stream ? "text/event-stream" : "application/json" }, body: bodyText, signal: ac.signal }, fetchImpl ? { fetchImpl } : undefined);
             } catch (e) {
                 // LlmKeyError codes from the holder (no_key | expired | bad_path); anything else (fetch failure, abort) is a network error
                 if (e && e.name === "LlmKeyError") throw { code: e.code === "expired" ? "key_expired" : e.code === "no_key" ? "no_key" : "internal", retry: false };
@@ -133,7 +135,7 @@ export function createLlmClient({ holder, config, tenantId, agentId, env = proce
             const costUsd = parseCost(res.headers);
             if (!res.body || typeof res.body.getReader !== "function") throw { code: "bad_response", retry: false };
             try {
-                const parsed = o.stream ? await readStream(res.body, o, rearm, ctx) : await readJson(res.body, config.maxResponseBytes);
+                const parsed = o.stream ? await readStream(res.body, o, rearm, ctx) : o.parseJson ? await o.parseJson(res.body, config.maxResponseBytes) : await readJson(res.body, config.maxResponseBytes);
                 return { ...parsed, costUsd };
             } catch (e) {
                 if (e && e.code && !e.name) throw e;   // our own { code, retry }
@@ -271,26 +273,31 @@ export function createLlmClient({ holder, config, tenantId, agentId, env = proce
             maxTokens = Math.min(maxTokens, room);
         }
         // 5. slot and the call
+        return dispatch(o, ctx, {}, (tags) => JSON.stringify({
+            model: o.model, messages: masked, max_tokens: maxTokens, stream: !!o.stream,
+            ...(o.stream ? { stream_options: { include_usage: true } } : {}),
+            ...(o.temperature !== undefined ? { temperature: o.temperature } : {}),
+            ...(tags ? { metadata: tags } : {}),
+        }));
+    }
+
+    /** The slot, the HTTP call with its retries and the bookkeeping, shared by chat() and messages(). `hooks` = { path, parseJson } of the API in use. */
+    async function dispatch(o, ctx, hooks, makeBody) {
         if (active >= config.maxConcurrent) return fail("busy", ctx);
         active++;
         try {
             const tags = config.tags ? { tags: [`vh-tenant:${tenantId}`, `vh-la:${agentId}`, ...(o.job?.jobId ? [`vh-job:${o.job.jobId}`] : []), ...(o.job?.agent && /^[a-z0-9][a-z0-9._-]{0,31}$/.test(o.job.agent) ? [`vh-agent:${o.job.agent}`] : [])] } : null;
-            const bodyText = JSON.stringify({
-                model: o.model, messages: masked, max_tokens: maxTokens, stream: !!o.stream,
-                ...(o.stream ? { stream_options: { include_usage: true } } : {}),
-                ...(o.temperature !== undefined ? { temperature: o.temperature } : {}),
-                ...(tags ? { metadata: tags } : {}),
-            });
+            const bodyText = makeBody(tags);
             stats.bytesOut += byteLength(bodyText);
             let attempts = 0;
             for (;;) {
                 attempts++;
                 try {
-                    const r = await attempt(bodyText, o, ctx);
+                    const r = await attempt(bodyText, { ...o, ...hooks }, ctx);
                     const usage = r.usage || { promptTokens: estimateTokens(ctx.promptBytes), completionTokens: estimateTokens(byteLength(r.text)), estimated: true };
                     stats.ok++; stats.tokensIn += usage.promptTokens; stats.tokensOut += usage.completionTokens; stats.bytesIn += byteLength(r.text);
-                    record({ ok: true, model: o.model, jobShort: ctx.jobShort, promptBytes: ctx.promptBytes, outBytes: byteLength(r.text), tokensIn: usage.promptTokens, tokensOut: usage.completionTokens, estimated: usage.estimated, attempts, redactions: ctx.redactions, ms: now() - ctx.t0, stream: !!o.stream });
-                    return { text: r.text, usage, costUsd: r.costUsd, model: r.model || o.model, finishReason: r.finishReason, attempts };
+                    record({ ok: true, model: o.model, jobShort: ctx.jobShort, promptBytes: ctx.promptBytes, outBytes: byteLength(r.text), tokensIn: usage.promptTokens, tokensOut: usage.completionTokens, estimated: usage.estimated, attempts, redactions: ctx.redactions, ms: now() - ctx.t0, stream: !!o.stream, ...(hooks.api ? { api: hooks.api } : {}) });
+                    return { text: r.text, usage, costUsd: r.costUsd, model: r.model || o.model, finishReason: r.finishReason, attempts, ...(r.message ? { message: r.message } : {}) };
                 } catch (e) {
                     const code = e && typeof e.code === "string" && LLM_ERROR_CODES.includes(e.code) ? e.code : "internal";
                     const canRetry = e && e.retry === true && !ctx.delivered && attempts <= config.maxRetries && !o.signal?.aborted;
@@ -307,5 +314,119 @@ export function createLlmClient({ holder, config, tenantId, agentId, env = proce
         }
     }
 
-    return { chat, stats, audit: auditor, get active() { return active; } };
+    // ------------------------------------------------------------------------------------------------ Anthropic Messages API (F3-08c)
+
+    /** Masks one string and adds its size; refuses (throws a code) like maskMessages. */
+    function maskText(text, ctx, acc) {
+        const res = protectEgress(text, { env, source: "llm.client" });
+        addCounts(ctx.redactions, res.redactions);
+        if (res.denied || res.text === DENIED || res.text === OVERSIZE) throw "dlp_denied";
+        if (res.blocked) throw "dlp_blocked";
+        acc.bytes += byteLength(res.text);
+        if (acc.bytes > config.maxPromptBytes) throw "prompt_too_large";
+        return res.text;
+    }
+
+    /** Masks every string leaf of a JSON value (tool input), bounded in depth and size. */
+    function maskJson(v, ctx, acc, depth = 0) {
+        if (depth > 8 || ++acc.nodes > 20_000) throw "bad_request";
+        if (typeof v === "string") return maskText(v, ctx, acc);
+        if (v === null || typeof v === "number" || typeof v === "boolean") return v;
+        if (Array.isArray(v)) return v.map((x) => maskJson(x, ctx, acc, depth + 1));
+        if (typeof v === "object") { const out = {}; for (const [k, x] of Object.entries(v)) { if (k === "__proto__" || k.length > 200) throw "bad_request"; out[k] = maskJson(x, ctx, acc, depth + 1); } return out; }
+        throw "bad_request";
+    }
+
+    const cacheOf = (b) => (b.cache_control && typeof b.cache_control === "object" && b.cache_control.type === "ephemeral" ? { cache_control: { type: "ephemeral" } } : {});
+
+    /** A block of the Messages API, rebuilt field by field: a type or a field this agent does not know is refused, never forwarded. */
+    function maskBlock(b, ctx, acc, { allowTools }) {
+        if (!b || typeof b !== "object" || Array.isArray(b)) throw "bad_request";
+        if (b.type === "text" && typeof b.text === "string") return { type: "text", text: maskText(b.text, ctx, acc), ...cacheOf(b) };
+        if (allowTools && b.type === "tool_use" && TOOL_ID.test(String(b.id)) && TOOL_NAME.test(String(b.name)) && b.input && typeof b.input === "object" && !Array.isArray(b.input)) return { type: "tool_use", id: b.id, name: b.name, input: maskJson(b.input, ctx, acc) };
+        if (allowTools && b.type === "tool_result" && TOOL_ID.test(String(b.tool_use_id))) {
+            const content = typeof b.content === "string" ? maskText(b.content, ctx, acc)
+                : Array.isArray(b.content) ? b.content.map((x) => maskBlock(x, ctx, acc, { allowTools: false })) : b.content === undefined ? "" : (() => { throw "bad_request"; })();
+            return { type: "tool_result", tool_use_id: b.tool_use_id, content, ...(b.is_error === true ? { is_error: true } : {}) };
+        }
+        throw "bad_request";
+    }
+
+    function maskTools(tools, ctx, acc) {
+        if (!Array.isArray(tools) || tools.length > 64) throw "bad_request";
+        return tools.map((t) => {
+            if (!t || typeof t !== "object" || !TOOL_NAME.test(String(t.name)) || !t.input_schema || typeof t.input_schema !== "object" || Array.isArray(t.input_schema)) throw "bad_request";
+            if (t.description !== undefined && (typeof t.description !== "string" || byteLength(t.description) > 16 * 1024)) throw "bad_request";
+            if (byteLength(JSON.stringify(t.input_schema)) > 64 * 1024) throw "bad_request";
+            return { name: t.name, ...(t.description !== undefined ? { description: maskText(t.description, ctx, acc) } : {}), input_schema: maskJson(t.input_schema, ctx, acc), ...cacheOf(t) };
+        });
+    }
+
+    async function parseMessagesJson(body, maxBytes) {
+        const text = await readBounded(body, maxBytes);
+        let j;
+        try { j = JSON.parse(text); } catch { throw { code: "bad_response", retry: false }; }
+        if (!j || typeof j !== "object" || !Array.isArray(j.content) || j.content.some((b) => !b || typeof b !== "object" || typeof b.type !== "string")) throw { code: "bad_response", retry: false };
+        const u = j.usage && typeof j.usage === "object" ? j.usage : null;
+        const n = (x) => (Number.isSafeInteger(x) && x >= 0 ? x : 0);
+        const input = u ? n(u.input_tokens) + n(u.cache_creation_input_tokens) + n(u.cache_read_input_tokens) : null;
+        const usage = u && Number.isSafeInteger(u.input_tokens) && Number.isSafeInteger(u.output_tokens) ? { promptTokens: input, completionTokens: n(u.output_tokens), estimated: false } : null;
+        const stop = typeof j.stop_reason === "string" ? j.stop_reason.slice(0, 32) : null;
+        const message = { id: typeof j.id === "string" ? j.id.slice(0, 128) : "msg_la", type: "message", role: "assistant", content: j.content, stop_reason: stop, stop_sequence: null,
+            usage: u ? { input_tokens: n(u.input_tokens), output_tokens: n(u.output_tokens), ...(Number.isSafeInteger(u.cache_creation_input_tokens) ? { cache_creation_input_tokens: u.cache_creation_input_tokens } : {}), ...(Number.isSafeInteger(u.cache_read_input_tokens) ? { cache_read_input_tokens: u.cache_read_input_tokens } : {}) } : { input_tokens: 0, output_tokens: 0 } };
+        return { text: j.content.filter((b) => b.type === "text" && typeof b.text === "string").map((b) => b.text).join(""), usage, model: modelOf(j.model), finishReason: stop, message };
+    }
+
+    /**
+     * F3-08c: one turn of the Anthropic Messages API (`POST <endpoint>/v1/messages`, what the packaged agent loop speaks, with tools), through the SAME gates
+     * as chat(): DLP enforce, key and alias, EVERY string the model will read masked (system, text, tool_use input, tool_result, tool descriptions), size and
+     * token budget, concurrency slot, timeouts and retries, codes-only errors. Not streaming. Blocks and fields outside the known set are refused.
+     * @param {object} o  model (alias), system (string | text blocks), messages [{role:user|assistant, content:string|blocks}], tools?, toolChoice?, maxTokens?, temperature?, signal?, job?, tokensLeft?
+     * @returns {Promise<{text:string, message:object, usage, costUsd, model, finishReason, attempts}>}  `message` = the response in the Messages API shape (local use only)
+     */
+    async function messages(o = {}) {
+        stats.calls++;
+        const ctx = { t0: now(), model: typeof o.model === "string" && MODEL.test(o.model) ? o.model : "invalid", jobShort: o.job?.jobId ? short(o.job.jobId) : undefined, promptBytes: 0, redactions: {}, stream: false, delivered: false, deadline: now() + config.totalMs };
+        const msgs = o.messages;
+        if (typeof o.model !== "string" || !MODEL.test(o.model) || !Array.isArray(msgs) || msgs.length < 1 || msgs.length > config.maxApiMessages
+            || !msgs.every((m) => m && typeof m === "object" && (m.role === "user" || m.role === "assistant") && (typeof m.content === "string" || (Array.isArray(m.content) && m.content.length >= 1 && m.content.length <= 256)))) return fail("bad_request", ctx);
+        if (o.temperature !== undefined && !(Number.isFinite(o.temperature) && o.temperature >= 0 && o.temperature <= 1)) return fail("bad_request", ctx);
+        if (o.system !== undefined && typeof o.system !== "string" && !(Array.isArray(o.system) && o.system.length <= 64)) return fail("bad_request", ctx);
+        if (o.toolChoice !== undefined && !(o.toolChoice && ((["auto", "any", "none"].includes(o.toolChoice.type)) || (o.toolChoice.type === "tool" && TOOL_NAME.test(String(o.toolChoice.name)))))) return fail("bad_request", ctx);
+        if (o.signal?.aborted) return fail("cancelled", ctx);
+        if (dlpConfigFromEnv(env).mode !== "enforce") return fail("dlp_not_enforced", ctx);
+        if (!holder.held) return fail("no_key", ctx);
+        const d = holder.describe();
+        if (!d.held) return fail("key_expired", ctx);
+        if (!d.models.includes(o.model)) return fail("model_not_allowed", ctx);
+        const acc = { bytes: 0, nodes: 0 };
+        let system;
+        let masked;
+        let tools;
+        try {
+            if (typeof o.system === "string") system = maskText(o.system, ctx, acc);
+            else if (Array.isArray(o.system)) system = o.system.map((b) => maskBlock(b, ctx, acc, { allowTools: false }));
+            masked = msgs.map((m) => ({ role: m.role, content: typeof m.content === "string" ? maskText(m.content, ctx, acc) : m.content.map((b) => maskBlock(b, ctx, acc, { allowTools: true })) }));
+            if (o.tools !== undefined) tools = maskTools(o.tools, ctx, acc);
+        } catch (code) {
+            return fail(typeof code === "string" ? code : "bad_request", ctx);
+        }
+        ctx.promptBytes = acc.bytes;
+        let maxTokens = Math.min(Number.isSafeInteger(o.maxTokens) && o.maxTokens > 0 ? o.maxTokens : config.maxOutputTokens, config.maxOutputTokens);
+        if (o.tokensLeft !== undefined) {
+            const room = o.tokensLeft - estimateTokens(ctx.promptBytes);
+            if (!(room >= 1)) return fail("budget_exceeded", ctx);
+            maxTokens = Math.min(maxTokens, room);
+        }
+        return dispatch(o, ctx, { path: config.messagesPath, parseJson: parseMessagesJson, api: "messages" }, (tags) => JSON.stringify({
+            model: o.model, max_tokens: maxTokens, messages: masked,
+            ...(system !== undefined ? { system } : {}),
+            ...(tools ? { tools } : {}),
+            ...(o.toolChoice ? { tool_choice: o.toolChoice } : {}),
+            ...(o.temperature !== undefined ? { temperature: o.temperature } : {}),
+            ...(tags ? { metadata: tags } : {}),
+        }));
+    }
+
+    return { chat, messages, stats, audit: auditor, get active() { return active; } };
 }

package/src/la-protocol-v2/llm/config.js

@@ -44,6 +44,8 @@ export function resolveLlmClientConfig(env = process.env, warn = console.warn) {
     return {
         enabled: true,
         path,                                                            // appended to the endpoint the control plane gave (the holder never shows it); set it to /chat/completions when that endpoint already ends in /v1
+        messagesPath: PATH.test(String(env.LOCAL_AGENT_LLM_MESSAGES_PATH ?? "").trim()) ? String(env.LOCAL_AGENT_LLM_MESSAGES_PATH).trim() : "/v1/messages",   // F3-08c: Anthropic Messages API (the packaged agent loop); set /messages when the endpoint of the key already ends in /v1
+        maxApiMessages: int(env.LOCAL_AGENT_LLM_MAX_API_MESSAGES, 256, 1, 1024),                                                                            // messages per turn of the Messages API (an agent loop re-sends its whole history)
         timeoutMs: int(env.LOCAL_AGENT_LLM_TIMEOUT_MS, 60_000, 1_000, 300_000),        // one attempt: headers + body (streaming: until the headers)
         streamIdleMs: int(env.LOCAL_AGENT_LLM_STREAM_IDLE_MS, 30_000, 1_000, 120_000), // streaming: silence between two chunks
         totalMs: int(env.LOCAL_AGENT_LLM_TOTAL_MS, 180_000, 1_000, 900_000),           // the whole call, retries included

package/src/la-protocol-v2/runtime.js

@@ -82,6 +82,27 @@ export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWo
     if (llmClientCfg.enabled && !(await dlpEnforce())) { err("[la-llm] ERROR: LOCAL_AGENT_LLM_CLIENT=true but LOCAL_AGENT_DLP_MODE is not enforce: prompts would leave this machine unmasked, the LLM client is NOT installed"); llmClientCfg = { enabled: false }; }
     let jobsCfg = resolveJobsConfig(env, (m) => log.warn(m));
     let runner = null;
+    // F3-08c (Local Agent half): LOCAL_AGENT_RUNNER=agent2 plugs the packaged agent loop (agent2, next to this agent) in as the runner. Default off: nothing of
+    // ./jobs/agent2 is loaded. It needs jobs, the LLM client (agent2 reaches the model ONLY through this agent: DLP + key holder) and DLP enforce; when one is
+    // missing the job receiver is NOT installed (never silently another runner).
+    let agent2Runner = null;
+    if (String(env.LOCAL_AGENT_RUNNER ?? "").trim().toLowerCase() === "agent2") {
+        const a2 = await import("./jobs/agent2/config.js");
+        const a2cfg = a2.resolveAgent2RunnerConfig(env, (m) => log.warn(m));
+        if (jobRunner) log.warn("[la-agent2] a runner was injected into buildV2Link: LOCAL_AGENT_RUNNER=agent2 is ignored");
+        else if (!jobsCfg.enabled) err("[la-agent2] ERROR: LOCAL_AGENT_RUNNER=agent2 but LOCAL_AGENT_JOBS is not true: the agent2 runner is NOT installed");
+        else if (!a2cfg.enabled) { err(`[la-agent2] ERROR: ${a2cfg.error || "the agent2 runner is not configured"}: job.assign is NOT registered`); jobsCfg = { enabled: false }; }
+        else if (!llmClientCfg.enabled) { err("[la-agent2] ERROR: LOCAL_AGENT_RUNNER=agent2 needs the LLM client (LOCAL_AGENT_LLM_CLIENT, LOCAL_AGENT_LLM_KEY, DLP enforce): agent2 reaches the model only through this agent. job.assign is NOT registered"); jobsCfg = { enabled: false }; }
+        else if (!(await dlpEnforce())) { err("[la-agent2] ERROR: LOCAL_AGENT_RUNNER=agent2 but LOCAL_AGENT_DLP_MODE is not enforce: job.assign is NOT registered"); jobsCfg = { enabled: false }; }
+        else {
+            const { createAgent2Runner } = await import("./jobs/agent2/runner.js");
+            const { makeWorkspaceResolver } = await import("./jobs/install.js");
+            const resolveWs = makeWorkspaceResolver({ wsManager, getWorkspaceRoot, tenantId: tenant });
+            agent2Runner = createAgent2Runner({ config: a2cfg, tenantId: tenant, resolveWorkspaceRoot: (id) => resolveWs(id)?.root || null, getSession: () => link.session, signing, env, log });
+            jobRunner = agent2Runner;
+            if (jobsCfg.maxConcurrent !== 1) { log.warn("[la-agent2] agent2 runs one job at a time: LOCAL_AGENT_JOBS_MAX_CONCURRENT is forced to 1"); jobsCfg = { ...jobsCfg, maxConcurrent: 1 }; }
+        }
+    }
     if (jobsCfg.enabled) {
         const { validateRunner } = await import("./jobs/manager.js");
         const given = jobRunner && validateRunner(jobRunner) ? jobRunner : null;
@@ -96,12 +117,15 @@ export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWo
     const incidentCaps = hasIncidentSource ? ["incident.candidate"] : [];
     const webhookCaps = webhookCfg.enabled ? ["webhook.forward", "webhook.chunked"] : [];
     const llmCaps = llmCfg.enabled ? ["llm.key"] : [];
-    const jobCaps = jobsCfg.enabled ? ["job.assign"] : [];   // F3-10: this agent runs jobs (the CP sends job.assign only to a session that announced it)
+    const jobCaps = jobsCfg.enabled ? ["job.assign", ...(agent2Runner ? ["approval.decision"] : [])] : [];   // approval.decision (F3-08c): this agent delivers a person's decision (ADR-0010) to agent2; proposal, not named in the contract   // F3-10: this agent runs jobs (the CP sends job.assign only to a session that announced it)
     // F3-10 (contract 2.1): `job.options` = the runner understands job.assign `options` (dryRun, createPullRequest, ...). Only a runner that declared supportsOptions
     // (the smoke runner does); an injected one that did not never gets options, and the CP, without this capability, refuses a dry run instead of sending it.
     const jobOptionCaps = jobsCfg.enabled && (runner ? runner.supportsOptions === true : jobsCfg.runner === "smoke") ? ["job.options"] : [];
+    // contract 2.2 (F3-08c): `policy.check` = this agent asks the PolicyGate over the channel (agent2's governed actions). Only the agent2 runner asks, so only then it is announced;
+    // the CP lists it back in `ready.capabilities` only with its feature on, and this agent sends a policy.check only after that (without it: DENY, fail closed)
+    const policyCaps = jobsCfg.enabled && agent2Runner ? ["policy.check"] : [];
     // contract 2.1: announced only when a 2.1 feature is on, so with every flag off register/hello are exactly what they were
-    const v21Caps = webhookCaps.length || llmCaps.length || incidentCaps.length ? ["contract.v2.1"] : [];
+    const v21Caps = webhookCaps.length || llmCaps.length || incidentCaps.length || policyCaps.length ? ["contract.v2.1"] : [];
     const link = createV2Link({
         log,
         sessionOptions: {
@@ -111,7 +135,7 @@ export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWo
             signing,
             laVersion: agentVersion(),
             // only what this build implements: the transport, the handshake and the v1 commands on the same connection
-            capabilities: ["protocol.v2", "v1.commands", "chunk.base64", ...contentCaps, ...incidentCaps, ...webhookCaps, ...llmCaps, ...jobCaps, ...jobOptionCaps, ...v21Caps],
+            capabilities: ["protocol.v2", "v1.commands", "chunk.base64", ...contentCaps, ...incidentCaps, ...webhookCaps, ...llmCaps, ...jobCaps, ...jobOptionCaps, ...policyCaps, ...v21Caps],
             // contract 2.1 (e): `llm.key.held` is a snapshot taken at every connect (register and hello alike): announced only while the holder has a
             // valid, unexpired key (a revoked or expired one is not announced from the next connection on). `link` is assigned below, before any attach.
             dynamicCapabilities: () => (llmCfg.enabled && link.llm && link.llm.holder.held ? ["llm.key.held"] : []),
@@ -148,6 +172,15 @@ export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWo
     if (jobsCfg.enabled) {
         const { installJobs } = await import("./jobs/install.js");
         installJobs({ link, tenantId: tenant, wsManager, getWorkspaceRoot, config: jobsCfg, env, log, runner, onResult: onJobResult });
+        if (agent2Runner && runner === agent2Runner) {
+            // approval.decision -> POST /local/v1/approvals/{id} of agent2, after the token check; the child process and the bridge stop with the link
+            link.session.setHandler("approval.decision", (ctx) => agent2Runner.handleApprovalDecision(ctx), { ackMs: 5_000 });
+            // policy.decision (contract 2.2): the CP's signed answer to a policy.check the bridge asked for agent2 (matched by the envelope requestId)
+            link.session.setHandler("policy.decision", (ctx) => agent2Runner.handlePolicyDecision(ctx));
+            link.agent2 = agent2Runner;
+            const closeJobs = link.close.bind(link);
+            link.close = () => { closeJobs(); agent2Runner.close().catch(() => {}); };
+        }
     }
     let webhookSource = null;
     if (webhookCfg.enabled) {

package/src/server.js

@@ -7297,6 +7297,8 @@ async function startWebSocketTunnel(port, gatewayUrl, authToken, tenantId, agent
     process.on('SIGINT', async () => {
         isShuttingDown = true;
         if (ws) ws.close();
+        // F3-08c: stops what the v2 link started (jobs in flight, the agent2 runner and the agent2 process it supervises). Nothing when v2 is off.
+        try { if (v2Link) v2Link.close(); } catch (_) { /* never block exit */ }
         // Phase 2: graceful shutdown of legacy connectors (AC-11; bounded to 5 s).
         try { await stopAll(_legacyAdapters, 5000); } catch (_) { /* never block exit */ }
         // Preserve existing process model: signal trap does NOT call process.exit();
@@ -7305,6 +7307,8 @@ async function startWebSocketTunnel(port, gatewayUrl, authToken, tenantId, agent
     process.on('SIGTERM', async () => {
         isShuttingDown = true;
         if (ws) ws.close();
+        // F3-08c: stops what the v2 link started (jobs in flight, the agent2 runner and the agent2 process it supervises). Nothing when v2 is off.
+        try { if (v2Link) v2Link.close(); } catch (_) { /* never block exit */ }
         // Phase 2: graceful shutdown of legacy connectors (AC-11; bounded to 5 s).
         try { await stopAll(_legacyAdapters, 5000); } catch (_) { /* never block exit */ }
         // Preserve existing process model: signal trap does NOT call process.exit();

package/src/utils/approval-token.js

@@ -23,7 +23,8 @@ export const MAX_APPROVAL_LIFETIME_SECONDS = 15 * 60;
 const b64urlDecode = (s) => Buffer.from(String(s).replace(/-/g, "+").replace(/_/g, "/"), "base64");
 
 /**
- * Returns { ok: true, approvedBy, decision } or { ok: false, reason }.
+ * Returns { ok: true, approvedBy, decision, jti } or { ok: false, reason }. (`jti` is additive, F3-08c: a caller that must not consume the single-use
+ * nonce before its own action succeeds passes `nonces: null` and remembers the jti itself.)
  * opts: { subject, keys: Map, identity, requestTenantId, nonces, now }
  */
 export function verifyApprovalToken(token, { subject, keys, identity = {}, requestTenantId, nonces, now = () => Date.now() } = {}) {
@@ -52,5 +53,5 @@ export function verifyApprovalToken(token, { subject, keys, identity = {}, reque
     if (requestTenantId && p.tid !== requestTenantId) return { ok: false, reason: "approval token tenant differs from the signed request" };
     if (!p.jti || !/^[A-Za-z0-9_-]{8,128}$/.test(p.jti)) return { ok: false, reason: "approval token without jti" };
     if (nonces && !nonces.checkAndRemember(`apr:${p.jti}`)) return { ok: false, reason: "approval token already used" };
-    return { ok: true, approvedBy: p.by || null, decision: p.decision || null };
+    return { ok: true, approvedBy: p.by || null, decision: p.decision || null, jti: p.jti };
 }