deepdebug-local-agent 1.5.0 → 1.7.0

package/src/la-protocol-v2/content-handlers/ref-registry.js

@@ -4,12 +4,16 @@
  * The control plane never sees a path: the `ref` of a `content.request` is an id that THIS agent minted when it
  * reported metadata (a file list, a diff summary) and that only this agent can map back to (workspace, relative path).
  *
- *   id        "cr1_" + 22 base64url chars = 128 random bits from crypto.randomBytes. NOT derived from the path
- *             (no hash, no HMAC of it): knowing a path tells nothing about its id and the other way round.
+ *   id        43 base64url chars, NO prefix = 256 random bits from crypto.randomBytes(32) (F3-07b: this is the shape
+ *             the gateway and the contract require; the F3-07 form `cr1_` + 22 chars is no longer minted nor accepted).
+ *             NOT derived from the path (no hash, no HMAC of it): knowing a path tells nothing about its id and the
+ *             other way round. The only symbolic ref is `worktree` (kind diff), handled by handler.js, never minted.
  *   validity  `ttlMs` from the mint (default 15 min); expired ids are gone (not_found), the CP asks for a new listing.
  *             In memory only: a restart of the agent forgets every id (also not_found), by design.
  *   binding   an id is valid for ONE tenant, ONE workspace (and the root that workspace had when it was minted),
  *             ONE kind. Any other combination resolves to null, indistinguishable from "never existed".
+ *   file.list (F3-07c) the id of a FOLDER (rel = the folder, null = the workspace root) or the continuation of a listing page
+ *             (`after` = the position where the previous page stopped, kept here: the control plane only ever sees the id).
  *   size      at most `maxEntries`; the oldest go first.
  *
  * Nothing here logs, throws a message with a path, or exposes an id's target to anything but resolve().
@@ -17,8 +21,8 @@
 import crypto from "node:crypto";
 import { normalizeRel, isSensitivePath } from "./path-guard.js";
 
