deepdebug-local-agent 1.12.1 → 1.13.0

package/src/la-protocol-v2/contract/README.md

@@ -5,6 +5,7 @@ sides. Design: vault `10 Library/Plans/Fase 3 Desenho Tecnico 2026-10-28.md` sec
 implements it behind `deepdebug.agent-ws.protocol-v2.enabled` (default off, F3-05a); the LA side (F3-05b) does not
 exist yet. v1 is untouched. The gateway packages `*.schema.json` + `index.json` from this folder as classpath
 `la-protocol-v2/` (pom resource; both Dockerfiles copy this folder), so this folder stays the only source.
+**Revision 2.3** (`index.json` `revision`, ADR-0014 Design A, last section): chat on the Local Agent. No new frame type: `job.assign.kind` gains `chat`, the inline input grows to 16384 chars, two body schemas (`job.stream.body`, `chat.session.body`) and the capabilities `job.chat` and `job.inline.16k`.
 **Revision 2.2** (`index.json` `revision`, F3-08c, last section): two new frame types, `policy.check` / `policy.decision`, and the capability `policy.check`.
 **Revision 2.1** (Fase 3): optional LLM key delivery, chunked webhooks, size/model in `incident.candidate`, `ready.capabilities`, `job.assign.options` and the capabilities `job.assign` / `job.options`.
 
@@ -13,6 +14,8 @@ exist yet. v1 is untouched. The gateway packages `*.schema.json` + `index.json`
   one per allowlisted type, each `$ref`s the envelope and closes `payload`. `defs.schema.json`: shared types.
 - `file.list.body.schema.json` (F3-07c): not a frame type; the schema of the DECODED body of a `content.response` for kind `file.list`
   (below). `vectors/file.list.body.vectors.json` holds its vectors (same format, `schema` names that file).
+- `job.stream.body.schema.json` and `chat.session.body.schema.json` (2.3): the same kind of file (decoded bodies of a `content.response`, not frames) for the
+  content kinds `job.stream` and `chat.session`; their vectors are `vectors/job.stream.body.vectors.json` and `vectors/chat.session.body.vectors.json`.
 - `index.json`: allowlist, direction, signed/control flags, content class per type (`none`, `relay`, `transit`, `secret`), the limits below and the contract `revision`.
 - Vector files of a BODY that travels inside a frame (not a frame) are named `*.body.vectors.json` and their schema `*.body.schema.json`; the frame
   suites skip them (`ProtocolV2ContractTest` checks them against their own schema, `SchemaLaV2ContractTest` does not read them as frames).
@@ -359,3 +362,42 @@ Nothing of a check is logged beyond ids, the action type and the outcome.
 **Compatible.** Additive: the 22 types, their schemas and their vectors are unchanged; the envelope `type` enum gained two names. Roll out the gateway first
 (it accepts both shapes and lists the capability only for an LA that announced it), then the LAs. Vectors: `vectors/policy.check.vectors.json` (5 valid, 20 invalid)
 and `vectors/policy.decision.vectors.json` (5 valid, 16 invalid).
