deepdebug-local-agent 1.8.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/config.js

@@ -0,0 +1,29 @@
+/**
+ * config.js - LOCAL_AGENT_LLM_KEY flag and limits of the LLM key holder (F3-09 consumer, contract 2.1 (a)).
+ *
+ *   false (default)  `config.update` keeps being acked `rejected protocol_unsupported`, the capability `llm.key` is NOT announced, so
+ *                    the control plane never sends a key: nothing of this folder is loaded.
+ *   true             the agent handles `config.update.llmKey` (set / revoke) and keeps the virtual key of the AI gateway IN MEMORY.
+ *                    Needs LOCAL_AGENT_PROTOCOL_V2=true as well (without a v2 session nobody sends a key: the flag does nothing).
+ *
+ *   LOCAL_AGENT_LLM_KEY_FILE   optional absolute path of a file (mode 0600, directory 0700) where the key survives a restart. It must be
+ *                              OUTSIDE every workspace (a workspace is what the content handlers may serve). Unset = memory only.
+ * Unset/empty/unrecognised = false (an unknown value must never open the door to a key).
+ */
+import path from "node:path";
+
+export const LLM_KEY_FLAG = "LOCAL_AGENT_LLM_KEY";
+
+const TRUE = new Set(["true", "1", "yes", "on"]);
+const FALSE = new Set(["", "false", "0", "no", "off"]);
+
+export function resolveLlmKeyConfig(env = process.env, warn = console.warn) {
+    const raw = String(env[LLM_KEY_FLAG] ?? "").trim().toLowerCase();
+    if (!TRUE.has(raw)) {
+        if (!FALSE.has(raw)) warn(`[la-llm-key] unrecognised ${LLM_KEY_FLAG} value; the LLM key handler stays off`);
+        return { enabled: false };
+    }
+    let file = String(env.LOCAL_AGENT_LLM_KEY_FILE ?? "").trim() || null;
+    if (file && !path.isAbsolute(file)) { warn("[la-llm-key] LOCAL_AGENT_LLM_KEY_FILE must be an absolute path; the key stays in memory only"); file = null; }
+    return { enabled: true, file: file ? path.normalize(file) : null };
+}

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

@@ -0,0 +1,33 @@
+/**
+ * handler.js - `config.update` with `llmKey` (F3-09 consumer, contract 2.1 (a)). Registered by install.js only with
+ * LOCAL_AGENT_LLM_KEY=true. The frame was already validated against the closed schema (a frame that carries `llmKey` carries nothing else);
+ * the session defers the rule `llmKey-id-sha256` to here, so a wrong id is a non-fatal `rejected schema_violation`, as the README says.
+ *
+ *   set     accepted | rejected schema_violation (id is not the sha256 of the key, key already expired)
+ *   revoke  accepted (also for an id this agent does not hold: it never says which key it has)
+ *   others  a `config.update` WITHOUT llmKey (flags, dlp hash, ...) is what it was before: rejected protocol_unsupported
+ * The answer is the plain ack: it never carries the key, the id or any text. Nothing here logs a value of the frame.
+ */
+import { llmKeyIdMismatch } from "../contract.js";
+
+export function createLlmKeyHandler({ holder }) {
+    const stats = { frames: 0, set: 0, revoke: 0, rejected: 0, other: 0 };
+    return {
+        stats,
+        handle(ctx) {
+            stats.frames++;
+            const k = ctx.params && ctx.params.llmKey;
+            if (!k) { stats.other++; return { reject: "protocol_unsupported" }; }
+            if (k.op === "revoke") { stats.revoke++; holder.revoke(k.keyId); return { accept: true }; }
+            if (k.op === "set") {
+                if (llmKeyIdMismatch(k)) { stats.rejected++; return { reject: "schema_violation" }; }
+                const r = holder.set(k);
+                if (!r.ok) { stats.rejected++; return { reject: r.code }; }
+                stats.set++;
+                return { accept: true };
+            }
+            stats.rejected++;
+            return { reject: "schema_violation" };
+        },
+    };
+}

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

@@ -0,0 +1,21 @@
+/**
+ * install.js - puts the LLM key holder on a v2 link (F3-09 consumer). Called by runtime.js only when LOCAL_AGENT_LLM_KEY=true and v2 is on.
+ * Returns link.llm = { holder, handler, request(path, init) }.
+ */
+import { createAudit } from "../content-handlers/audit.js";
+import { createLlmKeyHolder } from "./store.js";
+import { createLlmKeyHandler } from "./handler.js";
+
+export const LLM_KEY_CAPABILITIES = Object.freeze(["llm.key"]);
+
+export function installLlmKey({ link, config, workspaceRoots = () => [], log = console, now = Date.now }) {
+    const audit = createAudit({});   // ring only: a key event never goes to a file the operator did not ask for
+    const holder = createLlmKeyHolder({ file: config.file, workspaceRoots, now, audit, log });
+    holder.load();
+    const handler = createLlmKeyHandler({ holder });
+    link.session.setHandler("config.update", (ctx) => handler.handle(ctx));
+    const closeLink = link.close.bind(link);
+    link.close = () => { holder.close(); closeLink(); };
+    link.llm = { holder, handler, audit, request: (p, init, opts) => holder.request(p, init, opts) };
+    return link.llm;
+}