deepdebug-local-agent 1.12.1 → 1.13.0

package/src/la-protocol-v2/chat/store.js

@@ -0,0 +1,337 @@
+/**
+ * store.js - the ChatStore (LA-3, ADR-0014 Design A): the conversation of a chat job lives HERE, on the customer's machine, and nowhere else.
+ *
+ *   <dir>/<tenant>/<conversationId>.jsonl     one file per conversation, mode 0600 in a 0700 folder, JSON Lines:
+ *       {"k":"meta","v":1,"ws":"<workspaceId>","ts":"..."}              first line
+ *       {"k":"turn","role":"user|assistant","ts":"...","text":"..."}      the person's prompt, the model's answer
+ *       {"k":"ev","e":"<one event line of agent2>"}                       the live stream (position = order in the file), what `job.stream` replays
+ *       {"k":"end","state":"done|failed|cancelled","ts":"..."}            the job is over; no `end` in a file nobody is writing = interrupted (the agent restarted)
+ *   Until the contract carries a conversation id, a chat job IS its own conversation: conversationId = jobId (agent2 does the same: its `summary` echoes the
+ *   job id as `conversationId`). `chat.session` takes that id as `ref`.
+ *
+ * Rules:
+ *  - NO SECRET IS EVER WRITTEN: every piece (prompt, event line, answer) goes through the DLP in enforce before it touches the disk (dlp.js); a piece the DLP
+ *    cannot mask or blocks is stored as a fixed "withheld" text. The same pieces are masked again when they leave (content handlers).
+ *  - The conversation leaves this process only through the content relay (`job.stream`, `chat.session`), never in a log, an audit, a stat, an error or a job frame.
+ *    Everything this module logs or audits is a code, a counter or a short hash.
+ *  - Retention (LOCAL_AGENT_CHAT_RETENTION_DAYS, default 30) and a size ceiling (LOCAL_AGENT_CHAT_MAX_BYTES) are enforced by a sweep at start and every hour; the
+ *    oldest conversation goes first; a conversation being written is never swept. One conversation is capped (events beyond it are dropped, `truncated`).
+ *  - File names are UUIDs checked here: no path ever comes from outside.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { short } from "../content-handlers/audit.js";
+import { maskOrWithhold, maskEventLine, WITHHELD_LINE, WITHHELD_TEXT } from "./dlp.js";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const MAX_LINE_CHARS = 16_384;     // contract: job.stream.body events[].e maxLength; agent2 cuts its lines at the same size
+const MAX_TURN_CHARS = 65_536;     // contract: chat.session.body turns[].text maxLength
+const MAX_EVENTS = 5_000;          // events kept for one conversation, whatever the byte cap says
+const FILE_NAME = /^([0-9a-f-]{36})(\.\d+)?\.jsonl$/;   // <id>.jsonl, or an archived run <id>.<epoch ms>.jsonl
+const MAX_LOADED = 64;             // conversations kept in memory (the ones being written are never evicted)
+const utf8len = (s) => Buffer.byteLength(s, "utf8");
+
+const isoNow = (now) => new Date(now()).toISOString();
+
+export function createChatStore({ dir, tenantId, config, env = process.env, now = Date.now, log = console, audit = null, isActive = () => false }) {
+    const tenant = String(tenantId).toLowerCase();
+    if (!UUID.test(tenant)) throw new Error("chat store: the tenant id is not a UUID");
+    const tenantDir = path.join(dir, tenant);
+    const warn = (m) => (log.warn || log.log).call(log, m);
+    const note = (event, extra) => { try { audit?.record({ event, ...extra }); } catch { /* the audit never breaks the data path */ } };
+    const stats = { begun: 0, events: 0, eventsDropped: 0, withheld: 0, writeFailed: 0, loaded: 0, swept: 0, sweptBytes: 0, truncated: 0 };
+    const logs = new Map();                 // conversationId -> ConversationLog
+    const createdWaiters = new Set();       // woken when a conversation is begun (a request that came before the job reached its runner)
+    let sweepTimer = null;
+    let closed = false;
+
+    fs.mkdirSync(tenantDir, { recursive: true, mode: 0o700 });
+    for (const d of [dir, tenantDir]) { try { fs.chmodSync(d, 0o700); } catch { /* not ours to change (a shared mount): the files are 0600 anyway */ } }
+
+    const fileOf = (id) => path.join(tenantDir, `${id}.jsonl`);
+
+    // ---------------------------------------------------------------------------------------------------------------- a conversation in memory
+    function makeLog(id, workspaceId, startedAt) {
+        const l = { id, workspaceId, startedAt, turns: [], events: [], bytes: 0, truncated: false, ended: false, endState: null, writing: false,
+            waiters: new Set(), chain: Promise.resolve(), tokens: [], answer: "", tokenChars: 0 };
+        return l;
+    }
+    function wake(set) { for (const w of [...set]) { try { w(); } catch { /* a waiter's bug is its own */ } } }
+
+    /** Appends one record to the file, in order, without ever blocking the caller. A write error is counted and audited (a code), never thrown. */
+    function persist(l, obj) {
+        const line = `${JSON.stringify(obj)}\n`;
+        l.chain = l.chain.then(() => fs.promises.appendFile(fileOf(l.id), line, { mode: 0o600 })).catch(() => {
+            stats.writeFailed++;
+            note("chat_write_failed", { convShort: short(l.id) });
+        });
+    }
+
+    function evict() {
+        if (logs.size <= MAX_LOADED) return;
+        for (const [id, l] of logs) {
+            if (logs.size <= MAX_LOADED) break;
+            if (!l.writing && l.waiters.size === 0) logs.delete(id);
+        }
+    }
+
+    /** Reads a conversation from its file (a torn last line is ignored). null = no such file / not a conversation of this tenant. */
+    function load(id) {
+        if (!UUID.test(id)) return null;
+        let text;
+        try {
+            const st = fs.lstatSync(fileOf(id));
+            if (!st.isFile() || st.size > Math.max(config.maxConversationBytes * 2, 1 << 20)) return null;   // never a symlink, never an oversized file
+            text = fs.readFileSync(fileOf(id), "utf8");
+        } catch { return null; }
+        let l = null;
+        for (const raw of text.split("\n")) {
+            if (!raw) continue;
+            let r;
+            try { r = JSON.parse(raw); } catch { continue; }
+            if (!r || typeof r !== "object") continue;
+            if (r.k === "meta" && !l && typeof r.ws === "string") l = makeLog(id, r.ws, typeof r.ts === "string" ? r.ts : isoNow(now));
+            else if (!l) continue;
+            else if (r.k === "turn" && (r.role === "user" || r.role === "assistant") && typeof r.ts === "string" && typeof r.text === "string") l.turns.push({ role: r.role, ts: r.ts, text: r.text });
+            else if (r.k === "ev" && typeof r.e === "string") { l.events.push(r.e); l.bytes += utf8len(r.e); }
+            else if (r.k === "trunc") l.truncated = true;
+            else if (r.k === "end") { l.ended = true; l.endState = typeof r.state === "string" ? r.state : "done"; }
+        }
+        if (!l) return null;
+        if (!l.ended) { l.ended = true; l.endState = "interrupted"; }   // nobody is writing it in this process
+        stats.loaded++;
+        return l;
+    }
+
+    /** @returns {object|null} the conversation (memory first, then disk) */
+    function get(id) {
+        if (typeof id !== "string" || !UUID.test(id)) return null;
+        let l = logs.get(id);
+        if (!l) { l = load(id); if (l) { logs.set(id, l); evict(); } }
+        return l || null;
+    }
+
+    // ---------------------------------------------------------------------------------------------------------------- writing
+    /** Moves <id>.jsonl aside when it has its `end` mark (a torn file without one is an interrupted run and is replaced, as before). */
+    function archiveIfFinished(id) {
+        const file = fileOf(id);
+        let text;
+        try {
+            const st = fs.lstatSync(file);
+            if (!st.isFile()) return;
+            text = fs.readFileSync(file, "utf8");
+        } catch { return; }           // no file: nothing to keep
+        if (!text.includes('\n{"k":"end"')) return;
+        let to = path.join(tenantDir, `${id}.${now()}.jsonl`);
+        for (let n = 1; fs.existsSync(to); n++) to = path.join(tenantDir, `${id}.${now()}${n}.jsonl`);
+        try { fs.renameSync(file, to); } catch { stats.writeFailed++; throw new Error("chat store: cannot archive the finished conversation"); }
+        note("chat_archived", { convShort: short(id) });
+    }
+
+    function begin({ jobId, workspaceId, userText }) {
+        if (closed || !UUID.test(String(jobId)) || typeof workspaceId !== "string" || !workspaceId) throw new Error("chat store: bad conversation");
+        const id = String(jobId);
+        const prev = logs.get(id);
+        if (prev && prev.writing) throw new Error("chat store: conversation already being written");
+        const l = makeLog(id, workspaceId, isoNow(now));
+        l.writing = true;
+        logs.set(id, l);
+        stats.begun++;
+        // a job id seen again (the agent restarted and the job was assigned again) starts a clean file: the old run's events would be a different run's.
+        // A file that already carries its `end` mark is a FINISHED conversation: it is archived (<id>.<epoch ms>.jsonl, same retention) and never truncated.
+        archiveIfFinished(id);
+        try { fs.writeFileSync(fileOf(id), "", { mode: 0o600 }); try { fs.chmodSync(fileOf(id), 0o600); } catch { /* the mode of the create is enough */ } } catch { stats.writeFailed++; l.writing = false; logs.delete(id); throw new Error("chat store: cannot create the conversation"); }
+        persist(l, { k: "meta", v: 1, ws: workspaceId, ts: l.startedAt });
+        if (typeof userText === "string" && userText.trim()) {
+            const m = maskOrWithhold(userText.trim().slice(0, MAX_TURN_CHARS), WITHHELD_TEXT, { env, source: "chat.store.user" });
+            if (m.withheld) stats.withheld++;
+            const turn = { role: "user", ts: isoNow(now), text: m.text };
+            l.turns.push(turn);
+            persist(l, { k: "turn", ...turn });
+        }
+        wake(createdWaiters);
+        return recorder(l);
+    }
+
+    function recorder(l) {
+        return {
+            conversationId: l.id,
+            /** One event line of agent2's content stream (a JSON string). Masked, stored, and handed to whoever is polling. */
+            append(line) {
+                if (l.ended || typeof line !== "string" || line.length === 0) return false;
+                const raw = line.length > MAX_LINE_CHARS ? line.slice(0, MAX_LINE_CHARS) : line;
+                // what the answer is made of (before masking: a mask could break the JSON this reads; the answer is masked as a whole at the end)
+                try {
+                    const o = JSON.parse(raw);
+                    if (o && o.type === "token" && typeof o.content === "string" && l.tokenChars < MAX_TURN_CHARS) { l.tokens.push(o.content); l.tokenChars += o.content.length; }
+                    else if (o && o.type === "summary" && o.content && typeof o.content.answer === "string" && o.content.answer.trim()) l.answer = o.content.answer;
+                } catch { /* not JSON: kept as an event, not part of the answer */ }
+                const m = maskEventLine(raw, WITHHELD_LINE, { env, source: "chat.store.event" });
+                const e = m.text.length > MAX_LINE_CHARS ? WITHHELD_LINE : m.text;   // a mask that grew the line past the contract's limit: withheld, never cut (a cut line is not JSON)
+                if (m.withheld || e === WITHHELD_LINE) stats.withheld++;
+                const bytes = utf8len(e);
+                if (l.events.length >= MAX_EVENTS || l.bytes + bytes > config.maxConversationBytes) {
+                    if (!l.truncated) { l.truncated = true; stats.truncated++; persist(l, { k: "trunc", ts: isoNow(now) }); }
+                    stats.eventsDropped++;
+                    return false;
+                }
+                l.events.push(e);
+                l.bytes += bytes;
+                stats.events++;
+                persist(l, { k: "ev", e });
+                wake(l.waiters);
+                return true;
+            },
+            /** The job is over. `state`: done | failed | cancelled. Writes the assistant turn (masked) and the end mark; everyone polling is woken. Idempotent. */
+            finish(state) {
+                if (l.ended) return;
+                const st = ["done", "failed", "cancelled"].includes(state) ? state : "failed";
+                const text = (l.answer || l.tokens.join("\n\n")).trim();
+                if (text) {
+                    const m = maskOrWithhold(text.slice(0, MAX_TURN_CHARS), WITHHELD_TEXT, { env, source: "chat.store.answer" });
+                    if (m.withheld) stats.withheld++;
+                    const turn = { role: "assistant", ts: isoNow(now), text: m.text.slice(0, MAX_TURN_CHARS) };
+                    l.turns.push(turn);
+                    persist(l, { k: "turn", ...turn });
+                }
+                l.ended = true;
+                l.endState = st;
+                l.writing = false;
+                l.tokens = []; l.answer = "";
+                persist(l, { k: "end", state: st, ts: isoNow(now) });
+                wake(l.waiters);
+                evict();
+            },
+            get ended() { return l.ended; },
+        };
+    }
+
+    // ---------------------------------------------------------------------------------------------------------------- reading
+    /** Waits until `wakeSet` fires, `ms` pass or `signal` aborts. Resolves in every case (the caller looks at the state again). */
+    function waitOn(set, ms, signal) {
+        return new Promise((resolve) => {
+            if (signal?.aborted || ms <= 0) { resolve(); return; }
+            let timer = null;
+            const done = () => { clearTimeout(timer); set.delete(done); signal?.removeEventListener("abort", done); resolve(); };
+            timer = setTimeout(done, ms);   // bounded by the hold of the poll (<= 8 s) and cleared by every way out: it does not need to be unref'd
+            set.add(done);
+            signal?.addEventListener("abort", done, { once: true });
+        });
+    }
+
+    /**
+     * One page of the stream of a conversation, from event `from`, holding the request up to `waitMs` for something new (long-poll).
+     * @returns {Promise<{status:"not_found"|"aborted"} | {status:"ok", events:{i:number,e:string}[], next:number, done:boolean, truncated:boolean}>}
+     */
+    async function readStream({ conversationId, workspaceId, from = 0, waitMs = config.pollMs, signal }) {
+        const deadline = now() + Math.max(0, waitMs);
+        let l = get(conversationId);
+        // the job was accepted but has not reached its runner yet (workspace being cloned, agent2 starting): wait for it, as long as the job is alive
+        while (!l && !closed && !signal?.aborted && isActive(conversationId) && now() < deadline) {
+            await waitOn(createdWaiters, Math.min(250, deadline - now()), signal);
+            l = get(conversationId);
+        }
+        if (signal?.aborted) return { status: "aborted" };
+        if (!l || l.workspaceId !== workspaceId) return { status: "not_found" };
+        if (!Number.isSafeInteger(from) || from < 0 || from > l.events.length) return { status: "not_found" };
+        while (l.events.length <= from && !l.ended && !closed && !signal?.aborted && now() < deadline) await waitOn(l.waiters, deadline - now(), signal);
+        if (signal?.aborted) return { status: "aborted" };
+        const events = [];
+        let bytes = 0;
+        let i = from;
+        while (i < l.events.length && events.length < config.pageEvents) {
+            const e = l.events[i];
+            const b = utf8len(e);
+            if (events.length > 0 && bytes + b > config.pageBytes) break;
+            events.push({ i, e });
+            bytes += b;
+            i++;
+        }
+        return { status: "ok", events, next: i, done: l.ended && i >= l.events.length, truncated: l.truncated };
+    }
+
+    /** The turns of a conversation (copies). */
+    function readSession({ conversationId, workspaceId }) {
+        const l = get(conversationId);
+        if (!l || l.workspaceId !== workspaceId) return { status: "not_found" };
+        return { status: "ok", turns: l.turns.map((t) => ({ ...t })), truncated: l.truncated };
+    }
+
+    // ---------------------------------------------------------------------------------------------------------------- retention
+    /** Deletes the conversations older than the retention, then the oldest ones while the store is above its ceiling. Never one being written. */
+    async function sweep() {
+        let names;
+        try { names = await fs.promises.readdir(tenantDir); } catch { return { removed: 0, bytes: 0 }; }
+        const files = [];
+        for (const n of names) {
+            const m = FILE_NAME.exec(n);
+            if (!m || !UUID.test(m[1])) continue;
+            const mem = logs.get(m[1]);
+            if (!m[2] && mem && mem.writing) continue;     // an archive (m[2]) is never the file being written
+            try { const st = await fs.promises.lstat(path.join(tenantDir, n)); if (st.isFile()) files.push({ id: m[1], archived: !!m[2], file: path.join(tenantDir, n), size: st.size, mtime: st.mtimeMs }); } catch { /* gone */ }
+        }
+        files.sort((a, b) => a.mtime - b.mtime);
+        let total = files.reduce((s, f) => s + f.size, 0);
+        let removed = 0;
+        let bytes = 0;
+        const drop = async (f) => {
+            try { await fs.promises.unlink(f.file); } catch { return; }
+            if (!f.archived) logs.delete(f.id);
+            total -= f.size; removed++; bytes += f.size;
+        };
+        const cutoff = now() - config.retentionMs;
+        const keep = [];
+        for (const f of files) { if (f.mtime < cutoff) await drop(f); else keep.push(f); }
+        for (const f of keep) { if (total <= config.maxBytes) break; await drop(f); }
+        stats.swept += removed; stats.sweptBytes += bytes;
+        if (removed) note("chat_swept", { removed, bytes });
+        return { removed, bytes };
+    }
+
+    /**
+     * Removes the conversations (live and archived) of one workspace. NOTE: nothing calls this yet (the Local Agent has no "workspace deleted" event to hang it on);
+     * it is kept, tested, for the day the materializer reports a removal. Until then only the retention sweep deletes conversations.
+     */
+    async function deleteWorkspace(workspaceId) {
+        let removed = 0;
+        let names = [];
+        try { names = await fs.promises.readdir(tenantDir); } catch { return 0; }
+        for (const n of names) {
+            const m = FILE_NAME.exec(n);
+            if (!m || !UUID.test(m[1])) continue;
+            if (m[2]) {   // an archived run: its workspace is in its first line
+                let ws = null;
+                try {
+                    const fd = await fs.promises.open(path.join(tenantDir, n), "r");
+                    try { const b = Buffer.alloc(1024); const { bytesRead } = await fd.read(b, 0, 1024, 0); ws = JSON.parse(b.toString("utf8", 0, bytesRead).split("\n")[0]).ws; } finally { await fd.close(); }
+                } catch { continue; }
+                if (ws !== workspaceId) continue;
+                try { await fs.promises.unlink(path.join(tenantDir, n)); removed++; } catch { /* gone */ }
+                continue;
+            }
+            const l = get(m[1]);
+            if (!l || l.workspaceId !== workspaceId || l.writing) continue;
+            try { await fs.promises.unlink(path.join(tenantDir, n)); logs.delete(m[1]); removed++; } catch { /* gone */ }
+        }
+        return removed;
+    }
+
+    sweep().catch(() => {});
+    sweepTimer = setInterval(() => { sweep().catch(() => {}); }, config.sweepMs);
+    if (sweepTimer.unref) sweepTimer.unref();
+
+    return {
+        stats, dir: tenantDir,
+        begin, readStream, readSession, sweep, deleteWorkspace,
+        /** For tests and the health of the agent: how many conversations are open in memory. */
+        get open() { return logs.size; },
+        /** Resolves when every write queued so far reached the disk. */
+        async flush() { await Promise.all([...logs.values()].map((l) => l.chain)); },
+        close() {
+            closed = true;
+            clearInterval(sweepTimer);
+            for (const l of logs.values()) wake(l.waiters);
+            wake(createdWaiters);
+        },
+    };
+}

