deepdebug-local-agent 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -8,6 +8,8 @@ platform side does not sign commands yet.
 
 ### Added (opt-in, off by default)
 
+- **`LOCAL_AGENT_CHAT=true`** (LA-1 + LA-3, contract 2.3, default off). Chat on the Local Agent: `job.assign kind=chat` runs agent2's unified loop, a ChatStore on disk (0600, 30 days, no secrets) keeps the conversation, `job.stream` (long-poll with cursor) and `chat.session` serve it through the content relay (DLP enforce), `job.chat` / `job.inline.16k` are announced only if agent2 lists `chat`. See `docs/la-chat.md`. No behaviour change when off.
+
 - **`LOCAL_AGENT_RUNNER=agent2`** (F3-08c, default off). The packaged agent loop (agent2, next to the agent) runs `job.assign` jobs on the customer's side: supervised process or sidecar, a loopback bridge that
   serves its model calls (Anthropic Messages API with tools, new `ctx.llm.messages` / `LOCAL_AGENT_LLM_MESSAGES_PATH`) through the DLP and the key holder, `approval.decision` delivery with `vhapr1` token check (the approval is found through agent2's pending list of the job), PolicyGate over the v2 channel (contract 2.2 `policy.check` / `policy.decision`: the control plane
   derives tenant, agent and origin from the session, nothing is claimed here), agent2's `/workspace` calls signed for it by the bridge (signature mode stays `enforce`), a pidfile so a restart ends an orphan agent2,

package/docs/la-chat.md

@@ -0,0 +1,35 @@
+# Chat on the Local Agent (LA-1 + LA-3, ADR-0014 Design A, contract 2.3)
+
+For a tenant in `data_plane_mode=client` the chat loop runs HERE; the cloud only holds metadata. Flag `LOCAL_AGENT_CHAT` (default off).
+
+## What it needs (all of them, else it says why and stays off)
+`LOCAL_AGENT_PROTOCOL_V2`, `LOCAL_AGENT_JOBS`, `LOCAL_AGENT_RUNNER=agent2` with the LLM client, `LOCAL_AGENT_CONTENT_HANDLERS` and `LOCAL_AGENT_DLP_MODE=enforce`.
+The agent starts agent2 with `AGENT2_LOCAL_CHAT_ENABLED=true` (spawn mode); in attach mode the sidecar must have it.
+
+## Capabilities
+`job.chat` and `job.inline.16k` are announced in `register`/`hello` only when agent2's `GET /local/v1/health` lists `chat` in `kinds`. The agent asks at start-up
+(`LOCAL_AGENT_CHAT_PROBE_MS`, default 20 s; in spawn mode this starts agent2 at boot instead of at the first job). If agent2 is not ready in time, the capability appears at the next
+reconnection. The job start asks `/health` again: an agent2 that lost `chat` fails the job (`infra`); a chat is never run as another kind.
+
+## Flow
+`job.assign kind=chat` -> the ChatStore opens the conversation (conversationId = jobId) -> agent2 `unified` loop (no PR, no push) -> agent2's content stream
+(`GET /jobs/{id}/stream`, LOCAL ONLY) is recorded line by line -> the control plane reads it with `content.request`:
+- `job.stream`: long-poll (<= 8 s, `LOCAL_AGENT_CHAT_POLL_MS`) with a cursor. First `ref` = the job UUID; then the `nextRef` (43 chars) of the previous page. Body `{events:[{i,e}], nextRef, done}`.
+  The same cursor gives the same page. A job that is queued or being prepared is waited for.
+- `chat.session`: `ref` = conversation UUID. Body `{turns:[{role, ts, text}], truncated}`.
+The job frames (`job.event`, `job.result`, `audit.event`) stay metadata only.
+
+## Outcome of a chat
+`no_change`, `failed` or `cancelled`. The closed enum has no value for "answered and changed files locally", so `filesChangedCount` carries it: the greater of agent2's own count
+and the largest `filesChanged` of its job.event frames. A prompt over 16 KiB of UTF-8 is refused (`failed`/`unknown`), never cut.
+
+## Store (the customer's machine only)
+`LOCAL_AGENT_CHAT_DIR` (default `~/.deepdebug/chat`) `/<tenant>/<conversationId>.jsonl`, files 0600, folders 0700. Retention `LOCAL_AGENT_CHAT_RETENTION_DAYS` (30), ceiling
+`LOCAL_AGENT_CHAT_MAX_BYTES` (256 MiB, oldest first), per conversation `LOCAL_AGENT_CHAT_MAX_CONVERSATION_BYTES` (8 MiB, then `truncated`). A conversation being written is never swept.
+No secret is written: every piece (prompt, event line, answer) is masked by the DLP (enforce) BEFORE the disk and again on the way out; a blocked class (`LOCAL_AGENT_DLP_BLOCK_CLASSES`)
+is replaced by a fixed "withheld" text. Pieces are masked one by one, never the JSON around them. Nothing of the content is logged, audited or put in a stat.
+
+## Known gaps
+- The contract has no conversation id or `parentId` in `job.assign`: each chat job is its own conversation (`chat.session` ref = the job id) and a follow-up turn does not see the previous one.
+- `ChatStore.deleteWorkspace()` exists but nothing calls it yet (the agent has no workspace-removed hook).
+- The projection of agent2's lines into turns (answer from `summary.content.answer`, else the `token` lines) is checked against the real jar in `chat-real-e2e.test.js` only.

