deepdebug-local-agent 1.10.0 → 1.11.0

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

@@ -0,0 +1,269 @@
+/**
+ * supervisor.js - keeps agent2 (the packaged agent loop, profile local-agent) available for the runner (F3-08c, Local Agent half).
+ *
+ *   spawn   (LOCAL_AGENT_AGENT2_CMD)  this agent starts the process, with a minimal environment and a NEW random API token at every start; waits for
+ *                                     `/local/v1/health`; probes it while it runs; restarts it (at the next job) after a crash, at most `maxRestarts`
+ *                                     times inside `restartWindowMs`, then reports `unavailable` instead of looping; kills it above `maxRssBytes`;
+ *                                     stops it with the agent (SIGTERM, then SIGKILL after `stopGraceMs`).
+ *   attach  (LOCAL_AGENT_AGENT2_URL)  agent2 already runs (sidecar); only health is checked. The token is the one it was started with.
+ *
+ * The environment of the child is an ALLOWLIST (PATH, HOME, JAVA_HOME, locale, proxies, the git/ssh variables the machine's own credentials need) plus
+ * what this module sets and what the operator named in LOCAL_AGENT_AGENT2_ENV_PASSTHROUGH (never a name that looks like a secret). Nothing else of this
+ * agent's environment reaches agent2: not the LLM key (it lives in the holder, in memory), not LOCAL_AGENT_TOKEN's siblings, not the signing keys.
+ * stdout/stderr of the child are drained and DROPPED: they may hold customer content; agent2's own logging is configured in agent2.
+ */
+import { spawn as nodeSpawn, execFile } from "node:child_process";
+import crypto from "node:crypto";
+import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createAgent2Api } from "./api-client.js";
+import { isSecretEnvName } from "../../../utils/child-env.js";
+
+const ALLOW = Object.freeze(["PATH", "HOME", "USER", "LOGNAME", "LANG", "LC_ALL", "LC_CTYPE", "TZ", "TMPDIR", "TMP", "TEMP", "JAVA_HOME",
+    "SSH_AUTH_SOCK", "GIT_ASKPASS", "GIT_SSH", "GIT_SSH_COMMAND", "GIT_CONFIG_GLOBAL", "GIT_CONFIG_SYSTEM", "GIT_CONFIG_NOSYSTEM", "GIT_TERMINAL_PROMPT",
+    "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "no_proxy", "SSL_CERT_FILE", "SSL_CERT_DIR", "SYSTEMROOT", "PATHEXT", "COMSPEC"]);
+
+export class Agent2UnavailableError extends Error {
+    constructor(code) { super(code); this.name = "Agent2UnavailableError"; this.code = code; }
+}
+
+const defaultSleep = (ms) => new Promise((r) => { const t = setTimeout(r, ms); if (t.unref) t.unref(); });
+const defaultRss = (pid) => new Promise((resolve) => {
+    execFile("ps", ["-o", "rss=", "-p", String(pid)], { timeout: 3_000 }, (err, out) => {
+        const kb = err ? 0 : Number.parseInt(String(out).trim(), 10);
+        resolve(Number.isFinite(kb) && kb > 0 ? kb * 1024 : 0);
+    });
+});
+
+/** The full command line of a process, or null when it cannot be told (no `ps`, no such process). */
+const defaultCmdline = (pid) => new Promise((resolve) => {
+    execFile("ps", ["-ww", "-o", "command=", "-p", String(pid)], { timeout: 3_000 }, (err, out) => {
+        const t = err ? "" : String(out).trim();
+        resolve(t || null);
+    });
+});
+
+const isAlive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return !!e && e.code === "EPERM"; } };
+
+// Children still running when THIS process exits normally (SIGTERM/SIGINT handlers, process.exit): ended synchronously, best effort. A SIGKILL of this agent skips
+// 'exit' handlers: that case is the pidfile's (the next start ends the orphan).
+const liveChildren = new Set();
+let exitHooked = false;
+function hookExit() {
+    if (exitHooked) return;
+    exitHooked = true;
+    process.once("exit", () => { for (const c of liveChildren) { try { c.kill("SIGKILL"); } catch { /* gone */ } } });
+}
+
+/** The environment agent2 starts with (pure, so a test can pin it). */
+export function agent2ChildEnv({ config, env, tenantId, token, bridgeBase, callbackToken }) {
+    const out = {};
+    for (const k of ALLOW) if (env[k] !== undefined) out[k] = env[k];
+    for (const k of config.passthrough || []) if (env[k] !== undefined && !isSecretEnvName(k)) out[k] = env[k];
+    Object.assign(out, {
+        AGENT2_LOCAL_MODE: "true",
+        AGENT2_LOCAL_BIND: "127.0.0.1",
+        AGENT2_LOCAL_PORT: String(config.apiPort),
+        AGENT2_LOCAL_API_TOKEN: token,
+        AGENT2_LOCAL_TENANT_ID: tenantId,
+        AGENT2_LLM_BASE_URL: `${bridgeBase}/v1`,                    // the loopback bridge: DLP + the LLM client of this agent, never the AI gateway directly
+        // agent2 reaches this agent's /workspace API THROUGH the bridge, which signs for it (internal marker) and adds the API's X-Agent-Token itself: the token agent2 holds
+        // here is the bridge's callback token, NOT LOCAL_AGENT_TOKEN, and it opens nothing but the bridge
+        AGENT2_LA_WORKSPACE_URL: bridgeBase,
+        AGENT2_LA_WORKSPACE_TOKEN: callbackToken,
+        AGENT2_LA_CALLBACK_URL: bridgeBase,                         // POST {url}/agent2/cp-request: the PolicyGate door (-> policy.check over the v2 channel)
+        AGENT2_LA_CALLBACK_TOKEN: callbackToken,
+        DEEPDEBUG_POLICYGATE_TIMEOUT_MS: String(config.policyCheckTimeoutMs + 3_000),   // agent2 must wait longer than the channel does (default 3 s would cut a decision off)
+    });
+    if (config.maxHeapMb > 0) out.JAVA_TOOL_OPTIONS = `-Xmx${config.maxHeapMb}m`;
+    if (config.approvalWaitSeconds > 0) out.AGENT2_LOCAL_APPROVAL_WAIT_SECONDS = String(config.approvalWaitSeconds);
+    return out;
+}
+
+export function createAgent2Supervisor({ config, tenantId, bridge, env = process.env, log = console, spawnImpl = nodeSpawn, fetchImpl, now = Date.now, sleep = defaultSleep, rssOf = defaultRss, cmdlineOf = defaultCmdline }) {
+    const emitter = new EventEmitter();
+    const warn = (m) => (log.warn || log.log).call(log, m);
+    const info = (m) => (log.info || log.log).call(log, m);
+    const stats = { starts: 0, exits: 0, healthFailed: 0, killedForRss: 0, startFailures: 0, refusedRestartLimit: 0, orphansEnded: 0, orphanChecksSkipped: 0 };
+    const cmdSha = config.mode === "spawn" ? crypto.createHash("sha256").update(JSON.stringify(config.cmd)).digest("hex") : "";
+    const pidFile = config.mode === "spawn" ? (config.pidFile || path.join(env.HOME || env.USERPROFILE || os.homedir(), ".deepdebug", "agent2-runner.pid")) : null;
+    const startTimes = [];
+    let state = "idle";            // idle | starting | ready | down | stopped
+    let child = null;
+    let target = config.mode === "attach" ? { baseUrl: config.url, token: config.token } : null;
+    let starting = null;
+    let healthTimer = null;
+    let healthFails = 0;
+    let lastExitAt = 0;
+    let stopping = false;
+
+    // ---- the pidfile: a child that outlived this agent (SIGKILL, crash) would keep the API port and an old token; the next start ends it
+    function writePidFile(pid) {
+        if (!pidFile || !pid) return;
+        try {
+            fs.mkdirSync(path.dirname(pidFile), { recursive: true, mode: 0o700 });
+            fs.writeFileSync(pidFile, JSON.stringify({ pid, cmdSha, startedAt: now() }), { mode: 0o600 });
+        } catch { warn("[la-agent2] could not write the pidfile of agent2; a restart of this agent will not be able to end an orphan"); }
+    }
+    function removePidFile(onlyPid) {
+        if (!pidFile) return;
+        try {
+            if (onlyPid) { const cur = JSON.parse(fs.readFileSync(pidFile, "utf8")); if (cur && cur.pid !== onlyPid) return; }
+            fs.rmSync(pidFile, { force: true });
+        } catch { /* nothing to remove */ }
+    }
+    /**
+     * An agent2 left by a previous run of this agent: ended (SIGTERM, then SIGKILL after the grace) only when the pid is alive AND its command line is the command
+     * this agent starts (a reused pid of another program is never touched). Where the command line cannot be read (no `ps`) nothing is killed.
+     */
+    async function reapOrphan() {
+        if (!pidFile) return;
+        let rec;
+        try { rec = JSON.parse(fs.readFileSync(pidFile, "utf8")); } catch { return; }
+        const pid = rec && Number.isSafeInteger(rec.pid) && rec.pid > 1 ? rec.pid : 0;
+        if (!pid || pid === process.pid || !isAlive(pid)) { removePidFile(); return; }
+        const line = await cmdlineOf(pid);
+        if (line === null) { stats.orphanChecksSkipped++; warn("[la-agent2] the pidfile names a live process but its command line cannot be read; it is left alone"); return; }
+        if (rec.cmdSha !== cmdSha || !config.cmd.slice(0, 8).every((a) => line.includes(a))) { removePidFile(); return; }   // not ours (any more): the pid was reused
+        warn("[la-agent2] an agent2 from a previous run is still alive; ending it");
+        try { process.kill(pid, "SIGTERM"); } catch { /* gone */ }
+        const deadline = now() + config.stopGraceMs;
+        while (isAlive(pid) && now() < deadline) await sleep(50);
+        if (isAlive(pid)) { try { process.kill(pid, "SIGKILL"); } catch { /* gone */ } await sleep(100); }
+        if (isAlive(pid)) throw new Agent2UnavailableError("orphan_alive");
+        stats.orphansEnded++;
+        removePidFile();
+    }
+
+    const api = createAgent2Api({ getTarget: () => { if (!target) throw new Agent2UnavailableError("agent2_down"); return target; }, requestTimeoutMs: config.requestTimeoutMs, ...(fetchImpl ? { fetchImpl } : {}) });
+
+    function markDown(why) {
+        if (state === "down" || state === "stopped") return;
+        state = "down";
+        if (config.mode === "spawn") target = null;
+        emitter.emit("down", { why });
+    }
+
+    function startHealthTimer() {
+        clearInterval(healthTimer);
+        healthFails = 0;
+        healthTimer = setInterval(async () => {
+            if (state !== "ready") return;
+            if (await api.health()) healthFails = 0;
+            else if (++healthFails >= config.healthFailures) {
+                stats.healthFailed++;
+                warn("[la-agent2] agent2 stopped answering its health probe");
+                if (child) { try { child.kill("SIGKILL"); } catch { /* gone */ } }
+                markDown("health");
+                return;
+            }
+            if (config.mode === "spawn" && config.maxRssBytes > 0 && child && child.pid) {
+                const rss = await rssOf(child.pid);
+                if (rss > config.maxRssBytes) { stats.killedForRss++; warn("[la-agent2] agent2 is above LOCAL_AGENT_AGENT2_MAX_RSS_BYTES; stopping it (a new one starts at the next job)"); try { child.kill("SIGKILL"); } catch { /* gone */ } markDown("rss"); }
+            }
+        }, config.healthIntervalMs);
+        if (healthTimer.unref) healthTimer.unref();
+    }
+
+    async function waitHealthy(proc) {
+        const deadline = now() + config.startTimeoutMs;
+        for (;;) {
+            if (stopping) throw new Agent2UnavailableError("stopped");
+            if (proc && proc.exited) throw new Agent2UnavailableError("exited_during_start");
+            if (await api.health()) return;
+            if (now() >= deadline) throw new Agent2UnavailableError("start_timeout");
+            await sleep(Math.min(250, Math.max(10, config.startTimeoutMs / 20)));
+        }
+    }
+
+    async function startAttach() {
+        state = "starting";
+        try { await waitHealthy(null); } catch (e) { state = "down"; stats.startFailures++; throw e; }
+        state = "ready";
+        startHealthTimer();
+    }
+
+    async function startSpawn() {
+        const t = now();
+        while (startTimes.length && t - startTimes[0] > config.restartWindowMs) startTimes.shift();
+        if (startTimes.length >= config.maxRestarts + 1) { stats.refusedRestartLimit++; throw new Agent2UnavailableError("restart_limit"); }
+        if (startTimes.length > 0) { const wait = Math.max(0, lastExitAt + config.restartBackoffMs * startTimes.length - t); if (wait > 0) await sleep(wait); }
+        startTimes.push(now());
+        state = "starting";
+        stats.starts++;
+        try { await reapOrphan(); } catch (e) { state = "down"; stats.startFailures++; throw e; }
+        const token = crypto.randomBytes(32).toString("base64url");             // a NEW secret per start: nothing from a previous process works
+        const callbackToken = crypto.randomBytes(32).toString("base64url");
+        const { baseUrl: bridgeBase } = await bridge.listen();
+        bridge.setCallbackToken(callbackToken);
+        const childEnv = agent2ChildEnv({ config, env, tenantId, token, bridgeBase, callbackToken });
+        const proc = { exited: false };
+        let c;
+        try {
+            c = spawnImpl(config.cmd[0], config.cmd.slice(1), { env: childEnv, stdio: ["ignore", "pipe", "pipe"], shell: false, windowsHide: true });
+        } catch { state = "down"; stats.startFailures++; throw new Agent2UnavailableError("spawn_failed"); }
+        child = c;
+        liveChildren.add(c); hookExit();
+        writePidFile(c.pid);
+        for (const s of [c.stdout, c.stderr]) { if (s && typeof s.on === "function") { s.on("data", () => {}); s.on("error", () => {}); } }   // drained and dropped
+        c.on("error", () => { proc.exited = true; liveChildren.delete(c); });
+        c.on("exit", (code, signal) => {
+            proc.exited = true;
+            stats.exits++;
+            lastExitAt = now();
+            liveChildren.delete(c);
+            removePidFile(c.pid);
+            if (child === c) child = null;
+            if (!stopping) warn(`[la-agent2] agent2 exited (code ${code ?? "none"}, signal ${signal ?? "none"})`);
+            markDown("exit");
+        });
+        info(`[la-agent2] started agent2 (pid ${c.pid ?? "?"})`);
+        target = { baseUrl: `http://127.0.0.1:${config.apiPort}`, token };
+        try { await waitHealthy(proc); } catch (e) {
+            stats.startFailures++;
+            try { c.kill("SIGKILL"); } catch { /* gone */ }
+            state = "down"; target = null;
+            throw e;
+        }
+        if (proc.exited) { state = "down"; target = null; throw new Agent2UnavailableError("exited_during_start"); }
+        state = "ready";
+        startHealthTimer();
+    }
+
+    return {
+        api, stats,
+        on: (ev, fn) => emitter.on(ev, fn),
+        off: (ev, fn) => emitter.off(ev, fn),
+        get state() { return state; },
+        get pid() { return child ? child.pid : null; },
+        /** Resolves when agent2 answers its health probe (starting it first in spawn mode). Throws Agent2UnavailableError(code). */
+        async ensureReady() {
+            if (stopping) throw new Agent2UnavailableError("stopped");
+            if (state === "ready") {
+                if (await api.health()) return;
+                if (child) { try { child.kill("SIGKILL"); } catch { /* gone */ } }
+                markDown("health");
+            }
+            if (!starting) starting = (config.mode === "attach" ? startAttach() : startSpawn()).finally(() => { starting = null; });
+            await starting;
+        },
+        /** Stops the child (SIGTERM, then SIGKILL after the grace) and every timer. */
+        async stop() {
+            stopping = true;
+            state = "stopped";
+            clearInterval(healthTimer);
+            const c = child;
+            child = null;
+            if (!c) return;
+            await new Promise((resolve) => {
+                let done = false;
+                const fin = () => { if (!done) { done = true; clearTimeout(t); resolve(); } };
+                const t = setTimeout(() => { try { c.kill("SIGKILL"); } catch { /* gone */ } fin(); }, config.stopGraceMs);   // not unref'd: whoever awaits stop() waits at most stopGraceMs
+                c.once("exit", fin);
+                try { if (!c.kill("SIGTERM")) fin(); } catch { fin(); }
+            });
+        },
+    };
+}