package/src/la-protocol-v2/chat/stream-source.js

@@ -0,0 +1,23 @@
+/**
+ * stream-source.js - feeds the ChatStore from agent2's content stream (`GET /local/v1/jobs/{id}/stream`, LOCAL ONLY, LA-3).
+ *
+ * agent2 replays that stream from its start at every connection and ends it when the job is over, so a reconnect skips the lines already handled (counted).
+ * Returns when the stream ended on its own, when the signal aborted, or after `reconnects` reconnections that did not complete it. It never throws: a stream that
+ * cannot be read leaves the conversation with what arrived (the job's result is the truth about how it ended). The lines are content: they go to `recorder.append`
+ * (masked, stored) and nowhere else.
+ */
+export async function consumeAgent2Stream({ api, jobId, recorder, signal, reconnects = 3, sleep = (ms) => new Promise((r) => { const t = setTimeout(r, ms); if (t.unref) t.unref(); }), isDown = () => false }) {
+    let seen = 0;
+    for (let attempt = 0; ; attempt++) {
+        let count = 0;
+        try {
+            const r = await api.stream(jobId, { signal, onLine: (line) => { count++; if (count > seen) { seen = count; recorder.append(line); } } });
+            if (r && r.ended) return { ended: true, lines: seen };
+        } catch (e) {
+            if (signal.aborted) return { ended: false, lines: seen };
+            if (e && (e.code === "not_found" || e.code === "unauthorized")) return { ended: false, lines: seen };
+        }
+        if (signal.aborted || isDown() || attempt >= reconnects) return { ended: false, lines: seen };
+        await sleep(250 * (attempt + 1));
+    }
+}

