deepdebug-local-agent 1.9.0 → 1.10.0

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

@@ -0,0 +1,311 @@
+/**
+ * client.js - the Local Agent's LLM client (F3-10). One job: send a chat to the AI gateway the control plane named, with the virtual key the
+ * llm-key holder keeps, and give back the text and the usage. OpenAI-compatible `chat/completions`, optional streaming.
+ *
+ * Order of every call (nothing leaves before the DLP, nothing is read before the checks):
+ *   1. shape of the request (model name, messages) -> `bad_request`
+ *   2. DLP must be `enforce` (read per call) -> `dlp_not_enforced`
+ *   3. a valid key is held and the model is one of its aliases -> `no_key` | `key_expired` | `model_not_allowed`
+ *   4. EVERY message is masked with the agent's DLP (src/dlp); a hit of a blocked class, a DLP failure or an oversize input is refused
+ *      (`dlp_blocked` | `dlp_denied`); the masked prompt is capped (`prompt_too_large`) and checked against the token budget (`budget_exceeded`)
+ *   5. a concurrency slot (`busy`), then the HTTP call through `holder.request()` (the ONLY way out for the key: https endpoint from the
+ *      control plane, `Authorization` header set by the holder, no redirects) with a timeout per attempt, a total deadline and a few
+ *      retries (network error, 408, 429, 5xx; never after a streamed delta was delivered; never a 4xx)
+ *   6. the response is read under a byte cap; errors are CODES only
+ *
+ * What it never does: log, audit, throw or return a prompt, a response, the key, its id or the body of an error response. The audit record
+ * has the alias, byte counts, token counts, per-rule redaction COUNTS and a short hash of the job id. Tags (`metadata.tags`) carry ids only.
+ */
+import { dlpConfigFromEnv, protectEgress, DENIED } from "../../dlp/index.js";
+import { OVERSIZE } from "../../dlp/engine.js";
+import { createAudit, short } from "../content-handlers/audit.js";
+
+/** The complete list of error codes of this client (a test pins it: no free text ever travels in an error). */
+export const LLM_ERROR_CODES = Object.freeze([
+    "bad_request", "dlp_not_enforced", "no_key", "key_expired", "model_not_allowed", "dlp_blocked", "dlp_denied", "prompt_too_large",
+    "budget_exceeded", "busy", "key_rejected", "rate_limited", "timeout", "network_error", "upstream_error", "response_too_large",
+    "bad_response", "cancelled", "internal",
+]);
+
+export class LlmClientError extends Error {
+    constructor(code, { attempts = 0 } = {}) {
+        const known = LLM_ERROR_CODES.includes(code) ? code : "internal";   // the message is the code, never free text
+        super(known);
+        this.name = "LlmClientError";
+        this.code = known;
+        this.attempts = attempts;
+    }
+}
+
+const MODEL = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,95}$/;
+const ROLES = new Set(["system", "user", "assistant"]);
+const COST_HEADER = "x-litellm-response-cost";
+const MAX_SSE_LINE_BYTES = 256 * 1024;
+const utf8 = new TextEncoder();
+const byteLength = (s) => utf8.encode(s).length;
+const estimateTokens = (bytes) => Math.ceil(bytes / 3);   // pessimistic (code and non-English text are denser than 4 bytes/token)
+
+const defaultSleep = (ms, signal) => new Promise((resolve) => {
+    const t = setTimeout(done, ms);
+    function done() { signal?.removeEventListener("abort", done); clearTimeout(t); resolve(); }
+    signal?.addEventListener("abort", done, { once: true });
+});
+
+function addCounts(into, from) { for (const [k, v] of Object.entries(from || {})) into[k] = (into[k] || 0) + v; }
+
+/**
+ * @param {object} o
+ * @param {{request:Function, describe:Function, held:boolean}} o.holder  the llm-key holder (link.llm.holder)
+ * @param {object} o.config                                                resolveLlmClientConfig()
+ * @param {string} o.tenantId @param {string} o.agentId                    only for the request tags
+ * @param {object} [o.env]                                                 LOCAL_AGENT_DLP_* (read per call)
+ * @param {object} [o.audit]                                               createAudit() (a ring by default)
+ * @param {Function} [o.fetchImpl]                                         tests only; production uses globalThis.fetch through the holder
+ */
+export function createLlmClient({ holder, config, tenantId, agentId, env = process.env, audit = null, now = Date.now, sleep = defaultSleep, fetchImpl = undefined }) {
+    const auditor = audit || createAudit({ file: config.auditFile, now });
+    const stats = { calls: 0, ok: 0, failed: 0, retries: 0, bytesOut: 0, bytesIn: 0, tokensIn: 0, tokensOut: 0, byCode: {} };
+    let active = 0;
+
+    const record = (rec) => { try { auditor.record({ event: "llm_call", ...rec }); } catch { /* the audit never breaks the data path */ } };
+    const fail = (code, ctx, attempts = 0) => {
+        const err = new LlmClientError(code, { attempts });
+        stats.failed++;
+        stats.byCode[err.code] = (stats.byCode[err.code] || 0) + 1;
+        record({ ok: false, code: err.code, model: ctx.model, jobShort: ctx.jobShort, promptBytes: ctx.promptBytes, attempts, redactions: ctx.redactions, ms: now() - ctx.t0, stream: ctx.stream });
+        throw err;
+    };
+
+    /** Masks every message; returns the masked messages, their size and the per-rule counts. Throws a code (string) on refusal. */
+    function maskMessages(messages, ctx) {
+        const out = [];
+        let bytes = 0;
+        for (const m of messages) {
+            const res = protectEgress(m.content, { 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";
+            bytes += byteLength(res.text);
+            if (bytes > config.maxPromptBytes) throw "prompt_too_large";
+            out.push({ role: m.role, content: res.text });
+        }
+        return { masked: out, bytes };
+    }
+
+    function parseCost(headers) {
+        const raw = headers && typeof headers.get === "function" ? headers.get(COST_HEADER) : null;
+        const n = raw === null || raw === undefined || raw === "" ? NaN : Number(raw);
+        return Number.isFinite(n) && n >= 0 && n <= 100_000 ? n : null;
+    }
+
+    /** One attempt. Returns the parsed answer, or throws { code, retry, after? } (never text). */
+    async function attempt(bodyText, o, ctx) {
+        const ac = new AbortController();
+        let reason = null;
+        const abort = (why) => { if (!reason) { reason = why; ac.abort(); } };
+        const onExternal = () => abort("cancelled");
+        if (o.signal) { if (o.signal.aborted) throw { code: "cancelled", retry: false }; o.signal.addEventListener("abort", onExternal, { once: true }); }
+        let timer = setTimeout(() => abort("timeout"), Math.min(config.timeoutMs, Math.max(1, ctx.deadline - now())));
+        const rearm = (ms) => { clearTimeout(timer); timer = setTimeout(() => abort("timeout"), Math.min(ms, Math.max(1, ctx.deadline - now()))); };
+        const lift = (e) => ({ code: reason === "cancelled" ? "cancelled" : reason === "timeout" ? "timeout" : e?.code && LLM_ERROR_CODES.includes(e.code) ? e.code : "network_error", retry: reason !== "cancelled" });
+        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);
+            } 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 };
+                throw lift(e);
+            }
+            const status = res.status;
+            if (status < 200 || status >= 300) {
+                try { await res.body?.cancel(); } catch { /* the body of an error response is never read: it may echo the prompt */ }
+                const ra = res.headers?.get?.("retry-after");
+                const retryAfter = ra === null || ra === undefined || ra === "" ? NaN : Number(ra);   // seconds; an HTTP date is ignored
+                const after = Number.isFinite(retryAfter) && retryAfter >= 0 ? Math.min(retryAfter * 1000, config.maxBackoffMs) : undefined;
+                if (status === 401 || status === 403) throw { code: "key_rejected", retry: false };
+                if (status === 408) throw { code: "timeout", retry: true, after };
+                if (status === 429) throw { code: "rate_limited", retry: true, after };
+                if (status === 413) throw { code: "prompt_too_large", retry: false };
+                if (status >= 500) throw { code: "upstream_error", retry: true, after };
+                throw { code: "bad_request", retry: false };   // other 4xx: the request itself is wrong (alias unknown to the proxy, schema): repeating it changes nothing
+            }
+            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);
+                return { ...parsed, costUsd };
+            } catch (e) {
+                if (e && e.code && !e.name) throw e;   // our own { code, retry }
+                throw lift(e);
+            }
+        } finally {
+            clearTimeout(timer);
+            o.signal?.removeEventListener("abort", onExternal);
+        }
+    }
+
+    async function readBounded(body, maxBytes) {
+        const reader = body.getReader();
+        const chunks = [];
+        let total = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            total += value.byteLength;
+            if (total > maxBytes) { try { await reader.cancel(); } catch { /* gone */ } throw { code: "response_too_large", retry: false }; }
+            chunks.push(value);
+        }
+        return Buffer.concat(chunks.map((c) => Buffer.from(c.buffer, c.byteOffset, c.byteLength))).toString("utf8");
+    }
+
+    async function readJson(body, maxBytes) {
+        const text = await readBounded(body, maxBytes);
+        let j;
+        try { j = JSON.parse(text); } catch { throw { code: "bad_response", retry: false }; }
+        const choice = j && Array.isArray(j.choices) ? j.choices[0] : null;
+        const msg = choice && choice.message;
+        if (!choice || !msg || (msg.content !== null && msg.content !== undefined && typeof msg.content !== "string")) throw { code: "bad_response", retry: false };
+        return { text: msg.content || "", usage: usageOf(j.usage), model: modelOf(j.model), finishReason: typeof choice.finish_reason === "string" ? choice.finish_reason.slice(0, 32) : null };
+    }
+
+    async function readStream(body, o, rearm, ctx) {
+        const reader = body.getReader();
+        const dec = new TextDecoder("utf-8");
+        let buf = "";
+        let text = "";
+        let textBytes = 0;
+        let usage = null;
+        let model = null;
+        let finish = null;
+        let done = false;
+        const handleData = (data) => {
+            if (data === "[DONE]") { done = true; return; }
+            let j;
+            try { j = JSON.parse(data); } catch { throw { code: "bad_response", retry: false }; }
+            if (j && j.error) throw { code: "upstream_error", retry: false };
+            if (j && j.usage) usage = usageOf(j.usage);
+            if (j && typeof j.model === "string") model = modelOf(j.model);
+            const c = j && Array.isArray(j.choices) ? j.choices[0] : null;
+            if (!c) return;
+            if (typeof c.finish_reason === "string") finish = c.finish_reason.slice(0, 32);
+            const d = c.delta && typeof c.delta.content === "string" ? c.delta.content : "";
+            if (d) {
+                textBytes += byteLength(d);
+                if (textBytes > config.maxResponseBytes) throw { code: "response_too_large", retry: false };
+                text += d;
+                ctx.delivered = true;
+                if (typeof o.onDelta === "function") { try { o.onDelta(d); } catch { /* a consumer's bug never breaks the call */ } }
+            }
+        };
+        const handleLine = (line) => { if (line.startsWith("data:")) handleData(line.slice(5).trim()); };
+        rearm(config.streamIdleMs);
+        while (!done) {
+            const { done: eof, value } = await reader.read();
+            if (eof) break;
+            rearm(config.streamIdleMs);   // silence, not total time, is what the idle timeout measures (the total deadline still caps it)
+            buf += dec.decode(value, { stream: true });
+            let nl;
+            while ((nl = buf.search(/\r?\n/)) >= 0) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(buf[nl] === "\r" ? nl + 2 : nl + 1);
+                handleLine(line);
+                if (done) break;
+            }
+            if (buf.length > MAX_SSE_LINE_BYTES) throw { code: "bad_response", retry: false };
+        }
+        if (!done && buf.trim()) handleLine(buf.trim());
+        try { await reader.cancel(); } catch { /* closed */ }
+        if (!done && !finish && !text && !usage) throw { code: "bad_response", retry: false };
+        return { text, usage, model, finishReason: finish };
+    }
+
+    function usageOf(u) {
+        if (!u || typeof u !== "object") return null;
+        const p = Number(u.prompt_tokens);
+        const c = Number(u.completion_tokens);
+        return Number.isSafeInteger(p) && p >= 0 && Number.isSafeInteger(c) && c >= 0 ? { promptTokens: p, completionTokens: c, estimated: false } : null;
+    }
+    const modelOf = (m) => (typeof m === "string" && MODEL.test(m) ? m : null);
+
+    /**
+     * @param {object} o
+     * @param {string} o.model                         an alias of the key (`link.llm.holder.describe().models`)
+     * @param {{role:"system"|"user"|"assistant",content:string}[]} o.messages
+     * @param {number} [o.maxTokens]                   capped by the config and by what is left of the budget
+     * @param {number} [o.temperature]
+     * @param {boolean} [o.stream] @param {(delta:string)=>void} [o.onDelta]
+     * @param {AbortSignal} [o.signal]                 cancellation (job.cancel, deadline)
+     * @param {{jobId?:string, agent?:string}} [o.job] tags only
+     * @param {number} [o.tokensLeft]                  what is left of the job budget (prompt estimate + max_tokens must fit)
+     * @returns {Promise<{text:string, usage:{promptTokens:number,completionTokens:number,estimated:boolean}, costUsd:number|null, model:string, finishReason:string|null, attempts:number}>}
+     */
+    async function chat(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: !!o.stream, delivered: false, deadline: now() + config.totalMs };
+        // 1. shape
+        const msgs = o.messages;
+        if (typeof o.model !== "string" || !MODEL.test(o.model) || !Array.isArray(msgs) || msgs.length < 1 || msgs.length > config.maxMessages
+            || !msgs.every((m) => m && typeof m === "object" && ROLES.has(m.role) && typeof m.content === "string")) return fail("bad_request", ctx);
+        if (o.temperature !== undefined && !(Number.isFinite(o.temperature) && o.temperature >= 0 && o.temperature <= 2)) return fail("bad_request", ctx);
+        if (o.signal?.aborted) return fail("cancelled", ctx);
+        // 2. DLP enforce, per call
+        if (dlpConfigFromEnv(env).mode !== "enforce") return fail("dlp_not_enforced", ctx);
+        // 3. key and alias
+        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);
+        // 4. mask first, then size and budget
+        let masked;
+        try {
+            const r = maskMessages(msgs, ctx);
+            masked = r.masked; ctx.promptBytes = r.bytes;
+        } catch (code) {
+            return fail(typeof code === "string" ? code : "dlp_denied", ctx);
+        }
+        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);
+        }
+        // 5. slot and the call
+        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 } : {}),
+            });
+            stats.bytesOut += byteLength(bodyText);
+            let attempts = 0;
+            for (;;) {
+                attempts++;
+                try {
+                    const r = await attempt(bodyText, o, 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 };
+                } 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;
+                    if (!canRetry) return fail(code, ctx, attempts);
+                    const wait = Math.min(e.after ?? config.backoffMs * 2 ** (attempts - 1), config.maxBackoffMs);
+                    if (now() + wait >= ctx.deadline) return fail(code, ctx, attempts);
+                    stats.retries++;
+                    await sleep(wait, o.signal);
+                    if (o.signal?.aborted) return fail("cancelled", ctx, attempts);
+                }
+            }
+        } finally {
+            active--;
+        }
+    }
+
+    return { chat, stats, audit: auditor, get active() { return active; } };
+}

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