package/src/la-protocol-v2/jobs/install.js

@@ -11,10 +11,10 @@ import { createSmokeRunner } from "./smoke-runner.js";
 
 export const JOBS_CAPABILITIES = Object.freeze(["job.assign"]);
 
-export function installJobs({ link, tenantId, wsManager, getWorkspaceRoot, config, env = process.env, log = console, runner = null, onResult = null, now = Date.now, memoryUsage, sleep }) {
-    if (dlpConfigFromEnv(env).mode !== "enforce") throw new Error("job.assign needs LOCAL_AGENT_DLP_MODE=enforce");
+/** A workspace "served here": open in the manager (of this tenant, or of none yet) or the default root. -> { root } | null */
+export function makeWorkspaceResolver({ wsManager, getWorkspaceRoot, tenantId }) {
     const tenant = String(tenantId).toLowerCase();
-    const resolveWorkspace = (workspaceId) => {
+    return (workspaceId) => {
         if (typeof workspaceId !== "string" || !workspaceId) return null;
         const listed = (wsManager?.list?.() || []).find((w) => w && w.id === workspaceId);
         if (listed) {
@@ -24,6 +24,12 @@ export function installJobs({ link, tenantId, wsManager, getWorkspaceRoot, confi
         if (workspaceId === "default") { const root = getWorkspaceRoot(); return root ? { root } : null; }
         return null;
     };
+}
+
+export function installJobs({ link, tenantId, wsManager, getWorkspaceRoot, config, env = process.env, log = console, runner = null, onResult = null, now = Date.now, memoryUsage, sleep }) {
+    if (dlpConfigFromEnv(env).mode !== "enforce") throw new Error("job.assign needs LOCAL_AGENT_DLP_MODE=enforce");
+    const tenant = String(tenantId).toLowerCase();
+    const resolveWorkspace = makeWorkspaceResolver({ wsManager, getWorkspaceRoot, tenantId: tenant });
     const theRunner = runner || (config.runner === "smoke" ? createSmokeRunner({ maxFileBytes: config.smokeMaxFileBytes }) : null);
     if (!theRunner) throw new Error("job.assign needs a runner");
     const manager = createJobManager({ session: link.session, tenantId: tenant, resolveWorkspace, config, env, llm: link.llm || null,

package/src/la-protocol-v2/jobs/manager.js

@@ -77,7 +77,8 @@ export function createJobManager({ session, tenantId, resolveWorkspace, config,
     const note = (event, extra) => { try { auditor.record({ event, ...extra }); } catch { /* the audit never breaks the data path */ } };
     const reject = (rec, code) => { stats.rejected[code] = (stats.rejected[code] || 0) + 1; note("job_rejected", { code, ...rec }); return { reject: code }; };
 
-    const snapshot = (rec, over = {}) => ({ jobId: rec.jobId, state: rec.state, phase: rec.phase, iteration: rec.iteration, filesRead: rec.filesRead, filesChanged: rec.filesChanged,
+    // `waiting` (a runner that waits for a person: ADR-0010) shows as `waiting_approval` while the job runs; every other state is the job's own
+    const snapshot = (rec, over = {}) => ({ jobId: rec.jobId, state: rec.state === "running" && rec.waiting ? "waiting_approval" : rec.state, phase: rec.phase, iteration: rec.iteration, filesRead: rec.filesRead, filesChanged: rec.filesChanged,
         tokensIn: rec.tokensIn, tokensOut: rec.tokensOut, costUsd: rec.costUsd, durationMs: Math.max(0, now() - rec.acceptedAt), ...over });
     const tokensUsed = (rec) => rec.tokensIn + rec.tokensOut;
     const publish = (rec) => { if (rec.state === "running" || rec.state === "queued") ev.progress(rec, snapshot(rec)); };
@@ -154,20 +155,23 @@ export function createJobManager({ session, tenantId, resolveWorkspace, config,
             if (!llm || !llm.client) { finish(rec, null, Object.assign(new Error("no llm"), { jobErrorCode: "llm_error" })); return; }
             if (!llm.holder.held || !llm.holder.matches(rec.job.llm.keyRef)) { finish(rec, null, Object.assign(new Error("no key"), { jobErrorCode: "llm_error" })); return; }
         }
+        async function llmCall(kind, opts) {
+            if (rec.abortReason || rec.finished) throw new LlmClientError("cancelled");
+            const r = await llm.client[kind]({ ...opts, model: opts.model ?? rec.job.llm.alias, signal: rec.ac.signal, job: { jobId: rec.jobId, agent: theRunner.name }, tokensLeft: Math.max(0, rec.budget.tokens - tokensUsed(rec)) });
+            rec.tokensIn += r.usage.promptTokens;
+            rec.tokensOut += r.usage.completionTokens;
+            if (r.costUsd !== null && r.costUsd !== undefined) rec.costUsd = (rec.costUsd || 0) + r.costUsd;
+            publish(rec);
+            if (tokensUsed(rec) > rec.budget.tokens) abort(rec, "budget_exceeded");   // the next call is refused at equality (client: budget_exceeded); only an overshoot of the provider aborts
+            return r;
+        }
         const ctx = Object.freeze({
             signal: rec.ac.signal,
             workspace: Object.freeze({ id: rec.workspaceId }),
             llm: Object.freeze({
-                async chat(opts = {}) {
-                    if (rec.abortReason || rec.finished) throw new LlmClientError("cancelled");
-                    const r = await llm.client.chat({ ...opts, model: opts.model ?? rec.job.llm.alias, signal: rec.ac.signal, job: { jobId: rec.jobId, agent: theRunner.name }, tokensLeft: Math.max(0, rec.budget.tokens - tokensUsed(rec)) });
-                    rec.tokensIn += r.usage.promptTokens;
-                    rec.tokensOut += r.usage.completionTokens;
-                    if (r.costUsd !== null && r.costUsd !== undefined) rec.costUsd = (rec.costUsd || 0) + r.costUsd;
-                    publish(rec);
-                    if (tokensUsed(rec) > rec.budget.tokens) abort(rec, "budget_exceeded");   // the next call is refused at equality (client: budget_exceeded); only an overshoot of the provider aborts
-                    return r;
-                },
+                chat: (opts = {}) => llmCall("chat", opts),
+                /** F3-08c: one turn of the Anthropic Messages API (tools, content blocks) - what the packaged agent loop speaks. Same gates, same budget. */
+                messages: (opts = {}) => llmCall("messages", opts),
             }),
             async readFile(ref, opts = {}) {
                 // an abandoned, cancelled or timed-out job reads nothing more (no descriptor opened, no buffer built), and what a read that was already
@@ -183,6 +187,7 @@ export function createJobManager({ session, tenantId, resolveWorkspace, config,
                 if (rec.finished) return;
                 if (p.phase) rec.phase = p.phase;
                 for (const k of ["iteration", "filesRead", "filesChanged"]) if (Number.isSafeInteger(p[k]) && p[k] >= 0) rec[k] = p[k];
+                if (typeof p.waitingApproval === "boolean") rec.waiting = p.waitingApproval;
                 publish(rec);
             },
             budget: () => ({ tokensLeft: Math.max(0, rec.budget.tokens - tokensUsed(rec)), msLeft: Math.max(0, rec.startedAt + secondsMs - now()) }),
@@ -229,7 +234,7 @@ export function createJobManager({ session, tenantId, resolveWorkspace, config,
             const budget = { tokens: Math.min(p.budget.tokens, config.maxTokens), seconds: Math.min(p.budget.seconds, config.maxSeconds) };
             const rec = {
                 jobId: p.jobId, short: short(p.jobId), kind: p.kind, workspaceId: ctx.workspaceId, state: "queued", phase: "init", iteration: 0, filesRead: 0, filesChanged: 0,
-                tokensIn: 0, tokensOut: 0, costUsd: null, acceptedAt: now(), startedAt: 0, ac: new AbortController(), abortReason: null, finished: false, ev: null, holdsSlot: false,
+                tokensIn: 0, tokensOut: 0, costUsd: null, waiting: false, acceptedAt: now(), startedAt: 0, ac: new AbortController(), abortReason: null, finished: false, ev: null, holdsSlot: false,
                 reservedBytes: need, deadlineTimer: null, graceTimer: null, budget,
                 job: Object.freeze({ jobId: p.jobId, kind: p.kind, workspaceId: ctx.workspaceId, incidentRef: p.incidentRef, repoRef: p.repoRef, policy: p.policy, budget: Object.freeze({ ...budget }), llm: p.llm, inputs: p.inputs || [], options: opts.options }),
             };

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