package/src/la-protocol-v2/content-handlers/chat-session.js

@@ -0,0 +1,41 @@
+/**
+ * chat-session.js - `content.request kind=chat.session` (contract 2.3, LA-3): the stored conversation, read from the ChatStore of THIS machine when a person
+ * reopens a chat. ref = the conversation UUID (= the id of the chat job that started it). Body: {turns:[{role, ts, text}], truncated} (schema
+ * chat.session.body.schema.json). Every text is masked on its own (DLP enforce); when the whole does not fit one content.response the OLDEST turns are left out
+ * and `truncated` is true. Unknown id or another workspace than the conversation's: `not_found`.
+ */
+import { maskOrWithhold, WITHHELD_TEXT } from "../chat/dlp.js";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const MAX_TURNS = 1000;
+const MAX_TURN_CHARS = 65_536;
+const OVERHEAD = 64;
+
+export function produceChatSession({ store, env, maxBytes }, ctx, p) {
+    if (p.range) return { status: "error", errorCode: "protocol_unsupported" };
+    if (typeof p.ref !== "string" || !UUID.test(p.ref)) return { status: "not_found" };
+    const r = store.readSession({ conversationId: p.ref, workspaceId: ctx.workspaceId });
+    if (r.status !== "ok") return { status: "not_found" };
+    let total = 0;
+    const redactions = {};
+    const masked = r.turns.map((t) => {
+        const m = maskOrWithhold(t.text, WITHHELD_TEXT, { env, source: "content.chat.session" });
+        total += m.total;
+        for (const [k, n] of Object.entries(m.redactions || {})) redactions[k] = (redactions[k] || 0) + n;
+        return { role: t.role, ts: t.ts, text: m.text.slice(0, MAX_TURN_CHARS) };
+    });
+    // keep the NEWEST turns that fit: walk from the end
+    let size = OVERHEAD;
+    let first = masked.length;
+    for (let i = masked.length - 1; i >= 0; i--) {
+        const add = JSON.stringify(masked[i]).length + 1;
+        if (masked.length - i > MAX_TURNS || size + add > maxBytes) break;
+        size += add;
+        first = i;
+    }
+    const turns = masked.slice(first);
+    const truncated = r.truncated || first > 0;
+    const buffer = Buffer.from(JSON.stringify({ turns, truncated }), "utf8");
+    if (buffer.length > maxBytes) return { status: "error", errorCode: "payload_too_large" };
+    return { status: "ok", buffer, contentType: "application/json", dlp: { mode: "enforce", total, redactions } };
+}

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

