deepdebug-local-agent 1.6.0 → 1.7.0

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

@@ -6,7 +6,7 @@
  *   1. accept: the handler answers the session at once ({accept:true} = ack `accepted`); the work goes on in the
  *      background (the first chunk may take seconds, the ack timeout is 5 s). A request without requestId is refused.
  *   2. admission: at most `maxConcurrent` requests and `maxInFlightBytes` in memory; above it -> `rate_limited`.
- *   3. kind: `file` and `diff` are served; every other kind of the allowlist -> status `error` + `protocol_unsupported`
+ *   3. kind: `file`, `diff` and `file.list` (F3-07c: a folder listing that mints the ids of what it shows) are served; every other kind of the allowlist -> status `error` + `protocol_unsupported`
  *      (the contract has no "not supported" status; this is the code already used for "no handler").
  *   4. workspace: the envelope's workspace must be registered here (and belong to this tenant) -> else `not_found`.
  *   5. ref: an opaque id (ref-registry.js) valid for this tenant+workspace+root+kind -> else `not_found`, whatever the
@@ -22,16 +22,19 @@ import { ProtocolError } from "../errors.js";
 import { sendContent, sendContentFailure } from "../content.js";
 import { REF_KINDS } from "./ref-registry.js";
 import { normalizeRel, resolveInside, readRegular } from "./path-guard.js";
+import { listFolder, ROOT_REF, clampLimit, MAX_LIST_BYTES } from "./file-list.js";
 import { worktreeDiff } from "./git-diff.js";
-import { prepareOutgoing, contentTypeOf, decodeText } from "./egress.js";
+import { prepareOutgoing, prepareList, maskName, contentTypeOf, decodeText } from "./egress.js";
 import { createAudit, short } from "./audit.js";
 import { dlpConfigFromEnv } from "../../dlp/index.js";
 
-export const SERVED_KINDS = Object.freeze(["file", "diff"]);
+export const SERVED_KINDS = Object.freeze(["file", "diff", "file.list"]);
 /** Symbolic ref of kind `diff`: the whole work tree of the envelope's workspace (carries no client data). */
 export const WORKTREE_REF = "worktree";
 