+
+## Revision 2.3 (ADR-0014 Design A, GW-1): chat on the Local Agent
+Decisions of Edu (Q1-Q10, 2026-11-04): for a tenant in `data_plane_mode=client` the chat loop runs on the Local Agent; the cloud only holds metadata. This
+revision is **only the contract and its constants**: nothing in the gateway sends the new shapes yet (every flag stays off), so a 2.2 peer is not affected. All changes are
+additive; every frame a 2.2 peer sends is still valid under the 2.3 schemas (the only widening is the inline `maxLength`, the only new value is the enum member `chat`).
+
+### (a) `job.assign.payload.kind = "chat"` and the capability `job.chat`
+- `kind` enum is now `fix | implement | quality | chat`. `chat` runs the agent2 in its free (unified) mode on the Local Agent: the LA decides question, fix or feature. The
+  request text is `inputs[].inline` (transient), the workspace and repo are `workspaceId` + `repoRef` as for any job. `incidentRef` is absent for a chat.
+- **Capability `job.chat`.** The LA announces it in `register` and `hello` (it implies `job.assign`). The CP sends `kind:"chat"` ONLY to a session that announced it
+  (`LocalAgentMessageSender.CAP_JOB_CHAT`, enforced in `AgentWebSocketHandler.requiredCapabilities`); with none, the caller gets `503 AGENT_UNSUPPORTED`. The CP never falls
+  back to a hosted agent. A 2.2 LA would answer `kind:"chat"` with a schema violation, which is why the capability exists.
+- `job.result.outcome` for a chat is `no_change` (no pull request until a local provider credential exists, Q8) or `failed` / `cancelled`; no enum changed.
+- A credential has no field: the payload stays closed (git credentials are local to the LA, Q1; vector `chat-inline-with-git-token`). `/ask` is not a job kind (Q6; vector `kind-ask-outside-allowlist`).
+
+### (b) Inline input up to 16384 chars and the capability `job.inline.16k`
+- `inputs[].inline.maxLength` goes from 4096 to **16384** (still `x-content-class: transit`, `transient: true`, not persisted; `paramsRaw` echoes it).
+- **Capability `job.inline.16k`.** The CP sends an inline input above 4096 chars ONLY to a session that announced it (`CAP_JOB_INLINE_16K`, `INLINE_LEGACY_MAX_CHARS` = 4096,
+  `INLINE_16K_MAX_CHARS` = 16384). An LA without it would answer a schema violation. Both capability names match the `capability` pattern: no enum changes.
+- **Budget.** A CP->LA frame repeats the payload in `paramsRaw`: 16384 chars of inline appear twice, about 34 KiB with the rest of the payload and the signature,
+  under the 48 KiB frame limit (`valid-chat-job-and-stream` trace carries a full 16384-char inline). The "about 20 KiB" effective payload in "Limits" above refers to the
+  general case; an inline of 16384 chars is the largest single field the schema allows, and the frame check (`frame_too_large`) still applies to the whole frame.
+  Non-ASCII text counts by UTF-8 bytes in the frame: 16384 four-byte characters would not fit, and the CP must check the frame size before sending.
+
+### (c) Bodies of `content.response` for `job.stream` and `chat.session` (no frame change)
+`content.request.kind` already listed `job.stream` and `chat.session` and the opaque-ref convention above already allows a UUID `ref` for them. 2.3 defines the decoded body of the answer
+(client content in transit: DLP at the LA, never parsed for storage, persisted or logged by the CP; same bounds as any `content.response`, up to 2 MiB in 64 chunks):
+- **`job.stream.body`**: `{events:[{i, e}], nextRef, done}`. Long-poll: the first request has `ref` = the job UUID; the LA holds it up to about 8 s (the CP gives 10 s to the
+  first chunk and 30 s in total) and answers with the events since the cursor, or an empty page with `done:false`. `e` is one event line as the agent2 emits it (1..16384
+  chars), `i` its 0-based position in the job's stream, `nextRef` the opaque 43-character cursor the LA minted (the convention above: base64url, no prefix; the CP cannot reverse
+  it); the next request uses it as `ref`. `done:true` closes the stream. At most 512 events per page. A cursor the LA does not know is `not_found`.
+- **`chat.session.body`**: `{turns:[{role, ts, text}], truncated}`, `role` in `user | assistant`, `ts` UTC, `text` up to 65536 chars, up to 1000 turns, `truncated:true` when the LA cut the
+  oldest turns to fit the content cap. `ref` is the conversation UUID. Decision: `turns`, not the UI's `messages` shape (the gateway maps it for the UI).
+- `content.request` itself did not change (no `waitMs`: the LA uses its default of about 8 s for `job.stream`). Vectors: `job-stream-*` and `chat-session-*` in `vectors/content.request.vectors.json`.
+
+### Compatibility and roll-out order
+Gateway with the 2.3 schemas first (it accepts both shapes and sends nothing new while the flags are off), then the LA announces `job.chat` / `job.inline.16k` only when its
+handlers exist. Vectors: `job.assign.vectors.json` (`chat-*`, `inline-*`, `kind-*`), `register`/`hello` (`capabilities-job-chat-and-inline-16k`), the two `*.body.vectors.json`, and the
+trace `vectors/traces/valid-chat-job-and-stream.json`. The existing vector `inline-above-limit` now uses 16385 chars.

package/src/la-protocol-v2/contract/chat.session.body.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.visionhammer.io/la-protocol-v2/chat.session.body.schema.json",
+  "title": "LA protocol v2: decoded body of a content.response for kind chat.session (not a frame type)",
+  "description": "The stored conversation of ONE chat session (ref = conversation UUID), read by the control plane from the Local Agent's ChatStore on disk when a person reopens the chat. Client content in transit: relayed, never stored or logged by the CP. `turns` are in order; `truncated` is true when the Local Agent cut the oldest turns to fit the content cap (README). Decision 2.3: `turns` (role, ts, text), not the FE's `messages` shape; the gateway maps it for the UI.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "turns": {
+      "type": "array",
+      "maxItems": 1000,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "role": {
+            "type": "string",
+            "enum": [
+              "user",
+              "assistant"
+            ]
+          },
+          "ts": {
+            "$ref": "defs.schema.json#/$defs/ts"
+          },
+          "text": {
+            "type": "string",
+            "maxLength": 65536,
+            "x-content-class": "relay"
+          }
+        },
+        "required": [
+          "role",
+          "ts",
+          "text"
+        ]
+      }
+    },
+    "truncated": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "turns",
+    "truncated"
+  ]
+}

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

