deepdebug-local-agent 1.4.0 → 1.5.0

package/docs/la-protocol-v2.md

@@ -50,18 +50,52 @@ It also needs `TENANT_ID` to be a UUID and the agent id (`authorizationId` of `~
   answers in the v1 shape. **The gateway (F3-05a) still refuses to send v1 commands to a v2 agent
   (`protocol_mismatch`)**: this is ready on the LA side, but it will only be exercised once the gateway sends them.
 
+## Content handlers (F3-07, `LOCAL_AGENT_CONTENT_HANDLERS`, default false)
+
+Needs `LOCAL_AGENT_PROTOCOL_V2=true` too. Off (unset, empty, `false` or any unknown value): `content.request` is acked
+`rejected protocol_unsupported` exactly as before and the register announces no `content.*` capability. On: kinds
+`file` and `diff` are served (capabilities `content.file`, `content.diff`); any other kind of the allowlist answers
+`content.response` `status:"error"` + `errorCode:"protocol_unsupported"`.
+
+- **Opaque ids.** The `ref` is an id (`cr1_` + 128 random bits, base64url) minted by the agent, never derived from a path.
+  It maps in memory to (tenant, workspace, root, kind, relative path), lives `LOCAL_AGENT_CONTENT_REF_TTL_MS` (15 min) and
+  is forgotten when the agent restarts. Anything that is not a live id for this tenant+workspace+root+kind (unknown,
+  expired, another workspace, a path, `../x`) is `not_found` and is never echoed. The only other ref is the symbolic
+  `worktree` for kind `diff` (the work tree of the envelope's workspace). Whoever reports metadata to the control plane
+  gets an id with `link.content.mintRef({workspaceId, kind, rel})` (no caller yet: see the F3-07 note).
+- **The agent is the authority on paths.** Workspace must be registered here and belong to this tenant; the real path
+  must stay inside the real root (a link that leaves it is `forbidden`), must not be sensitive under its real name,
+  must be a regular file opened without following links. Sensitive by default: `.env*`, `*.pem`, `*.key`, `*.p12`,
+  `id_rsa*`..., `.npmrc`, `.netrc`, `*.tfstate`, `.git/`, `.ssh/`, `.aws/`, `.docker/`... (`LOCAL_AGENT_CONTENT_DENY_GLOBS`
+  adds to the list). No id is ever minted for them.
+- **DLP before anything leaves** (`LOCAL_AGENT_DLP_MODE`, the module `src/dlp`): `enforce` masks the whole text before it is
+  chunked (a secret cannot straddle chunks), withholds a file with a hit in `LOCAL_AGENT_DLP_BLOCK_CLASSES`, and fails
+  closed for binary files, inputs above `LOCAL_AGENT_DLP_MAX_BYTES` and DLP errors. `warn` and `off` send the content as
+  read (warn only counts). The agent warns at start-up when handlers are on and the mode is not `enforce`.
+- **Limits.** `LOCAL_AGENT_CONTENT_MAX_BYTES` per response (default 1 MiB, ceiling 2 MiB = 64 chunks; a file above it is
+  `payload_too_large` without being read), `LOCAL_AGENT_CONTENT_MAX_CONCURRENT` (4) and `..._MAX_INFLIGHT_BYTES`
+  (`rate_limited` above), `LOCAL_AGENT_CONTENT_TOTAL_MS` (25 s), the session window (8 chunks in flight, backpressure).
+  Cancellation: `handler.cancel(requestId)`, the deadline, closing the link, or loss of the session.
+- **Diff.** `git diff HEAD` of the work tree, no shell, without external diff/textconv/fsmonitor, without any `GIT_*` of
+  the agent's env, only for files that pass the same deny list, at most `LOCAL_AGENT_CONTENT_MAX_DIFF_FILES` (500).
+- **Audit.** One local record per request (kind, status, code, sizes, DLP mode and per-rule counts, a short hash of the
+  ref): in memory and optionally `LOCAL_AGENT_CONTENT_AUDIT_FILE` (JSONL, 0600, rotates at 5 MiB). Never content,
+  paths or the ref.
+
 ## What it does NOT do
 
-No handler of `content.request` (F3-07), no DLP on what is sent (F3-09, must run before `sendContent` is
-called), no log/incident detector (F3-11b), no `job.assign` runtime (F3-08). Those frames are acked
-`rejected protocol_unsupported`. `sha256` of `content.response` is not sent (the contract does not say what it covers).
+No handler for the other kinds (`incident.*`, `log.*`, `chat.session`, `wiki.page`, `job.*`, `approval.detail`, `report`),
+no inventory frame that tells the control plane which ids exist (the contract has none), no log/incident detector
+(F3-11b), no `job.assign` runtime (F3-08). Those frames are acked `rejected protocol_unsupported`. `sha256` of
+`content.response` is not sent (the contract does not say what it covers).
 
 ## Tests
 
 `npm test` (node:test), all in `test/la-protocol-v2/`:
 `contract.test.js` (all 134 vectors of F3-22, valid and invalid, plus the drift check), `traces.test.js` (the 24
 traces), `session-inbound.test.js`, `session-outbound.test.js`, `link.test.js`, `tunnel-e2e.test.js` (the real
-`src/server.js` against a reference CP; flag off = v1 frames). The reference CP (`test/la-protocol-v2/helpers/reference-cp.js`)
+`src/server.js` against a reference CP; flag off = v1 frames), and for F3-07 `content-path-guard.test.js`,
+`content-handlers.test.js`, `content-wiring.test.js` (flag, runtime wiring, real `src/server.js`). The reference CP (`test/la-protocol-v2/helpers/reference-cp.js`)
 is a Node model of the gateway rules, not the gateway.
 
 **Interoperability with the real gateway session** (`LaV2Session`, Java, real Reactor Netty socket on loopback, real

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepdebug-local-agent",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "DeepDebug Local Agent - AI-powered code debugging assistant",
   "private": false,
   "type": "module",

package/src/la-protocol-v2/content-handlers/audit.js

@@ -0,0 +1,36 @@
+/**
+ * audit.js - local audit of served content (F3-07). One record per content.request, NEVER the content, a path or
+ * the ref: kind, status, sizes, DLP mode and per-rule counts, timing, a short hash of the ref and of the user id.
+ *
+ *   ring    the last `ringSize` records in memory (tests, support, future heartbeat summary)
+ *   file    optional JSONL (LOCAL_AGENT_CONTENT_AUDIT_FILE), mode 0600; at `maxFileBytes` it rotates to <file>.1
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+
+export const short = (v) => crypto.createHash("sha256").update(String(v ?? "")).digest("hex").slice(0, 16);
+
+export function createAudit({ file = null, ringSize = 500, maxFileBytes = 5 * 1024 * 1024, now = Date.now } = {}) {
+    const ring = [];
+    let written = 0;
+    let broken = false;
+    if (file) { try { written = fs.statSync(file).size; } catch { written = 0; } }
+    return {
+        record(entry) {
+            const rec = { ts: new Date(now()).toISOString(), ...entry };
+            ring.push(rec);
+            if (ring.length > ringSize) ring.shift();
+            if (file && !broken) {
+                try {
+                    const line = JSON.stringify(rec) + "\n";
+                    if (written + line.length > maxFileBytes) { fs.renameSync(file, `${file}.1`); written = 0; }
+                    fs.appendFileSync(file, line, { mode: 0o600 });
+                    written += line.length;
+                } catch { broken = true; /* auditing to disk must never break the data path; the ring still has it */ }
+            }
+            return rec;
+        },
+        tail(n = 50) { return ring.slice(-n); },
+        get brokenFile() { return broken; },
+    };
+}

package/src/la-protocol-v2/content-handlers/config.js

@@ -0,0 +1,48 @@
+/**
+ * config.js - LOCAL_AGENT_CONTENT_HANDLERS flag and limits of the content.request handlers (F3-07).
+ *
+ *   false (default)  `content.request` keeps being acked `rejected protocol_unsupported`: nothing of this folder is loaded.
+ *   true             handlers for `file` and `diff` are registered. Needs LOCAL_AGENT_PROTOCOL_V2=true as well
+ *                    (without it there is no v2 session and the flag does nothing).
+ *
+ * Unset/empty/unrecognised = false (an unknown value must never open the door to client content).
+ * Every number is clamped: a bad value falls back to the default, never to "unlimited".
+ */
+export const CONTENT_HANDLERS_FLAG = "LOCAL_AGENT_CONTENT_HANDLERS";
+
+const TRUE = new Set(["true", "1", "yes", "on"]);
+const FALSE = new Set(["", "false", "0", "no", "off"]);
+
+const MIB = 1024 * 1024;
+
+function int(raw, def, min, max) {
+    const n = Number.parseInt(String(raw ?? ""), 10);
+    return Number.isFinite(n) && n >= min && n <= max ? n : def;
+}
+
+export function resolveContentHandlersConfig(env = process.env, warn = console.warn) {
+    const raw = String(env[CONTENT_HANDLERS_FLAG] ?? "").trim().toLowerCase();
+    if (!TRUE.has(raw)) {
+        if (!FALSE.has(raw)) warn(`[la-content] unrecognised ${CONTENT_HANDLERS_FLAG} value; content handlers stay off`);
+        return { enabled: false };
+    }
+    const maxConcurrent = int(env.LOCAL_AGENT_CONTENT_MAX_CONCURRENT, 4, 1, 16);
+    const maxBytes = int(env.LOCAL_AGENT_CONTENT_MAX_BYTES, 1 * MIB, 1, 2 * MIB);   // per response (the contract caps it at 2 MiB)
+    return {
+        enabled: true,
+        maxBytes,
+        maxConcurrent,
+        // total bytes held in memory by requests in flight (a response is built whole, masked, then streamed)
+        // (each request reserves 2 x maxBytes: the bytes read and the masked copy)
+        maxInFlightBytes: int(env.LOCAL_AGENT_CONTENT_MAX_INFLIGHT_BYTES, 2 * maxBytes * maxConcurrent, 2 * maxBytes, 256 * MIB),
+        refTtlMs: int(env.LOCAL_AGENT_CONTENT_REF_TTL_MS, 15 * 60_000, 10_000, 24 * 3_600_000),
+        maxRefs: int(env.LOCAL_AGENT_CONTENT_MAX_REFS, 20_000, 100, 200_000),
+        // the gateway gives a request 30 s in total (contract: contentTotalMs)
+        totalMs: int(env.LOCAL_AGENT_CONTENT_TOTAL_MS, 25_000, 1_000, 30_000),
+        gitTimeoutMs: int(env.LOCAL_AGENT_CONTENT_GIT_TIMEOUT_MS, 8_000, 500, 20_000),
+        maxDiffFiles: int(env.LOCAL_AGENT_CONTENT_MAX_DIFF_FILES, 500, 1, 5_000),
+        // additive to the built-in list (path-guard.js); comma separated globs
+        extraDenyGlobs: String(env.LOCAL_AGENT_CONTENT_DENY_GLOBS ?? "").split(",").map((s) => s.trim()).filter(Boolean).slice(0, 200),
+        auditFile: String(env.LOCAL_AGENT_CONTENT_AUDIT_FILE ?? "").trim() || null,
+    };
+}

package/src/la-protocol-v2/content-handlers/egress.js

@@ -0,0 +1,65 @@
+/**
+ * egress.js - everything between "bytes read on this machine" and "bytes handed to sendContent" (F3-07).
+ *
+ * The DLP is the one of the agent (src/dlp, LOCAL_AGENT_DLP_MODE=off|warn|enforce, same rules, same counters):
+ *   off      content goes as read.
+ *   warn     content goes as read; the DLP only counts what enforce WOULD have masked (the existing "warn" meaning).
+ *   enforce  every hit is replaced by [REDACTED:<rule>]; a hit in LOCAL_AGENT_DLP_BLOCK_CLASSES withholds the whole
+ *            content (`forbidden`); an input above LOCAL_AGENT_DLP_MAX_BYTES, a DLP failure, or a binary file (it cannot
+ *            be inspected) never goes out (payload_too_large | internal | forbidden). Fail closed, as in the DLP module.
+ * The WHOLE text is masked before it is split into chunks, so a secret that would straddle two chunks is still found.
+ * A `range` is applied to the bytes AS SERVED (after masking): the offsets are stable between requests.
+ */
+import { dlpConfigFromEnv, protectEgress, DENIED } from "../../dlp/index.js";
+import { OVERSIZE } from "../../dlp/engine.js";
+
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+
+export function decodeText(buffer) {
+    const probe = buffer.subarray(0, 8000);
+    if (probe.includes(0)) return null;
+    try { return utf8.decode(buffer); } catch { return null; }
+}
+
+const EXT_TYPES = new Map([
+    [".md", "text/markdown"], [".markdown", "text/markdown"], [".json", "application/json"],
+    [".diff", "text/x-diff"], [".patch", "text/x-diff"], [".zip", "application/zip"],
+]);
+
+export function contentTypeOf(rel, isText) {
+    const m = /(\.[A-Za-z0-9]+)$/.exec(rel || "");
+    const t = m ? EXT_TYPES.get(m[1].toLowerCase()) : undefined;
+    if (isText) return t && t !== "application/zip" ? t : "text/plain";
+    return t === "application/zip" ? t : "application/octet-stream";
+}
+
+/**
+ * @param {{buffer:Buffer, contentType?:string, range?:{offset:number,length:number}, maxBytes:number, env?:object, source:string}} o
+ * @returns {{ok:true, buffer:Buffer, contentType:string, dlp:{mode:string,total:number,redactions:object}} |
+ *           {ok:false, status:"forbidden"|"error", errorCode?:string, dlp:{mode:string,total:number,redactions:object}}}
+ */
+export function prepareOutgoing({ buffer, contentType, range, maxBytes, env = process.env, source }) {
+    const cfg = dlpConfigFromEnv(env);
+    const dlp = { mode: cfg.mode, total: 0, redactions: {} };
+    let out = buffer;
+    let type = contentType;
+    const text = decodeText(buffer);
+    if (text === null) {
+        if (cfg.mode === "enforce") return { ok: false, status: "forbidden", dlp };      // cannot be inspected: fail closed
+        type = type && !type.startsWith("text/") ? type : "application/octet-stream";
+    } else if (cfg.mode !== "off") {
+        if (cfg.mode === "enforce" && text.length > cfg.maxBytes) return { ok: false, status: "error", errorCode: "payload_too_large", dlp };
+        const res = protectEgress(text, { env, source });
+        dlp.total = res.total;
+        dlp.redactions = res.redactions;
+        if (res.denied || res.text === DENIED) return { ok: false, status: "error", errorCode: "internal", dlp };
+        if (cfg.mode === "enforce") {
+            if (res.blocked) return { ok: false, status: "forbidden", dlp };
+            if (res.text === OVERSIZE) return { ok: false, status: "error", errorCode: "payload_too_large", dlp };
+            out = Buffer.from(res.text, "utf8");
+        }
+    }
+    if (range) out = out.subarray(Math.min(range.offset, out.length), Math.min(range.offset + range.length, out.length));
+    if (out.length > maxBytes) return { ok: false, status: "error", errorCode: "payload_too_large", dlp };
+    return { ok: true, buffer: out, contentType: type || "text/plain", dlp };
+}

package/src/la-protocol-v2/content-handlers/git-diff.js

@@ -0,0 +1,92 @@
+/**
+ * git-diff.js - `diff` kind: the work tree against HEAD, for the files that may be shown (F3-07).
+ *
+ * No shell. git runs with the agent's env minus secret-looking variables and minus every GIT_* variable (a stray
+ * GIT_DIR must not point it at another repository), without external diff drivers, textconv filters or fsmonitor
+ * hooks (a malicious repo config could name a command for each), with literal pathspecs. The file list is taken
+ * first and filtered (sensitive and out-of-root names never reach the second call), then diffed with that explicit list
+ * (at most `maxFiles` names and 128 KiB of arguments). Output is capped while it streams (the process is killed above the cap).
+ */
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import { sanitizedChildEnv } from "../../utils/child-env.js";
+import { isSensitivePath, normalizeRel } from "./path-guard.js";
+
+const GIT_SAFE = ["--literal-pathspecs", "-c", "core.quotepath=off", "-c", "core.fsmonitor=false", "-c", "core.pager=cat", "-c", "diff.external="];
+
+function gitEnv() {
+    const env = sanitizedChildEnv(process.env);
+    for (const k of Object.keys(env)) if (k.startsWith("GIT_")) delete env[k];
+    return { ...env, GIT_TERMINAL_PROMPT: "0", GIT_OPTIONAL_LOCKS: "0", GIT_PAGER: "cat" };
+}
+
+/** @returns {Promise<{code:number|null, out:Buffer, overflow:boolean, timedOut:boolean, aborted:boolean}>} */
+function runGit(args, { cwd, input, maxBytes, timeoutMs, signal }) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn("git", args, { cwd, env: gitEnv(), shell: false, stdio: ["pipe", "pipe", "ignore"], windowsHide: true });
+        } catch {
+            resolve({ code: null, out: Buffer.alloc(0), overflow: false, timedOut: false, aborted: false });
+            return;
+        }
+        const chunks = [];
+        let size = 0;
+        const st = { overflow: false, timedOut: false, aborted: false };
+        const kill = () => { try { child.kill("SIGKILL"); } catch { /* gone */ } };
+        const timer = setTimeout(() => { st.timedOut = true; kill(); }, timeoutMs);
+        const onAbort = () => { st.aborted = true; kill(); };
+        if (signal) { if (signal.aborted) onAbort(); else signal.addEventListener("abort", onAbort, { once: true }); }
+        child.stdout.on("data", (d) => {
+            size += d.length;
+            if (size > maxBytes) { st.overflow = true; kill(); return; }
+            chunks.push(d);
+        });
+        child.stdin.on("error", () => {});
+        child.stdin.end(input || "");
+        child.on("error", () => { clearTimeout(timer); resolve({ code: null, out: Buffer.alloc(0), ...st }); });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            if (signal) signal.removeEventListener("abort", onAbort);
+            resolve({ code, out: Buffer.concat(chunks), ...st });
+        });
+    });
+}
+
+/**
+ * @param {{root:string, rel?:string|null, maxBytes:number, maxFiles:number, timeoutMs:number, denyGlobs?:string[], signal?:AbortSignal}} o
+ * @returns {Promise<{ok:true, text:string} | {ok:false, status:"not_found"|"forbidden"|"error", errorCode?:string}>}
+ */
+export async function worktreeDiff({ root, rel = null, maxBytes, maxFiles, timeoutMs, denyGlobs = [], signal }) {
+    let cwd;
+    try { cwd = await fs.promises.realpath(root); } catch { return { ok: false, status: "not_found" }; }
+    let only = null;
+    if (rel !== null) {
+        only = normalizeRel(rel);
+        if (!only) return { ok: false, status: "not_found" };
+        if (isSensitivePath(only, denyGlobs)) return { ok: false, status: "forbidden" };
+    }
+    const listArgs = [...GIT_SAFE, "diff", "--name-only", "-z", "--no-renames", "--no-ext-diff", "--relative", "HEAD", "--", ...(only ? [only] : ["."])];
+    const listed = await runGit(listArgs, { cwd, maxBytes: 4 * 1024 * 1024, timeoutMs, signal });
+    if (listed.aborted) return { ok: false, status: "error", errorCode: "agent_offline" };
+    if (listed.timedOut) return { ok: false, status: "error", errorCode: "timeout" };
+    if (listed.overflow) return { ok: false, status: "error", errorCode: "payload_too_large" };
+    if (listed.code !== 0) return { ok: false, status: "not_found" }; // not a repository, no HEAD yet, unsafe directory...
+    const names = [];
+    let argBytes = 0;
+    for (const n of listed.out.toString("utf8").split("\0")) {
+        const norm = n ? normalizeRel(n) : null;
+        if (!norm || isSensitivePath(norm, denyGlobs)) continue;
+        argBytes += Buffer.byteLength(norm) + 1;
+        if (names.length >= maxFiles || argBytes > 128 * 1024) break;
+        names.push(norm);
+    }
+    if (names.length === 0) return { ok: true, text: "" };
+    const diffArgs = [...GIT_SAFE, "diff", "--no-color", "--no-ext-diff", "--no-textconv", "--no-renames", "--relative", "-U3", "HEAD", "--", ...names];
+    const diff = await runGit(diffArgs, { cwd, maxBytes: maxBytes + 1, timeoutMs, signal });
+    if (diff.aborted) return { ok: false, status: "error", errorCode: "agent_offline" };
+    if (diff.timedOut) return { ok: false, status: "error", errorCode: "timeout" };
+    if (diff.overflow) return { ok: false, status: "error", errorCode: "payload_too_large" };
+    if (diff.code !== 0) return { ok: false, status: "error", errorCode: "internal" };
+    return { ok: true, text: diff.out.toString("utf8") };
+}

package/src/la-protocol-v2/content-handlers/handler.js

@@ -0,0 +1,170 @@
+/**
+ * handler.js - `content.request` handlers of the Local Agent (F3-07). Registered by runtime.js only when
+ * LOCAL_AGENT_PROTOCOL_V2=true AND LOCAL_AGENT_CONTENT_HANDLERS=true.
+ *
+ * Order of every request (nothing is read before the checks, nothing leaves before the DLP):
+ *   1. accept: the handler answers the session at once ({accept:true} = ack `accepted`); the work goes on in the
+ *      background (the first chunk may take seconds, the ack timeout is 5 s). A request without requestId is refused.
+ *   2. admission: at most `maxConcurrent` requests and `maxInFlightBytes` in memory; above it -> `rate_limited`.
+ *   3. kind: `file` and `diff` are served; every other kind of the allowlist -> status `error` + `protocol_unsupported`
+ *      (the contract has no "not supported" status; this is the code already used for "no handler").
+ *   4. workspace: the envelope's workspace must be registered here (and belong to this tenant) -> else `not_found`.
+ *   5. ref: an opaque id (ref-registry.js) valid for this tenant+workspace+root+kind -> else `not_found`, whatever the
+ *      reason (unknown, expired, other workspace, or "../etc/passwd": no oracle, nothing echoed). The ref is never
+ *      interpreted as a path.
+ *   6. path (file): realpath inside the root, not sensitive, regular file, <= maxBytes (path-guard.js) -> `forbidden` /
+ *      `not_found` / `payload_too_large`.
+ *   7. DLP + range + size (egress.js), then 8. sendContent: <= 32 KiB per chunk, <= 64 chunks, window + backpressure of the
+ *      session, aborted by cancel()/deadline/connection loss.
+ * Answers carry a status and a wire code only. Logs, errors and the audit never contain a path, a ref or content.
+ */
+import { ProtocolError } from "../errors.js";
+import { sendContent, sendContentFailure } from "../content.js";
+import { REF_KINDS } from "./ref-registry.js";
+import { normalizeRel, resolveInside, readRegular } from "./path-guard.js";
+import { worktreeDiff } from "./git-diff.js";
+import { prepareOutgoing, contentTypeOf, decodeText } from "./egress.js";
+import { createAudit, short } from "./audit.js";
+
+export const SERVED_KINDS = Object.freeze(["file", "diff"]);
+/** Symbolic ref of kind `diff`: the whole work tree of the envelope's workspace (carries no client data). */
+export const WORKTREE_REF = "worktree";
+
+export function createContentHandler({ session, tenantId, resolveWorkspace, registry, config, env = process.env, log = console, audit = null, now = Date.now }) {
+    const inflight = new Map(); // requestId -> { ac, timer }
+    let reservedBytes = 0;
+    const auditor = audit || createAudit({ file: config.auditFile, now });
+    const reserveEach = 2 * config.maxBytes;
+    const warn = (m) => (log.warn || log.log).call(log, m);
+
+    const stats = { received: 0, ok: 0, notFound: 0, forbidden: 0, error: 0, cancelled: 0, byCode: {} };
+    const bump = (k) => { stats.byCode[k] = (stats.byCode[k] || 0) + 1; };
+
+    /** @returns {Promise<{status:string, errorCode?:string, buffer?:Buffer, contentType?:string, dlp?:object}>} */
+    async function produce(ctx, p, signal) {
+        if (!SERVED_KINDS.includes(p.kind)) return { status: "error", errorCode: "protocol_unsupported" };
+        const ws = await resolveWorkspace(ctx.workspaceId);
+        if (!ws || !ws.root) return { status: "not_found" };
+        const target = registry.resolve(p.ref, { workspaceId: ctx.workspaceId, root: ws.root, kind: p.kind });
+        if (p.kind === "diff" && !target && p.ref === WORKTREE_REF) return produceDiff(p, ws, null, signal);
+        if (!target) return { status: "not_found" };
+        if (p.kind === "diff") return produceDiff(p, ws, target.rel, signal);
+        return produceFile(p, ws, target.rel, signal);
+    }
+
+    async function produceFile(p, ws, rel, signal) {
+        const norm = rel && normalizeRel(rel);
+        if (!norm) return { status: "not_found" };
+        const resolved = await resolveInside(ws.root, norm, config.extraDenyGlobs);
+        if (!resolved.ok) return { status: resolved.status };
+        if (signal.aborted) return { status: "error", errorCode: "agent_offline" };
+        const read = await readRegular(resolved, config.maxBytes, signal);
+        if (!read.ok) return read.status === "too_large" ? { status: "error", errorCode: "payload_too_large" } : { status: read.status };
+        const isText = decodeText(read.buffer) !== null;
+        return finish(p, read.buffer, contentTypeOf(norm, isText), "content.file");
+    }
+
+    async function produceDiff(p, ws, rel, signal) {
+        const d = await worktreeDiff({ root: ws.root, rel, maxBytes: config.maxBytes, maxFiles: config.maxDiffFiles,
+            timeoutMs: config.gitTimeoutMs, denyGlobs: config.extraDenyGlobs, signal });
+        if (!d.ok) return d;
+        return finish(p, Buffer.from(d.text, "utf8"), "text/x-diff", "content.diff");
+    }
+
+    function finish(p, buffer, contentType, source) {
+        const out = prepareOutgoing({ buffer, contentType, range: p.range, maxBytes: config.maxBytes, env, source });
+        return out.ok ? { status: "ok", buffer: out.buffer, contentType: out.contentType, dlp: out.dlp }
+            : { status: out.status, errorCode: out.errorCode, dlp: out.dlp };
+    }
+
+    async function run(ctx, p, entry) {
+        const t0 = now();
+        let result;
+        let sent = null;
+        let errorCode;
+        try {
+            if (inflight.size > config.maxConcurrent || reservedBytes + reserveEach > config.maxInFlightBytes) {
+                result = { status: "error", errorCode: "rate_limited" };
+            } else {
+                reservedBytes += reserveEach;
+                entry.reserved = true;
+                result = await produce(ctx, p, entry.ac.signal);
+            }
+            if (entry.ac.signal.aborted) {
+                errorCode = "cancelled";
+                // out of time before the first chunk: the gateway still waits for an answer, give it one (a code only)
+                if (entry.reason === "deadline") {
+                    await sendContentFailure(session, { requestId: ctx.requestId, status: "error", errorCode: "timeout", workspaceId: ctx.workspaceId }).catch(() => {});
+                    errorCode = "timeout";
+                }
+            } else if (result.status === "ok") {
+                try {
+                    sent = await sendContent(session, { requestId: ctx.requestId, source: result.buffer, contentType: result.contentType,
+                        workspaceId: ctx.workspaceId, signal: entry.ac.signal });
+                } catch (e) {
+                    errorCode = e instanceof ProtocolError ? (entry.ac.signal.aborted ? "cancelled" : e.code) : "internal";
+                }
+            } else {
+                await sendContentFailure(session, { requestId: ctx.requestId, status: result.status,
+                    errorCode: result.errorCode || null, workspaceId: ctx.workspaceId });
+            }
+        } catch (e) {
+            errorCode = e instanceof ProtocolError ? e.code : "internal";
+        } finally {
+            clearTimeout(entry.timer);
+            if (entry.reserved) reservedBytes -= reserveEach;
+            inflight.delete(ctx.requestId);
+        }
+        const status = errorCode === "cancelled" || errorCode === "timeout" ? errorCode : errorCode ? "send_failed" : result.status;
+        if (status === "ok") stats.ok++;
+        else if (status === "not_found") stats.notFound++;
+        else if (status === "forbidden") stats.forbidden++;
+        else if (status === "cancelled" || status === "timeout") stats.cancelled++;
+        else stats.error++;
+        bump(errorCode || result.errorCode || status);
+        auditor.record({
+            requestId: ctx.requestId, workspaceId: ctx.workspaceId, kind: p.kind, status, errorCode: errorCode || result.errorCode || null,
+            bytes: sent ? sent.bytes : 0, chunks: sent ? sent.chunks : 0, ms: now() - t0,
+            dlpMode: result.dlp ? result.dlp.mode : null, dlpHits: result.dlp ? result.dlp.total : 0, dlpRules: result.dlp ? result.dlp.redactions : {},
+            refSha: short(p.ref), actorRole: p.actor && p.actor.role, actorSha: short(p.actor && p.actor.userId),
+        });
+        if (status === "send_failed") warn(`[la-content] ${p.kind} not delivered: ${errorCode}`);
+    }
+
+    return {
+        stats,
+        audit: auditor,
+        get inflight() { return inflight.size; },
+        get reservedBytes() { return reservedBytes; },
+
+        /** The session handler for `content.request` (session.setHandler). */
+        handle(ctx) {
+            stats.received++;
+            const p = ctx.params;
+            if (!ctx.requestId) return { reject: "schema_violation" };
+            if (inflight.has(ctx.requestId)) return { accept: true }; // already working on it (a retransmission with another seq)
+            const entry = { ac: new AbortController(), timer: null, reserved: false, reason: null };
+            entry.timer = setTimeout(() => { entry.reason = "deadline"; entry.ac.abort(); }, config.totalMs);
+            inflight.set(ctx.requestId, entry);
+            // background: ack first, answer later
+            queueMicrotask(() => { run(ctx, p, entry).catch(() => {}); });
+            return { accept: true };
+        },
+
+        /** Stops one request (no further chunk is read or written). There is no content.cancel frame in the contract. */
+        cancel(requestId) {
+            const e = inflight.get(requestId);
+            if (!e) return false;
+            e.reason = e.reason || "cancel";
+            e.ac.abort();
+            session.cancelWaiting(requestId);
+            return true;
+        },
+
+        cancelAll() {
+            for (const id of [...inflight.keys()]) this.cancel(id);
+        },
+    };
+}
+
+export { REF_KINDS };

package/src/la-protocol-v2/content-handlers/index.js

@@ -0,0 +1,6 @@
+export { CONTENT_HANDLERS_FLAG, resolveContentHandlersConfig } from "./config.js";
+export { ContentRefRegistry, REF_PATTERN } from "./ref-registry.js";
+export { createContentHandler, SERVED_KINDS, WORKTREE_REF } from "./handler.js";
+export { installContentHandlers, CONTENT_CAPABILITIES } from "./install.js";
+export { isSensitivePath, normalizeRel, resolveInside, DEFAULT_DENY_GLOBS } from "./path-guard.js";
+export { createAudit } from "./audit.js";

package/src/la-protocol-v2/content-handlers/install.js

@@ -0,0 +1,50 @@
+/**
+ * install.js - puts the content handlers on a v2 link (F3-07). Called by runtime.js only when
+ * LOCAL_AGENT_CONTENT_HANDLERS=true (and v2 is on). Returns what the rest of the agent needs:
+ *
+ *   mintRef({workspaceId, kind, rel})  the HOOK for whoever reports metadata to the control plane (file lists,
+ *                                      diff summaries): returns an opaque id for that item, or null (sensitive
+ *                                      path, unknown workspace). Nothing calls it yet: the contract has no
+ *                                      LA->CP frame that carries an inventory (see the F3-07 note, open questions).
+ */
+import { dlpConfigFromEnv } from "../../dlp/index.js";
+import { ContentRefRegistry } from "./ref-registry.js";
+import { createContentHandler, SERVED_KINDS } from "./handler.js";
+
+export const CONTENT_CAPABILITIES = Object.freeze(SERVED_KINDS.map((k) => `content.${k}`));
+
+export function installContentHandlers({ link, tenantId, wsManager, getWorkspaceRoot, config, env = process.env, log = console }) {
+    const tenant = String(tenantId).toLowerCase();
+    const registry = new ContentRefRegistry({ tenantId: tenant, ttlMs: config.refTtlMs, maxEntries: config.maxRefs, denyGlobs: config.extraDenyGlobs });
+
+    /** A workspace "registered here": open in the manager (of this tenant, or of none yet) or the default root. */
+    const resolveWorkspace = (workspaceId) => {
+        if (typeof workspaceId !== "string" || !workspaceId) return null;
+        const listed = (wsManager?.list?.() || []).find((w) => w && w.id === workspaceId);
+        if (listed) {
+            if (listed.tenantId && String(listed.tenantId).toLowerCase() !== tenant) return null;
+            return listed.root ? { root: listed.root } : null;
+        }
+        if (workspaceId === "default") { const root = getWorkspaceRoot(); return root ? { root } : null; }
+        return null;
+    };
+
+    const handler = createContentHandler({ session: link.session, tenantId: tenant, resolveWorkspace, registry, config, env, log });
+    link.session.setHandler("content.request", (ctx) => handler.handle(ctx));
+
+    const closeLink = link.close.bind(link);
+    link.close = () => { handler.cancelAll(); registry.clear(); closeLink(); };
+
+    if (dlpConfigFromEnv(env).mode !== "enforce") {
+        (log.warn || log.log).call(log, "[la-content] content handlers are on but LOCAL_AGENT_DLP_MODE is not enforce: file content leaves this machine unmasked");
+    }
+    link.content = {
+        registry,
+        handler,
+        mintRef: ({ workspaceId, kind, rel }) => {
+            const ws = resolveWorkspace(workspaceId);
+            return ws ? registry.mint({ workspaceId, root: ws.root, kind, rel }) : null;
+        },
+    };
+    return link.content;
+}