@@ -0,0 +1,61 @@
+/**
+ * config.js - LOCAL_AGENT_LLM_CLIENT flag and limits of the Local Agent's LLM client (F3-10).
+ *
+ *   false (default)  there is NO LLM client: `link.llm.client` does not exist, the key holder (F3-09) only holds the key.
+ *   true             `link.llm.client.chat()` calls the AI gateway (the endpoint the control plane delivered with the key, OpenAI-compatible
+ *                    chat/completions) with the virtual key held by the llm-key holder. It needs, all three:
+ *                      LOCAL_AGENT_PROTOCOL_V2=true   (a v2 session: nobody delivers a key without it)
+ *                      LOCAL_AGENT_LLM_KEY=true       (the holder: the client has no key of its own)
+ *                      LOCAL_AGENT_DLP_MODE=enforce   (prompts leave this machine only masked; there is no opt-out)
+ *                    runtime.js refuses (and says so) when one is missing.
+ *
+ * Unset/empty/unrecognised = false (an unknown value must never open a way out for client content).
+ * Every number is clamped: a bad value falls back to the default, never to "unlimited".
+ */
+export const LLM_CLIENT_FLAG = "LOCAL_AGENT_LLM_CLIENT";
+
+const TRUE = new Set(["true", "1", "yes", "on"]);
+const FALSE = new Set(["", "false", "0", "no", "off"]);
+const KIB = 1024;
+const MIB = 1024 * KIB;
+
+function int(raw, def, min, max) {
+    const n = Number.parseInt(String(raw ?? ""), 10);
+    return Number.isFinite(n) && n >= min && n <= max ? n : def;
+}
+
+const bool = (raw, def) => {
+    const v = String(raw ?? "").trim().toLowerCase();
+    if (TRUE.has(v)) return true;
+    if (v !== "" && FALSE.has(v)) return false;
+    return def;
+};
+
+const PATH = /^\/(?!\/)[A-Za-z0-9._~/-]{1,200}$/;
+
+export function resolveLlmClientConfig(env = process.env, warn = console.warn) {
+    const raw = String(env[LLM_CLIENT_FLAG] ?? "").trim().toLowerCase();
+    if (!TRUE.has(raw)) {
+        if (!FALSE.has(raw)) warn(`[la-llm] unrecognised ${LLM_CLIENT_FLAG} value; the LLM client stays off`);
+        return { enabled: false };
+    }
+    let path = String(env.LOCAL_AGENT_LLM_PATH ?? "").trim() || "/v1/chat/completions";
+    if (!PATH.test(path) || path.split("/").includes("..")) { warn("[la-llm] LOCAL_AGENT_LLM_PATH is not a plain absolute path; using /v1/chat/completions"); path = "/v1/chat/completions"; }
+    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
+        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
+        maxRetries: int(env.LOCAL_AGENT_LLM_MAX_RETRIES, 2, 0, 5),
+        backoffMs: int(env.LOCAL_AGENT_LLM_BACKOFF_MS, 500, 0, 10_000),
+        maxBackoffMs: 10_000,
+        maxPromptBytes: int(env.LOCAL_AGENT_LLM_MAX_PROMPT_BYTES, 256 * KIB, KIB, 2 * MIB),       // all messages, after masking
+        maxOutputTokens: int(env.LOCAL_AGENT_LLM_MAX_OUTPUT_TOKENS, 4_096, 1, 32_768),
+        maxResponseBytes: int(env.LOCAL_AGENT_LLM_MAX_RESPONSE_BYTES, 1 * MIB, 4 * KIB, 8 * MIB),
+        maxMessages: 64,
+        maxConcurrent: int(env.LOCAL_AGENT_LLM_MAX_CONCURRENT, 4, 1, 16),
+        tags: bool(env.LOCAL_AGENT_LLM_TAGS, true),                      // request metadata.tags (tenant, agent, job); ids only, never content
+        auditFile: String(env.LOCAL_AGENT_LLM_AUDIT_FILE ?? "").trim() || null,
+    };
+}

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