@@ -1,6 +1,6 @@
 {
   "protocol": 2,
-  "revision": "2.2",
+  "revision": "2.3",
   "baseId": "https://schemas.visionhammer.io/la-protocol-v2/",
   "limits": {
     "maxFrameBytes": 49152,

package/src/la-protocol-v2/contract/job.assign.schema.json

@@ -24,7 +24,8 @@
           "enum": [
             "fix",
             "implement",
-            "quality"
+            "quality",
+            "chat"
           ]
         },
         "incidentRef": {
@@ -170,7 +171,7 @@
                   "inline": {
                     "type": "string",
                     "minLength": 1,
-                    "maxLength": 4096,
+                    "maxLength": 16384,
                     "x-content-class": "transit"
                   },
                   "transient": {

package/src/la-protocol-v2/contract/job.stream.body.schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.visionhammer.io/la-protocol-v2/job.stream.body.schema.json",
+  "title": "LA protocol v2: decoded body of a content.response for kind job.stream (not a frame type)",
+  "description": "One long-poll page of the event stream of ONE job (kind chat in 2.3): what the Local Agent puts, as JSON, in the base64 `data` of a content.response (contentType application/json). Client content in transit (the model's answer): the control plane relays it, never parses for storage, persists or logs it. `events[].e` is one event line exactly as the agent2 emits it; `i` is its 0-based position in the job's stream; `nextRef` is the opaque 43-character cursor the Local Agent minted: ask job.stream again with it as `ref` to continue after the last event of this page; `done` is true when the job's stream is closed and no event follows. An empty `events` with done=false is a long-poll that timed out (ask again). The first request uses the job UUID as `ref`. Total size of the body is bounded by the content relay (README), which JSON Schema cannot state.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "events": {
+      "type": "array",
+      "maxItems": 512,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "i": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          },
+          "e": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 16384,
+            "x-content-class": "relay"
+          }
+        },
+        "required": [
+          "i",
+          "e"
+        ]
+      }
+    },
+    "nextRef": {
+      "type": "string",
+      "minLength": 43,
+      "maxLength": 43,
+      "pattern": "^[A-Za-z0-9_-]{43}$"
+    },
+    "done": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "events",
+    "nextRef",
+    "done"
+  ]
+}

package/src/la-protocol-v2/jobs/agent2/api-client.js

@@ -36,6 +36,59 @@ async function readJson(res, maxBytes = MAX_JSON_BYTES) {
     try { return JSON.parse(Buffer.concat(chunks).toString("utf8")); } catch { return undefined; }
 }
 