@@ -26,13 +26,18 @@ import { listFolder, ROOT_REF, clampLimit, MAX_LIST_BYTES } from "./file-list.js
 import { worktreeDiff } from "./git-diff.js";
 import { prepareOutgoing, prepareList, maskName, contentTypeOf, decodeText } from "./egress.js";
 import { createAudit, short } from "./audit.js";
+import { produceJobStream } from "./job-stream.js";
+import { produceChatSession } from "./chat-session.js";
 import { dlpConfigFromEnv } from "../../dlp/index.js";
 
 export const SERVED_KINDS = Object.freeze(["file", "diff", "file.list"]);
+/** Contract 2.3 (LA-3): served only when the chat is on (`chat` dependency of createContentHandler); they read the ChatStore, not the work tree. */
+export const CHAT_KINDS = Object.freeze(["job.stream", "chat.session"]);
 /** 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, mint = null }) {
+export function createContentHandler({ session, tenantId, resolveWorkspace, registry, config, env = process.env, log = console, audit = null, now = Date.now, mint = null, chat = null }) {
+    const served = new Set(chat ? [...SERVED_KINDS, ...CHAT_KINDS] : SERVED_KINDS);
     // F3-07c: where the ids of a listing come from. install.js passes mintRef (registry + content.index); without it (tests) the registry alone.
     const mintFor = (workspaceId, root) => (o) => (mint ? mint({ workspaceId, ...o }) : registry.mint({ workspaceId, root, ...o }));
     const inflight = new Map(); // requestId -> { ac, timer }
@@ -46,10 +51,13 @@ export function createContentHandler({ session, tenantId, resolveWorkspace, regi
 
     /** @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" };
+        if (!served.has(p.kind)) return { status: "error", errorCode: "protocol_unsupported" };
         // F3-07b: content never leaves unmasked. runtime.js does not even register this handler without DLP enforce; this is the
         // same rule at the moment of the request (the env is read per request), so a changed mode can not open the door.
         if (dlpConfigFromEnv(env).mode !== "enforce") return { status: "error", errorCode: "protocol_unsupported" };
+        // LA-3: the conversation is in the ChatStore, bound to the workspace id of its job (no root needed: it must stay readable after a restart)
+        if (p.kind === "job.stream") return produceJobStream({ ...chat, env, maxBytes: config.maxBytes }, ctx, p, signal);
+        if (p.kind === "chat.session") return produceChatSession({ ...chat, env, maxBytes: config.maxBytes }, ctx, p);
         const ws = await resolveWorkspace(ctx.workspaceId);
         if (!ws || !ws.root) return { status: "not_found" };
         if (p.kind === "file.list") return produceList(ctx, p, ws, signal);

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

@@ -17,7 +17,7 @@ import { decodeText } from "./egress.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 }) {
+export function installContentHandlers({ link, tenantId, wsManager, getWorkspaceRoot, config, env = process.env, log = console, chat = null }) {
     // F3-07b, defence in depth: runtime.js already refuses; nobody can install the handlers without DLP enforce
     if (dlpConfigFromEnv(env).mode !== "enforce") throw new Error("content handlers need LOCAL_AGENT_DLP_MODE=enforce");
     const tenant = String(tenantId).toLowerCase();
@@ -52,7 +52,7 @@ export function installContentHandlers({ link, tenantId, wsManager, getWorkspace
     };
 
     // F3-07c: the listing handler mints through mintRef, so every id it hands out is also announced with content.index
-    const handler = createContentHandler({ session: link.session, tenantId: tenant, resolveWorkspace, registry, config, env, log, mint: mintRef });
+    const handler = createContentHandler({ session: link.session, tenantId: tenant, resolveWorkspace, registry, config, env, log, mint: mintRef, chat });
     link.session.setHandler("content.request", (ctx) => handler.handle(ctx));
     indexer = createContentIndexer({ session: link.session, registry, config, log });
 

package/src/la-protocol-v2/content-handlers/job-stream.js

@@ -0,0 +1,62 @@
+/**
+ * job-stream.js - `content.request kind=job.stream` (contract 2.3, LA-3): one long-poll page of the event stream of a chat job, read from the ChatStore of THIS
+ * machine. The answer is client content in transit: masked piece by piece (DLP enforce; an event line on its decoded JSON strings, see maskEventLine), sent as a `content.response` and never stored or logged by the control plane.
+ *
+ *   ref = the job UUID            first request: from the start of the stream
+ *   ref = a `nextRef` (43 chars)  the cursor this agent minted with the previous page: after the last event of that page (cursors.js; asking again with the
+ *                                 same cursor gives the same page)
+ *   body                          {events:[{i, e}], nextRef, done}  (schema job.stream.body.schema.json)
+ *
+ * The request is held up to LOCAL_AGENT_CHAT_POLL_MS (8 s) while there is nothing new and the job is alive; an empty page with done:false means "ask again".
+ * A job the store does not know (or that belongs to another workspace of the envelope) and a cursor it does not know are `not_found`, whatever the reason.
+ */
+import { maskEventLine, WITHHELD_LINE } from "../chat/dlp.js";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const CURSOR = /^[A-Za-z0-9_-]{43}$/;
+const MAX_LINE_CHARS = 16_384;
+const PAGE_OVERHEAD = 128;     // {"events":[],"nextRef":"<43>","done":false} and the commas
+
+/**
+ * @param {object} d  { store, cursors, chatConfig, env, maxBytes }
+ * @returns {Promise<{status:string, errorCode?:string, buffer?:Buffer, contentType?:string, dlp?:object}>}
+ */
+export async function produceJobStream({ store, cursors, chatConfig, env, maxBytes }, ctx, p, signal) {
+    if (p.range) return { status: "error", errorCode: "protocol_unsupported" };   // a stream page has no byte range
+    let jobId;
+    let from = 0;
+    if (typeof p.ref === "string" && UUID.test(p.ref)) jobId = p.ref;
+    else if (typeof p.ref === "string" && CURSOR.test(p.ref)) {
+        const c = cursors.resolve(p.ref, { workspaceId: ctx.workspaceId });
+        if (!c) return { status: "not_found" };
+        jobId = c.jobId; from = c.next;
+    } else return { status: "not_found" };
+
+    const r = await store.readStream({ conversationId: jobId, workspaceId: ctx.workspaceId, from, waitMs: chatConfig.pollMs, signal });
+    if (r.status === "aborted") return { status: "error", errorCode: "agent_offline" };
+    if (r.status !== "ok") return { status: "not_found" };
+
+    // egress: each event line is masked on its own, on its decoded strings and re-serialized (maskEventLine); the page is cut so that the body fits one content.response
+    let total = 0;
+    const redactions = {};
+    const events = [];
+    let size = PAGE_OVERHEAD;
+    for (const ev of r.events) {
+        const m = maskEventLine(ev.e, WITHHELD_LINE, { env, source: "content.job.stream" });
+        let e = m.text;
+        if (e.length > MAX_LINE_CHARS || e.length === 0) e = WITHHELD_LINE;   // a mask that grew the line past the contract's limit: withheld, never cut
+        const add = JSON.stringify(e).length + 16 + String(ev.i).length;
+        if (events.length > 0 && size + add > maxBytes) break;
+        if (events.length === 0 && size + add > maxBytes) return { status: "error", errorCode: "payload_too_large" };
+        size += add;
+        events.push({ i: ev.i, e });
+        total += m.total;
+        for (const [k, n] of Object.entries(m.redactions || {})) redactions[k] = (redactions[k] || 0) + n;
+    }
+    const next = events.length ? events[events.length - 1].i + 1 : r.next;
+    const done = r.done && next >= r.next;
+    const nextRef = cursors.mint({ workspaceId: ctx.workspaceId, jobId, next });
+    const buffer = Buffer.from(JSON.stringify({ events, nextRef, done }), "utf8");
+    if (buffer.length > maxBytes) return { status: "error", errorCode: "payload_too_large" };
+    return { status: "ok", buffer, contentType: "application/json", dlp: { mode: "enforce", total, redactions } };
+}