@@ -0,0 +1,17 @@
+/**
+ * install.js - puts the LLM client on the key holder (F3-10). Called by runtime.js only when LOCAL_AGENT_LLM_CLIENT=true, LOCAL_AGENT_LLM_KEY=true
+ * (link.llm exists) and LOCAL_AGENT_DLP_MODE=enforce. Hooks `link.llm.request` (the holder's one way out for the key) into the client:
+ * the client has no other way to reach the AI gateway. Returns the client; also at `link.llm.client`.
+ */
+import { dlpConfigFromEnv } from "../../dlp/index.js";
+import { createLlmClient } from "./client.js";
+
+export function installLlmClient({ link, config, tenantId, agentId, env = process.env, now = Date.now, fetchImpl }) {
+    if (!link.llm || !link.llm.holder) throw new Error("the LLM client needs the llm-key holder (LOCAL_AGENT_LLM_KEY=true)");
+    // F3-07b/F3-10, defence in depth: runtime.js already refuses; nobody can install the client without DLP enforce
+    if (dlpConfigFromEnv(env).mode !== "enforce") throw new Error("the LLM client needs LOCAL_AGENT_DLP_MODE=enforce");
+    const client = createLlmClient({ holder: { request: link.llm.request, describe: () => link.llm.holder.describe(), get held() { return link.llm.holder.held; } },
+        config, tenantId: String(tenantId).toLowerCase(), agentId: String(agentId).toLowerCase(), env, now, fetchImpl });
+    link.llm.client = client;
+    return client;
+}

