@jini-ai/platform 0.6.15-rc.2 → 0.6.16

package/dist/fs/directory-sync.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { readOptionalText, readWindowsOneDriveRoots } from "./user-data-directories.js";
+import { fallbackIfMissing } from "./errno.js";
 const MOUNT_PROVIDERS = [["OneDrive-", "OneDrive"], ["GoogleDrive-", "Google Drive"], ["Dropbox", "Dropbox"]];
 function canonicalOrResolved({ path: value }) { try {
     return fs.realpathSync(value);
@@ -12,9 +13,7 @@ function listDirectoriesOrEmpty(root) { try {
     return fs.readdirSync(root);
 }
 catch (error) {
-    if (error.code === "ENOENT")
-        return [];
-    throw error;
+    return fallbackIfMissing(error, []);
 } }
 function macRoots({ homeDir, documents }, { paths, exists, listDirectories }) {
     const cloud = paths.join(homeDir, "Library", "Mobile Documents", "com~apple~CloudDocs");

package/dist/fs/directory-user-config.d.ts

@@ -1,5 +1,14 @@
 import type { DurableJsonFile } from "./durable-json.js";
 import { type UserDirectoryOptions } from "./user-data-directories.js";
+/** An expected settings refusal whose message is safe to show to the caller.
+ * Filesystem and persistence failures retain their original errors for private diagnostics.
+ */
+export declare class DirectoryUserConfigRefusal extends Error {
+    readonly name = "DirectoryUserConfigRefusal";
+    constructor({ message }: {
+        message: string;
+    }, _options?: {});
+}
 export interface DirectoryUserConfig {
     sitesHome: string;
     siteRoots: string[];

package/dist/fs/directory-user-config.js

@@ -3,6 +3,13 @@ import { createHash } from "node:crypto";
 import { resolveDirectoryHome } from "./directory-home.js";
 import { resolveUserDataDirectories } from "./user-data-directories.js";
 import { detectDirectorySync } from "./directory-sync.js";
+/** An expected settings refusal whose message is safe to show to the caller.
+ * Filesystem and persistence failures retain their original errors for private diagnostics.
+ */
+export class DirectoryUserConfigRefusal extends Error {
+    name = "DirectoryUserConfigRefusal";
+    constructor({ message }, _options = {}) { super(message); }
+}
 const SAFE_SITE_ID = /^[a-zA-Z0-9_-]+$/;
 const invalidMarker = (markerPath) => new Error(`Interrupted database move has an invalid recovery marker: ${markerPath}. Restore the pre-move backup before starting.`);
 function assertDatabaseFilename(filename) {
@@ -78,14 +85,14 @@ export function createDirectoryUserConfig({ homeDir, defaultFolder, envName, pol
                 continue;
             const expanded = expand(directory);
             if (exists(expanded) && !isDirectory(expanded))
-                throw new Error(`Sites folder is not a directory: ${directory}`);
+                throw new DirectoryUserConfigRefusal({ message: `Sites folder is not a directory: ${directory}` });
         }
     }
     function assertNotOverridden(checked) {
         if (checked.sitesHome !== undefined && env[envName] !== undefined)
-            throw new Error(`${envName} overrides this setting. Unset it before changing the directory home.`);
+            throw new DirectoryUserConfigRefusal({ message: `${envName} overrides this setting. Unset it before changing the directory home.` });
         if (checked.siteRoots !== undefined && env[policy.rootsEnvName] !== undefined)
-            throw new Error(`${policy.rootsEnvName} overrides this setting. Unset it before changing site roots.`);
+            throw new DirectoryUserConfigRefusal({ message: `${policy.rootsEnvName} overrides this setting. Unset it before changing site roots.` });
     }
     function merged(previous, checked, incremental) {
         const next = { ...previous, ...checked,
@@ -213,13 +220,13 @@ const SETTING_RULES = [
  */
 export function validateDirectoryUserConfig({ value }, _options = {}) {
     if (!value || typeof value !== "object" || Array.isArray(value))
-        throw new Error("User config must be an object.");
+        throw new DirectoryUserConfigRefusal({ message: "User config must be an object." });
     const row = value;
     if (Object.keys(row).some((key) => !SETTING_RULES.some(([known]) => known === key)))
-        throw new Error("Unknown user config setting.");
+        throw new DirectoryUserConfigRefusal({ message: "Unknown user config setting." });
     for (const [key, valid, message] of SETTING_RULES)
         if (row[key] !== undefined && !valid(row[key]))
-            throw new Error(message);
+            throw new DirectoryUserConfigRefusal({ message });
     return row;
 }
 //# sourceMappingURL=directory-user-config.js.map

package/dist/fs/directory-workspace.js

@@ -7,6 +7,9 @@ import { createDirectoryUserConfig, validateDirectoryUserConfig } from "./direct
 import { resolveDirectoryHome } from "./directory-home.js";
 import { createDirectoryRegistry } from "./directory-registry.js";
 import { createDirectoryRunningLock } from "./directory-running-lock.js";
+import { fallbackIfMissing } from "./errno.js";
+/** Migration id recorded once the old per-app catalogs are merged into the shared registry. */
+const APP_DATA_CATALOG_MIGRATION = "app-data-catalog-v1";
 /** Node assembly only. Policy modules receive explicit filesystem, clock and process ports.
  * Settings live outside the selected home so changing the setting never loses the pointer.
  * Reading a missing home/catalog does not create it. Opt-in registry recovery may prune known
@@ -23,9 +26,7 @@ export function createNodeDirectoryWorkspace({ homeDir, defaultFolder, envName,
             return true;
         }
         catch (error) {
-            if (error.code === "ENOENT")
-                return false;
-            throw error;
+            return fallbackIfMissing(error, false);
         } },
     }, { env, cwd, report: (message) => ports.report.error({ message }), ...directoryOptions }) : undefined;
     const settings = fileAt(config?.filePath ?? settingsFile);
@@ -63,9 +64,7 @@ export function createNodeDirectoryWorkspace({ homeDir, defaultFolder, envName,
                 return false;
             }
             catch (error) {
-                if (error.code === "ENOENT")
-                    return true;
-                throw error;
+                return fallbackIfMissing(error, true);
             }
         },
         reportDiscarded: ({ entries }) => ports.report.error({ message: `Directory workspace: removed ${entries.length} test/temporary catalog entries: ${entries.map((entry) => entry.id).join(", ")}` }),
@@ -91,10 +90,10 @@ export function createNodeDirectoryWorkspace({ homeDir, defaultFolder, envName,
     };
     const importOldCatalog = () => {
         const current = atHome();
-        if (!config || current.hasMigration({ migration: "app-data-catalog-v1" }))
+        if (!config || current.hasMigration({ migration: APP_DATA_CATALOG_MIGRATION }))
             return;
         const previous = oldCatalogs();
-        current.merge({ entries: previous.flatMap((catalog) => catalog.list({})), migrations: previous.flatMap((catalog) => catalog.migrations({})), migration: "app-data-catalog-v1" });
+        current.merge({ entries: previous.flatMap((catalog) => catalog.list({})), migrations: previous.flatMap((catalog) => catalog.migrations({})), migration: APP_DATA_CATALOG_MIGRATION });
     };
     // One lease adapter for both the app-data and the site-local (legacy) lease locations.
     const runningLockAt = (filePath) => createDirectoryRunningLock({ file: fileAt(filePath), isAlive: ports.process.isAlive,
@@ -105,7 +104,7 @@ export function createNodeDirectoryWorkspace({ homeDir, defaultFolder, envName,
     const registry = {
         list: (required, options = {}) => {
             const current = atHome();
-            if (!config || current.hasMigration({ migration: "app-data-catalog-v1" }))
+            if (!config || current.hasMigration({ migration: APP_DATA_CATALOG_MIGRATION }))
                 return current.list(required, options);
             const rows = [...oldCatalogs().flatMap((catalog) => catalog.list(required, options)), ...current.list(required, options)];
             return [...new Map(rows.map((row) => [canonicalPath({ path: row.path }), row])).values()];
@@ -148,9 +147,7 @@ export function createNodeDirectoryWorkspace({ homeDir, defaultFolder, envName,
                 return ports.filesystem.statSync(parent).isDirectory();
             }
             catch (error) {
-                if (error.code === "ENOENT")
-                    return false;
-                throw error;
+                return fallbackIfMissing(error, false);
             }
         },
         legacyHomes: (_required, _options = {}) => config?.legacyHomes({}) ?? [],
@@ -187,9 +184,9 @@ export function createNodeDirectoryWorkspace({ homeDir, defaultFolder, envName,
                                     read: () => state === undefined ? { state: "missing" } : { state: "ok", value: state },
                                     write: ({ value: next }) => { state = next; }, withLock: ({ critical }) => critical(),
                                 } });
-                            if (!staged.hasMigration({ migration: "app-data-catalog-v1" })) {
+                            if (!staged.hasMigration({ migration: APP_DATA_CATALOG_MIGRATION })) {
                                 const previous = oldCatalogs();
-                                staged.merge({ entries: previous.flatMap((catalog) => catalog.list({})), migrations: previous.flatMap((catalog) => catalog.migrations({})), migration: "app-data-catalog-v1" });
+                                staged.merge({ entries: previous.flatMap((catalog) => catalog.list({})), migrations: previous.flatMap((catalog) => catalog.migrations({})), migration: APP_DATA_CATALOG_MIGRATION });
                             }
                             const existing = staged.list({}).find((row) => row.path === from || row.id === entry.id);
                             if (existing && existing.path !== from && existing.path !== to)

package/dist/fs/durable-json.js

@@ -43,8 +43,9 @@ export function createNodeDurableJsonPorts(_required) {
 export function createDurableJsonFile({ filePath, filesystem: fs, clock, sleep, process, random, report, notices }, { pollMs = 10, staleMs = 30000 } = {}) {
     if (!filePath)
         throw new TypeError("filePath is required");
-    if (!Number.isSafeInteger(pollMs) || pollMs <= 0 ||
-        ((!Number.isSafeInteger(staleMs) && staleMs !== Infinity) || staleMs <= 0))
+    const validPoll = Number.isSafeInteger(pollMs) && pollMs > 0;
+    const validStale = (Number.isSafeInteger(staleMs) || staleMs === Infinity) && staleMs > 0;
+    if (!validPoll || !validStale)
         throw new TypeError("lock intervals must be positive safe integers");
     // A synchronous read-modify-write normally takes milliseconds; five seconds allows contention
     // while refusing a wedged change. Short ten-millisecond polling fits those short critical sections.
@@ -139,31 +140,36 @@ export function salvageJsonPrefix({ text }, { maxAttempts = 1000 } = {}) {
 }
 // Cut only at completed strings/objects/arrays, sufficient for string-valued lists. Damage inside a
 // bare number/boolean falls back to the previous cut and loses that element rather than guessing it.
+const CLOSER_FOR = new Map([["{", "}"], ["[", "]"]]);
+const CLOSERS = new Set(["}", "]"]);
 function elementEnds(text) {
     const open = [];
     const cuts = [];
-    for (let index = 0; index < text.length; index += 1) {
+    let index = 0;
+    while (index < text.length) {
         const char = text[index];
+        const closer = CLOSER_FOR.get(char);
+        // An opener only records its closer; a completed string or container is a cut point.
+        if (closer !== undefined)
+            open.push(closer);
+        if (CLOSERS.has(char))
+            open.pop();
         if (char === '"')
             index = endOfString(text, index);
-        else if (char === "{" || char === "[") {
-            open.push(char === "{" ? "}" : "]");
-            continue;
-        }
-        else if (char === "}" || char === "]")
-            open.pop();
-        else
-            continue;
-        cuts.push({ end: index + 1, closers: [...open].reverse().join("") });
+        if (char === '"' || CLOSERS.has(char))
+            cuts.push({ end: index + 1, closers: [...open].reverse().join("") });
+        index += 1;
     }
     return cuts;
 }
 function endOfString(text, start) {
-    for (let index = start + 1; index < text.length; index += 1) {
-        if (text[index] === "\\")
-            index += 1;
-        else if (text[index] === '"')
+    let index = start + 1;
+    while (index < text.length) {
+        const char = text[index];
+        if (char === '"')
             return index;
+        // A backslash escapes the next character, whatever it is.
+        index += char === "\\" ? 2 : 1;
     }
     return text.length;
 }

package/dist/fs/errno.d.ts

@@ -0,0 +1,9 @@
+/** The string `code` of a Node system error (`ENOENT`, `EEXIST`, ...), or undefined for anything else.
+ *  @complexity O(1). */
+export declare function errorCodeOf(error: unknown): string | undefined;
+/** Returns `fallback` when `matches(error)` and rethrows anything else, so an expected failure reads
+ *  `catch (error) { return fallbackIf(error, isExpected, undefined); }`. @complexity O(matches). */
+export declare function fallbackIf<T>(error: unknown, matches: (error: unknown) => boolean, fallback: T): T;
+/** {@link fallbackIf} for a missing entry (ENOENT). @complexity O(1). */
+export declare function fallbackIfMissing<T>(error: unknown, fallback: T): T;
+//# sourceMappingURL=errno.d.ts.map

package/dist/fs/errno.js

@@ -0,0 +1,21 @@
+/** The string `code` of a Node system error (`ENOENT`, `EEXIST`, ...), or undefined for anything else.
+ *  @complexity O(1). */
+export function errorCodeOf(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return undefined;
+    return typeof error.code === "string" ? error.code : undefined;
+}
+/** Returns `fallback` when `matches(error)` and rethrows anything else, so an expected failure reads
+ *  `catch (error) { return fallbackIf(error, isExpected, undefined); }`. @complexity O(matches). */
+export function fallbackIf(error, matches, fallback) {
+    if (matches(error))
+        return fallback;
+    throw error;
+}
+/** {@link fallbackIf} for a missing entry (ENOENT). @complexity O(1). */
+export function fallbackIfMissing(error, fallback) {
+    if (error.code === "ENOENT")
+        return fallback;
+    throw error;
+}
+//# sourceMappingURL=errno.js.map

package/dist/fs/file-lock.d.ts

@@ -35,6 +35,7 @@ export interface HeldFileLockSync {
 export type FileLockSyncFilesystem = Pick<typeof fs, "mkdirSync" | "openSync" | "writeSync" | "fstatSync" | "readFileSync" | "statSync" | "closeSync" | "rmSync">;
 export type FileLockAsyncFilesystem = Pick<typeof asyncFs, "mkdir" | "open" | "stat" | "rm">;
 export interface FileLockOptions {
+    /** Infinity follows an operation with its own deadline; dead local owners remain reclaimable. */
     timeoutMs?: number;
     /** Infinity disables age stealing; dead local owners remain reclaimable. */
     staleMs?: number;

package/dist/fs/file-lock.js

@@ -18,6 +18,7 @@ import { hostname as nodeHostname } from "node:os";
 import path from "node:path";
 import { createSystemClock } from "@jini-ai/core/primitives";
 import { defaultPlatformMessages } from "../messages.js";
+import { errorCodeOf, fallbackIf } from "./errno.js";
 export const DEFAULT_LOCK_TIMEOUT_MS = 15_000;
 export const DEFAULT_LOCK_STALE_AFTER_MS = 10_000;
 export class FileLockTimeoutError extends Error {
@@ -44,14 +45,14 @@ export class FileLockLostError extends Error {
 export function isContendedLockError({ code, platform }) {
     return code === "EEXIST" || (code === "EPERM" && platform === "win32");
 }
-function errorCode(error) {
-    return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" ? error.code : undefined;
+function isContended(error) {
+    return isContendedLockError({ code: errorCodeOf(error), platform: process.platform });
 }
 function isAbsentOrContended(error) {
-    const code = errorCode(error);
+    const code = errorCodeOf(error);
     return code === "ENOENT" || isContendedLockError({ code, platform: process.platform });
 }
-function rethrowUnlessMissing(error) { if (errorCode(error) !== "ENOENT")
+function rethrowUnlessMissing(error) { if (errorCodeOf(error) !== "ENOENT")
     throw error; }
 function validPid(pid) { return typeof pid === "number" && Number.isSafeInteger(pid) && pid > 0; }
 function isHolderRecord(value) {
@@ -77,7 +78,10 @@ export function isLockStale(required) {
     return (required.ownerAlive === false || required.nowMs - required.mtimeMs > required.staleMs) && required.observedInode === required.currentInode && required.observedDevice === required.currentDevice;
 }
 function intervalsValid({ timeoutMs, staleMs, pollMs }) {
-    return Number.isSafeInteger(timeoutMs) && timeoutMs >= 0 && (Number.isSafeInteger(staleMs) || staleMs === Infinity) && staleMs > 0 && Number.isSafeInteger(pollMs) && pollMs > 0;
+    const validTimeout = (Number.isSafeInteger(timeoutMs) && timeoutMs >= 0) || timeoutMs === Infinity;
+    const validStale = (Number.isSafeInteger(staleMs) || staleMs === Infinity) && staleMs > 0;
+    const validPoll = Number.isSafeInteger(pollMs) && pollMs > 0;
+    return validTimeout && validStale && validPoll;
 }
 function intervals(options) {
     const timeoutMs = options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS, staleMs = options.staleMs ?? DEFAULT_LOCK_STALE_AFTER_MS, pollMs = options.pollMs ?? 10;
@@ -91,7 +95,7 @@ function defaultProcessPort() {
             return true;
         }
         catch (error) {
-            return errorCode(error) !== "ESRCH";
+            return errorCodeOf(error) !== "ESRCH";
         } } };
 }
 function settings(options) {
@@ -102,7 +106,9 @@ function settings(options) {
     return { ...checked, processPort, clock, monotonicMs, boot: processPort.bootIdentity?.(), hostname: (options.hostname ?? nodeHostname)(), token: (options.token ?? randomUUID)() };
 }
 function ownership(s, options) {
-    return options.format === "token" ? `${s.processPort.pid}:${s.token}${s.boot ? ":" + s.boot.id : ""}` : JSON.stringify({ pid: s.processPort.pid, hostname: s.hostname, token: s.token, acquiredAt: new Date(s.clock.nowMs()).toISOString(), ...(s.boot ? { bootId: s.boot.id } : {}) });
+    if (options.format === "token")
+        return `${s.processPort.pid}:${s.token}${s.boot ? ":" + s.boot.id : ""}`;
+    return JSON.stringify({ pid: s.processPort.pid, hostname: s.hostname, token: s.token, acquiredAt: new Date(s.clock.nowMs()).toISOString(), ...(s.boot ? { bootId: s.boot.id } : {}) });
 }
 function holderAlive(holder, s) {
     if (holder.hostname !== s.hostname)
@@ -155,9 +161,7 @@ function inspectSync(lockPath, filesystem) {
         descriptor = filesystem.openSync(lockPath, "r");
     }
     catch (error) {
-        if (isAbsentOrContended(error))
-            return undefined;
-        throw error;
+        return fallbackIf(error, isAbsentOrContended, undefined);
     }
     try {
         const info = filesystem.fstatSync(descriptor), raw = filesystem.readFileSync(descriptor, "utf8");
@@ -173,9 +177,7 @@ async function inspectAsync(lockPath, filesystem) {
         handle = await filesystem.open(lockPath, "r");
     }
     catch (error) {
-        if (isAbsentOrContended(error))
-            return undefined;
-        throw error;
+        return fallbackIf(error, isAbsentOrContended, undefined);
     }
     try {
         const info = await handle.stat(), raw = await handle.readFile("utf8");
@@ -203,9 +205,7 @@ function tryCreateSync(ctx) {
         descriptor = filesystem.openSync(lockPath, "wx", 0o600);
     }
     catch (error) {
-        if (!isContendedLockError({ code: errorCode(error), platform: process.platform }))
-            throw error;
-        return undefined;
+        return fallbackIf(error, isContended, undefined);
     }
     let identity;
     try {
@@ -300,9 +300,7 @@ async function tryCreateAsync(ctx) {
         handle = await ctx.filesystem.open(ctx.lockPath, "wx", 0o600);
     }
     catch (error) {
-        if (!isContendedLockError({ code: errorCode(error), platform: process.platform }))
-            throw error;
-        return undefined;
+        return fallbackIf(error, isContended, undefined);
     }
     let identity;
     try {

package/dist/fs/guarded-reader.d.ts

@@ -14,6 +14,27 @@ export type AddedReaderOptions = {
     descriptorRead?: DescriptorReadPolicy;
 };
 export type GuardedReaderFilesystem = Pick<typeof nodeFs, "existsSync" | "lstatSync" | "readdirSync" | "realpathSync" | "statSync" | "openSync" | "readSync" | "closeSync" | "createReadStream"> & DescriptorCapabilities;
+/** Opt-in listing pages; omitted options preserve the legacy recursive reader contract.
+ * Cursors are offsets in a sorted snapshot; keep path/depth fixed and restart after tree changes.
+ */
+export interface GuardedListingOptions {
+    relativePath?: string;
+    depth?: number;
+    limit?: number;
+    cursor?: string;
+    maxOutputBytes?: number;
+}
+export interface GuardedListingResult {
+    files: string[];
+    truncated: boolean;
+    remaining?: number;
+    nextCursor?: string;
+    message?: string;
+}
+/** Adds optional paging without changing existing guarded-reader implementations. */
+export interface PagedGuardedFileReader extends GuardedFileReader {
+    list(required: Record<string, never>, optional?: GuardedListingOptions): GuardedListingResult;
+}
 /** Native filesystem adapter; callers can replace individual operations for a virtual filesystem. */
 export declare function createNodeGuardedReaderFilesystem(_required: Record<string, never>): GuardedReaderFilesystem;
 /** Contains both requested and resolved paths, including symlink aliases and nonexistent descendants.
@@ -28,5 +49,5 @@ export declare function createGuardedFileReader({ rootPath, denyRules, limits, f
     filesystem: GuardedReaderFilesystem;
 }, { excludedListingDirs, descriptorRead }?: {
     excludedListingDirs?: ReadonlySet<string>;
-} & AddedReaderOptions): GuardedFileReader;
+} & AddedReaderOptions): PagedGuardedFileReader;
 //# sourceMappingURL=guarded-reader.d.ts.map

package/dist/fs/guarded-reader.js

@@ -1,6 +1,9 @@
 import nodeFs from "node:fs";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { trimCharsEnd } from "@jini-ai/core/primitives";
 import { FsFilePathError } from '@jini-ai/core/filesystem';
+/** Path segments that never add a component: empty (doubled separator), ".", and "..". */
+const NON_DESCENDING_SEGMENTS = new Set(["", ".", ".."]);
 export { FsFilePathError } from '@jini-ai/core/filesystem';
 /** Native filesystem adapter; callers can replace individual operations for a virtual filesystem. */
 export function createNodeGuardedReaderFilesystem(_required) { return nodeFs; }
@@ -34,8 +37,9 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
     // name::$DATA as name. Compare raw AND folded names: folding may add denials, never remove them,
     // and must not change the path actually opened.
     function foldFsNameForDenylist(name) {
-        const withoutStream = name.replace(/:[^]*$/, "");
-        const withoutTrailing = withoutStream.replace(/[. ]+$/, "");
+        const streamAt = name.indexOf(":");
+        const withoutStream = streamAt === -1 ? name : name.slice(0, streamAt);
+        const withoutTrailing = trimCharsEnd({ text: withoutStream, chars: ". " });
         return withoutTrailing.toLowerCase().toUpperCase().toLowerCase();
     }
     // Split both separator spellings even on a host whose native separator is '/', so deny checks
@@ -43,13 +47,11 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
     function normalizeFsRelativePath(relativePath) {
         const segments = [];
         for (const segment of relativePath.split(/[\\/]/)) {
-            if (segment === "" || segment === ".")
-                continue;
-            if (segment === "..") {
+            // Empty and "." segments are no-ops; ".." climbs one level; anything else descends.
+            if (segment === "..")
                 segments.pop();
-                continue;
-            }
-            segments.push(segment);
+            if (!NON_DESCENDING_SEGMENTS.has(segment))
+                segments.push(segment);
         }
         return segments.join("/");
     }
@@ -155,6 +157,10 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
         if (stat.isDirectory()) {
             if (isDeniedFsPathSegment(name) || EXCLUDED_LISTING_DIR_NAMES.has(name))
                 return;
+            if (state.paged && depth === state.maxDepth) {
+                found.push(relative(base, full).split(sep).join("/") + "/");
+                return;
+            }
             walkFsDir(full, depth + 1, base, found, state);
             return;
         }
@@ -167,14 +173,17 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
     // Results, entries, and depth are independent limits; keep the decision shared by entry and
     // loop checks so adding one limit cannot leave an unbounded arm.
     function walkBoundReached(found, state, depth) {
-        return depth > MAX_WALK_DEPTH || found.length >= MAX_LISTED_FILES || state.remaining <= 0;
+        return depth > state.maxDepth || found.length >= state.maxFiles || state.remaining <= 0;
     }
     function walkFsDir(dir, depth, base, found, state) {
         if (walkBoundReached(found, state, depth)) {
             state.truncated = true;
             return;
         }
-        for (const name of readdirSync(dir)) {
+        const names = readdirSync(dir);
+        if (state.paged)
+            names.sort();
+        for (const name of names) {
             // Recheck per entry: this loop spends traversal budget and adds results. Remaining
             // entries mean a bound must set truncated rather than present a short list as complete.
             if (walkBoundReached(found, state, depth)) {
@@ -185,26 +194,36 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
             visitFsDirEntry(dir, name, depth, base, found, state);
         }
     }
+    /** Walk with existing containment/deny rules, then bound the serialized page independently.
+     * @complexity At most maxWalkEntries probes; sorting uses O(n log n) time and O(n) paths.
+     * Directory reads remain synchronous; traversal exhaustion is reported as an unknown remainder.
+     */
     function listFsFiles(required) {
+        const paged = [required.depth, required.limit, required.cursor, required.maxOutputBytes].some(value => value !== undefined);
+        const page = listingPageOptions(required, { maxDepth: MAX_WALK_DEPTH, maxFiles: MAX_LISTED_FILES });
         const { rootPath } = required;
         const relativePath = required.relativePath ?? "";
+        const pathLabel = relativePath || ".";
         const startDir = relativePath.length === 0 ? resolve(rootPath) : resolveFsFilePath({ rootPath, relativePath });
         // Freshly provisioned roots/subdirectories may not exist yet; an empty listing is valid.
         if (!existsSync(startDir))
             return { files: [], truncated: false };
-        const startStat = statOrFsPathError(startDir, relativePath || ".");
+        const startStat = statOrFsPathError(startDir, pathLabel);
         if (!startStat)
             return { files: [], truncated: false };
         if (!startStat.isDirectory()) {
-            throw new FsFilePathError({ message: `path '${relativePath || "."}' is not a directory` });
+            throw new FsFilePathError({ message: `path '${pathLabel}' is not a directory` });
         }
         const base = realpathSync(startDir);
         const found = [];
-        const state = { remaining: MAX_WALK_ENTRIES, truncated: false };
+        const state = { remaining: MAX_WALK_ENTRIES, truncated: false,
+            maxDepth: paged ? page.depth - 1 : MAX_WALK_DEPTH,
+            maxFiles: paged ? MAX_WALK_ENTRIES : MAX_LISTED_FILES, paged };
         walkFsDir(base, 0, base, found, state);
         // Paths are relative to the requested walk base, so a subdirectory listing can be consumed
         // without stripping that subdirectory's prefix a second time.
-        return { files: found.sort(), truncated: state.truncated };
+        const listing = { files: found.sort(), truncated: state.truncated };
+        return paged ? paginateListing(listing, page) : listing;
     }
     // Circular-link ELOOP and other filesystem exceptions must become the reader's refusal class,
     // not escape raw while an ordinary missing path is represented by undefined.
@@ -351,6 +370,53 @@ export function createGuardedFileReader({ rootPath, denyRules, limits, filesyste
         isDeniedPathSegment: ({ segmentName }) => isDeniedFsPathSegment(segmentName),
     };
 }
+/** Validate page controls even for raw callers bypassing a tool schema; no filesystem effects. */
+function listingPageOptions(input, { maxDepth, maxFiles }) {
+    const depth = input.depth ?? 1, limit = input.limit ?? Math.min(100, maxFiles), maxOutputBytes = input.maxOutputBytes ?? 8000;
+    for (const [name, value, max] of [["depth", depth, maxDepth], ["limit", limit, maxFiles], ["maxOutputBytes", maxOutputBytes, Number.MAX_SAFE_INTEGER]]) {
+        if (!Number.isSafeInteger(value) || value < 1 || value > max)
+            throw new FsFilePathError({ message: `${name} must be an integer between 1 and ${max}` });
+    }
+    if (maxOutputBytes < 512)
+        throw new FsFilePathError({ message: "maxOutputBytes must be at least 512 to fit listing metadata" });
+    return { depth, limit, maxOutputBytes, offset: listingOffset(input) };
+}
+/** Parse only cursors the pager can issue; refuse unsafe numeric offsets before traversal. */
+function listingOffset({ cursor = "0" }, _options = {}) {
+    if (typeof cursor !== "string" || !/^(0|[1-9]\d*)$/.test(cursor) || !Number.isSafeInteger(Number(cursor)))
+        throw new FsFilePathError({ message: "cursor must be a non-negative integer string returned as nextCursor; keep path/depth fixed" });
+    return Number(cursor);
+}
+/** Bound JSON bytes as well as entry count: long or escaped filenames must not flood model input.
+ * Rescanning keeps cursors stateless; the existing traversal budget bounds work on every page.
+ * @throws FsFilePathError if one path cannot fit; narrowing path shortens relative entries.
+ */
+function paginateListing(listing, { limit, maxOutputBytes, offset }) {
+    const files = [];
+    // Reserve space for truncation guidance, cursor and the tool's root/path envelope.
+    let bytes = 512;
+    for (const file of listing.files.slice(offset, offset + limit)) {
+        const size = Buffer.byteLength(JSON.stringify(file)) + 1;
+        if (bytes + size > maxOutputBytes)
+            break;
+        files.push(file);
+        bytes += size;
+    }
+    const end = offset + files.length, remaining = Math.max(0, listing.files.length - end);
+    if (remaining > 0 && files.length === 0)
+        throw new FsFilePathError({ message: "A listing entry exceeds the output budget; pass a narrower path to shorten the relative filename" });
+    return listingPageResult({ files, end, remaining, walkTruncated: listing.truncated });
+}
+/** Never claim an exact count when the traversal budget left directories unscanned. */
+function listingPageResult({ files, end, remaining, walkTruncated }, _options = {}) {
+    if (remaining === 0 && !walkTruncated)
+        return { files, truncated: false };
+    const count = walkTruncated ? "unknown" : String(remaining);
+    return { files, truncated: true,
+        ...(!walkTruncated ? { remaining } : {}),
+        ...(remaining > 0 ? { nextCursor: String(end) } : {}),
+        message: `truncated: ${count} more entries; pass path/depth/cursor to see more. Keep path/depth fixed when paging; restart if files change.${walkTruncated ? " Traversal limit reached; narrow path to inspect unscanned directories." : ""}` };
+}
 /** Validate opt-in capability support without weakening legacy filesystem adapters. */
 function descriptorOpenFlags({ filesystem, policy }) {
     if (!filesystem.fstatSync || !filesystem.constants)
@@ -362,11 +428,15 @@ function descriptorOpenFlags({ filesystem, policy }) {
         throw new TypeError("exactMode must contain only permission bits (0o0000 through 0o7777)");
     return O_RDONLY | O_NOFOLLOW | O_NONBLOCK;
 }
+/** A safe, non-negative integer no larger than `max`; guards the size reported by an injected stat. */
+function isByteCountWithin(value, max) {
+    return Number.isSafeInteger(value) && value >= 0 && value <= max;
+}
 /** Both read paths validate the opened object, independent of earlier pathname metadata. */
 function assertDescriptorStat({ stat, relativePath, maxBytes }, { exactMode } = {}) {
     if (!stat.isFile())
         throw new FsFilePathError({ message: `path '${relativePath}' is not a regular file` });
-    if (!Number.isSafeInteger(stat.size) || stat.size < 0 || stat.size > maxBytes)
+    if (!isByteCountWithin(stat.size, maxBytes))
         throw new FsFilePathError({ message: `file '${relativePath}' exceeds the ${maxBytes}-byte descriptor limit` });
     // Include setuid/setgid/sticky: "exact" 0o600 must refuse a 0o4600 file.
     if (exactMode !== undefined && (stat.mode & 0o7777) !== exactMode)

package/dist/fs/index.d.ts

@@ -9,6 +9,7 @@ export * from "./directory-home.js";
 export * from "./directory-registry.js";
 export * from "./directory-running-lock.js";
 export * from "./directory-workspace.js";
+export { DirectoryUserConfigRefusal, validateDirectoryUserConfig } from "./directory-user-config.js";
 export * from "./workspace-directory.js";
 export * from "./verified-directory-move.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/fs/index.js

@@ -10,6 +10,7 @@ export * from "./directory-home.js";
 export * from "./directory-registry.js";
 export * from "./directory-running-lock.js";
 export * from "./directory-workspace.js";
+export { DirectoryUserConfigRefusal, validateDirectoryUserConfig } from "./directory-user-config.js";
 export * from "./workspace-directory.js";
 export * from "./verified-directory-move.js";
 //# sourceMappingURL=index.js.map