-export const REF_PATTERN = /^cr1_[A-Za-z0-9_-]{22}$/;
-export const REF_KINDS = Object.freeze(["file", "diff"]);
+export const REF_PATTERN = /^[A-Za-z0-9_-]{43}$/;
+export const REF_KINDS = Object.freeze(["file", "file.list", "diff"]);
 
 export class ContentRefRegistry {
     constructor({ tenantId, ttlMs = 15 * 60_000, maxEntries = 20_000, now = Date.now, denyGlobs = [] } = {}) {
@@ -27,7 +31,7 @@ export class ContentRefRegistry {
         this.maxEntries = maxEntries;
         this.now = now;
         this.denyGlobs = denyGlobs;
-        this.entries = new Map(); // id -> { tenantId, workspaceId, root, kind, rel, expiresAt }   (insertion order = age)
+        this.entries = new Map(); // id -> { tenantId, workspaceId, root, kind, rel, size, expiresAt }   (insertion order = age)
     }
 
     get size() { return this.entries.size; }
@@ -42,29 +46,40 @@ export class ContentRefRegistry {
     }
 
     /**
-     * @param {{workspaceId:string, root:string, kind:"file"|"diff", rel?:string|null}} o
-     *        rel = path relative to the workspace root (file: required; diff: optional, null = the whole work tree)
+     * @param {{workspaceId:string, root:string, kind:"file"|"file.list"|"diff", rel?:string|null, size?:number, after?:{dir:boolean,name:string}|null}} o
+     *        rel  = path relative to the workspace root (file: required; diff: optional, null = the whole work tree;
+     *               file.list: the folder, null = the root)
+     *        after = file.list only: the last entry of the previous page (dirs first, then names by code point)
+     *        size = informative size in bytes that content.index announces (0 when unknown); never a name or a path
      * @returns {{id:string, expiresAt:number} | null}  null = refused (bad kind/path or a sensitive file): no id exists
      */
-    mint({ workspaceId, root, kind, rel = null }) {
+    mint({ workspaceId, root, kind, rel = null, size = 0, after = null }) {
         if (!REF_KINDS.includes(kind) || typeof workspaceId !== "string" || !workspaceId || typeof root !== "string" || !root) return null;
         let norm = null;
         if (rel !== null && rel !== undefined) {
             norm = normalizeRel(rel);
-            if (!norm || isSensitivePath(norm, this.denyGlobs)) return null; // never hand out an id for a file we would refuse
+            // never hand out an id for a file we would refuse (for a folder id: the folder rules)
+            if (!norm || isSensitivePath(norm, this.denyGlobs, { dir: kind === "file.list" })) return null;
         } else if (kind === "file") {
             return null;
         }
+        let cursor = null;
+        if (after !== null && after !== undefined) {
+            if (kind !== "file.list" || typeof after !== "object" || typeof after.name !== "string" || !after.name || after.name.length > 1024) return null;
+            cursor = { dir: after.dir === true, name: after.name };
+        }
         this.#purge();
-        const id = `cr1_${crypto.randomBytes(16).toString("base64url")}`;
+        let id;
+        do { id = crypto.randomBytes(32).toString("base64url"); } while (this.entries.has(id)); // 43 chars; a repeat is astronomically unlikely, never reused
         const expiresAt = this.now() + this.ttlMs;
-        this.entries.set(id, { tenantId: this.tenantId, workspaceId, root, kind, rel: norm, expiresAt });
+        const sz = Number.isSafeInteger(size) && size >= 0 && size <= 2 ** 40 ? size : 0;
+        this.entries.set(id, { tenantId: this.tenantId, workspaceId, root, kind, rel: norm, size: sz, after: cursor, expiresAt });
         this.#purge(); // capacity includes the new entry
         return { id, expiresAt };
     }
 
     /**
-     * @returns {{rel:string|null}} | null   null for: not an id, unknown, expired, other tenant/workspace/root/kind
+     * @returns {{rel:string|null, after:{dir:boolean,name:string}|null}} | null   null for: not an id, unknown, expired, other tenant/workspace/root/kind
      */
     resolve(id, { workspaceId, root, kind }) {
         if (typeof id !== "string" || !REF_PATTERN.test(id)) return null;
@@ -72,7 +87,20 @@ export class ContentRefRegistry {
         if (!e) return null;
         if (e.expiresAt <= this.now()) { this.entries.delete(id); return null; }
         if (e.tenantId !== this.tenantId || e.workspaceId !== workspaceId || e.root !== root || e.kind !== kind) return null;
-        return { rel: e.rel };
+        return { rel: e.rel, after: e.after };
+    }
+
+    /**
+     * The live ids of this tenant, oldest first, for content.index (re-announcing after a reconnect). Only what that
+     * frame may carry: workspace, kind, id, size. The path stays here.
+     * @returns {{workspaceId:string, kind:string, id:string, size:number, expiresAt:number}[]}
+     */
+    live() {
+        this.#purge();
+        const t = this.now();
+        const out = [];
+        for (const [id, e] of this.entries) if (e.expiresAt > t) out.push({ workspaceId: e.workspaceId, kind: e.kind, id, size: e.size, expiresAt: e.expiresAt });
+        return out;
     }
 
     revoke(id) { return this.entries.delete(id); }

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

@@ -2,25 +2,26 @@
   "repo": "VISIONHAMMER/vh-api-gateway",
   "path": "docs/contracts/la-protocol-v2",
   "branch": "release/qa",
-  "commit": "b090144e19b1da0182554553b18f321452f03bd6",
-  "branchTip": "7043f75e3ed1b201e2c958fd52f721b5a1177efe",
+  "commit": "b9176054337eeabe416117bafd90ce484a71968e",
   "note": "Copied by scripts/sync-la-protocol-v2-contract.mjs. Do not edit: change the gateway folder and sync again.",
   "files": {
-    "README.md": "41dd3cbceccb487ca30da5838841f04d8abffcc81c31424da833114ab646b291",
+    "README.md": "93fe7d94f212c36d5402a20cd1397e5236012c6bf1f6bb81546a65033703a88f",
     "ack.schema.json": "d6dfdaa8b1ec2dd47db9e858cd047ca860196ab6b0ad350f8ccb5d2596441ccf",
     "alert.schema.json": "01a8a77840be8ab7901ed7d07c3d68a2295bfaeb638694564e19e60be1747054",
     "approval.decision.schema.json": "a9c7bc74d146465afde1d5830839165a02f232b830b5f6cfd8c8e91fb6da1563",
     "audit.event.schema.json": "e9ceb58ea00077151373955957b8319324de488c80da4063f6d0dcb40a8b3ed0",
     "config.update.schema.json": "f5318f24230f542c76a3cb996d08f33210c0b2cc2fc55ad73c4f95648582033f",
-    "content.request.schema.json": "9966b55ec051832ac93ee43e9cd226e4f0efaeb49741947bfc48193e40e00a32",
+    "content.index.schema.json": "1abc24344435f0f392d5b626c3abb6879d8f9dd2c1d0463840a67634a5caa71e",
+    "content.request.schema.json": "440e3675246657e9aae23e51176168bc21c91283b5fcaf6782111a18110bf76e",
     "content.response.schema.json": "c9a66ac9cbbcaec7fc182b3e3fa23b34877bd342592521c7e393779230332231",
     "defs.schema.json": "f19fd27fd103d8da02de4506c086263c6236250c5c127aa3aab41833a90b743a",
-    "envelope.schema.json": "670fb26c7d532475da144185e5100b3a2ffe0d267451b1ef9debadf31b33ab79",
+    "envelope.schema.json": "92b3e5b31e6235689a1c22fae1d1eab3f93d377a19032809e47ee014c0ce67e1",
     "error.schema.json": "b1fd663d4a1ea73d88cb575422f15f8c7279001f9385ebb2d5e1889b5d5ef878",
+    "file.list.body.schema.json": "dd58ac2af91bbde53e0fd585dc55af0adb01380492d1604f21ed8e972d7ba8d1",
     "heartbeat.schema.json": "8aff84a1ef3ca56bdff8819abb3b0ab01a2547814c2ea2f9ee893cb08f7a08f1",
     "hello.schema.json": "bd500320f01ff10da49ded6f99c7e8081252019984afb3c178e27003df20b963",
     "incident.candidate.schema.json": "b292a85917b5958fc6de10a2895732e30a35420385623930c78e47341862dc62",
-    "index.json": "55543ecf492b1ffe2b9a78075890ee05518d3539fbcaeb04e8b2da8ff37c9130",
+    "index.json": "cf8f05e70b6265a169b0117d4577f78b699818eb5091df6cd4c7c7416385582a",
     "job.assign.schema.json": "fdebb4ae98bf38a2c723281c1cf9477f71d877171df9a55b0baeb0b65244f60c",
     "job.cancel.schema.json": "40ef64373283e17306d857c9a40081689786015294b0b88ab8f68f063bd2cfb8",
     "job.event.schema.json": "493d08f9db4f7ffd4a97403ee33ca4a73a65dc8f774d8f18ef0a137fdb5fc470",
@@ -36,10 +37,12 @@
     "vectors/approval.decision.vectors.json": "338115973bf2c4390d2bb33ce8f4079f3132cd739cd5505e1e873fdc252d2271",
     "vectors/audit.event.vectors.json": "d05c1820103eef041a84eb8b13d9a67a8a5b54b9b54ee3b6e43fd4ef15ed7000",
     "vectors/config.update.vectors.json": "8a5088d547e3eb4e460b25a5e413caaa02d4402a601340e279166d8c17758e1c",
-    "vectors/content.request.vectors.json": "6922748edfc630ce881a1b79d24827de03f849e05c441ef7eecc684bf2238e58",
-    "vectors/content.response.vectors.json": "35ef18edbcec24c029781e97d60dcb0b9111697fa3a5a2a8dfd159744e7f8258",
+    "vectors/content.index.vectors.json": "f167db30910989c46f317313d651ca59f9cd9d881d2ea81b84912155d18227b7",
+    "vectors/content.request.vectors.json": "fdf0f4d9e19f6480e20e40f4652bf8205da2b113620f8461dfaeb0d61add36a0",
+    "vectors/content.response.vectors.json": "cbb47cbf8a9512aa5360eea425f0cdd9064334311d37834dc75bddff07dadc5d",
     "vectors/cross-type.vectors.json": "f7ed403d3e3f53150b715a5423fde1bed708e8c6245709ed4ad74389dc8c3307",
     "vectors/error.vectors.json": "f5fd7954f2c1736ee0943eb330c2f85b7fdd7a8959e4f043f9cc9e9bcda39aa5",
+    "vectors/file.list.body.vectors.json": "da1dcc5d4ec976853161bef4b3947572f36b5526cbe16b838ac4ef72ddded403",
     "vectors/heartbeat.vectors.json": "cfd2e048139c67aa925f1fa94c05326e75248839645c1a1e4d6d3bb60cafa624",
     "vectors/hello.vectors.json": "51067dc645a2e9d8116997b36e6f3fe36401d27f3ee3c18de32ec30f8a052c5f",
     "vectors/incident.candidate.vectors.json": "0dd75ef396bf7b7911d20b3ab220469701f07866bb032ee31af58523c3633ab6",
@@ -59,6 +62,7 @@
     "vectors/traces/invalid-chunk-out-of-order.json": "c6560290755d86b524316823d32fcbd1420c170b13e198813c3b7e7b7f32ecb6",
     "vectors/traces/invalid-chunk-total-changes.json": "9b7ade197252275725bc0754e40eadc12a289c063fed13a2905c55583a27a767",
     "vectors/traces/invalid-clock-skew.json": "de16e0bd72e08bb03d44d5f2f04a238dcd38447ff1690f8acfe712ca3fe2028b",
+    "vectors/traces/invalid-content-index-before-ready.json": "360ea95992bdc7f0530c4983db0035d73eb0a4c15db952b8c3d9886f4bd00ad7",
     "vectors/traces/invalid-event-before-ready.json": "17081f197fab5f4490b15a088f2bce620921007b5fdd7ed63bd988899d674883",
     "vectors/traces/invalid-first-frame-not-register.json": "cf41c2d0e67f6df382790dab13bb9e49db99a34a88c1f9d108214be5df1e4ea3",
     "vectors/traces/invalid-frame-over-48kib.json": "912e37c9a326ad92284ba22af752269cb5dd52ed06cdc22b17fd3b74a8423734",
@@ -73,6 +77,7 @@
     "vectors/traces/invalid-tenant-mismatch.json": "dcc04ea423bddef20524ead7bfd146a5d9c42fe474c9216dc38c90544d291151",
     "vectors/traces/invalid-type-outside-allowlist.json": "e492d326cfa044d3fc9f7e48dee63a52b715a62ba4867fc5ce21f1d86e3c435f",
     "vectors/traces/valid-content-chunks-in-order.json": "c5fc301527b062b30c625da2798c7cfab3e3debac29a36f6ec7c699705267ab3",
+    "vectors/traces/valid-content-index.json": "9305dc955c4cca1f09158a9c8cf21d9e89d6a6b03646088c547f64a61cd59c30",
     "vectors/traces/valid-handshake-and-job.json": "9aa3c423c496403ca77d63965f1805f0a57ea9f6f8a01351310515b265aeb9cc",
     "vectors/traces/valid-resume-continues-seq.json": "8aa90f24598f8f2d87a5355ec58c3531d16fd11ad41c782f53eca063372b704a",
     "vectors/traces/valid-retransmit-is-idempotent.json": "924e9d296a67f0006c289e7cc978b9529ae1aa03bec2cd331a62f31354a90257",

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

@@ -7,8 +7,10 @@ exist yet. v1 is untouched. The gateway packages `*.schema.json` + `index.json`
 `la-protocol-v2/` (pom resource; both Dockerfiles copy this folder), so this folder stays the only source.
 
 ## Files
-- `envelope.schema.json`: common frame, closed (`additionalProperties:false`). `<type>.schema.json` (21):
+- `envelope.schema.json`: common frame, closed (`additionalProperties:false`). `<type>.schema.json` (22):
   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).
 - `index.json`: allowlist, direction, signed/control flags, content class per type, and the limits below.
 - `vectors/<type>.vectors.json` (+ `cross-type`): valid and invalid messages with `expect` (`valid`, error `code`,
   optional JSON Schema `keyword`, optional session `rule`). `vectors/traces/*.json`: whole sessions for the stateful rules.
@@ -79,7 +81,7 @@ schema does not know. That runtime check covers the data frames sent through the
 handshake and control frames (`ready`, `ack`, `error`) are assembled by fixed code and are NOT schema-checked at runtime: the
 test transport validates every frame the session writes, and the tests fail on a violation.
 A fatal error closes the socket with 4400 + the position of its code in the `errorCode` enum (a test pins the order; `timeout` = 4420). Resume works only on the same gateway instance (state is in memory, 90 s); elsewhere `resumed:false`. Not done in
-F3-05a: relaying a v2 stream between gateway instances, the HTTP relay (F3-06), LA handlers (F3-05b/07). Gaps, for
+F3-05a: relaying a v2 stream between gateway instances and the HTTP relay (both done in F3-06, see docs/architecture/la-content-relay.md), LA handlers (F3-05b/07). Gaps, for
 F3-05b to confirm (none changes a schema):
 1. **`byteLength` is the decoded size of `data`**; the gateway refuses a chunk where it differs (`chunk_inconsistent`).
    The F3-22 vectors had 27 for a 26-byte payload and a `max-size-chunk` that decoded to 32769 bytes (fixed in F3-05a); the
@@ -101,3 +103,86 @@ F3-05b to confirm (none changes a schema):
 7. v1 commands are refused for an LA that speaks v2 (`protocol_mismatch`): until F3-06/07 move the callers, a v2 LA
    cannot serve `sendCommand`, so the LA must stay on v1 for tenants whose flows still use v1 commands.
 
+## Opaque refs in `content.request` (F3-06b, F3-07b) - convention, no schema change
+`content.request.payload.ref` stays `string, 1..512, no control characters` (the schema and its vectors are unchanged), but
+the gateway, when `deepdebug.content-relay.enabled` is on, ONLY sends one of three shapes and refuses anything else with a 400
+before the agent is asked (no path ever reaches the Local Agent, the logs of the load balancer or the gateway):
+- **opaque id**: exactly **43 characters** of the base64url alphabet (`A-Z a-z 0-9 - _`, no padding, **no prefix**), i.e. 32
+  bytes. The Local Agent mints it (32 random bytes, or HMAC-SHA256 of the workspace path under a local secret: a stable id per
+  file is fine, a guessable one is not) and keeps the id -> path map LOCALLY; the gateway cannot reverse it. An id is scoped to
+  the `workspaceId` of the envelope: the agent must resolve it inside that workspace only. A shorter or prefixed id (for
+  example a 26-character `cr1_...`) is NOT an opaque id: the gateway answers 400 and never asks.
+- **UUID** (canonical lower-case 8-4-4-4-12), only for the kinds whose subject is minted by VisionHammer:
+  `incident.detail incident.stack chat.session job.stream job.timeline approval.detail`.
+- **`worktree`**, the one symbolic ref, ONLY for `kind: "diff"`: the diff of the whole work tree of the workspace of the
+  envelope (`git diff HEAD`, never a file name). Exact, lower-case; it names nothing of the customer's, so it may appear in a
+  URL. The gateway requires a `workspaceId` with it (400 otherwise: "the work tree" of which workspace?) and refuses it for
+  every other kind. The agent resolves it inside that workspace only, as for an id.
+The Local Agent is the authority: it MUST NOT trust the shape. It validates the workspace (the one in the signed envelope, one
+it serves, else `forbidden`/`not_found`), resolves the id to a path inside that workspace's root (no `..`, no symlink out of
+the root, no sensitive file) and answers `not_found` for an id it does not know. With several agents per tenant the gateway
+asks the one that declared the workspace in `register.workspaces[]` first and tries the next only after `not_found`,
+`forbidden` or `agent_offline` (see docs/architecture/la-content-relay.md). A later contract revision may tighten the schema
+`pattern` once no client sends a path; until then this README is the convention.
+
+## `content.index` (LA -> CP, F3-07b): which ids exist
+An unsolicited, **unsigned** LA -> CP frame (`seq` 1.., never chunked, `agentId` required, like `log.stats`) that announces
+the opaque ids the agent minted for ONE workspace (the `workspaceId` of the envelope, required and non-empty here):
+`payload.entries[]`, 1..256 items `{kind, ref, size, updatedAt?}`, closed. `kind` is the `content.request` kind list; `ref` is
+exactly the 43-character id above; `size` is an integer 0..2^40 bytes of the item (informative: the relay still caps a
+response at 2 MiB); `updatedAt` an optional UTC timestamp. **It cannot carry a name or a path**: no free-form field exists,
+every string is an enum or the 43-character pattern, `additionalProperties:false` everywhere, and `uniqueItems` refuses the
+same entry twice. 256 entries with `updatedAt` are about 36 KiB, one frame; the agent sends more messages for more ids.
+It is metadata about client content, not client content (`contentClass: none`).
+- **What the gateway does** (`deepdebug.content-relay.enabled` on): validates the frame like any other (schema first, then
+  tenant/agent/direction/state/seq), keeps the entries IN MEMORY of that gateway instance for `index-ttl-seconds` (default 15 min,
+  renewed by announcing again), with limits per session, per tenant and per instance, never persists them and never logs an id
+  or a size. The key is a digest of tenant, workspace, kind and id, so a heap dump lists no id.
+- **The answer is the `ack`** (non-fatal, the session goes on): `accepted` = stored; `rejected` + `rate_limited` = a limit was
+  reached, NOTHING of that message was stored (all or nothing), announce less and later; `rejected` + `protocol_unsupported` =
+  this gateway keeps no index (content relay off), stop sending; `rejected` + `internal` = retry later.
+- **What it is for**: the control plane can know which ids exist for a workspace. It is NOT an access list: the agent stays the
+  authority and answers `not_found` / `forbidden` for what it does not serve, known id or not. Optional refusal of unknown ids
+  before asking the agent: `deepdebug.content-relay.require-known-ref`, default **false**, and it must stay false with more than
+  one gateway instance (the index is the memory of the instance that holds the agent's session, a request that lands on another
+  instance would be refused wrongly).
+- **What the agent must do**: announce ids when it mints them (or in a burst after `ready`), stay within 256 entries per frame
+  and 2048 live ids per session, send `content.index` only when its content handlers are on and DLP is `enforce`, and treat the
+  ids as expiring (it answers `not_found` for an id it forgot). It must never put a path or a file name in a frame.
+
+
+## `file.list` (CP -> LA content kind, F3-07c): how the front finds out what exists on the customer's side
+**Decision (Edu, 2026-11-03; no new frame type, no new limit in `index.json`).** The control plane knows no file, no folder and no name,
+and must not learn them: `content.index` carries ids only. So the answer to "what is there?" is a content kind like the others, served on
+demand and relayed without being kept: `file.list` lists ONE folder of ONE workspace, and its body (names, sizes, times) travels only
+inside `content.response.data` (client content in transit: DLP at the agent, never parsed, stored or logged by the CP, bounded). The
+front then asks for an item by the id it was given (`file` for a file, `file.list` for a folder). Nothing else was needed: the
+existing kinds, `ref` convention, ids, envelope and chunking are reused; the changes are the kind in two enums and the body schema.
+- **Request** `content.request{kind:"file.list", ref, limit?, actor}` (the envelope carries the `workspaceId`, always required for this
+  kind). `ref` is `root` (symbolic, exact, lower-case: the root folder of that workspace) or a 43-character opaque id: a folder id taken
+  from a previous listing, or the `nextRef` of one. `range` is not used (the gateway refuses it); `limit` is the page size, 1..1000
+  (default chosen by the agent, 200 suggested). The gateway never accepts a path or a UUID here.
+- **Response** `content.response`, `contentType:"application/json"` (anything else is refused by the gateway as `agent_error`), body =
+  `file.list.body.schema.json`: `{entries:[{id, name, type:"file"|"dir", size, mtime}], nextRef?}`. `name` is the BASE name, 1..255
+  characters, no `/`, no control character, never `.` or `..`; a path cannot be expressed. `id` (43 chars) is minted by the agent
+  for the item, scoped to the workspace like every id; `size` is bytes (0 for a dir); `mtime` UTC. `nextRef`, when present, means
+  more entries: ask `file.list` again with it as `ref` (it is a continuation id the agent minted, 43 chars, not a position the client
+  can build). Order is the agent's and stable within one listing: dirs first, then names in code point order. An empty folder is
+  `entries: []`.
+- **Limits.** At most **1000 entries** per page. The whole body is at most **1048576 bytes (1 MiB)**, half of the generic 2 MiB: the
+  gateway answers `too_large` above it, so the agent must cut a page by size as well as by count (1000 entries of 255-character
+  names do not fit) and give a `nextRef`. A page never holds the whole tree: there is no recursive listing.
+- **What the agent lists.** Only what it could serve with kind `file` / `file.list`: it applies the same deny list, the same
+  symlink/hard-link and root checks to the listing, so an entry the agent would refuse (a credential, a link out of the root, an
+  unreadable file) is simply absent, and the ids it hands out resolve inside the workspace only. Names are client content: the DLP
+  runs on the body like on any other, the front must treat them as text (escape, never HTML).
+- **Ids and the index.** Ids minted for a listing may be announced with `content.index` (kind `file.list` for a folder id or a
+  continuation, `file` for a file), within its limits (256 per frame, 2048 per session). That matters only with
+  `deepdebug.content-relay.require-known-ref`, default off and single-instance: with it on, an id that was not announced is `not_found`
+  at the gateway; the agent stays the authority either way.
+- **Capability.** An agent that serves this announces `content.file.list` in `register.capabilities` (and `hello`). The gateway sends
+  kind `file.list` ONLY to a session that announced it (a Local Agent built before F3-07c does not have the kind in its copy of this
+  contract and would answer the whole request with a schema violation); others are skipped, and if no agent of the tenant has it the
+  answer is HTTP 501 `not_supported`. That announcement is also how the front/CP discovers that listing exists on a given agent.
+- **Compatibility.** Additive: the kind is added to the `content.request` and `content.index` enums, nothing else changes there. The
+  `content.request` payload gained no field. With `deepdebug.content-relay.enabled` off nothing is mapped, as before.

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

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.visionhammer.io/la-protocol-v2/content.index.schema.json",
+  "title": "LA protocol v2: content.index (la->cp)",
+  "description": "Inventory of the opaque content ids the Local Agent minted for ONE workspace (the workspaceId of the envelope): kind, id and size, never a name or a path. The control plane keeps it in memory with a TTL, never persists or logs it.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "envelope.schema.json"
+    }
+  ],
+  "properties": {
+    "type": {
+      "const": "content.index"
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "entries": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 256,
+          "uniqueItems": true,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "kind": {
+                "type": "string",
+                "enum": [
+                  "incident.detail",
+                  "incident.stack",
+                  "file",
+                  "file.list",
+                  "diff",
+                  "log.window",
+                  "log.groups",
+                  "chat.session",
+                  "wiki.page",
+                  "job.stream",
+                  "job.timeline",
+                  "approval.detail",
+                  "report"
+                ]
+              },
+              "ref": {
+                "type": "string",
+                "minLength": 43,
+                "maxLength": 43,
+                "pattern": "^[A-Za-z0-9_-]{43}$"
+              },
+              "size": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 1099511627776
+              },
+              "updatedAt": {
+                "$ref": "defs.schema.json#/$defs/ts"
+              }
+            },
+            "required": [
+              "kind",
+              "ref",
+              "size"
+            ]
+          }
+        }
+      },
+      "required": [
+        "entries"
+      ]
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "workspaceId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64
+    },
+    "chunk": false,
+    "sig": false,
+    "paramsRaw": false,
+    "agentId": true
+  },
+  "required": [
+    "payload",
+    "agentId"
+  ]
+}