+/**
+ * Server-Sent Events reader shared by `events` and `stream`: `onEvent(eventName, dataLines[])` for every complete event. The caller picks target and token.
+ */
+async function sseRead(getTarget, fetchImpl, path, { signal, idleMs, onEvent }) {
+    const { baseUrl, token } = getTarget();
+    const ac = new AbortController();
+    let idle = null;
+    const arm = () => { if (!idleMs) return; clearTimeout(idle); idle = setTimeout(() => ac.abort(), idleMs); };
+    const onAbort = () => ac.abort();
+    if (signal) { if (signal.aborted) throw new Agent2ApiError("cancelled"); signal.addEventListener("abort", onAbort, { once: true }); }
+    let res;
+    try {
+        arm();
+        res = await fetchImpl(`${baseUrl}/local/v1${path}`, { method: "GET", headers: { accept: "text/event-stream", authorization: `Bearer ${token}` }, signal: ac.signal });
+        if (res.status !== 200) { try { await res.body?.cancel(); } catch { /* gone */ } throw new Agent2ApiError(res.status === 404 ? "not_found" : res.status === 401 ? "unauthorized" : "http_error", { status: res.status }); }
+        if (!res.body || typeof res.body.getReader !== "function") throw new Agent2ApiError("bad_response");
+        const reader = res.body.getReader();
+        const dec = new TextDecoder("utf-8");
+        let buf = "";
+        let event = "message";
+        let data = [];
+        const dispatch = () => {
+            if (data.length || event !== "message") onEvent(event, data);
+            event = "message"; data = [];
+        };
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            arm();
+            buf += dec.decode(value, { stream: true });
+            if (buf.length > MAX_SSE_LINE_BYTES * 2) throw new Agent2ApiError("bad_response");
+            let nl;
+            while ((nl = buf.search(/\r?\n/)) >= 0) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(buf[nl] === "\r" ? nl + 2 : nl + 1);
+                if (line === "") dispatch();
+                else if (line.startsWith("event:")) event = line.slice(6).trim();
+                else if (line.startsWith("data:")) data.push(line.slice(5).replace(/^ /, ""));
+                // comments (`:`), `id:` and `retry:` are ignored
+            }
+        }
+        if (buf.trim() === "" ) dispatch();
+        return { ended: true };
+    } catch (e) {
+        if (e instanceof Agent2ApiError) throw e;
+        throw new Agent2ApiError(signal?.aborted ? "cancelled" : "stream_broken");
+    } finally {
+        clearTimeout(idle);
+        signal?.removeEventListener("abort", onAbort);
+        try { ac.abort(); } catch { /* done */ }
+    }
+}
+
 export function createAgent2Api({ getTarget, requestTimeoutMs = 10_000, fetchImpl = (...a) => globalThis.fetch(...a) }) {
     /** getTarget() -> { baseUrl, token } of the agent2 that is up now (the token changes at every start of a supervised process). */
     async function call(method, path, { body, signal, timeoutMs = requestTimeoutMs, auth = true } = {}) {
@@ -66,11 +119,21 @@ export function createAgent2Api({ getTarget, requestTimeoutMs = 10_000, fetchImp
         }
     }
 
+    const readSse = (path, o) => sseRead(getTarget, fetchImpl, path, o);
+
     return {
         /** GET /health (no token). true when agent2 answers `status: up`. */
         async health(signal) {
             try { const r = await call("GET", "/health", { auth: false, timeoutMs: Math.min(requestTimeoutMs, 3_000), signal }); return !!r.json && r.json.status === "up"; } catch { return false; }
         },
+        /** GET /health -> { up, kinds }: `kinds` is what agent2 runs (`["fix","implement"]`, plus `"chat"` with AGENT2_LOCAL_CHAT_ENABLED); an agent2 without the field has none listed. */
+        async healthInfo(signal) {
+            try {
+                const r = await call("GET", "/health", { auth: false, timeoutMs: Math.min(requestTimeoutMs, 3_000), signal });
+                const j = r.json && typeof r.json === "object" ? r.json : {};
+                return { up: j.status === "up", kinds: Array.isArray(j.kinds) ? j.kinds.filter((k) => typeof k === "string" && /^[a-z][a-z0-9._-]{0,31}$/.test(k)).slice(0, 16) : [] };
+            } catch { return { up: false, kinds: [] }; }
+        },
         async postJob(body, signal) { return (await call("POST", "/jobs", { body, signal })).json; },
         async cancel(jobId, reason = "user", signal) { return (await call("POST", `/jobs/${encodeURIComponent(jobId)}/cancel`, { body: { reason }, signal })).json; },
         async jobState(jobId, signal) { return (await call("GET", `/jobs/${encodeURIComponent(jobId)}`, { signal })).json; },
@@ -94,57 +157,21 @@ export function createAgent2Api({ getTarget, requestTimeoutMs = 10_000, fetchImp
          * rejects with Agent2ApiError on a non-200, a broken stream or an abort. The stream replays from the start: the caller skips what it already handled.
          */
         async events(jobId, { signal, onFrame, idleMs = 0 }) {
-            const { baseUrl, token } = getTarget();
-            const ac = new AbortController();
-            let idle = null;
-            const arm = () => { if (!idleMs) return; clearTimeout(idle); idle = setTimeout(() => ac.abort(), idleMs); };
-            const onAbort = () => ac.abort();
-            if (signal) { if (signal.aborted) throw new Agent2ApiError("cancelled"); signal.addEventListener("abort", onAbort, { once: true }); }
-            let res;
-            try {
-                arm();
-                res = await fetchImpl(`${baseUrl}/local/v1/jobs/${encodeURIComponent(jobId)}/events`, { method: "GET", headers: { accept: "text/event-stream", authorization: `Bearer ${token}` }, signal: ac.signal });
-                if (res.status !== 200) { try { await res.body?.cancel(); } catch { /* gone */ } throw new Agent2ApiError(res.status === 404 ? "not_found" : res.status === 401 ? "unauthorized" : "http_error", { status: res.status }); }
-                if (!res.body || typeof res.body.getReader !== "function") throw new Agent2ApiError("bad_response");
-                const reader = res.body.getReader();
-                const dec = new TextDecoder("utf-8");
-                let buf = "";
-                let event = "message";
-                let data = [];
-                const dispatch = () => {
-                    if (event === "frame" && data.length) {
-                        let frame;
-                        try { frame = JSON.parse(data.join("\n")); } catch { frame = undefined; }
-                        if (frame !== undefined) onFrame(frame);
-                    }
-                    event = "message"; data = [];
-                };
-                for (;;) {
-                    const { done, value } = await reader.read();
-                    if (done) break;
-                    arm();
-                    buf += dec.decode(value, { stream: true });
-                    if (buf.length > MAX_SSE_LINE_BYTES * 2) throw new Agent2ApiError("bad_response");
-                    let nl;
-                    while ((nl = buf.search(/\r?\n/)) >= 0) {
-                        const line = buf.slice(0, nl);
-                        buf = buf.slice(buf[nl] === "\r" ? nl + 2 : nl + 1);
-                        if (line === "") dispatch();
-                        else if (line.startsWith("event:")) event = line.slice(6).trim();
-                        else if (line.startsWith("data:")) data.push(line.slice(5).replace(/^ /, ""));
-                        // comments (`:`), `id:` and `retry:` are ignored
-                    }
-                }
-                if (buf.trim() === "" ) dispatch();
-                return { ended: true };
-            } catch (e) {
-                if (e instanceof Agent2ApiError) throw e;
-                throw new Agent2ApiError(signal?.aborted ? "cancelled" : "stream_broken");
-            } finally {
-                clearTimeout(idle);
-                signal?.removeEventListener("abort", onAbort);
-                try { ac.abort(); } catch { /* done */ }
-            }
+            return readSse(`/jobs/${encodeURIComponent(jobId)}/events`, { signal, idleMs, onEvent: (event, data) => {
+                if (event !== "frame" || !data.length) return;
+                let frame;
+                try { frame = JSON.parse(data.join("\n")); } catch { frame = undefined; }
+                if (frame !== undefined) onFrame(frame);
+            } });
+        },
+
+        /**
+         * LA-3: `GET /jobs/{id}/stream`, the CONTENT of a run (agent2's chat; LOCAL ONLY). `onLine(text)` for every SSE event, the text being its `data` (one line of
+         * agent2's event format: a JSON string). Same rules as `events`: replays from the start, `{ ended: true }` when agent2 ends it, Agent2ApiError otherwise.
+         * The lines are customer content: the caller hands them to the ChatStore and to nobody else.
+         */
+        async stream(jobId, { signal, onLine, idleMs = 0 }) {
+            return readSse(`/jobs/${encodeURIComponent(jobId)}/stream`, { signal, idleMs, onEvent: (_event, data) => { if (data.length) onLine(data.join("\n")); } });
         },
     };
 }

package/src/la-protocol-v2/jobs/agent2/config.js

@@ -91,6 +91,7 @@ export function resolveAgent2RunnerConfig(env = process.env, warn = console.warn
     }
     const common = {
         enabled: true,
+        chat: false,                                                                                     // LA-1: runtime.js turns it on (LOCAL_AGENT_CHAT + prerequisites); it makes this agent start agent2 with AGENT2_LOCAL_CHAT_ENABLED=true
         passthrough: pass,
         laUrl: loopbackBase(env.LOCAL_AGENT_AGENT2_LA_URL) || `http://127.0.0.1:${int(env.LOCAL_AGENT_PORT ?? env.PORT, 5055, 1, 65535)}`,   // this agent's own API: the bridge forwards agent2's /workspace calls to it, signed for agent2
         maxWorkspaceBodyBytes: int(env.LOCAL_AGENT_AGENT2_WORKSPACE_MAX_BODY_BYTES, 16 * MIB, 4 * KIB, 256 * MIB),   // one /workspace request body (write_file, safe-patch, ...)

package/src/la-protocol-v2/jobs/agent2/runner.js

@@ -15,6 +15,13 @@
  *   approval.decision --> POST /local/v1/approvals/{id}              after the token check (approvals.js)
  *   job.cancel / timeout --> POST /local/v1/jobs/{id}/cancel
  *
+ * kind `chat` (contract 2.3, LA-3; only with the `chat` dependency = LOCAL_AGENT_CHAT and an agent2 whose `/health` lists `chat`): the prompt is the job's inline input
+ * (up to 16 KiB of UTF-8, never cut: over it the job fails), agent2 runs its `unified` loop, and its content stream (`GET /jobs/{id}/stream`, customer content)
+ * is recorded in the ChatStore on THIS machine, masked, while the job runs. The control plane gets the same metadata frames as for any job; the conversation
+ * leaves only through `job.stream` / `chat.session` (content handlers). A chat opens no pull request (agent2 forces it): `job.result.outcome` is `no_change`,
+ * `failed` or `cancelled`, and `filesChangedCount` carries what the loop changed on disk (the greater of agent2's own count and the largest `filesChanged` of its
+ * job.event frames), so "answered" and "answered and changed files locally" stay apart even though the outcome enum has no value for the second.
+ *
  * One job at a time (agent2 refuses a second with 409; runtime.js forces LOCAL_AGENT_JOBS_MAX_CONCURRENT=1 for this runner). Failure codes only: agent2
  * unavailable / crashed / stream lost = `infra`; agent2 refusing the job = `policy_denied` (403) or `unknown`.
  *
@@ -29,6 +36,7 @@ import { createAgent2Supervisor, Agent2UnavailableError } from "./supervisor.js"
 import { createApprovalDecider } from "./approvals.js";
 import { normalizeFrame } from "./frames.js";
 import { createPolicyCheckRelay } from "./policy-check.js";
+import { consumeAgent2Stream } from "../../chat/stream-source.js";
 import { internalSignatureHeaders } from "../../../utils/request-signing.js";
 import { internalAuthHeaders, resolveAuthConfig } from "../../../utils/agent-auth.js";
 
@@ -53,6 +61,8 @@ function truncateBytes(text, max) {
     return new TextDecoder("utf-8", { fatal: false }).decode(b.subarray(0, max)).replace(/�+$/, "");
 }
 
+const CHAT_MAX_PROMPT_BYTES = 16 * 1024;   // contract 2.3 job.inline.16k, and agent2's own limit for kind=chat
+
 const HTTP_TO_JOB = Object.freeze({ 403: "policy_denied", 401: "infra", 409: "infra" });
 
 /**
@@ -62,9 +72,10 @@ const HTTP_TO_JOB = Object.freeze({ 403: "policy_denied", 401: "infra", 409: "in
  * @param {(workspaceId:string)=>string|null} o.resolveWorkspaceRoot
  * @param {()=>object} o.getSession                  the v2 session (late-bound: the link does not exist yet when the runner is built)
  * @param {{keys:Map}} o.signing                     the trusted platform keys (approval tokens)
+ * @param {object} [o.chat]                          LA-3: the chat (chat/index.js createChat()); without it this runner does not list `chat` in its kinds
  * @param {Function} [o.policyRelay]                 ({body, job}) => Promise<{status, json}>; TEST SEAM. Default: the policy.check relay over the v2 session (no session / no answer = DENY)
  */
-export function createAgent2Runner({ config, tenantId, resolveWorkspaceRoot, getSession, signing, env = process.env, log = console, policyRelay = null, fetchImpl, spawnImpl, now = Date.now, sleep = defaultSleep, rssOf, audit = null }) {
+export function createAgent2Runner({ config, tenantId, resolveWorkspaceRoot, getSession, signing, env = process.env, log = console, policyRelay = null, fetchImpl, spawnImpl, now = Date.now, sleep = defaultSleep, rssOf, audit = null, chat = null }) {
     const tenant = String(tenantId).toLowerCase();
     const auditor = audit || createAudit({ now });
     const warn = (m) => (log.warn || log.log).call(log, m);
@@ -80,6 +91,7 @@ export function createAgent2Runner({ config, tenantId, resolveWorkspaceRoot, get
     const approvals = createApprovalDecider({ api: supervisor.api, signing, tenantId: tenant, now, audit: auditor, log });
     const stats = { jobs: 0, ok: 0, failed: 0, cancelled: 0, busy: 0, framesDropped: 0, tenantViolations: 0, jobViolations: 0, auditForwarded: 0, auditGivenUp: 0, streamReconnects: 0, byCode: {} };
     let active = null;   // { jobId, workspaceId }
+    let chatKinds = false;   // agent2's `/health` listed `chat` (probeChat / start of a chat job)
 
     async function forwardAudit(payload, workspaceId, jobShort) {
         const session = getSession();
@@ -92,7 +104,7 @@ export function createAgent2Runner({ config, tenantId, resolveWorkspaceRoot, get
         }
     }
 
-    async function requestText(job, ctx) {
+    async function requestText(job, ctx, maxBytes = config.maxRequestTextBytes) {
         const parts = [];
         for (const i of job.inputs || []) {
             if (typeof i.inline === "string") parts.push(i.inline);
@@ -103,7 +115,18 @@ export function createAgent2Runner({ config, tenantId, resolveWorkspaceRoot, get
         }
         let text = parts.join("\n\n").trim();
         if (!text) text = `${job.kind === "implement" ? "Implement the requested change in this repository." : "Investigate and fix the reported problem in this repository."}${job.incidentRef?.id ? ` Incident ${job.incidentRef.id}.` : ""}`;
-        return truncateBytes(text, config.maxRequestTextBytes);
+        return truncateBytes(text, maxBytes);
+    }
+
+    /** Only the inline parts of a chat job's inputs: that is the person's prompt, the one thing the ChatStore keeps as the user's turn. */
+    const inlineText = (job) => (job.inputs || []).filter((i) => typeof i.inline === "string").map((i) => i.inline).join("\n\n");
+
+    /** Brings agent2 (and the bridge) up: the same steps before a job and before the start-up probe of the chat capability. */
+    async function ensureAgent2() {
+        const { baseUrl } = await bridge.listen();
+        if (config.mode === "attach" && config.callbackToken) bridge.setCallbackToken(config.callbackToken);
+        void baseUrl;
+        await supervisor.ensureReady();
     }
 
     function jobBody(job, root, text, token) {
@@ -122,7 +145,7 @@ export function createAgent2Runner({ config, tenantId, resolveWorkspaceRoot, get
 
     const failed = (errorCode) => { stats.failed++; stats.byCode[errorCode] = (stats.byCode[errorCode] || 0) + 1; return { outcome: "failed", errorCode }; };
 
-    async function start(job, ctx) {
+    async function run(job, ctx, rec) {
         stats.jobs++;
         const jobShort = short(job.jobId);
         if (active) { stats.busy++; note("job_refused_busy", { jobShort }); return failed("infra"); }
@@ -132,21 +155,28 @@ export function createAgent2Runner({ config, tenantId, resolveWorkspaceRoot, get
         let cancelTimer = null;
         let onDown = null;
         let sendCancel = null;
+        let streamAc = null;
+        let streamTask = null;
         try {
             const root = resolveWorkspaceRoot(job.workspaceId);
             if (!root) return failed("infra");
             try {
-                const { baseUrl } = await bridge.listen();
-                if (config.mode === "attach" && config.callbackToken) bridge.setCallbackToken(config.callbackToken);
-                void baseUrl;
-                await supervisor.ensureReady();
+                await ensureAgent2();
             } catch (e) {
                 note("agent2_unavailable", { jobShort, code: e instanceof Agent2UnavailableError ? e.code : "bridge", mode: config.mode });
                 return failed("infra");
             }
             if (ctx.signal.aborted) return { outcome: "cancelled" };
+            if (rec) {
+                // a chat never runs as another kind: an agent2 that does not list `chat` (restarted without the flag, a sidecar of another build) fails the job
+                const info = await supervisor.api.healthInfo(ctx.signal);
+                chatKinds = info.up && info.kinds.includes("chat");
+                if (!chatKinds) { note("chat_unsupported_by_agent2", { jobShort }); return failed("infra"); }
+            }
             proxyToken = bridge.registerJob({ jobId: job.jobId, alias: job.llm.alias, llm: ctx.llm, workspaceId: job.workspaceId, incidentId: job.incidentRef?.id, root, repoRef: job.repoRef });
-            const text = await requestText(job, ctx);
+            // a chat prompt is cut at 4 bytes past the limit only to be able to tell "too long" (a cut inside a character drops at most 3 bytes): it is refused below, never sent shortened
+            const text = await requestText(job, ctx, rec ? CHAT_MAX_PROMPT_BYTES + 4 : config.maxRequestTextBytes);
+            if (rec && utf8.encode(text).length > CHAT_MAX_PROMPT_BYTES) { note("chat_prompt_too_large", { jobShort }); return failed("unknown"); }   // never cut a prompt silently
             try {
                 await supervisor.api.postJob(jobBody(job, root, text, proxyToken), ctx.signal);
             } catch (e) {
@@ -155,6 +185,10 @@ export function createAgent2Runner({ config, tenantId, resolveWorkspaceRoot, get
                 return failed(HTTP_TO_JOB[e && e.status] || (e && (e.status === 400 || e.status === 422) ? "unknown" : "infra"));
             }
             ctx.progress({ phase: "context" });
+            if (rec) {
+                streamAc = new AbortController();
+                streamTask = consumeAgent2Stream({ api: supervisor.api, jobId: job.jobId, recorder: rec, signal: streamAc.signal, reconnects: config.streamReconnects, sleep, isDown: () => supervisor.state !== "ready" });
+            }
 
             // ---- cancellation: the job's signal reaches agent2, which reports `cancelled` itself; we wait for that for a while, then let go
             let cancelSent = false;
@@ -171,7 +205,7 @@ export function createAgent2Runner({ config, tenantId, resolveWorkspaceRoot, get
             supervisor.on("down", onDown);   // agent2 died: nothing more will come
 
             // ---- the event stream (replays from the start on a reconnect: skip what was handled)
-            const st = { lastSeq: 0, result: null, terminal: null, waiting: false, forwards: [] };
+            const st = { lastSeq: 0, result: null, terminal: null, waiting: false, forwards: [], maxFilesChanged: 0 };
             const handle = (raw) => {
                 const f = normalizeFrame(raw, { tenantId: tenant, jobId: job.jobId });
                 if (!f) { stats.framesDropped++; return; }
@@ -180,6 +214,7 @@ export function createAgent2Runner({ config, tenantId, resolveWorkspaceRoot, get
                 st.lastSeq = f.seq;
                 if (f.type === "job.event") {
                     if (f.terminal) { st.terminal = f.payload; return; }
+                    if (f.payload.filesChanged > st.maxFilesChanged) st.maxFilesChanged = f.payload.filesChanged;
                     const waiting = f.payload.state === "waiting_approval";
                     st.waiting = waiting;
                     ctx.progress({ ...(f.payload.phase ? { phase: f.payload.phase } : {}), ...(f.payload.iteration !== undefined ? { iteration: f.payload.iteration } : {}),
@@ -207,6 +242,12 @@ export function createAgent2Runner({ config, tenantId, resolveWorkspaceRoot, get
                 await sleep(250 * reconnects);
             }
             await Promise.allSettled(st.forwards);
+            if (streamTask) {
+                // agent2 closes its content stream when the job is over: give it a moment to deliver the last lines (the answer), then let go
+                await Promise.race([streamTask, sleep(chat.config.streamDrainMs)]);
+                streamAc.abort();
+                await streamTask;
+            }
 
             // ---- the outcome
             const r = st.result;
@@ -221,6 +262,12 @@ export function createAgent2Runner({ config, tenantId, resolveWorkspaceRoot, get
             }
             if (r.outcome === "cancelled") { stats.cancelled++; return { outcome: "cancelled" }; }
             stats.ok++;
+            if (rec) {
+                if (r.outcome === "pr_opened") note("chat_unexpected_pr", { jobShort });   // agent2 forces no PR for a chat; if it says otherwise, the metadata is passed on as it is and this is audited
+                const filesChangedCount = Math.max(Number.isSafeInteger(r.filesChangedCount) ? r.filesChangedCount : 0, st.maxFilesChanged);
+                return { outcome: r.outcome, ...(r.prUrl ? { prUrl: r.prUrl } : {}), ...(r.branch ? { branch: r.branch } : {}), ...(r.commitSha ? { commitSha: r.commitSha } : {}),
+                    filesChangedCount, ...(r.diffSha256 ? { diffSha256: r.diffSha256 } : {}), ...(r.tests ? { tests: r.tests } : {}) };
+            }
             return { outcome: r.outcome, ...(r.prUrl ? { prUrl: r.prUrl } : {}), ...(r.branch ? { branch: r.branch } : {}), ...(r.commitSha ? { commitSha: r.commitSha } : {}),
                 ...(r.filesChangedCount !== undefined ? { filesChangedCount: r.filesChangedCount } : {}), ...(r.diffSha256 ? { diffSha256: r.diffSha256 } : {}), ...(r.tests ? { tests: r.tests } : {}) };
         } finally {
@@ -228,17 +275,51 @@ export function createAgent2Runner({ config, tenantId, resolveWorkspaceRoot, get
             if (onDown) supervisor.off("down", onDown);
             if (sendCancel) ctx.signal.removeEventListener("abort", sendCancel);
             try { evAc.abort(); } catch { /* done */ }
+            if (streamAc) { try { streamAc.abort(); } catch { /* done */ } }
             approvals.forgetJob(job.jobId);
             if (proxyToken) bridge.revokeJob(job.jobId);   // the per-job "key" stops working the moment the job is over
             if (active && active.jobId === job.jobId) active = null;
         }
     }
 
+    /** The job.assign entry point. A chat job is recorded in the ChatStore from the first moment (so `job.stream` finds it) and closed there whatever happens. */
+    async function start(job, ctx) {
+        if (job.kind !== "chat") return run(job, ctx, null);
+        if (!chat) { stats.jobs++; return failed("infra"); }   // the manager only gets here for a kind the runner lists; defence in depth
+        let rec;
+        try { rec = chat.store.begin({ jobId: job.jobId, workspaceId: job.workspaceId, userText: inlineText(job) }); } catch {
+            stats.jobs++;
+            note("chat_store_unavailable", { jobShort: short(job.jobId) });
+            return failed("infra");
+        }
+        let outcome = null;
+        try {
+            outcome = await run(job, ctx, rec);
+            return outcome;
+        } finally {
+            rec.finish(outcome ? (outcome.outcome === "failed" ? "failed" : outcome.outcome === "cancelled" ? "cancelled" : "done") : ctx.signal.aborted ? "cancelled" : "failed");
+        }
+    }
+
     return {
         name: "agent2",
-        kinds: ["fix", "implement"],       // `quality` is not served by agent2 local mode (422 there): the manager acks it protocol_unsupported
+        // `quality` is not served by agent2 local mode (422 there): the manager acks it protocol_unsupported. `chat` only with the ChatStore AND an agent2 that listed it.
+        get kinds() { return chat && chatKinds ? ["fix", "implement", "chat"] : ["fix", "implement"]; },
         needsLlm: true,
         supportsOptions: true,
+        /** LA-1: true once agent2's `/health` listed `chat` (probeChat or the start of a chat job) and the ChatStore exists: what `job.chat` is announced on. */
+        get chatReady() { return !!chat && chatKinds; },
+        /** Starts/finds agent2 and reads the kinds it runs. In spawn mode this starts the process now (not at the first job). Never throws. */
+        async probeChat() {
+            if (!chat) return false;
+            try {
+                await ensureAgent2();
+                const info = await supervisor.api.healthInfo();
+                chatKinds = info.up && info.kinds.includes("chat");
+            } catch { chatKinds = false; }
+            if (!chatKinds) note("chat_probe_negative", { mode: config.mode });
+            return chatKinds;
+        },
         start,
         cancel(jobId) {
             if (active && active.jobId === jobId && active.sendCancel) active.sendCancel();

package/src/la-protocol-v2/jobs/agent2/supervisor.js

@@ -79,6 +79,8 @@ export function agent2ChildEnv({ config, env, tenantId, token, bridgeBase, callb
     });
     if (config.maxHeapMb > 0) out.JAVA_TOOL_OPTIONS = `-Xmx${config.maxHeapMb}m`;
     if (config.approvalWaitSeconds > 0) out.AGENT2_LOCAL_APPROVAL_WAIT_SECONDS = String(config.approvalWaitSeconds);
+    // LA-1 (ADR-0014): the chat is on in agent2 only when this agent runs it (LOCAL_AGENT_CHAT and its prerequisites); runtime.js sets `config.chat`
+    if (config.chat === true) out.AGENT2_LOCAL_CHAT_ENABLED = "true";
     return out;
 }
 

package/src/la-protocol-v2/jobs/manager.js

@@ -41,7 +41,7 @@ export function jobErrorCodeOf(err) {
 
 /**
  * Runner interface (F3-08c plugs the packaged agent loop in here):
- *   { name: string, kinds?: string[] (default: all of fix|implement|quality), needsLlm?: boolean (default true),
+ *   { name: string, kinds?: string[] (default: all of fix|implement|quality; `chat` only when the runner lists it: contract 2.3, capability job.chat), needsLlm?: boolean (default true),
  *     start(job, ctx): Promise<{ outcome: "pr_opened"|"no_change"|"failed"|"cancelled", errorCode?, prUrl?, branch?, commitSha?, filesChangedCount?,
  *                                diffSha256?, tests?, answer? }>,
  *     cancel(jobId): void|Promise<void> }
@@ -54,7 +54,7 @@ export function jobErrorCodeOf(err) {
  */
 export function validateRunner(r) {
     return !!r && typeof r === "object" && typeof r.name === "string" && /^[a-z0-9][a-z0-9._-]{0,31}$/.test(r.name) && typeof r.start === "function" && typeof r.cancel === "function"
-        && (r.kinds === undefined || (Array.isArray(r.kinds) && r.kinds.every((k) => ["fix", "implement", "quality"].includes(k))))
+        && (r.kinds === undefined || (Array.isArray(r.kinds) && r.kinds.every((k) => ["fix", "implement", "quality", "chat"].includes(k))))
         && (r.supportsOptions === undefined || typeof r.supportsOptions === "boolean");
 }
 
@@ -206,6 +206,8 @@ export function createJobManager({ session, tenantId, resolveWorkspace, material
         stats, audit: auditor, events: ev,
         get runner() { return theRunner; },
         get activeCount() { return active.size; },
+        /** LA-3: true while a chat job with that id is queued, being prepared (workspace clone) or running: the ChatStore waits for such a job to appear instead of saying `not_found`. */
+        isActiveChat(jobId) { const rec = active.get(jobId); return !!rec && rec.kind === "chat" && !rec.finished; },
         get running() { return running; },
         get reservedBytes() { return reserved; },
         /** F3-08c: the packaged agent loop replaces the runner (jobs already running keep the one they started with only as far as their own cancel). */