deepdebug-local-agent 1.12.0 → 1.13.0

package/test/la-protocol-v2/chat-la.test.js

@@ -0,0 +1,490 @@
+// LA-1 + LA-3 (ADR-0014 Design A, contract 2.3): chat on the Local Agent. The REAL v2 link (buildV2Link with every flag), the REAL agent2 runner, ChatStore and content
+// handlers, against the ReferenceCp (which validates every frame against the contract) and a FAKE agent2 (helpers/fake-agent2.js: `kind=chat`, `/health` kinds,
+// the content stream). The decoded bodies are validated here against job.stream.body / chat.session.body. What it proves is limited by the fakes: the jar of agent2 is
+// exercised by chat-real-e2e.test.js when AGENT2_JAR points at one (opt-in).
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { closeAllFakes } from "./helpers/fake-llm.js";
+import { SCENARIOS } from "./helpers/fake-agent2.js";
+import { agent2Rig, CANARIES, GH, waitFor, uuid } from "./helpers/agent2-rig.js";
+import { loadContract } from "../../src/la-protocol-v2/contract.js";
+import { agent2ChildEnv } from "../../src/la-protocol-v2/jobs/agent2/supervisor.js";
+import { resolveAgent2RunnerConfig } from "../../src/la-protocol-v2/jobs/agent2/config.js";
+
+after(closeAllFakes);
+const contract = loadContract();
+const PROMPT = "CHAT-PROMPT-CANARY where is the login implemented?";
+const CHAT_CANARIES = ["CHAT-PROMPT-CANARY", "CHAT-TOKEN-ONE", "CHAT-TOKEN-TWO", "CHAT-ANSWER-FINAL", "CHAT-FILES", "CHAT-SLOW", "CHAT-SECRET", "CHAT-FAIL"];
+const PEM_MARK = "BEGIN RSA PRIVATE KEY";
+
+const KINDS_CHAT = ["fix", "implement", "chat"];
+
+async function chatRig({ scenario = "chat_answer", env = {}, fakeKinds = KINDS_CHAT, chatDir = null, ...rest } = {}) {
+    const dir = chatDir || fs.mkdtempSync(path.join(os.tmpdir(), "la-chat-it-"));
+    const r = await agent2Rig({ scenario, fakeKinds, env: { LOCAL_AGENT_CHAT: "true", LOCAL_AGENT_CHAT_DIR: dir, LOCAL_AGENT_CHAT_POLL_MS: "400", LOCAL_AGENT_CHAT_PROBE_MS: "10000", LOCAL_AGENT_CHAT_STREAM_DRAIN_MS: "3000", ...env }, ...rest });
+    const stop = r.stop;
+    r.chatDir = dir;
+    r.stop = async () => { await stop(); if (!chatDir) fs.rmSync(dir, { recursive: true, force: true }); };
+    return r;
+}
+
+const chatAssign = (r, over = {}) => r.assign({ kind: "chat", incidentRef: undefined, inputs: [{ inline: PROMPT, transient: true }], ...over });
+
+/** content.request -> { status, errorCode, body (parsed JSON or null), text, frames } */
+async function content(r, { kind, ref, workspaceId = "ws-1", waitMs = 6000 }) {
+    const requestId = uuid();
+    r.cp.sendData("content.request", { kind, ref, actor: { userId: "u-1", role: "member" } }, { workspaceId, requestId });
+    await waitFor(() => r.cp.received.some((f) => f.type === "content.response" && f.requestId === requestId && (f.chunk?.last || f.payload.status !== "ok")), waitMs);
+    const frames = r.cp.received.filter((f) => f.type === "content.response" && f.requestId === requestId);
+    const text = Buffer.concat(r.cp.contentRequests.get(requestId)?.chunks || []).toString("utf8");
+    let body = null;
+    if (frames[0]?.payload.status === "ok") body = JSON.parse(text);
+    return { requestId, status: frames[0]?.payload.status, errorCode: frames[0]?.payload.errorCode, body, text, frames };
+}
+
+/** Follows job.stream from the job id to done:true. Every page is checked against the contract's body schema. */
+async function drain(r, jobId, { workspaceId = "ws-1", max = 60 } = {}) {
+    const events = [];
+    const pages = [];
+    let ref = jobId;
+    for (let n = 0; n < max; n++) {
+        const a = await content(r, { kind: "job.stream", ref, workspaceId });
+        assert.equal(a.status, "ok", `page ${n}: ${a.status} ${a.errorCode}`);
+        assert.equal(contract.validateBody("job.stream.body.schema.json", a.body), true, `page ${n} is not a valid job.stream body: ${a.text.slice(0, 200)}`);
+        pages.push(a.body);
+        events.push(...a.body.events);
+        ref = a.body.nextRef;
+        if (a.body.done) return { events, pages };
+    }
+    throw new Error("the stream did not end");
+}
+
+const wireWithoutContent = (r) => JSON.stringify(r.cp.received.filter((f) => f.type !== "content.response"));
+const noCanary = (text, list = CHAT_CANARIES) => { for (const c of list) assert.ok(!text.includes(c), `content leaked outside the relay: ${c}`); };
+
+test("announces job.chat and job.inline.16k only from a complete chat: flag, agent2 that lists chat, content handlers", async () => {
+    const on = await chatRig();
+    try {
+        for (const frame of [on.cp.registers[0], on.cp.hellos[0]]) {
+            assert.ok(frame.capabilities.includes("job.chat") && frame.capabilities.includes("job.inline.16k"), JSON.stringify(frame.capabilities));
+            assert.ok(frame.capabilities.includes("job.assign"), "job.chat implies job.assign");
+        }
+        assert.deepEqual(on.link.agent2.kinds, KINDS_CHAT);
+    } finally { await on.stop(); }
+
+    // agent2 that does not list chat (an old build, or a sidecar started without AGENT2_LOCAL_CHAT_ENABLED): not announced, and a chat job is refused, never run as another kind
+    const old = await chatRig({ fakeKinds: ["fix", "implement"] });
+    try {
+        assert.ok(!old.cp.registers[0].capabilities.includes("job.chat"));
+        assert.ok(!old.cp.registers[0].capabilities.includes("job.inline.16k"));
+        assert.ok(old.cp.registers[0].capabilities.includes("job.assign"), "fix/implement are unchanged");
+        const a = chatAssign(old);
+        assert.deepEqual([(await a.acked()).status, (await a.acked()).errorCode], ["rejected", "protocol_unsupported"]);
+        assert.equal(old.fake.jobs.size, 0, "nothing reached agent2");
+    } finally { await old.stop(); }
+
+    // flag off: the same agent2 and nothing is announced
+    const off = await agent2Rig({ scenario: "chat_answer", fakeKinds: KINDS_CHAT });
+    try {
+        assert.ok(!off.cp.registers[0].capabilities.includes("job.chat"));
+        assert.equal(off.link.chat, undefined);
+        const a = off.assign({ kind: "chat", incidentRef: undefined, inputs: [{ inline: PROMPT, transient: true }] });
+        assert.equal((await a.acked()).errorCode, "protocol_unsupported");
+        const q = await content(off, { kind: "job.stream", ref: a.p.jobId });
+        assert.deepEqual([q.status, q.errorCode], ["error", "protocol_unsupported"], "without the chat, job.stream is not served");
+        const s = await content(off, { kind: "chat.session", ref: a.p.jobId });
+        assert.deepEqual([s.status, s.errorCode], ["error", "protocol_unsupported"]);
+    } finally { await off.stop(); }
+
+    // chat requested but the content handlers are off: it says why and stays off (a chat nobody can read is not announced)
+    const noContent = await agent2Rig({ scenario: "chat_answer", fakeKinds: KINDS_CHAT, env: { LOCAL_AGENT_CHAT: "true", LOCAL_AGENT_CONTENT_HANDLERS: "false", LOCAL_AGENT_CHAT_DIR: path.join(os.tmpdir(), "la-chat-never") } });
+    try {
+        assert.ok(!noContent.cp.registers[0].capabilities.includes("job.chat"));
+        assert.ok(noContent.errors.some((m) => /LOCAL_AGENT_CHAT=true but the content handlers/.test(m)), noContent.errors.join("|"));
+        assert.ok(!fs.existsSync(path.join(os.tmpdir(), "la-chat-never")), "no folder is created for a chat that stays off");
+    } finally { await noContent.stop(); }
+});
+
+test("the chat end to end: job.assign kind chat -> agent2 gets kind chat and the prompt -> job.stream pages (cursor) -> chat.session; the job frames carry no content", async () => {
+    const r = await chatRig();
+    try {
+        const a = chatAssign(r);
+        assert.equal((await a.acked()).status, "accepted");
+        await r.done(a.p.jobId, 8000);
+        const job = r.fake.jobs.get(a.p.jobId);
+        assert.equal(job.kind, "chat", "agent2 was asked for kind=chat (its unified loop), not implement");
+        assert.equal(job.request.text, PROMPT);
+        assert.equal(job.workspaceId.length, 36);
+        const res = r.frames(a.p.jobId, "job.result")[0].payload;
+        assert.equal(res.outcome, "no_change");
+        assert.equal(res.prUrl, undefined, "a chat opens no pull request");
+        assert.equal(res.filesChangedCount, 0, "answered, nothing changed on disk");
+        assert.equal(r.frames(a.p.jobId, "job.event").at(-1).payload.state, "succeeded");
+
+        // job.stream from the job id: every event line as agent2 emitted it, in order, with its position
+        const { events, pages } = await drain(r, a.p.jobId);
+        assert.deepEqual(events.map((e) => e.i), [0, 1, 2, 3, 4]);
+        assert.deepEqual(events.map((e) => JSON.parse(e.e).type), ["session_start", "status", "token", "token", "summary"]);
+        assert.match(events[2].e, /CHAT-TOKEN-ONE/);
+        assert.equal(pages.at(-1).done, true);
+        for (const p of pages) assert.match(p.nextRef, /^[A-Za-z0-9_-]{43}$/);
+
+        // the same cursor twice = the same page (a lost answer is asked for again); a cursor is not the job id
+        const first = await content(r, { kind: "job.stream", ref: a.p.jobId });
+        const next = first.body.nextRef;
+        const x = await content(r, { kind: "job.stream", ref: next });
+        const y = await content(r, { kind: "job.stream", ref: next });
+        assert.deepEqual(x.body, y.body);
+
+        // chat.session: the turns, in order, role/ts/text
+        const s = await content(r, { kind: "chat.session", ref: a.p.jobId });
+        assert.equal(s.status, "ok");
+        assert.equal(contract.validateBody("chat.session.body.schema.json", s.body), true, s.text);
+        assert.deepEqual(s.body.turns.map((t) => t.role), ["user", "assistant"]);
+        assert.equal(s.body.turns[0].text, PROMPT);
+        assert.match(s.body.turns[1].text, /CHAT-ANSWER-FINAL/);
+        assert.equal(s.body.truncated, false);
+        for (const t of s.body.turns) assert.match(t.ts, /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?Z$/);
+
+        // the content never rides a job frame, an audit or a log: only the content.response frames carry it
+        noCanary(wireWithoutContent(r));
+        noCanary(r.everything().replace(/"type":"content\.response"/g, ""), ["CHAT-PROMPT-CANARY", "CHAT-TOKEN-ONE", "CHAT-ANSWER-FINAL"]);
+        assert.deepEqual(r.cp.errorsSent, [], "every frame was valid for the contract validator of the CP");
+        noCanary([...r.logs, ...r.errors].join("\n"));
+        noCanary(JSON.stringify([r.link.chat.audit.tail(500), r.link.chat.store.stats, r.link.agent2.stats, r.link.jobs.audit.tail(500)]));
+    } finally { await r.stop(); }
+});
+
+test("a 16384-char prompt (job.inline.16k) reaches agent2 whole; a prompt over 16 KiB of UTF-8 is never cut: the job fails and agent2 is not called", async () => {
+    const r = await chatRig({ env: { LOCAL_AGENT_JOBS_MEM_PER_JOB_BYTES: String(1024 * 1024) } });
+    try {
+        const big = `CHAT-PROMPT-CANARY ${"a".repeat(16384 - 19)}`;
+        assert.equal(big.length, 16384);
+        const a = chatAssign(r, { inputs: [{ inline: big, transient: true }] });
+        assert.equal((await a.acked()).status, "accepted", "the frame with a full 16384-char inline fits the 48 KiB limit");
+        await r.done(a.p.jobId, 8000);
+        assert.equal(r.fake.jobs.get(a.p.jobId).request.text.length, 16384);
+        assert.equal(r.frames(a.p.jobId, "job.result")[0].payload.outcome, "no_change");
+        const s = await content(r, { kind: "chat.session", ref: a.p.jobId });
+        assert.equal(s.body.turns[0].text.length, 16384);
+
+        // 5000 four-byte characters: 5000 chars (the schema allows it) but 20000 bytes (agent2 and the contract's frame budget count bytes)
+        const wide = "\u{1F600}".repeat(5000);
+        const posts = () => r.fake.requests.filter((x) => x.method === "POST" && x.path === "/local/v1/jobs").length;
+        const before = posts();
+        const b = chatAssign(r, { inputs: [{ inline: wide, transient: true }] });
+        assert.equal((await b.acked()).status, "accepted");
+        await r.done(b.p.jobId, 8000);
+        const res = r.frames(b.p.jobId, "job.result")[0].payload;
+        assert.equal(res.outcome, "failed");
+        assert.equal(r.fake.jobs.has(b.p.jobId), false, "agent2 never saw a truncated prompt");
+        assert.equal(posts(), before, "agent2 was not even called: the Local Agent refuses the prompt itself");
+        assert.equal(r.frames(b.p.jobId, "job.event").at(-1).payload.state, "failed");
+        const st = await content(r, { kind: "job.stream", ref: b.p.jobId });
+        assert.equal(st.body.done, true, "a failed chat closes its stream");
+    } finally { await r.stop(); }
+});
+
+test("long-poll: held up to the hold while nothing is new, answered as soon as an event arrives; a done:false empty page keeps the same cursor", async () => {
+    const r = await chatRig({ scenario: "chat_slow", env: { LOCAL_AGENT_CHAT_POLL_MS: "500" } });
+    try {
+        const a = chatAssign(r);
+        await a.acked();
+        await waitFor(() => r.fake.jobs.get(a.p.jobId)?.lines.length >= 1, 5000);
+        // drain what is there, then ask again: the live job ticks every 60 ms so there is always something soon
+        const t0 = Date.now();
+        const p1 = await content(r, { kind: "job.stream", ref: a.p.jobId });
+        assert.equal(p1.status, "ok");
+        assert.ok(p1.body.events.length >= 1);
+        assert.equal(p1.body.done, false);
+        const p2 = await content(r, { kind: "job.stream", ref: p1.body.nextRef });
+        assert.ok(p2.body.events[0].i === p1.body.events.at(-1).i + 1, "continues exactly after the last event of the previous page");
+        assert.ok(Date.now() - t0 < 3000);
+        // stop the ticks: cancel; then a poll on the end gets done:true
+        await r.cancel(a.p.jobId);
+        await r.done(a.p.jobId, 8000);
+        const end = await drain(r, a.p.jobId);
+        assert.equal(end.pages.at(-1).done, true);
+    } finally { await r.stop(); }
+
+    // idle: an empty page after the hold, same cursor, done=false
+    const idle = await chatRig({ scenario: "stuck", env: { LOCAL_AGENT_CHAT_POLL_MS: "250" } });
+    try {
+        const a = chatAssign(idle);
+        await a.acked();
+        await waitFor(() => idle.fake.jobs.has(a.p.jobId), 5000);
+        const t0 = Date.now();
+        const p = await content(idle, { kind: "job.stream", ref: a.p.jobId });
+        assert.ok(Date.now() - t0 >= 200, `held ${Date.now() - t0} ms`);
+        assert.deepEqual([p.body.events.length, p.body.done], [0, false]);
+        const q = await content(idle, { kind: "job.stream", ref: p.body.nextRef });
+        assert.equal(q.body.nextRef, p.body.nextRef, "the same position, the same cursor");
+        await idle.cancel(a.p.jobId);
+    } finally { await idle.stop(); }
+});
+
+test("job.stream asked while the job is still QUEUED (no ChatStore record yet) waits for the job instead of failing; once the job starts the request is answered", async () => {
+    const scenario = (job, h) => (job.request.text.includes("FIRST-JOB") ? SCENARIOS.chat_slow(job, h) : SCENARIOS.chat_answer(job, h));
+    const r = await chatRig({ scenario, env: { LOCAL_AGENT_CHAT_POLL_MS: "4000" } });
+    try {
+        const first = chatAssign(r, { inputs: [{ inline: "FIRST-JOB hold the runner", transient: true }] });
+        await first.acked();
+        await waitFor(() => r.fake.jobs.has(first.p.jobId), 5000);
+        const second = chatAssign(r);   // one job at a time: this one is queued in the manager and never reached its runner
+        assert.equal((await second.acked()).status, "accepted");
+        assert.equal(r.fake.jobs.has(second.p.jobId), false);
+        assert.equal(r.link.jobs.isActiveChat(second.p.jobId), true);
+        const requestId = uuid();
+        r.cp.sendData("content.request", { kind: "job.stream", ref: second.p.jobId, actor: { userId: "u-1", role: "member" } }, { workspaceId: "ws-1", requestId });
+        await new Promise((res) => setTimeout(res, 400));
+        assert.equal(r.cp.received.some((f) => f.type === "content.response" && f.requestId === requestId), false, "held, not refused");
+        await r.cancel(first.p.jobId);   // the runner is free: the queued job starts, the held request is answered
+        await waitFor(() => r.cp.received.some((f) => f.type === "content.response" && f.requestId === requestId), 8000);
+        const frames = r.cp.received.filter((f) => f.type === "content.response" && f.requestId === requestId);
+        assert.equal(frames[0].payload.status, "ok");
+        await r.done(second.p.jobId, 8000);
+        const { events } = await drain(r, second.p.jobId);
+        assert.equal(events.length, 5);
+        // a job nobody holds is not_found at once (no wait)
+        const t0 = Date.now();
+        const nf = await content(r, { kind: "job.stream", ref: uuid() });
+        assert.equal(nf.status, "not_found");
+        assert.ok(Date.now() - t0 < 2000);
+    } finally { await r.stop(); }
+});
+
+test("cancel: job.cancel reaches agent2, the job ends cancelled, what was written stays, the stream closes with done:true and the session keeps the user's turn", async () => {
+    const r = await chatRig({ scenario: "chat_slow" });
+    try {
+        const a = chatAssign(r);
+        await a.acked();
+        await waitFor(() => r.fake.jobs.get(a.p.jobId)?.lines.length >= 3, 5000);
+        assert.equal((await r.cancel(a.p.jobId)).status, "accepted");
+        await r.done(a.p.jobId, 10000);
+        assert.equal(r.fake.jobs.get(a.p.jobId).record.cancelCalls, 1);
+        assert.equal(r.frames(a.p.jobId, "job.result")[0].payload.outcome, "cancelled");
+        const { events, pages } = await drain(r, a.p.jobId);
+        assert.equal(pages.at(-1).done, true);
+        assert.ok(events.length >= 3, "the part already written is still there");
+        assert.match(events[0].e, /CHAT-SLOW first/);
+        const s = await content(r, { kind: "chat.session", ref: a.p.jobId });
+        assert.equal(s.body.turns[0].role, "user");
+        // the file on disk says it ended cancelled
+        const file = path.join(r.chatDir, r.cp.tenantId, `${a.p.jobId}.jsonl`);
+        const recs = fs.readFileSync(file, "utf8").trim().split("\n").map((l) => JSON.parse(l));
+        assert.equal(recs.at(-1).k, "end");
+        assert.equal(recs.at(-1).state, "cancelled");
+        assert.equal(r.link.agent2.active, null, "no orphan job in the runner");
+        noCanary(wireWithoutContent(r));
+    } finally { await r.stop(); }
+});
+
+test("outcome of a chat: the loop changed files but the model concluded no_change -> outcome stays no_change and filesChangedCount says how many; failed stays failed", async () => {
+    const r = await chatRig({ scenario: "chat_files" });
+    try {
+        const a = chatAssign(r);
+        await a.acked();
+        await r.done(a.p.jobId, 8000);
+        const res = r.frames(a.p.jobId, "job.result")[0].payload;
+        assert.deepEqual([res.outcome, res.filesChangedCount, res.prUrl], ["no_change", 3, undefined]);
+        assert.equal(r.frames(a.p.jobId, "job.event").at(-1).payload.filesChanged, 3);
+        assert.deepEqual(r.cp.errorsSent, []);
+        noCanary(wireWithoutContent(r));
+    } finally { await r.stop(); }
+
+    const f = await chatRig({ scenario: "chat_fail" });
+    try {
+        const a = chatAssign(f);
+        await a.acked();
+        await f.done(a.p.jobId, 8000);
+        const res = f.frames(a.p.jobId, "job.result")[0].payload;
+        assert.equal(res.outcome, "failed");
+        assert.equal(f.frames(a.p.jobId, "job.event").at(-1).payload.errorCode, "llm_error");
+        const s = await content(f, { kind: "chat.session", ref: a.p.jobId });
+        assert.deepEqual(s.body.turns.map((t) => t.role), ["user", "assistant"], "what the person saw before it failed is kept");
+        assert.match(s.body.turns[1].text, /CHAT-FAIL started/);
+        assert.equal((await drain(f, a.p.jobId)).pages.at(-1).done, true);
+    } finally { await f.stop(); }
+});
+
+test("DLP: secrets in the prompt, the stream and the answer are masked on the disk and on the wire; a private key is withheld; DLP not enforce at request time = nothing served", async () => {
+    const r = await chatRig({ scenario: "chat_secret" });
+    try {
+        const a = chatAssign(r, { inputs: [{ inline: `CHAT-PROMPT-CANARY my token is ${GH}`, transient: true }] });
+        await a.acked();
+        await r.done(a.p.jobId, 8000);
+        const { events } = await drain(r, a.p.jobId);
+        const s = await content(r, { kind: "chat.session", ref: a.p.jobId });
+        const everything = JSON.stringify([events, s.body]);
+        assert.ok(!everything.includes(GH), "the token never leaves");
+        assert.ok(!everything.includes(PEM_MARK) && !everything.includes("MIIEowIBAAKC"), "the private key never leaves");
+        assert.match(everything, /CHAT-SECRET-CANARY/, "the rest of the content is delivered");
+        assert.match(everything, /withheld by the Local Agent DLP/);
+        assert.match(everything, /REDACTED/);
+        const onDisk = fs.readFileSync(path.join(r.chatDir, r.cp.tenantId, `${a.p.jobId}.jsonl`), "utf8");
+        assert.ok(!onDisk.includes(GH) && !onDisk.includes("MIIEowIBAAKC") && !onDisk.includes(PEM_MARK), "no secret on the customer's disk either");
+        // the agent2 request itself carries the prompt as the person wrote it: that is agent2's local input, not the store
+        // the door closes per request: DLP is read at every request
+        r.env.LOCAL_AGENT_DLP_MODE = "warn";
+        const w = await content(r, { kind: "job.stream", ref: a.p.jobId });
+        assert.deepEqual([w.status, w.errorCode], ["error", "protocol_unsupported"]);
+        const w2 = await content(r, { kind: "chat.session", ref: a.p.jobId });
+        assert.deepEqual([w2.status, w2.errorCode], ["error", "protocol_unsupported"]);
+        r.env.LOCAL_AGENT_DLP_MODE = "enforce";
+        assert.equal((await content(r, { kind: "chat.session", ref: a.p.jobId })).status, "ok");
+        noCanary(wireWithoutContent(r));
+    } finally { await r.stop(); }
+});
+
+test("egress masks again: a conversation file written by something else (or by an older build) with a secret in it is still served masked", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "la-chat-old-"));
+    const r = await chatRig({ chatDir: dir });
+    try {
+        const id = uuid();
+        const tenantDir = path.join(dir, r.cp.tenantId);
+        const rec = (o) => `${JSON.stringify(o)}\n`;
+        fs.writeFileSync(path.join(tenantDir, `${id}.jsonl`), rec({ k: "meta", v: 1, ws: "ws-1", ts: "2026-11-05T10:00:00.000Z" })
+            + rec({ k: "turn", role: "user", ts: "2026-11-05T10:00:00.000Z", text: `hello ${GH}` })
+            + rec({ k: "ev", e: JSON.stringify({ type: "token", content: `secret ${GH}` }) })
+            + rec({ k: "turn", role: "assistant", ts: "2026-11-05T10:00:01.000Z", text: `answer ${GH}` })
+            + rec({ k: "end", state: "done", ts: "2026-11-05T10:00:01.000Z" }), { mode: 0o600 });
+        const { events } = await drain(r, id);
+        const s = await content(r, { kind: "chat.session", ref: id });
+        const all = JSON.stringify([events, s.body]);
+        assert.ok(!all.includes(GH), "the second mask, on the way out, caught it");
+        assert.match(all, /REDACTED/);
+        assert.equal(events.length, 1);
+        JSON.parse(events[0].e);   // masking a piece never breaks the JSON of an event line
+    } finally { await r.stop(); fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("egress, quoted secrets: a stored event line with {\"db_password\":...} / password = \"...\" in token, tool result and summary is masked in the job.stream BODY (decoded strings, not the JSON text)", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "la-chat-q-"));
+    const r = await chatRig({ chatDir: dir });
+    try {
+        const PW = "Sup3rS3cretValue!99";
+        const KEY = "abcd1234efgh5678ijkl9999";
+        const id = uuid();
+        const rec = (o) => `${JSON.stringify(o)}\n`;
+        const evs = [
+            { type: "token", content: `password = "${PW}"` },
+            { type: "tool_result", content: { db_password: PW, api_key: KEY } },
+            { type: "summary", content: { answer: `password = "${PW}" and api_key: "${KEY}"`, conversationId: id } },
+        ];
+        fs.writeFileSync(path.join(dir, r.cp.tenantId, `${id}.jsonl`), rec({ k: "meta", v: 1, ws: "ws-1", ts: "2026-11-05T10:00:00.000Z" })
+            + evs.map((e) => rec({ k: "ev", e: JSON.stringify(e) })).join("") + rec({ k: "end", state: "done", ts: "2026-11-05T10:00:01.000Z" }), { mode: 0o600 });
+        const { events } = await drain(r, id);
+        assert.equal(events.length, 3);
+        const wire = JSON.stringify(events);
+        assert.ok(!wire.includes(PW) && !wire.includes(KEY), "no quoted secret in the body that crosses the control plane");
+        for (const e of events) JSON.parse(e.e);
+        assert.match(wire, /REDACTED/);
+    } finally { await r.stop(); fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("refs: a cursor of another workspace, a foreign workspace, a path-like or unknown ref are all not_found, with no oracle", async () => {
+    const r = await chatRig();
+    try {
+        const a = chatAssign(r);
+        await a.acked();
+        await r.done(a.p.jobId, 8000);
+        const ok = await content(r, { kind: "job.stream", ref: a.p.jobId });
+        const cursor = ok.body.nextRef;
+        const nf = async (o) => { const x = await content(r, o); assert.deepEqual([x.status, x.errorCode ?? null], ["not_found", null], JSON.stringify(o)); };
+        await nf({ kind: "job.stream", ref: a.p.jobId, workspaceId: "ws-other" });
+        await nf({ kind: "job.stream", ref: cursor, workspaceId: "ws-other" });
+        await nf({ kind: "job.stream", ref: uuid() });
+        await nf({ kind: "job.stream", ref: "A".repeat(43) });
+        await nf({ kind: "job.stream", ref: "../../etc/passwd" });
+        await nf({ kind: "job.stream", ref: `${a.p.jobId}/../x` });
+        await nf({ kind: "chat.session", ref: uuid() });
+        await nf({ kind: "chat.session", ref: cursor });
+        await nf({ kind: "chat.session", ref: "../../../etc/passwd" });
+        await nf({ kind: "chat.session", ref: a.p.jobId, workspaceId: "ws-other" });
+        // a byte range makes no sense on a page
+        r.cp.sendData("content.request", { kind: "job.stream", ref: a.p.jobId, range: { offset: 0, length: 10 }, actor: { userId: "u-1", role: "member" } }, { workspaceId: "ws-1", requestId: uuid() });
+        assert.deepEqual(r.cp.errorsSent, []);
+    } finally { await r.stop(); }
+});
+
+test("after a restart of the Local Agent: the conversation is read from the disk (retention), a new link serves chat.session and job.stream of the old job", async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "la-chat-restart-"));
+    const a = await chatRig({ chatDir: dir });
+    let jobId;
+    try {
+        const j = chatAssign(a);
+        await j.acked();
+        await a.done(j.p.jobId, 8000);
+        jobId = j.p.jobId;
+        await a.link.chat.store.flush();
+    } finally { await a.stop(); }
+    const b = await chatRig({ chatDir: dir });
+    try {
+        const s = await content(b, { kind: "chat.session", ref: jobId });
+        assert.equal(s.status, "ok");
+        assert.deepEqual(s.body.turns.map((t) => t.role), ["user", "assistant"]);
+        const { events, pages } = await drain(b, jobId);
+        assert.equal(events.length, 5);
+        assert.equal(pages.at(-1).done, true);
+    } finally { await b.stop(); fs.rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("a many-line chat: pages are bounded (events and bytes), every page fits the contract and the lines come back whole and in order", async () => {
+    const r = await chatRig({ scenario: "chat_many", env: { LOCAL_AGENT_CHAT_PAGE_EVENTS: "10", LOCAL_AGENT_CHAT_PAGE_BYTES: String(40 * 1024) } });
+    try {
+        const a = chatAssign(r);
+        await a.acked();
+        await r.done(a.p.jobId, 10000);
+        const { events, pages } = await drain(r, a.p.jobId);
+        assert.equal(events.length, 61);
+        assert.deepEqual(events.map((e) => e.i), [...Array(61).keys()]);
+        assert.ok(pages.every((p) => p.events.length <= 10));
+        assert.ok(pages.length >= 7);
+        for (const e of events) JSON.parse(e.e);   // never a cut line
+    } finally { await r.stop(); }
+});
+
+test("agent2 that lost chat after the start (restarted without the flag): the job fails (infra), agent2 gets no job, and it is never run as another kind", async () => {
+    const kinds = [...KINDS_CHAT];
+    const r = await chatRig({ fakeKinds: kinds });
+    try {
+        assert.ok(r.cp.registers[0].capabilities.includes("job.chat"));
+        kinds.splice(kinds.indexOf("chat"), 1);   // /health no longer lists chat
+        const a = chatAssign(r);
+        await a.acked();
+        await r.done(a.p.jobId, 8000);
+        assert.equal(r.frames(a.p.jobId, "job.result")[0].payload.outcome, "failed");
+        assert.equal(r.frames(a.p.jobId, "job.event").at(-1).payload.errorCode, "infra");
+        assert.equal(r.fake.jobs.size, 0);
+        assert.equal((await drain(r, a.p.jobId)).pages.at(-1).done, true, "the stream of a failed chat is closed");
+    } finally { await r.stop(); }
+});
+
+test("kind chat does not weaken the other kinds: fix and implement run as before and are not recorded in the ChatStore", async () => {
+    const r = await chatRig({ scenario: "ok_pr" });
+    try {
+        const a = r.assign({ kind: "implement", options: { createPullRequest: true }, inputs: [{ inline: `${CANARIES.request} add it`, transient: true }] });
+        assert.equal((await a.acked()).status, "accepted");
+        await r.done(a.p.jobId, 8000);
+        assert.equal(r.frames(a.p.jobId, "job.result")[0].payload.outcome, "pr_opened");
+        assert.equal(r.fake.jobs.get(a.p.jobId).kind, "implement");
+        assert.deepEqual(fs.readdirSync(path.join(r.chatDir, r.cp.tenantId)), [], "no conversation file for a non-chat job");
+        const q = await content(r, { kind: "job.stream", ref: a.p.jobId });
+        assert.equal(q.status, "not_found");
+        assert.equal(r.fake.requests.filter((x) => x.method === "STREAM").length, 0, "the content stream of agent2 is read for chats only");
+    } finally { await r.stop(); }
+});
+
+test("agent2 is started with AGENT2_LOCAL_CHAT_ENABLED only when this agent runs the chat", () => {
+    const env = { PATH: "/usr/bin", HOME: "/home/x" };
+    const base = resolveAgent2RunnerConfig({ LOCAL_AGENT_RUNNER: "agent2", LOCAL_AGENT_AGENT2_CMD: '["java","-jar","a.jar"]' }, () => {});
+    const args = { env, tenantId: "3f2b8c1e-5a4d-4e7b-9c21-0a1b2c3d4e5f", token: "t".repeat(43), bridgeBase: "http://127.0.0.1:1", callbackToken: "c".repeat(43) };
+    assert.equal(base.chat, false);
+    assert.equal(agent2ChildEnv({ config: base, ...args }).AGENT2_LOCAL_CHAT_ENABLED, undefined);
+    assert.equal(agent2ChildEnv({ config: { ...base, chat: true }, ...args }).AGENT2_LOCAL_CHAT_ENABLED, "true");
+    // an operator's own value in the environment of this agent is not passed on (the allowlist)
+    assert.equal(agent2ChildEnv({ config: base, ...args, env: { ...env, AGENT2_LOCAL_CHAT_ENABLED: "true" } }).AGENT2_LOCAL_CHAT_ENABLED, undefined);
+});

package/test/la-protocol-v2/chat-real-e2e.test.js

@@ -0,0 +1,69 @@
+// LA-1 + LA-3, OPT-IN: the REAL agent2 (jar of visionhammer-agents release/qa with kind=chat, PR #313) started by this agent with AGENT2_LOCAL_CHAT_ENABLED, a real v2 session
+// against the ReferenceCp, a FAKE AI gateway (the model concludes with conclude_no_change) and a stub of the LA /workspace API. Skipped unless AGENT2_JAR points at the jar
+// (agents/software-engineer/target/software-engineer-*.jar, JDK 21) and a Java is found (AGENT2_JAVA or JAVA_HOME). Proves beyond the fakes: the real agent2 lists `chat` in
+// /health, accepts kind=chat, its real content stream (`/jobs/{id}/stream`) is recorded and served by job.stream / chat.session, and `job.chat` is announced from that /health.
+// Does not prove: a real model, a real repository, the gateway.
+import { test, after } from "node:test";
+import assert from "node:assert/strict";
+import http from "node:http";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { closeAllFakes, okMessages, byPath } from "./helpers/fake-llm.js";
+import { agent2Rig, CANARIES, waitFor, uuid } from "./helpers/agent2-rig.js";
+import { loadContract } from "../../src/la-protocol-v2/contract.js";
+
+after(closeAllFakes);
+const JAR = process.env.AGENT2_JAR || "";
+const JAVA = process.env.AGENT2_JAVA || (process.env.JAVA_HOME ? `${process.env.JAVA_HOME}/bin/java` : "");
+const skip = !JAR || !fs.existsSync(JAR) || !JAVA || !fs.existsSync(JAVA) ? "set AGENT2_JAR (and AGENT2_JAVA or JAVA_HOME) to run the real agent2 chat end to end" : false;
+const contract = loadContract();
+
+async function fakeLaWorkspace() {
+    const server = http.createServer((req, res) => { req.resume(); res.writeHead(200, { "content-type": "application/json" }); res.end(JSON.stringify({ ok: true, success: true, files: [], content: "" })); });
+    await new Promise((r) => server.listen(0, "127.0.0.1", r));
+    return { url: `http://127.0.0.1:${server.address().port}`, close: () => new Promise((r) => { server.closeAllConnections?.(); server.close(() => r()); }) };
+}
+
+test("REAL agent2 chat: /health lists chat -> job.chat announced -> kind=chat -> content stream recorded -> job.stream + chat.session; metadata only on the job frames", { skip, timeout: 300_000 }, async () => {
+    const la = await fakeLaWorkspace();
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "la-chat-real-"));
+    const conclude = okMessages("", { blocks: [{ type: "tool_use", id: "toolu_1", name: "conclude_no_change", input: { answer: CANARIES.answer, reason: "informational" } }], promptTokens: 120, completionTokens: 20 });
+    const r = await agent2Rig({ spawn: { cmd: [JAVA, "-Xmx512m", "-jar", JAR], env: { LOCAL_AGENT_AGENT2_START_TIMEOUT_MS: "150000", LOCAL_AGENT_AGENT2_LA_URL: la.url } },
+        behavior: byPath({ messages: conclude }),
+        env: { LOCAL_AGENT_CHAT: "true", LOCAL_AGENT_CHAT_DIR: dir, LOCAL_AGENT_CHAT_PROBE_MS: "170000", LOCAL_AGENT_CHAT_POLL_MS: "2000", LOCAL_AGENT_LLM_MAX_PROMPT_BYTES: String(2 * 1024 * 1024), LOCAL_AGENT_JOBS_CANCEL_GRACE_MS: "20000", LOCAL_AGENT_AGENT2_CANCEL_WAIT_MS: "15000" } });
+    try {
+        assert.ok(r.cp.registers[0].capabilities.includes("job.chat"), `job.chat announced from the real /health: ${JSON.stringify(r.cp.registers[0].capabilities)}`);
+        const a = r.assign({ kind: "chat", incidentRef: undefined, inputs: [{ inline: `${CANARIES.request} explain the greeting`, transient: true }], budget: { tokens: 200_000, seconds: 200 } });
+        assert.equal((await a.acked()).status, "accepted");
+        await r.done(a.p.jobId, 200_000);
+        const res = r.frames(a.p.jobId, "job.result")[0].payload;
+        assert.deepEqual([res.outcome, res.prUrl], ["no_change", undefined], JSON.stringify(r.link.agent2.audit.tail(20)));
+        // read the stream
+        const events = [];
+        let ref = a.p.jobId;
+        for (let n = 0; n < 40; n++) {
+            const requestId = uuid();
+            r.cp.sendData("content.request", { kind: "job.stream", ref, actor: { userId: "u-1", role: "member" } }, { workspaceId: "ws-1", requestId });
+            await waitFor(() => r.cp.received.some((f) => f.type === "content.response" && f.requestId === requestId && f.chunk?.last), 20_000);
+            const body = JSON.parse(Buffer.concat(r.cp.contentRequests.get(requestId).chunks).toString("utf8"));
+            assert.equal(contract.validateBody("job.stream.body.schema.json", body), true);
+            events.push(...body.events);
+            ref = body.nextRef;
+            if (body.done) break;
+        }
+        const types = events.map((e) => { try { return JSON.parse(e.e).type; } catch { return "?"; } });
+        assert.ok(types.includes("session_start") && types.at(-1) === "summary", types.join(","));
+        assert.ok(events.some((e) => e.e.includes(CANARIES.answer)), "the answer is in the recorded stream");
+        const requestId = uuid();
+        r.cp.sendData("content.request", { kind: "chat.session", ref: a.p.jobId, actor: { userId: "u-1", role: "member" } }, { workspaceId: "ws-1", requestId });
+        await waitFor(() => r.cp.received.some((f) => f.type === "content.response" && f.requestId === requestId && f.chunk?.last), 20_000);
+        const s = JSON.parse(Buffer.concat(r.cp.contentRequests.get(requestId).chunks).toString("utf8"));
+        assert.equal(contract.validateBody("chat.session.body.schema.json", s), true);
+        assert.deepEqual(s.turns.map((t) => t.role), ["user", "assistant"]);
+        assert.match(s.turns[1].text, new RegExp(CANARIES.answer));
+        const wire = JSON.stringify(r.cp.received.filter((f) => f.type !== "content.response"));
+        for (const c of [CANARIES.request, CANARIES.answer]) assert.ok(!wire.includes(c), `content on a job frame: ${c}`);
+        assert.deepEqual(r.cp.errorsSent, []);
+    } finally { await r.stop(); await la.close(); fs.rmSync(dir, { recursive: true, force: true }); }
+});