deepdebug-local-agent 1.9.0 → 1.11.0

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

@@ -10,6 +10,8 @@ import { createV2Link } from "./link.js";
 import { resolveContentHandlersConfig } from "./content-handlers/config.js";
 import { resolveLlmKeyConfig } from "./llm-key/config.js";
 import { resolveWebhookConfig } from "./webhooks/config.js";
+import { resolveLlmClientConfig } from "./llm/config.js";
+import { resolveJobsConfig } from "./jobs/config.js";
 import { loadContract } from "./contract.js";
 
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
@@ -38,7 +40,7 @@ async function diskFreeBytes(dir) {
 /**
  * @returns {Promise} the link, or null (with a warning) when v2 cannot run here: then the tunnel is the plain v1 client.
  */
-export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWorkspaceRoot, log = console, env = process.env }) {
+export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWorkspaceRoot, log = console, env = process.env, jobRunner = null, onJobResult = null, llmFetch = undefined }) {
     const tenant = String(tenantId || "").toLowerCase();
     if (!UUID.test(tenant)) { log.warn("[la-v2] off: the tenant id is not a UUID"); return null; }
     if (!agentId) { log.warn("[la-v2] off: no agent id (authorizationId in ~/.deepdebug/config.json or LOCAL_AGENT_ID)"); return null; }
@@ -71,12 +73,59 @@ export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWo
     }
     // F3-09 consumer: virtual LLM key of the AI gateway (config.update.llmKey), behind LOCAL_AGENT_LLM_KEY (default off)
     const llmCfg = resolveLlmKeyConfig(env, (m) => log.warn(m));
+    // F3-10: LLM client (LOCAL_AGENT_LLM_CLIENT) and job.assign receiver (LOCAL_AGENT_JOBS), both default off. Both need DLP enforce (no opt-out);
+    // the client needs the key holder; the receiver needs a runner (and the client unless the runner says it does not think).
+    const dlpEnforce = async () => (await import("../dlp/index.js")).dlpConfigFromEnv(env).mode === "enforce";
+    const err = (m) => (log.error || log.warn).call(log, m);
+    let llmClientCfg = resolveLlmClientConfig(env, (m) => log.warn(m));
+    if (llmClientCfg.enabled && !llmCfg.enabled) { err("[la-llm] ERROR: LOCAL_AGENT_LLM_CLIENT=true but LOCAL_AGENT_LLM_KEY is not true: there is no key holder, the LLM client is NOT installed"); llmClientCfg = { enabled: false }; }
+    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;
+        const needsLlm = given ? given.needsLlm !== false : jobsCfg.runner === "smoke";
+        if (jobRunner && !given) err("[la-jobs] ERROR: the runner passed to buildV2Link does not implement start()/cancel(); it is ignored");
+        if (!given && !jobsCfg.runner) { err("[la-jobs] ERROR: LOCAL_AGENT_JOBS=true but there is no runner (LOCAL_AGENT_JOBS_RUNNER=smoke or an injected one): job.assign is NOT registered"); jobsCfg = { enabled: false }; }
+        else if (!(await dlpEnforce())) { err("[la-jobs] ERROR: LOCAL_AGENT_JOBS=true but LOCAL_AGENT_DLP_MODE is not enforce: job.assign is NOT registered and no job capability is announced"); jobsCfg = { enabled: false }; }
+        else if (needsLlm && !llmClientCfg.enabled) { err("[la-jobs] ERROR: LOCAL_AGENT_JOBS=true with a runner that needs the LLM client, but the client is not installed (LOCAL_AGENT_LLM_CLIENT, LOCAL_AGENT_LLM_KEY, DLP enforce): job.assign is NOT registered"); jobsCfg = { enabled: false }; }
+        else runner = given;
+    }
     const hasIncidentSource = incidentCfg.enabled && (incidentCfg.files.length > 0 || incidentCfg.stdin || !!incidentCfg.loki || webhookCfg.enabled);
     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", ...(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: {
@@ -86,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, ...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"] : []),
@@ -116,6 +165,23 @@ export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWo
         const roots = () => [getWorkspaceRoot(), ...(wsManager?.list?.() || []).map((w) => w && w.root)].filter(Boolean);
         installLlmKey({ link, config: llmCfg, workspaceRoots: roots, log });
     }
+    if (llmClientCfg.enabled) {
+        const { installLlmClient } = await import("./llm/install.js");
+        installLlmClient({ link, config: llmClientCfg, tenantId: tenant, agentId, env, ...(llmFetch ? { fetchImpl: llmFetch } : {}) });
+    }
+    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) {
         const { createWebhookSource } = await import("../incident-detector/sources/webhook-source.js");

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 };
 }