package/src/la-protocol-v2/contract/content.request.schema.json

@@ -22,6 +22,7 @@
             "incident.detail",
             "incident.stack",
             "file",
+            "file.list",
             "diff",
             "log.window",
             "log.groups",

package/src/la-protocol-v2/contract/envelope.schema.json

@@ -34,6 +34,7 @@
         "job.result",
         "content.request",
         "content.response",
+        "content.index",
         "approval.decision",
         "config.update",
         "scan.upload",

package/src/la-protocol-v2/contract/file.list.body.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.visionhammer.io/la-protocol-v2/file.list.body.schema.json",
+  "title": "LA protocol v2: decoded body of a content.response for kind file.list (not a frame type)",
+  "description": "One page of the listing of ONE folder of a workspace: what the Local Agent puts, as JSON, in the base64 `data` of a content.response (contentType application/json). Client content in transit: the control plane relays it, never parses, stores or logs it. Entries carry the opaque id to ask for the item later (kind `file` for a file, kind `file.list` for a dir), the base name (never a path), size and mtime. Total size of the body: at most 1048576 bytes, which JSON Schema cannot state (README).",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "entries": {
+      "type": "array",
+      "maxItems": 1000,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 43,
+            "maxLength": 43,
+            "pattern": "^[A-Za-z0-9_-]{43}$"
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 255,
+            "pattern": "^[^\\u0000-\\u001f\\u007f/]{1,255}$",
+            "not": {
+              "enum": [
+                ".",
+                ".."
+              ]
+            }
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "file",
+              "dir"
+            ]
+          },
+          "size": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 1099511627776
+          },
+          "mtime": {
+            "$ref": "defs.schema.json#/$defs/ts"
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "type",
+          "size",
+          "mtime"
+        ]
+      }
+    },
+    "nextRef": {
+      "type": "string",
+      "minLength": 43,
+      "maxLength": 43,
+      "pattern": "^[A-Za-z0-9_-]{43}$"
+    }
+  },
+  "required": [
+    "entries"
+  ]
+}

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

