deepdebug-local-agent 1.9.0 → 1.11.0

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

@@ -0,0 +1,432 @@
+/**
+ * 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 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;
+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(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 };
+                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) : 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 }
+                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
+        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 = makeBody(tags);
+            stats.bytesOut += byteLength(bodyText);
+            let attempts = 0;
+            for (;;) {
+                attempts++;
+                try {
+                    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, ...(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;
+                    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--;
+        }
+    }
+
+    // ------------------------------------------------------------------------------------------------ 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

@@ -0,0 +1,63 @@
+/**
+ * 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
+        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
+        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(); },