package/package.json

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

package/src/dlp/rules.js

@@ -17,7 +17,7 @@ import {
     plausibleCard, ibanValid, ptNifValid,
 } from './validators.js';
 
-export const RULESET_VERSION = '2026.10.28-1';
+export const RULESET_VERSION = '2026.11.05-1';
 
 export const RULE_CLASSES = Object.freeze([
     'private-key', 'cloud-credential', 'vcs-token', 'payment-key', 'saas-token', 'token',
@@ -79,7 +79,7 @@ export const RULES = Object.freeze([
 
     // Generic "name = literal" assignments
     r('generic_secret_assignment', 'credential',
-        /\b(?:[A-Za-z0-9_-]{0,40}?(?:password|passwd|pwd|secret|api[_-]?key|apikey|access[_-]?token|auth[_-]?token|client[_-]?secret|private[_-]?key|token))["']?\s*(?::|=|=>)\s*["']?([^\s"'`,;]{8,})/gi,
+        /\b(?:[A-Za-z0-9_-]{0,40}?(?:password|passwd|pwd|secret|api[_-]?key|apikey|access[_-]?token|auth[_-]?token|client[_-]?secret|private[_-]?key|token))(?:\\*["'`])?\s*(?::|=|=>)\s*(?:\\*["'`])?([^\s"'`,;]{8,})/gi,
         { group: 1, validate: looksLikeLiteralSecret }),
 
     // PII

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

@@ -0,0 +1,60 @@
+/**
+ * config.js - LOCAL_AGENT_CHAT flag and limits of the chat on the Local Agent (LA-1 + LA-3, ADR-0014 Design A, contract 2.3).
+ *
+ *   false (default)  nothing of this folder is loaded: `job.chat` / `job.inline.16k` are not announced, `job.stream` and `chat.session` answer
+ *                    `protocol_unsupported`, agent2 is not told to accept `kind=chat`.
+ *   true             the agent2 runner also runs `kind: "chat"` (agent2 `unified` loop), the ChatStore keeps the conversation ON THIS MACHINE and the content
+ *                    handlers serve `job.stream` (long-poll) and `chat.session`. Needs, all of them: LOCAL_AGENT_PROTOCOL_V2, LOCAL_AGENT_JOBS,
+ *                    LOCAL_AGENT_RUNNER=agent2 (+ the LLM client), LOCAL_AGENT_CONTENT_HANDLERS and LOCAL_AGENT_DLP_MODE=enforce (runtime.js refuses, and says so,
+ *                    when one is missing).
+ *
+ * Unset/empty/unrecognised = false. Every number is clamped: a bad value falls back to the default, never to "unlimited".
+ */
+import os from "node:os";
+import path from "node:path";
+
+export const CHAT_FLAG = "LOCAL_AGENT_CHAT";
+
+const TRUE = new Set(["true", "1", "yes", "on"]);
+const FALSE = new Set(["", "false", "0", "no", "off"]);
+const KIB = 1024;
+const MIB = 1024 * KIB;
+const DAY_MS = 86_400_000;
+
+function int(raw, def, min, max) {
+    const n = Number.parseInt(String(raw ?? ""), 10);
+    return Number.isFinite(n) && n >= min && n <= max ? n : def;
+}
+
+/** True when LOCAL_AGENT_CHAT asks for the chat (the other prerequisites are checked by runtime.js). */
+export function chatRequested(env = process.env) {
+    return TRUE.has(String(env[CHAT_FLAG] ?? "").trim().toLowerCase());
+}
+
+export function resolveChatConfig(env = process.env, warn = console.warn) {
+    const raw = String(env[CHAT_FLAG] ?? "").trim().toLowerCase();
+    if (!TRUE.has(raw)) {
+        if (!FALSE.has(raw)) warn(`[la-chat] unrecognised ${CHAT_FLAG} value; the chat stays off`);
+        return { enabled: false };
+    }
+    return {
+        enabled: true,
+        // where the conversations live: <dir>/<tenant>/<conversationId>.jsonl, 0600 in a 0700 folder; the customer's machine only
+        dir: path.resolve(String(env.LOCAL_AGENT_CHAT_DIR ?? "").trim() || path.join(os.homedir(), ".deepdebug", "chat")),
+        retentionMs: int(env.LOCAL_AGENT_CHAT_RETENTION_DAYS, 30, 1, 3650) * DAY_MS,          // Edu Q7: 30 days
+        maxBytes: int(env.LOCAL_AGENT_CHAT_MAX_BYTES, 256 * MIB, MIB, 64 * 1024 * MIB),        // the whole store; the oldest conversations go first
+        maxConversationBytes: int(env.LOCAL_AGENT_CHAT_MAX_CONVERSATION_BYTES, 8 * MIB, 16 * KIB, 256 * MIB),   // events beyond it are dropped (the chat is `truncated`)
+        sweepMs: int(env.LOCAL_AGENT_CHAT_SWEEP_MS, 3_600_000, 1_000, 86_400_000),
+        // job.stream long-poll: the gateway gives a request 10 s to the first chunk and 30 s in total (contract 2.3); the default hold is 8 s
+        pollMs: int(env.LOCAL_AGENT_CHAT_POLL_MS, 8_000, 10, 8_000),
+        pageEvents: int(env.LOCAL_AGENT_CHAT_PAGE_EVENTS, 256, 1, 512),                        // the contract caps a page at 512 events
+        pageBytes: int(env.LOCAL_AGENT_CHAT_PAGE_BYTES, 256 * KIB, 16 * KIB, 1024 * KIB),     // and the whole body must fit a content.response (1 MiB by default)
+        cursorTtlMs: int(env.LOCAL_AGENT_CHAT_CURSOR_TTL_MS, 30 * 60_000, 1_000, 24 * 3_600_000),
+        maxCursors: int(env.LOCAL_AGENT_CHAT_MAX_CURSORS, 4_096, 16, 100_000),
+        // how long the runner waits for agent2's content stream to end after the job's result before it lets go
+        streamDrainMs: int(env.LOCAL_AGENT_CHAT_STREAM_DRAIN_MS, 5_000, 100, 60_000),
+        // at start-up the runner asks agent2 which kinds it runs (`GET /health`), because `job.chat` is announced only if it says `chat`;
+        // the link waits for that at most this long (in spawn mode this starts agent2 at boot instead of at the first job)
+        probeWaitMs: int(env.LOCAL_AGENT_CHAT_PROBE_MS, 20_000, 0, 120_000),
+    };
+}

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

@@ -0,0 +1,57 @@
+/**
+ * cursors.js - the `nextRef` of `job.stream` (contract 2.3): an opaque 43-character id (base64url, no prefix, 256 random bits) that THIS agent mints for
+ * "this job, from event N". The control plane cannot read it. It is valid for ONE tenant and ONE workspace; any other combination is `null`, as if it never
+ * existed. In memory only: a restart of the agent forgets every cursor and the caller starts again from the job id (the ChatStore on disk is the truth).
+ *
+ * A cursor is NOT consumed when it is used: a lost answer is asked for again with the same cursor and gets the same page (idempotent). The same
+ * (job, position) always maps to the same id, so a long-poll that times out empty does not mint a new id every 8 s.
+ */
+import crypto from "node:crypto";
+
+export const CURSOR_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+
+export function createCursorRegistry({ tenantId, ttlMs = 30 * 60_000, maxEntries = 4096, now = Date.now } = {}) {
+    const byId = new Map();     // id -> { workspaceId, jobId, next, expiresAt }   (insertion order = age)
+    const byKey = new Map();    // `${workspaceId}|${jobId}|${next}` -> id
+    const keyOf = (e) => `${e.workspaceId}|${e.jobId}|${e.next}`;
+
+    function drop(id) {
+        const e = byId.get(id);
+        if (!e) return;
+        byId.delete(id);
+        if (byKey.get(keyOf(e)) === id) byKey.delete(keyOf(e));
+    }
+    function purge() {
+        const t = now();
+        for (const [id, e] of byId) { if (e.expiresAt > t) break; drop(id); }   // one ttl for all: insertion order is expiry order
+        while (byId.size > maxEntries) drop(byId.keys().next().value);
+    }
+
+    return {
+        get size() { return byId.size; },
+        /** @returns {string} the 43-char id for (workspace, job, next) */
+        mint({ workspaceId, jobId, next }) {
+            purge();
+            const k = keyOf({ workspaceId, jobId, next });
+            const known = byKey.get(k);
+            if (known && byId.has(known)) { const e = byId.get(known); drop(known); byId.set(known, { ...e, expiresAt: now() + ttlMs }); byKey.set(k, known); return known; }   // refresh: moves it to the young end
+            let id;
+            do { id = crypto.randomBytes(32).toString("base64url"); } while (byId.has(id));
+            byId.set(id, { workspaceId, jobId, next, expiresAt: now() + ttlMs });
+            byKey.set(k, id);
+            purge();
+            return id;
+        },
+        /** @returns {{jobId:string, next:number} | null} */
+        resolve(id, { workspaceId }) {
+            if (typeof id !== "string" || !CURSOR_PATTERN.test(id)) return null;
+            const e = byId.get(id);
+            if (!e) return null;
+            if (e.expiresAt <= now()) { drop(id); return null; }
+            if (e.workspaceId !== workspaceId) return null;
+            return { jobId: e.jobId, next: e.next };
+        },
+        clear() { byId.clear(); byKey.clear(); },
+        tenantId,
+    };
+}

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

@@ -0,0 +1,92 @@
+/**
+ * dlp.js - the one place where chat text is masked (LA-3). The conversation is client content: it is masked BEFORE it is written to the ChatStore (the store
+ * never holds a secret) and again, per piece, on the way out (`job.stream`, `chat.session`). Pieces are masked one by one, never the JSON that carries them,
+ * so a mask can never reach across the structure of a body and make it invalid.
+ *
+ * Enforce only. Any other mode, a DLP failure or an input above the DLP limit is `ok:false` (fail closed). A hit in LOCAL_AGENT_DLP_BLOCK_CLASSES withholds the piece.
+ */
+import { dlpConfigFromEnv, protectEgress, DENIED } from "../../dlp/index.js";
+import { OVERSIZE } from "../../dlp/engine.js";
+
+/** What replaces a withheld piece of text (a turn). */
+export const WITHHELD_TEXT = "[withheld by the Local Agent DLP]";
+/** What replaces a withheld event line: a valid event of the hosted format, so the front end renders it like any status. */
+export const WITHHELD_LINE = JSON.stringify({ type: "status", content: WITHHELD_TEXT });
+
+/**
+ * @returns {{ok:true, text:string, blocked:boolean, total:number, redactions:object} | {ok:false}}
+ */
+export function maskChatText(text, { env = process.env, source = "chat" } = {}) {
+    const cfg = dlpConfigFromEnv(env);
+    if (cfg.mode !== "enforce") return { ok: false };
+    if (typeof text !== "string") return { ok: false };
+    if (text.length > cfg.maxBytes) return { ok: false };
+    const res = protectEgress(text, { env, source });
+    if (res.denied || res.text === DENIED || res.text === OVERSIZE) return { ok: false };
+    return { ok: true, text: res.text, blocked: !!res.blocked, total: res.total, redactions: res.redactions };
+}
+
+/** Masks a piece and applies the withhold rule: a blocked or un-maskable piece becomes `withheld`. */
+export function maskOrWithhold(text, withheld, opts) {
+    const m = maskChatText(text, opts);
+    if (!m.ok) return { text: withheld, withheld: true, total: 0, redactions: {} };
+    if (m.blocked) return { text: withheld, withheld: true, total: m.total, redactions: m.redactions };
+    return { text: m.text, withheld: false, total: m.total, redactions: m.redactions };
+}
+
+const MAX_JSON_DEPTH = 64;
+const MAX_JSON_NODES = 20_000;
+
+/**
+ * Masks ONE event line of agent2 (a JSON string) on its DECODED strings. Masking the serialized line is wrong: inside JSON the quotes of a value are `\"`, the
+ * assignment patterns with a quoted value stop matching and the secret stays in the clear. So: JSON.parse, mask every decoded string (values and keys,
+ * recursively), re-serialize. A string value under a key is masked together with its key (`key: value`), because that is the context a secret is recognised by
+ * (`{"db_password":"..."}`). A line that is not valid JSON is masked as text. Any failure (DLP not enforce, oversize, depth, a blocked class, a context that
+ * cannot be told apart from the value) withholds the whole line: fail closed.
+ *
+ * @returns {{text:string, withheld:boolean, total:number, redactions:object}}
+ */
+export function maskEventLine(line, withheld, opts) {
+    let parsed;
+    try { parsed = JSON.parse(line); } catch { return maskOrWithhold(line, withheld, opts); }
+
+    const fail = { text: withheld, withheld: true, total: 0, redactions: {} };
+    let total = 0;
+    let nodes = 0;
+    const redactions = {};
+    let bad = false;
+    const add = (m) => { total += m.total || 0; for (const [k, n] of Object.entries(m.redactions || {})) redactions[k] = (redactions[k] || 0) + n; };
+    const piece = (s) => {
+        const m = maskChatText(s, opts);
+        if (!m.ok || m.blocked) { bad = true; return s; }
+        add(m);
+        return m.text;
+    };
+    const SEP = ": ";
+    const value = (key, s) => {
+        if (key === null) return piece(s);
+        // the key gives the context; it is removed again from the masked text. If the mask touched the key, the cut is not safe: withhold.
+        const ctx = `${key}${SEP}`;
+        const out = piece(ctx + s);
+        if (bad) return s;
+        if (!out.startsWith(ctx)) { bad = true; return s; }
+        return out.slice(ctx.length);
+    };
+    const walk = (v, key, depth) => {
+        if (bad) return v;
+        if (++nodes > MAX_JSON_NODES || depth > MAX_JSON_DEPTH) { bad = true; return v; }
+        if (typeof v === "string") return value(key, v);
+        if (v === null || typeof v !== "object") return v;
+        if (Array.isArray(v)) return v.map((x) => walk(x, key, depth + 1));
+        const entries = [];
+        for (const [k, x] of Object.entries(v)) {
+            const mk = piece(k);                         // a key can be a secret too (a map keyed by token)
+            entries.push([mk, walk(x, mk, depth + 1)]);  // the value is judged with its (masked) key as context
+        }
+        return Object.fromEntries(entries);              // own data properties, even for a key named __proto__
+    };
+    let out;
+    try { out = walk(parsed, null, 0); } catch { return fail; }
+    if (bad) return fail;
+    return { text: JSON.stringify(out), withheld: false, total, redactions };
+}

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

@@ -0,0 +1,28 @@
+/**
+ * index.js - assembles the chat of the Local Agent (LA-3): the ChatStore, the cursor registry and the `chat` dependency the content handlers take.
+ * Built by runtime.js only with LOCAL_AGENT_CHAT=true and every prerequisite (see config.js).
+ */
+import { createAudit } from "../content-handlers/audit.js";
+import { createChatStore } from "./store.js";
+import { createCursorRegistry } from "./cursors.js";
+
+export { resolveChatConfig, chatRequested, CHAT_FLAG } from "./config.js";
+export { consumeAgent2Stream } from "./stream-source.js";
+
+/**
+ * @param {object} o
+ * @param {object} o.config      resolveChatConfig() (enabled)
+ * @param {string} o.tenantId
+ * @param {(jobId:string)=>boolean} [o.isActive]   true while the job manager still holds that chat job (queued, cloning, running): a request that comes first waits for it
+ */
+export function createChat({ config, tenantId, env = process.env, log = console, now = Date.now, isActive = () => false, audit = null }) {
+    const auditor = audit || createAudit({ now });
+    const store = createChatStore({ dir: config.dir, tenantId, config, env, now, log, audit: auditor, isActive: (id) => { try { return !!isActive(id); } catch { return false; } } });
+    const cursors = createCursorRegistry({ tenantId, ttlMs: config.cursorTtlMs, maxEntries: config.maxCursors, now });
+    return {
+        config, store, cursors, audit: auditor,
+        /** What the content handler needs to serve `job.stream` and `chat.session`. */
+        content: Object.freeze({ store, cursors, chatConfig: config }),
+        close() { store.close(); cursors.clear(); },
+    };
+}