-export function createContentHandler({ session, tenantId, resolveWorkspace, registry, config, env = process.env, log = console, audit = null, now = Date.now }) {
+export function createContentHandler({ session, tenantId, resolveWorkspace, registry, config, env = process.env, log = console, audit = null, now = Date.now, mint = null }) {
+    // F3-07c: where the ids of a listing come from. install.js passes mintRef (registry + content.index); without it (tests) the registry alone.
+    const mintFor = (workspaceId, root) => (o) => (mint ? mint({ workspaceId, ...o }) : registry.mint({ workspaceId, root, ...o }));
     const inflight = new Map(); // requestId -> { ac, timer }
     let reservedBytes = 0;
     const auditor = audit || createAudit({ file: config.auditFile, now });
@@ -49,6 +52,7 @@ export function createContentHandler({ session, tenantId, resolveWorkspace, regi
         if (dlpConfigFromEnv(env).mode !== "enforce") return { status: "error", errorCode: "protocol_unsupported" };
         const ws = await resolveWorkspace(ctx.workspaceId);
         if (!ws || !ws.root) return { status: "not_found" };
+        if (p.kind === "file.list") return produceList(ctx, p, ws, signal);
         const target = registry.resolve(p.ref, { workspaceId: ctx.workspaceId, root: ws.root, kind: p.kind });
         if (p.kind === "diff" && !target && p.ref === WORKTREE_REF) return produceDiff(p, ws, null, signal);
         if (!target) return { status: "not_found" };
@@ -68,6 +72,26 @@ export function createContentHandler({ session, tenantId, resolveWorkspace, regi
         return finish(p, read.buffer, contentTypeOf(norm, isText), "content.file");
     }
 
+    /** F3-07c: `root` or a folder id (or the nextRef of a previous page) -> one page of names with the ids to ask for them. */
+    async function produceList(ctx, p, ws, signal) {
+        if (p.range) return { status: "error", errorCode: "protocol_unsupported" }; // a listing has no byte range
+        let rel = null;
+        let after = null;
+        if (p.ref !== ROOT_REF) {
+            const target = registry.resolve(p.ref, { workspaceId: ctx.workspaceId, root: ws.root, kind: "file.list" });
+            if (!target) return { status: "not_found" };
+            rel = target.rel && normalizeRel(target.rel);
+            if (target.rel && !rel) return { status: "not_found" };
+            after = target.after;
+        }
+        const r = await listFolder({ root: ws.root, rel, after, limit: clampLimit(p.limit), maxBytes: config.maxBytes, maxDirEntries: config.maxDirEntries,
+            denyGlobs: config.extraDenyGlobs, allowHardlinks: config.allowHardlinks, signal, mint: mintFor(ctx.workspaceId, ws.root),
+            maskName: (n) => maskName(n, { env }) });
+        if (!r.ok) return r;
+        const out = prepareList({ buffer: r.body, maxBytes: Math.min(config.maxBytes, MAX_LIST_BYTES), dlp: { mode: "enforce", total: r.dlp.total, redactions: r.dlp.redactions } });
+        return out.ok ? { status: "ok", buffer: out.buffer, contentType: out.contentType, dlp: out.dlp } : { status: out.status, errorCode: out.errorCode, dlp: out.dlp };
+    }
+
     async function produceDiff(p, ws, rel, signal) {
         const d = await worktreeDiff({ root: ws.root, rel, maxBytes: config.maxBytes, maxFiles: config.maxDiffFiles,
             timeoutMs: config.gitTimeoutMs, denyGlobs: config.extraDenyGlobs, allowHardlinks: config.allowHardlinks, signal });

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

@@ -2,11 +2,11 @@
  * install.js - puts the content handlers on a v2 link (F3-07, F3-07b). Called by runtime.js only when
  * LOCAL_AGENT_CONTENT_HANDLERS=true, v2 is on AND LOCAL_AGENT_DLP_MODE=enforce. Returns what the rest of the agent needs:
  *
- *   mintRef({workspaceId, kind, rel, size?})  the HOOK for whoever reports metadata to the control plane (file lists, diff
- *                                      summaries): returns {id, expiresAt} for that item (id = 43 base64url chars), or null
+ *   mintRef({workspaceId, kind, rel, size?, after?})  returns {id, expiresAt} for that item (id = 43 base64url chars), or null
  *                                      (sensitive path, unknown workspace). The id is also announced to the control plane in a
- *                                      `content.index` frame ({kind, ref, size}: no name, no path). Nothing in the agent calls
- *                                      it yet (the inventory producer is a later increment); `announce()` re-sends what is live.
+ *                                      `content.index` frame ({kind, ref, size}: no name, no path). F3-07c: the real caller is the
+ *                                      `file.list` handler (handler.js / file-list.js), which mints one id per entry it lists;
+ *                                      `announce()` re-sends what is live.
  */
 import { dlpConfigFromEnv } from "../../dlp/index.js";
 import { ContentRefRegistry } from "./ref-registry.js";
@@ -34,9 +34,26 @@ export function installContentHandlers({ link, tenantId, wsManager, getWorkspace
         return null;
     };
 
-    const handler = createContentHandler({ session: link.session, tenantId: tenant, resolveWorkspace, registry, config, env, log });
+    // `indexer` is created below (it needs the session only); mintRef and the handler use it through this binding
+    let indexer = null;
+    const mintRef = ({ workspaceId, kind, rel, size, after }) => {
+        try {
+            const ws = resolveWorkspace(workspaceId);
+            if (!ws) return null;
+            const bytes = Number.isSafeInteger(size) ? size
+                : kind === "file" && typeof rel === "string" ? sizeInsideSync(ws.root, rel.replace(/\\/g, "/"), { allowHardlinks: config.allowHardlinks }) : 0;
+            const minted = registry.mint({ workspaceId, root: ws.root, kind, rel, size: bytes, after });
+            if (minted && indexer) indexer.add({ workspaceId, kind, ref: minted.id, size: bytes, expiresAt: minted.expiresAt });
+            return minted;
+        } catch {
+            return null; // a failing workspace manager means "no id", never an exception with a path in it
+        }
+    };
+
+    // F3-07c: the listing handler mints through mintRef, so every id it hands out is also announced with content.index
+    const handler = createContentHandler({ session: link.session, tenantId: tenant, resolveWorkspace, registry, config, env, log, mint: mintRef });
     link.session.setHandler("content.request", (ctx) => handler.handle(ctx));
-    const indexer = createContentIndexer({ session: link.session, registry, config, log });
+    indexer = createContentIndexer({ session: link.session, registry, config, log });
 
     const closeLink = link.close.bind(link);
     link.close = () => { handler.cancelAll(); indexer.close(); registry.clear(); closeLink(); };
@@ -45,19 +62,7 @@ export function installContentHandlers({ link, tenantId, wsManager, getWorkspace
         registry,
         handler,
         indexer,
-        mintRef: ({ workspaceId, kind, rel, size }) => {
-            try {
-                const ws = resolveWorkspace(workspaceId);
-                if (!ws) return null;
-                const bytes = Number.isSafeInteger(size) ? size
-                    : kind === "file" && typeof rel === "string" ? sizeInsideSync(ws.root, rel.replace(/\\/g, "/"), { allowHardlinks: config.allowHardlinks }) : 0;
-                const minted = registry.mint({ workspaceId, root: ws.root, kind, rel, size: bytes });
-                if (minted) indexer.add({ workspaceId, kind, ref: minted.id, size: bytes, expiresAt: minted.expiresAt });
-                return minted;
-            } catch {
-                return null; // a failing workspace manager means "no id", never an exception with a path in it
-            }
-        },
+        mintRef,
         /** Announces again the live ids (of one workspace or all) that the gateway does not know yet. */
         announce: (opts) => indexer.announce(opts),
     };

package/src/la-protocol-v2/content-handlers/path-guard.js

@@ -3,7 +3,10 @@
  * The gateway lets anything through (it only sees an opaque id); every check that matters is here.
  *
  *   normalizeRel     a relative path as the agent itself minted it: no NUL/control chars, not absolute, no `..`.
- *   isSensitivePath  deny list (built-in + LOCAL_AGENT_CONTENT_DENY_GLOBS): .env*, private keys, .git/, .ssh/, ...
+ *   isSensitivePath  deny list (built-in globs + name rules + LOCAL_AGENT_CONTENT_DENY_GLOBS): .env*, private keys, .git/, .ssh/, ...
+ *                    F3-07c: names that merely MENTION a credential (credentials.service.ts, CredentialsController.java) are
+ *                    code and are served; files that ARE credentials (credentials, credentials.json, .credentials,
+ *                    application_default_credentials.json, ...) are not. See sensitiveByName(). The DLP stays the 2nd layer.
  *   resolveInside    realpath of root and target; the real target must stay inside the real root (a symlink that
  *                    leaves the workspace is `forbidden`), must not be sensitive under its REAL name either
  *                    (a harmless-looking link to .env), and must be a regular file.
@@ -25,14 +28,17 @@ const O_NOFOLLOW = fs.constants.O_NOFOLLOW ?? 0;
 /** Built-in deny list. A pattern with no `/` matches any path segment; with `/` it matches a path (or its prefix). */
 export const DEFAULT_DENY_GLOBS = Object.freeze([
     // secrets by name
-    ".env", ".env.*", "*.env",
+    ".env", ".env.*", "*.env", ".envs/",
     "*.pem", "*.key", "*.p12", "*.pfx", "*.jks", "*.keystore", "*.p8", "*.ppk", "*.kdbx", "*.gpg", "*.crt.key",
     "id_rsa*", "id_dsa*", "id_ecdsa*", "id_ed25519*",
     ".npmrc", ".pypirc", ".netrc", "_netrc", ".pgpass", ".my.cnf", ".git-credentials", ".htpasswd", ".vault-token",
-    "credentials*", "service-account*.json", "serviceaccount*.json", "secrets.json", "secrets.yml", "secrets.yaml",
+    "service-account*.json", "serviceaccount*.json", "secrets.json", "secrets.yml", "secrets.yaml",
+    // F3-07c: directories named for secrets (everything under them), by Edu's decision of 2026-11-03
+    "secrets/", ".secrets/", ".credentials/",
     "*.secret", "*.secrets", "*.tfstate", "*.tfstate.*", "*.tfvars", "*.tfvars.json", "terraform.rc",
     // F3-07b: editor backups / autosaves of the env file, kubeconfig files
-    ".env~", ".env#", ".#.env", "kubeconfig", "kubeconfig.*", "*.kubeconfig",
+    ".env~", ".env#", ".#.env", "*.kubeconfig",
+    // (F3-07c: .envrc, .env_backup, .env-prod, env.production, kubeconfig-prod, credentials* ... are name RULES, sensitiveByName() below)
     // F3-07b: Windows 8.3 aliases ("short names") of the files above: ".env" is also reachable as ENV~1, ".npmrc" as NPMRC~1,
     // "credentials.json" as CREDEN~1.JSO, "id_ed25519" as ID_ED2~1 ... The real name is checked as well (resolveInside), this
     // covers the alias form on its own. `~?*` = "~" + at least one more character.
@@ -41,6 +47,16 @@ export const DEFAULT_DENY_GLOBS = Object.freeze([
     // (an alias keeps the first 3 characters of the extension: `*.pem`, `*.key`, `*.p12`... already catch their aliases; these are the ones whose
     // extension is longer than 3: .tfstate -> .TFS, .tfvars -> .TFV, .kdbx -> .KDB, .secret(s) -> .SEC)
     "*~?*.tfs", "*~?*.tfv", "*~?*.kdb", "*~?*.sec",
+    // F3-07c review: credential files that no rule above names (the DLP is only the second layer: it masks known token shapes, not plain values)
+    ".dockercfg", ".yarnrc", ".yarnrc.yml", ".pnpmrc", ".s3cfg", ".boto", ".terraformrc", ".renviron", "auth.json",
+    "client_secret*.json", "firebase-adminsdk*.json", "gha-creds-*.json", "local.settings.json", "wp-config.php",
+    "application-prod.properties", "application-prod.yml", "application-prod.yaml",
+    "*_rsa", "*_dsa", "*_ecdsa", "*_ed25519", "ssh_host_*_key",
+    ".m2/settings.xml", ".m2/settings-security.xml",
+    // family names that are also directories: everything under them is blocked (a bare `.env_backup/a.txt` was readable)
+    ".envrc/", ".env_backup/", ".env-prod/", "env.production/", "kubeconfig-prod/",
+    // 8.3 aliases of .envrc / .envs
+    "envrc~?*", "envs~?*",
     // directories that hold credentials or the repository internals (.git/config may carry a token in a URL)
     ".git/", ".ssh/", ".aws/", ".gnupg/", ".kube/", ".docker/", ".azure/", ".terraform/", ".config/gcloud/",
 ]);
@@ -82,12 +98,65 @@ function withoutStreams(folded) {
     return folded.split("/").map((seg) => { const i = seg.indexOf(":"); return i > 0 ? seg.slice(0, i) : seg; }).join("/");
 }
 
-export function isSensitivePath(rel, extraGlobs = []) {
+/**
+ * Extensions of SOURCE / documentation files (F3-07c). A name that mentions a credential, a kubeconfig or an env file is
+ * served only when its last extension is one of these: credentials.service.ts, CredentialsController.java, credentials_test.py
+ * are code about credentials; credentials, credentials.json, .credentials, credentials.bak are credentials. Everything that is not
+ * known code fails closed (an unknown extension is NOT a reason to serve). Not in the list on purpose: data and config formats
+ * (json, yml, yaml, xml, toml, ini, cfg, conf, csv, txt, properties, db, sqlite, enc, env ...), shell/batch scripts and gradle
+ * (they export or hold values), key stores, backups (bak, old, orig, tmp, swp) and anything with no extension.
+ */
+export const CODE_EXTENSIONS = Object.freeze(new Set([
+    "ts", "tsx", "mts", "cts", "js", "jsx", "mjs", "cjs", "java", "kt", "kts", "py", "go", "rb", "cs", "rs", "php", "scala", "swift",
+    "vue", "svelte", "astro", "c", "cc", "cpp", "cxx", "h", "hh", "hpp", "m", "mm", "sql", "md", "markdown", "rst", "adoc", "html", "htm",
+    "css", "scss", "sass", "less", "dart", "ex", "exs", "erl", "hrl", "clj", "cljs", "lua", "pl", "pm", "r", "jl", "hs", "ml", "fs", "fsx",
+    "vb", "groovy", "proto", "graphql", "gql", "tf", "cshtml", "razor", "jsp", "ejs", "hbs", "pug", "zig", "nim", "sol",
+]));
+
+/** Last extension of a (folded) file name; "" for no extension and for a name that only starts with a dot. */
+function extOf(name) {
+    const i = name.lastIndexOf(".");
+    return i > 0 ? name.slice(i + 1) : "";
+}
+const isCodeName = (name) => CODE_EXTENSIONS.has(extOf(name));
+
+/**
+ * Name rules (on top of the globs): the families whose names have to be told apart from source code. `segs` are the folded path
+ * segments; the last one is a directory when `dir` is true (a listing entry), a file otherwise.
+ *   - .env family: `.env`, `.envrc`, then end or a separator (. _ - # ~): .env_backup, .env-prod, .env.local~, .envrc.local. Not .environment.
+ *   - env.<x> / env_<x> / env-<x> and a bare `env` file: env.production, env_prod: unless code (env.ts, env.d.ts, env.config.mjs).
+ *   - names with "credential" or "kubeconfig": unless code (credentials.service.ts) ... a DIRECTORY with such a name is fine
+ *     (src/credentials/), but a file under one has to be code (credentials/prod.json is not), and `.credentials` is never fine.
+ */
+function sensitiveByName(segs, dir) {
+    const last = segs.length - 1;
+    for (let i = 0; i < segs.length; i++) {
+        const seg = segs[i];
+        const asDir = i < last || dir;
+        if (asDir) {
+            if (seg === ".credentials") return true;
+            continue;
+        }
+        if (/^\.env(?:rc)?(?![a-z])/.test(seg)) return true;
+        if (seg === "env" || (/^env[._-]/.test(seg) && !isCodeName(seg))) return true;
+        if ((seg.includes("credential") || seg.includes("kubeconfig")) && !isCodeName(seg)) return true;
+        if (i > 0 && segs.slice(0, i).some((d) => d.includes("credential")) && !isCodeName(seg)) return true;
+    }
+    return false;
+}
+
+/**
+ * @param {string} rel
+ * @param {string[]} [extraGlobs]
+ * @param {{dir?: boolean}} [o]  dir: the last segment is a directory (a listing entry, a folder id): file-only name rules do not apply to it
+ */
+export function isSensitivePath(rel, extraGlobs = [], { dir = false } = {}) {
     if (typeof rel !== "string") return true;
     const folded = foldForMatch(rel.replace(/\\/g, "/"));
     const stripped = withoutStreams(folded);
     const forms = stripped === folded ? [folded] : [folded, stripped];
     for (const g of DEFAULT_DENY_GLOBS) { const re = regexFor(g); if (forms.some((f) => re.test(f))) return true; }
+    for (const f of forms) if (sensitiveByName(f.split("/"), dir)) return true;
     for (const g of extraGlobs) if (typeof g === "string" && g) { const re = regexFor(g); if (forms.some((f) => re.test(f))) return true; }
     return false;
 }

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

@@ -12,6 +12,8 @@
  *             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().
@@ -20,7 +22,7 @@ import crypto from "node:crypto";
 import { normalizeRel, isSensitivePath } from "./path-guard.js";
 
 export const REF_PATTERN = /^[A-Za-z0-9_-]{43}$/;
-export const REF_KINDS = Object.freeze(["file", "diff"]);
+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 = [] } = {}) {
@@ -44,32 +46,40 @@ export class ContentRefRegistry {
     }
 
     /**
-     * @param {{workspaceId:string, root:string, kind:"file"|"diff", rel?:string|null, size?:number}} 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, size = 0 }) {
+    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();
         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;
         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, expiresAt });
+        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;
@@ -77,7 +87,7 @@ 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 };
     }
 
     /**

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

@@ -1,22 +1,23 @@
 {
   "repo": "VISIONHAMMER/vh-api-gateway",
   "path": "docs/contracts/la-protocol-v2",
-  "branch": "feat/edu/f3-07b-gateway-contract",
-  "commit": "55921963e461464b34daf8be604bae162a1c3289",
+  "branch": "release/qa",
+  "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": "77e95e25b4fa0eb5eb82c1bb3d9676fed4d946d8ce0e02838d8c3f7f57f972a9",
+    "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.index.schema.json": "ba770a0b429331cc801b7b402b74c4e73d229d3b72f3052781720b34c14fb777",
-    "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": "92b3e5b31e6235689a1c22fae1d1eab3f93d377a19032809e47ee014c0ce67e1",
     "error.schema.json": "b1fd663d4a1ea73d88cb575422f15f8c7279001f9385ebb2d5e1889b5d5ef878",
+    "file.list.body.schema.json": "dd58ac2af91bbde53e0fd585dc55af0adb01380492d1604f21ed8e972d7ba8d1",
     "heartbeat.schema.json": "8aff84a1ef3ca56bdff8819abb3b0ab01a2547814c2ea2f9ee893cb08f7a08f1",
     "hello.schema.json": "bd500320f01ff10da49ded6f99c7e8081252019984afb3c178e27003df20b963",
     "incident.candidate.schema.json": "b292a85917b5958fc6de10a2895732e30a35420385623930c78e47341862dc62",
@@ -36,11 +37,12 @@
     "vectors/approval.decision.vectors.json": "338115973bf2c4390d2bb33ce8f4079f3132cd739cd5505e1e873fdc252d2271",
     "vectors/audit.event.vectors.json": "d05c1820103eef041a84eb8b13d9a67a8a5b54b9b54ee3b6e43fd4ef15ed7000",
     "vectors/config.update.vectors.json": "8a5088d547e3eb4e460b25a5e413caaa02d4402a601340e279166d8c17758e1c",
-    "vectors/content.index.vectors.json": "0a59f6b633388d0d1dcb1ebfc6fa6b5e9ad5e399b5a9d8c60b625a9f318f99f9",
-    "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",

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

@@ -9,6 +9,8 @@ exist yet. v1 is untouched. The gateway packages `*.schema.json` + `index.json`
 ## Files
 - `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.
@@ -148,3 +150,39 @@ It is metadata about client content, not client content (`contentClass: none`).
   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

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

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/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.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

@@ -55,7 +55,7 @@ export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWo
             contentCfg = { enabled: false };
         }
     }
-    const contentCaps = contentCfg.enabled ? ["content.diff", "content.file"] : [];
+    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: {

package/test/contract/la-protocol-v2/vectors/content.index.vectors.json

@@ -3772,6 +3772,38 @@
           "last": true
         }
       }
+    },
+    {
+      "name": "file-list-kind",
+      "why": "ids of folders (kind file.list) are announced like any other id",
+      "expect": {
+        "valid": true
+      },
+      "message": {
+        "schemaVersion": 2,
+        "type": "content.index",
+        "msgId": "00000000-0000-4000-8000-000000000001",
+        "seq": 1,
+        "tenantId": "3f2b8c1e-5a4d-4e7b-9c21-0a1b2c3d4e5f",
+        "workspaceId": "ws-1",
+        "ts": "2026-11-03T10:00:00Z",
+        "agentId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
+        "payload": {
+          "entries": [
+            {
+              "kind": "file.list",
+              "ref": "CQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQk",
+              "size": 0
+            },
+            {
+              "kind": "file",
+              "ref": "CgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgo",
+              "size": 2048,
+              "updatedAt": "2026-11-03T09:30:00Z"
+            }
+          ]
+        }
+      }
     }
   ]
 }