package/src/la-protocol-v2/contract/CONTRACT_SOURCE.json

@@ -2,14 +2,15 @@
   "repo": "VISIONHAMMER/vh-api-gateway",
   "path": "docs/contracts/la-protocol-v2",
   "branch": "release/qa",
-  "commit": "155a076c4ba8a57e8dd4ee0f4c7951b0a7dad5d1",
+  "commit": "a2a5f67c3b48f8dc616fdd441d126441d714e5a4",
   "note": "Copied by scripts/sync-la-protocol-v2-contract.mjs. Do not edit: change the gateway folder and sync again.",
   "files": {
-    "README.md": "7a9910594f8d2ee0795f6d8e8085f3a97f6064cdbad1f659d5952f3c934d1ba1",
+    "README.md": "06f54d7a309ebc36175dedae483cb2366dd2eeccf10f4589e300871142403bfb",
     "ack.schema.json": "d6dfdaa8b1ec2dd47db9e858cd047ca860196ab6b0ad350f8ccb5d2596441ccf",
     "alert.schema.json": "01a8a77840be8ab7901ed7d07c3d68a2295bfaeb638694564e19e60be1747054",
     "approval.decision.schema.json": "a9c7bc74d146465afde1d5830839165a02f232b830b5f6cfd8c8e91fb6da1563",
     "audit.event.schema.json": "e9ceb58ea00077151373955957b8319324de488c80da4063f6d0dcb40a8b3ed0",
+    "chat.session.body.schema.json": "f172821026471f82440207e964a0ae193c3f7b9b2816b63ed134d4910035a30d",
     "config.update.schema.json": "432438b0c93ddafa0741e47f99b7357ad5f2b06b606779bf846c282e2f8a5639",
     "content.index.schema.json": "1abc24344435f0f392d5b626c3abb6879d8f9dd2c1d0463840a67634a5caa71e",
     "content.request.schema.json": "440e3675246657e9aae23e51176168bc21c91283b5fcaf6782111a18110bf76e",
@@ -21,11 +22,12 @@
     "heartbeat.schema.json": "8aff84a1ef3ca56bdff8819abb3b0ab01a2547814c2ea2f9ee893cb08f7a08f1",
     "hello.schema.json": "a90a6bf0e9a8a20e4c6edcf2137931cf044846e7924977228275ef648a48934f",
     "incident.candidate.schema.json": "ffec36aca6916079debc2c6060d093819ea3ea660b57c0c92ac3b541a0e99000",
-    "index.json": "d37b59b77a9408f5d2495f616b4067f88023d610801143b4c62e9e5e0fd255e6",
-    "job.assign.schema.json": "c61bf42bfd94003ca373f94f2f7adb93026b1b96079beab97662497c629cbec1",
+    "index.json": "b40a15480a4b038de6a08da4b53a369d462bc9cf75802593a390d7ad118f95ed",
+    "job.assign.schema.json": "0234e0cec55c03b97ac40497b514c9f0c6a66f28d8b975dc6506de6f72b7d579",
     "job.cancel.schema.json": "40ef64373283e17306d857c9a40081689786015294b0b88ab8f68f063bd2cfb8",
     "job.event.schema.json": "493d08f9db4f7ffd4a97403ee33ca4a73a65dc8f774d8f18ef0a137fdb5fc470",
     "job.result.schema.json": "9cbc61211482557283b8f4df44e79011ead1abbacdb2d986138199c747edc043",
+    "job.stream.body.schema.json": "2536d9f890c3000d245f20fdacc45b8cba24d2b1e4ef63a3116dd9611541b658",
     "log.stats.schema.json": "4b33b111946a19793a60756793294e90911b06f7050e48821759f2497ec17641",
     "policy.check.schema.json": "ebd3b99628bc827784b495b239656fc918cc7ce792ee5554372dba084bbdcc09",
     "policy.decision.schema.json": "84c1f14a1bfa698573d8cc621f4d6189f4ef09baa37e5e990fb94723e73296fe",
@@ -38,25 +40,27 @@
     "vectors/alert.vectors.json": "0bf179ff390bbecf07a117b80237cb7ac8778864e5780f36d68c8c9a64db8f04",
     "vectors/approval.decision.vectors.json": "338115973bf2c4390d2bb33ce8f4079f3132cd739cd5505e1e873fdc252d2271",
     "vectors/audit.event.vectors.json": "d05c1820103eef041a84eb8b13d9a67a8a5b54b9b54ee3b6e43fd4ef15ed7000",
+    "vectors/chat.session.body.vectors.json": "2f5311e05e4f65f371dbb476b02bf0b1408fba21f95f5fbaf0a00d051f978788",
     "vectors/config.update.vectors.json": "e61865fad9b4efa808e02877c4352d3720c8069a0b31261701b369d8ae11f9cf",
     "vectors/content.index.vectors.json": "f167db30910989c46f317313d651ca59f9cd9d881d2ea81b84912155d18227b7",
-    "vectors/content.request.vectors.json": "fdf0f4d9e19f6480e20e40f4652bf8205da2b113620f8461dfaeb0d61add36a0",
+    "vectors/content.request.vectors.json": "5f751ceb0645cad079bce7e45d14e764973799e663c891a9200b3d8b38712f38",
     "vectors/content.response.vectors.json": "cbb47cbf8a9512aa5360eea425f0cdd9064334311d37834dc75bddff07dadc5d",
     "vectors/cross-type.vectors.json": "f7ed403d3e3f53150b715a5423fde1bed708e8c6245709ed4ad74389dc8c3307",
     "vectors/error.vectors.json": "f5fd7954f2c1736ee0943eb330c2f85b7fdd7a8959e4f043f9cc9e9bcda39aa5",
     "vectors/file.list.body.vectors.json": "da1dcc5d4ec976853161bef4b3947572f36b5526cbe16b838ac4ef72ddded403",
     "vectors/heartbeat.vectors.json": "cfd2e048139c67aa925f1fa94c05326e75248839645c1a1e4d6d3bb60cafa624",
-    "vectors/hello.vectors.json": "7a50c4e54e6a4ef1227fd7485071bca8ec7b797c3b2907fddda3d8836c3feab6",
+    "vectors/hello.vectors.json": "0beae9adf4dd69c9e71951d8fa7b3870543a36a3c80b9d8a18ec69f9c3d7f4d4",
     "vectors/incident.candidate.vectors.json": "a78eb4b103f411f1ec64d9eeb4c39623851e710ac0cc20b4d78b2739b7ff78d5",
-    "vectors/job.assign.vectors.json": "0358a8e3bd94a332ef922abd80faf6e07bb8dbec0436cb463a4826a47e4d65e2",
+    "vectors/job.assign.vectors.json": "1062e2ea97e0ac33ce04bfc45dd38cad3a9e520df6c7400941d697db84e83767",
     "vectors/job.cancel.vectors.json": "0fc9f99c8662435e9425389068adf418273489dc73928a21eae1b283256b9bc5",
     "vectors/job.event.vectors.json": "03a2a2435918ba561821916bf4e435f2780210900139ecf68091acac6abf200c",
     "vectors/job.result.vectors.json": "05995fbe65e5357705d75e9b660b517f54c6902069d36b62190b1b79f283e7a5",
+    "vectors/job.stream.body.vectors.json": "c7b0748628f3711cd8296cc36ea6bf3829315feaaf9ad576b229ad9739a56392",
     "vectors/log.stats.vectors.json": "a8a67e09ef0f87b81f4028b77427ed7afd809c3f8534b8423a712b2ceef9a27f",
     "vectors/policy.check.vectors.json": "7222d74b010e304af5733ed2802c9a907f7186351d3d4b5eedfe6ff1e1f2fc8d",
     "vectors/policy.decision.vectors.json": "9fd61a5198568f4471dc28a2ce52eaa768f065d9cb7c76419af0c47f28295b09",
     "vectors/ready.vectors.json": "16327f5e5eccc57a0ec635bcde96116feeeeec7ddbc4b621d4d070738cdc48d5",
-    "vectors/register.vectors.json": "b612e9462b1e2ac198442afccf450f1535daadc4c32d87f6a99b9752c343c486",
+    "vectors/register.vectors.json": "0ee59c72c8ad8835092c103142a3f561538cc47980c4d5dfb8374f18d649217c",
     "vectors/scan.upload.vectors.json": "e8a6f73fe91ac58a3222b68cf28124c1254aa4f00c3ef8f472deb7de31cab76e",
     "vectors/scan.uploaded.vectors.json": "7314ea15b1afa7b9625048fb7e245492d8910bc0dae8a52ea62afe2a1e240382",
     "vectors/traces/invalid-agent-mismatch.json": "5f17b867de71c1bcc6c42723acb53a50338c0e491193499ea25c2220ea4fa558",
@@ -87,6 +91,7 @@
     "vectors/traces/invalid-webhook-chunk-out-of-order.json": "b6baa056b4e3347deaf0a4b901a126a3f93d20627faaa3951028bd47894715f4",
     "vectors/traces/invalid-webhook-chunk-sha-mismatch.json": "1bb79d0e1794cd791625ed2a7eab154e20150c5d7bee7c86aa97f9bf4aaeab6d",
     "vectors/traces/invalid-webhook-chunk-total-changes.json": "5edf3c1916927f94ef15061a13a6ded8a0168cb0492158f34db8160c0d6bdbe4",
+    "vectors/traces/valid-chat-job-and-stream.json": "b9ad5e045e9409737cb1a2607cfc652dc6f178ae266cc144875731fcbfeaa692",
     "vectors/traces/valid-content-chunks-in-order.json": "c5fc301527b062b30c625da2798c7cfab3e3debac29a36f6ec7c699705267ab3",
     "vectors/traces/valid-content-index.json": "9305dc955c4cca1f09158a9c8cf21d9e89d6a6b03646088c547f64a61cd59c30",
     "vectors/traces/valid-handshake-and-job.json": "9aa3c423c496403ca77d63965f1805f0a57ea9f6f8a01351310515b265aeb9cc",