@jini-ai/platform 0.6.15 → 0.6.16

package/README.md

@@ -14,12 +14,9 @@ that were split out of OD's monolithic daemon (see the archived provenance ledge
 npm install @jini-ai/platform
 ```
 
-`undici@^7.25.0` is an optional peer for the SSRF-safe asset cache's default dispatcher.
-Install it when calling `createAssetCacheDispatcher` or creating a cache without a host-supplied
-guarded dispatcher. Root imports and `@jini-ai/platform/asset-cache` imports do not load undici;
-the synchronous factory loads it on demand and reports a missing-peer error if it is absent.
-The root declarations retain undici types, so TypeScript consumers of those declarations also
-need the peer available. The dispatcher validates DNS at connection time, and cache `close()`
+`undici@^7.25.0` is a regular dependency, installed with this package for the SSRF-safe asset
+cache's default dispatcher. The synchronous factory constructs it on demand and propagates
+construction failures. The dispatcher validates DNS at connection time, and cache `close()`
 closes only its default dispatcher; a host-supplied dispatcher remains owned by the host.
 Interactive terminal sessions (`createTerminalService`)
 need a `PtySpawn` implementation supplied by the caller — this package defines the `PtyProcess`/

package/dist/asset-cache.adapter.d.ts

@@ -1,7 +1,7 @@
 import type { LookupFunction } from 'node:net';
 import type { Agent } from 'undici';
-/** Load the optional vendor only for a default dispatcher; the cache owns lookup validation.
- * @throws When the optional peer cannot be loaded or its Agent cannot be constructed.
+/** Construct the dispatcher with platform's required undici dependency; the cache owns lookup validation.
+ * @throws When the Agent cannot be constructed.
  */
 export declare function createUndiciAssetCacheDispatcher({ lookup }: {
     lookup: LookupFunction;

package/dist/asset-cache.adapter.js

@@ -1,7 +1,7 @@
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
-/** Load the optional vendor only for a default dispatcher; the cache owns lookup validation.
- * @throws When the optional peer cannot be loaded or its Agent cannot be constructed.
+/** Construct the dispatcher with platform's required undici dependency; the cache owns lookup validation.
+ * @throws When the Agent cannot be constructed.
  */
 export function createUndiciAssetCacheDispatcher({ lookup }, _options = {}) {
     const { Agent } = require('undici');

package/dist/asset-cache.d.ts

@@ -52,9 +52,7 @@ export interface AssetCache {
     /** Closes only the default adapter; an injected dispatcher remains owned by its host. */
     close?(): Promise<void>;
 }
-/** Default adapter: validate DNS at connection time, so the checked address is the connected one.
- * @throws {AssetCacheError} When the host has not installed the optional undici peer.
- */
+/** Default adapter: validate DNS at connection time, so the checked address is the connected one. */
 export declare function createAssetCacheDispatcher(_required: Record<string, never>, { lookupImpl }?: {
     lookupImpl?: DnsLookupCb;
 }): Agent;

package/dist/asset-cache.js

@@ -130,21 +130,9 @@ export function createValidatingLookup(lookupImpl = dnsLookupCb) {
         });
     };
 }
-/** Default adapter: validate DNS at connection time, so the checked address is the connected one.
- * @throws {AssetCacheError} When the host has not installed the optional undici peer.
- */
+/** Default adapter: validate DNS at connection time, so the checked address is the connected one. */
 export function createAssetCacheDispatcher(_required, { lookupImpl } = {}) {
-    // Keep the factory synchronous while root imports and host-supplied dispatchers need no undici.
-    try {
-        return createUndiciAssetCacheDispatcher({ lookup: createValidatingLookup(lookupImpl) });
-    }
-    catch (error) {
-        if (error instanceof Error && error.code === 'MODULE_NOT_FOUND'
-            && error.message.split('\n')[0] === "Cannot find module 'undici'") {
-            throw new AssetCacheError(500, 'Asset cache dispatcher requires the optional peer "undici"; install undici@^7.25.0 or supply a guarded dispatcher.');
-        }
-        throw error;
-    }
+    return createUndiciAssetCacheDispatcher({ lookup: createValidatingLookup(lookupImpl) });
 }
 /** Build a disk-backed cache for external sandboxed-content media. Concurrent
  *  requests for the same URL share one in-flight fetch; completed fetches

package/dist/fetch-with-timeout.d.ts

@@ -37,7 +37,7 @@
  * module has zero imports of its own — no `node:*` builtin, no `undici` — unlike the package's root
  * barrel (`index.ts`), which re-exports sibling modules (`process.ts`, `fs.ts`, `terminal.ts`,
  * `asset-cache.ts`, …) that import `node:child_process`, `node:fs`, etc.; the asset-cache
- * dispatcher loads the optional `undici` peer only when its synchronous factory is called.
+ * dispatcher constructs its required `undici` dependency only when its synchronous factory is called.
  * Importing from the root barrel in browser-bundled code is silently fine in a *production* build
  * through Vite/Rollup — tree-shaking (this package sets `sideEffects: false`) proves the Node-only
  * re-exports are unused and drops them before the `node:*` imports are ever resolved — but it is

package/dist/fetch-with-timeout.js

@@ -37,7 +37,7 @@
  * module has zero imports of its own — no `node:*` builtin, no `undici` — unlike the package's root
  * barrel (`index.ts`), which re-exports sibling modules (`process.ts`, `fs.ts`, `terminal.ts`,
  * `asset-cache.ts`, …) that import `node:child_process`, `node:fs`, etc.; the asset-cache
- * dispatcher loads the optional `undici` peer only when its synchronous factory is called.
+ * dispatcher constructs its required `undici` dependency only when its synchronous factory is called.
  * Importing from the root barrel in browser-bundled code is silently fine in a *production* build
  * through Vite/Rollup — tree-shaking (this package sets `sideEffects: false`) proves the Node-only
  * re-exports are unused and drops them before the `node:*` imports are ever resolved — but it is

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

@@ -78,7 +78,7 @@ 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 }) {
-    const validTimeout = Number.isSafeInteger(timeoutMs) && timeoutMs >= 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;

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

@@ -157,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;
         }
@@ -169,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)) {
@@ -187,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.
@@ -353,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)

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

package/dist/fs/workspace-directory.d.ts

@@ -1,6 +1,8 @@
 import type { DirectoryRecord } from "./directory-registry.js";
 /** Shared selection policy for CLI/dev hosts. A registry ID disambiguates adopted paths;
  * a basename selects the home first. No initialized home site preserves the supplied fallback.
+ * Hosts may probe availability to resolve an ambiguous name to its sole available directory.
+ * Offline records and explicit ID selection are preserved; probe failures propagate.
  * @complexity O(n) registered/child directories and validation probes.
  */
 export declare function selectWorkspaceDirectory({ home, entries, fallback, selected, roots, listDirectories, isInitialized }: {
@@ -15,5 +17,9 @@ export declare function selectWorkspaceDirectory({ home, entries, fallback, sele
     isInitialized: (required: {
         path: string;
     }) => boolean;
-}, _options?: {}): string;
+}, { isAvailable }?: {
+    isAvailable?: (required: {
+        path: string;
+    }) => boolean;
+}): string;
 //# sourceMappingURL=workspace-directory.d.ts.map

package/dist/fs/workspace-directory.js

@@ -1,9 +1,11 @@
 import path from "node:path";
 /** Shared selection policy for CLI/dev hosts. A registry ID disambiguates adopted paths;
  * a basename selects the home first. No initialized home site preserves the supplied fallback.
+ * Hosts may probe availability to resolve an ambiguous name to its sole available directory.
+ * Offline records and explicit ID selection are preserved; probe failures propagate.
  * @complexity O(n) registered/child directories and validation probes.
  */
-export function selectWorkspaceDirectory({ home, entries, fallback, selected, roots = [home], listDirectories, isInitialized }, _options = {}) {
+export function selectWorkspaceDirectory({ home, entries, fallback, selected, roots = [home], listDirectories, isInitialized }, { isAvailable } = {}) {
     if (selected !== undefined) {
         const byId = entries.find((entry) => entry.id === selected);
         if (byId)
@@ -13,8 +15,13 @@ export function selectWorkspaceDirectory({ home, entries, fallback, selected, ro
             return inHome;
         const matches = [...new Set([...entries.filter((entry) => path.basename(entry.path) === selected).map((entry) => entry.path),
                 ...roots.filter((root) => root !== home).map((root) => path.join(root, selected)).filter((dir) => isInitialized({ path: dir }))])];
-        if (matches.length > 1)
+        if (matches.length > 1) {
+            // A stale scratch catalog row must not block the sole live site or choose by row order.
+            const available = matches.filter(dir => isAvailable?.({ path: dir }) ?? true);
+            if (available.length === 1)
+                return available[0];
             throw new Error("More than one registered directory has this name. Select its registry ID.");
+        }
         return matches[0] ?? path.join(path.dirname(fallback), selected);
     }
     const candidates = [...entries.filter((entry) => path.dirname(entry.path) === home).sort((a, b) => (b.lastOpened ? Date.parse(b.lastOpened) : 0) - (a.lastOpened ? Date.parse(a.lastOpened) : 0)).map((entry) => entry.path), ...roots.flatMap((root) => listDirectories({ root }))];

package/dist/messages.js

@@ -5,7 +5,7 @@ export const defaultPlatformMessages = {
     atomicSymlinkRefused: () => "atomic write refused a symbolic-link destination",
     atomicPermissionsRefused: () => "atomic write refused non-owner-only permissions",
     atomicJsonUnserializable: () => "atomic JSON data must be serializable",
-    fileLockIntervalsInvalid: () => "file lock intervals must be positive safe integers (timeout may be zero; stale may be Infinity)",
+    fileLockIntervalsInvalid: () => "file lock intervals must be positive safe integers (timeout may be zero or Infinity; stale may be Infinity)",
     fileLockWriteNoProgress: () => "file lock ownership write made no progress",
     egressRefused: () => "egress to the requested host was refused by the outbound network policy",
     rootKeySealedWarning: ({ subject }) => `IMPORTANT: anything sealed while ${subject} was in place was sealed under key material derived from these same bytes, `,

package/dist/net/index.d.ts

@@ -1,2 +1,3 @@
 export { isPrivateAddress, expandIpv6, isLoopbackApiHost, isBlockedExternalApiHostname, isLoopbackHostname } from "./address.js";
+export { probeLoopbackHttp } from './local-http-probe.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/net/index.js

@@ -1,2 +1,3 @@
 export { isPrivateAddress, expandIpv6, isLoopbackApiHost, isBlockedExternalApiHostname, isLoopbackHostname } from "./address.js";
+export { probeLoopbackHttp } from './local-http-probe.js';
 //# sourceMappingURL=index.js.map

package/dist/net/local-http-probe.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Probe a loopback service once, accepting only HTTP 200 without following redirects.
+ * @param required Absolute HTTP(S) URL. Non-loopback targets are refused before connecting.
+ * @param options Optional expected leaf PEM, TLS server name and request deadline (default 1500ms).
+ * @returns False for transport, TLS, timeout or non-200 failures; true for an authenticated 200.
+ * @throws For malformed URLs, certificate PEM or invalid timeout values (configuration errors).
+ * @complexity O(c) time/space for c certificate bytes; one bounded network request.
+ */
+export declare function probeLoopbackHttp({ url }: {
+    url: string;
+}, { certificate, servername, timeoutMs }?: {
+    certificate?: string | Buffer | undefined;
+    servername?: string | undefined;
+    timeoutMs?: number;
+}): Promise<boolean>;
+//# sourceMappingURL=local-http-probe.d.ts.map

package/dist/net/local-http-probe.js

@@ -0,0 +1,36 @@
+import { X509Certificate } from 'node:crypto';
+import { get as httpGet } from 'node:http';
+import { get as httpsGet } from 'node:https';
+import { isLoopbackHostname } from './address.js';
+/**
+ * Probe a loopback service once, accepting only HTTP 200 without following redirects.
+ * @param required Absolute HTTP(S) URL. Non-loopback targets are refused before connecting.
+ * @param options Optional expected leaf PEM, TLS server name and request deadline (default 1500ms).
+ * @returns False for transport, TLS, timeout or non-200 failures; true for an authenticated 200.
+ * @throws For malformed URLs, certificate PEM or invalid timeout values (configuration errors).
+ * @complexity O(c) time/space for c certificate bytes; one bounded network request.
+ */
+export function probeLoopbackHttp({ url }, { certificate, servername, timeoutMs = 1500 } = {}) {
+    const target = new URL(url);
+    if (!isLoopbackHostname({ hostname: target.hostname }))
+        return Promise.resolve(false);
+    if (target.protocol !== 'http:' && target.protocol !== 'https:')
+        return Promise.resolve(false);
+    const hostname = target.hostname.replace(/^\[|\]$/g, '').replace(/\.$/, '');
+    // Only the configured leaf is a trust anchor, never an issuer bundled after it.
+    // Partial-chain trust permits mkcert leaves without installing their CA into this Node process.
+    const trust = certificate === undefined ? {} : { ca: new X509Certificate(certificate).toString(), allowPartialTrustChain: true };
+    const options = {
+        agent: false, signal: AbortSignal.timeout(timeoutMs), rejectUnauthorized: true,
+        // Do not let a hosts-file/DNS override turn the localhost exception into remote trust.
+        hostname: hostname.replace(/^localhost$/, '127.0.0.1'),
+        servername: servername ?? (hostname === 'localhost' ? 'localhost' : undefined),
+        ...trust,
+    };
+    return new Promise(resolve => {
+        const receive = (response) => { response.resume(); resolve(response.statusCode === 200); };
+        const get = target.protocol === 'https:' ? httpsGet : httpGet;
+        get(target, options, receive).once('error', () => resolve(false));
+    });
+}
+//# sourceMappingURL=local-http-probe.js.map

package/dist/secrets/credential-sets/index.d.ts

@@ -4,5 +4,6 @@ export { buildVaultAad } from "./vault.aad.js";
 export { createVaultMetaParsers, isCopyableKind } from "./vault.meta.js";
 export { SecretsVaultService, type VaultServiceDeps, type VaultPutInput, type VaultCopyInput } from "./vault.service.js";
 export { InMemoryVaultRepo } from "./vault.repo.memory.js";
+export { captureVaultArchive, prepareVaultArchiveRestore, type VaultArchiveEntry } from "./vault-archive.js";
 export { matchingCredentialProviderIds, selectCredentialForProvider, suggestCredentialWorksFor, normalizeCredentialWorksFor, type CredentialProviderDescriptor, type MatchableCredential } from "./provider-matches.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/secrets/credential-sets/index.js

@@ -3,5 +3,6 @@ export { buildVaultAad } from "./vault.aad.js";
 export { createVaultMetaParsers, isCopyableKind } from "./vault.meta.js";
 export { SecretsVaultService } from "./vault.service.js";
 export { InMemoryVaultRepo } from "./vault.repo.memory.js";
+export { captureVaultArchive, prepareVaultArchiveRestore } from "./vault-archive.js";
 export { matchingCredentialProviderIds, selectCredentialForProvider, suggestCredentialWorksFor, normalizeCredentialWorksFor } from "./provider-matches.js";
 //# sourceMappingURL=index.js.map

package/dist/secrets/credential-sets/vault-archive.d.ts

@@ -0,0 +1,41 @@
+import type { SecretsVaultService } from "./vault.service.js";
+import { type VaultKind, type VaultMeta, type VaultOptions, type VaultPutRecord, type VaultQuery, type VaultRepoPort } from "./vault.types.js";
+/** Logical transport only: source workspace, root keys, envelopes and revision history never travel. */
+export interface VaultArchiveEntry {
+    id: string;
+    kind: VaultKind;
+    ownerKey: string;
+    binding: string | null;
+    provider: string | null;
+    label: string;
+    isDefault: boolean;
+    meta: VaultMeta;
+    payload: VaultMeta | null;
+}
+/** Capture through the owning service's authorization and parsers. Hosts supply exact scopes and
+ * attachment-filtered repositories; this helper never discovers other workspaces or principals.
+ * Diagnostics contain only a count, because even labels/IDs may contain pasted secrets.
+ * @example const captured = await captureVaultArchive({ vault, repo, queries: [siteScope] });
+ * @complexity O(rows + payload bytes), bounded to 2,000 rows by the transport contract.
+ */
+export declare function captureVaultArchive({ vault, queries, repo }: {
+    vault: SecretsVaultService;
+    queries: readonly VaultQuery[];
+    repo?: Pick<VaultRepoPort, "list">;
+}, _options?: VaultOptions): Promise<{
+    entries: VaultArchiveEntry[];
+    notices: string[];
+}>;
+/** Validate and re-seal every entry before the host atomically commits any of them. Keeping the
+ * transaction in the host lets settings and vault rows join the same commit. Never call put in a
+ * loop: a bad later entry must leave the recipient completely unchanged.
+ * @throws VaultError or the host's policy error; callers expose a fixed optional-import notice.
+ * @example const records = await prepareVaultArchiveRestore({ vault, workspaceId, entries });
+ * @complexity O(entries + payload bytes), at most 2,000 entries.
+ */
+export declare function prepareVaultArchiveRestore({ vault, workspaceId, entries }: {
+    vault: SecretsVaultService;
+    workspaceId: string;
+    entries: readonly VaultArchiveEntry[];
+}, _options?: VaultOptions): Promise<VaultPutRecord[]>;
+//# sourceMappingURL=vault-archive.d.ts.map

package/dist/secrets/credential-sets/vault-archive.js

@@ -0,0 +1,64 @@
+import { VaultError, isInVaultQueryScope } from "./vault.types.js";
+function assertPortable(kind, principalId) {
+    // Personal and MCP credentials require their own identity/configuration transport, outside v1.
+    if (principalId !== null || ["personal-execution", "mcp-env", "mcp-auth"].includes(kind))
+        throw new VaultError({ code: "context" });
+}
+/** Capture through the owning service's authorization and parsers. Hosts supply exact scopes and
+ * attachment-filtered repositories; this helper never discovers other workspaces or principals.
+ * Diagnostics contain only a count, because even labels/IDs may contain pasted secrets.
+ * @example const captured = await captureVaultArchive({ vault, repo, queries: [siteScope] });
+ * @complexity O(rows + payload bytes), bounded to 2,000 rows by the transport contract.
+ */
+export async function captureVaultArchive({ vault, queries, repo }, _options = {}) {
+    const entries = [];
+    let omitted = 0, count = 0;
+    for (const query of queries) {
+        assertPortable(query.kind, query.principalId);
+        // Optional raw enumeration isolates unsupported metadata; every payload still passes get's
+        // exact identity, authorization, parser and AAD checks before it can enter the result.
+        for (const row of await (repo ?? vault).list(query)) {
+            if (++count > 2000)
+                throw new VaultError({ code: "invalid-record" });
+            try {
+                if (!isInVaultQueryScope({ record: row, query }))
+                    throw new VaultError({ code: "context" });
+                const found = await vault.get(row);
+                if (!found)
+                    throw new VaultError({ code: "conflict" });
+                const s = found.summary;
+                entries.push({ id: s.id, kind: s.kind, ownerKey: s.ownerKey, binding: s.binding, provider: s.provider,
+                    label: s.label, isDefault: s.isDefault, meta: s.meta, payload: found.payload });
+            }
+            catch {
+                omitted++;
+            }
+        }
+    }
+    return { entries, notices: omitted ? [`${omitted} saved credential(s) could not be opened and were left out.`] : [] };
+}
+/** Validate and re-seal every entry before the host atomically commits any of them. Keeping the
+ * transaction in the host lets settings and vault rows join the same commit. Never call put in a
+ * loop: a bad later entry must leave the recipient completely unchanged.
+ * @throws VaultError or the host's policy error; callers expose a fixed optional-import notice.
+ * @example const records = await prepareVaultArchiveRestore({ vault, workspaceId, entries });
+ * @complexity O(entries + payload bytes), at most 2,000 entries.
+ */
+export async function prepareVaultArchiveRestore({ vault, workspaceId, entries }, _options = {}) {
+    if (!Array.isArray(entries) || entries.length > 2000)
+        throw new VaultError({ code: "invalid-record" });
+    const ids = new Set();
+    const records = [];
+    for (const entry of entries) {
+        assertPortable(entry.kind, null);
+        if (ids.has(entry.id))
+            throw new VaultError({ code: "invalid-record" });
+        ids.add(entry.id);
+        // Enumerating fields prevents an archive from supplying a revision, principal or workspace.
+        records.push(await vault.prepare({ workspaceId, id: entry.id, kind: entry.kind, ownerKey: entry.ownerKey,
+            principalId: null, binding: entry.binding, provider: entry.provider, label: entry.label,
+            isDefault: entry.isDefault, meta: entry.meta, payload: entry.payload, expectedRevision: null }));
+    }
+    return records;
+}
+//# sourceMappingURL=vault-archive.js.map

package/dist/secrets/credential-sets/vault.types.d.ts

@@ -155,7 +155,7 @@ export interface VaultRepoPort {
 /** The record belongs to the query's exact workspace, kind, owner and principal; an omitted provider
  * matches every provider. @complexity O(1). */
 export declare function isInVaultQueryScope({ record, query }: {
-    record: VaultRecord;
+    record: Pick<VaultRecord, keyof VaultQuery>;
     query: VaultQuery;
 }, _options?: VaultOptions): boolean;
 /** Unambiguous scope encoding keeps adapter default/identity checks on the same contract. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/platform",
-  "version": "0.6.15",
+  "version": "0.6.16",
   "description": "Generic OS/platform primitives: process exec and lifecycle, filesystem containment, HTTP readiness polling, toolchain discovery, blob storage, AWS signing, and an SSRF-safe asset cache.",
   "license": "Apache-2.0",
   "repository": {
@@ -55,6 +55,13 @@
         "src/fetch-with-timeout.ts",
         "src/http/guarded/errors.ts"
       ]
+    },
+    "optionalPeers": {
+      "hast-util-from-parse5": "opt-in: html to markdown conversion; import @jini-ai/platform/web — HTML to Markdown conversion could not load hast-util-from-parse5. Install hast-util-from-parse5 to enable this feature, or check its installed version and native binaries.",
+      "hast-util-to-mdast": "opt-in: html to markdown conversion; import @jini-ai/platform/web — HTML to Markdown conversion could not load hast-util-to-mdast. Install hast-util-to-mdast to enable this feature, or check its installed version and native binaries.",
+      "mdast-util-to-markdown": "opt-in: html to markdown conversion; import @jini-ai/platform/web — HTML to Markdown conversion could not load mdast-util-to-markdown. Install mdast-util-to-markdown to enable this feature, or check its installed version and native binaries.",
+      "mdast-util-gfm-table": "opt-in: markdown table conversion; import @jini-ai/platform/web — Markdown table conversion could not load mdast-util-gfm-table. Install mdast-util-gfm-table to enable this feature, or check its installed version and native binaries.",
+      "parse5": "opt-in: html parsing; import @jini-ai/platform/web — HTML parsing could not load parse5. Install parse5 to enable this feature, or check its installed version and native binaries."
     }
   },
   "type": "module",
@@ -206,7 +213,8 @@
     "!dist/**/*.map"
   ],
   "dependencies": {
-    "@jini-ai/core": "^0.6.13"
+    "@jini-ai/core": "^0.6.13",
+    "undici": "^7.25.0"
   },
   "publishConfig": {
     "access": "public",
@@ -223,7 +231,6 @@
     "fast-check": "4.3.0"
   },
   "peerDependencies": {
-    "undici": "^7.25.0",
     "hast-util-from-parse5": "8.0.3",
     "hast-util-to-mdast": "10.1.2",
     "mdast-util-to-markdown": "2.1.2",
@@ -231,9 +238,6 @@
     "parse5": "7.3.0"
   },
   "peerDependenciesMeta": {
-    "undici": {
-      "optional": true
-    },
     "hast-util-from-parse5": {
       "optional": true
     },