@@ -99,6 +99,13 @@
       "signed": false,
       "contentClass": "relay"
     },
+    "content.index": {
+      "schema": "content.index.schema.json",
+      "direction": "la->cp",
+      "control": false,
+      "signed": false,
+      "contentClass": "none"
+    },
     "approval.decision": {
       "schema": "approval.decision.schema.json",
       "direction": "cp->la",

package/src/la-protocol-v2/contract.js

@@ -64,6 +64,15 @@ export function loadContract() {
         outboundTypes: Object.entries(index.types).filter(([, i]) => accepts(i, "la->cp")).map(([t]) => t),
         canReceive: (type) => { const i = typeInfo(type); return !!i && accepts(i, "cp->la"); },
         canSend: (type) => { const i = typeInfo(type); return !!i && accepts(i, "la->cp"); },
+        /**
+         * F3-07c: validates a DECODED body that is not a frame (the file.list listing carried in content.response.data) against its
+         * schema file (`*.body.schema.json`). @returns {boolean}
+         */
+        validateBody(schemaFile, value) {
+            const v = ajv.getSchema(index.baseId + schemaFile);
+            if (!v) throw new Error(`contract: no schema ${schemaFile}`);
+            return v(value) === true;
+        },
         validateFrame(frame) {
             if (frame === null || typeof frame !== "object" || typeof frame.type !== "string") {
                 // no `type` at all (a v1 command frame, say): the envelope says what is missing

package/src/la-protocol-v2/runtime.js

@@ -44,8 +44,18 @@ export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWo
     const refreshDisk = () => diskFreeBytes(getWorkspaceRoot() || process.cwd()).then((v) => { lastDisk = v; });
     refreshDisk();
     // F3-07: content.request handlers, behind LOCAL_AGENT_CONTENT_HANDLERS (default off: nothing below changes anything)
-    const contentCfg = resolveContentHandlersConfig(env, (m) => log.warn(m));
-    const contentCaps = contentCfg.enabled ? ["content.diff", "content.file"] : [];
+    let contentCfg = resolveContentHandlersConfig(env, (m) => log.warn(m));
+    if (contentCfg.enabled) {
+        // F3-07b: client content leaves this machine only masked. Without LOCAL_AGENT_DLP_MODE=enforce the handlers are NOT
+        // registered and no content.* capability is announced: content.request is acked `rejected protocol_unsupported`, as
+        // with the flag off. There is no opt-out.
+        const { dlpConfigFromEnv } = await import("../dlp/index.js");
+        if (dlpConfigFromEnv(env).mode !== "enforce") {
+            (log.error || log.warn).call(log, "[la-content] ERROR: LOCAL_AGENT_CONTENT_HANDLERS=true but LOCAL_AGENT_DLP_MODE is not enforce: the content handlers are NOT registered and no content capability is announced (content.request answers protocol_unsupported). Set LOCAL_AGENT_DLP_MODE=enforce to serve content.");
+            contentCfg = { enabled: false };
+        }
+    }
+    const contentCaps = contentCfg.enabled ? ["content.diff", "content.file", "content.file.list"] : []; // content.file.list: F3-07c, how the front finds out what exists (the gateway only sends file.list to agents that announce it)
     const link = createV2Link({
         log,
         sessionOptions: {