package/src/la-protocol-v2/llm-key/store.js

@@ -150,6 +150,16 @@ export function createLlmKeyHolder({ file = null, workspaceRoots = () => [], now
                 return true;
             } catch { return false; }
         },
+        /**
+         * F3-10: does this reference (`job.assign.llm.keyRef`) name the key held right now? Compares in constant time and answers a boolean only:
+         * the id never leaves the holder. A reference is the key id or its first 8..64 hex characters (the `key_short` the control plane logs).
+         */
+        matches(ref) {
+            if (!active() || typeof ref !== "string" || !/^[0-9a-f]{8,64}$/.test(ref)) return false;
+            const a = Buffer.from(held.keyId.slice(0, ref.length));
+            const b = Buffer.from(ref);
+            return a.length === b.length && crypto.timingSafeEqual(a, b);
+        },
         /** Metadata only. */
         describe() { return active() ? { held: true, models: [...held.models], expiresAt: held.expiresAt } : { held: false }; },
         get held() { return active(); },

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,10 +73,33 @@ 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;
+    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"] : [];   // 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.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 link = createV2Link({
@@ -86,7 +111,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, ...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 +141,14 @@ 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 });
+    }
     let webhookSource = null;
     if (webhookCfg.enabled) {
         const { createWebhookSource } = await import("../incident-detector/sources/webhook-source.js");