@abot-ai/runtime 1.3.0 → 1.4.0

package/dist/src/runtime/plugins/loader.js

@@ -1,6 +1,6 @@
-import { realpathSync } from "node:fs";
+import { validateManifestEntrypoint } from "./entrypoint-validation.js";
 import { createRequire } from "node:module";
-import { join, resolve } from "node:path";
+import { join } from "node:path";
 import { createRuntimeToolPathResolver } from "../capabilities/runtime-target-path.js";
 import { validateToolModuleDeclarations } from "../../capabilities/tool-definition-validator.js";
 import { traceDebug } from "../observability/debug-logger.js";
@@ -8,42 +8,11 @@ import { ABOT_RUNTIME_EXTENSION } from "../../plugin-contract/manifest.js";
 import { discoverAgentPluginManifests } from "./manifest-discovery.js";
 import { resolveBundledRuntimeRoot } from "./bundled-root.js";
 import { projectManifestRuntimeContract } from "./manifest-projection.js";
+import { discoverConfiguredRuntimePluginManifests } from "./configured-manifests.js";
+import { isPluginCatalogDisabled, isPluginToolSelected, normalizePluginSelection, pluginSelectionCacheKey, } from "./selection.js";
 const require = createRequire(import.meta.url);
 const compiledCatalogCache = new WeakMap();
 const bundledCatalogCache = new Map();
-function uniqueSorted(values) {
-    return [
-        ...new Set((values ?? [])
-            .map((value) => value.trim())
-            .filter((value) => value.length > 0)),
-    ].sort((left, right) => left.localeCompare(right));
-}
-function normalizePluginSelection(config) {
-    return Object.freeze({
-        enabled: config?.enabled !== false,
-        allow: Object.freeze(uniqueSorted(config?.allow)),
-        deny: Object.freeze(uniqueSorted(config?.deny)),
-    });
-}
-function pluginSelectionCacheKey(selection) {
-    return JSON.stringify([selection.enabled, selection.allow, selection.deny]);
-}
-function matchesPluginToolId(pluginId, toolName, configuredId) {
-    return (configuredId === "*" ||
-        configuredId === pluginId ||
-        configuredId === toolName ||
-        configuredId === `${pluginId}.${toolName}`);
-}
-function isPluginToolSelected(params) {
-    if (!params.selection.enabled) {
-        return false;
-    }
-    if (params.selection.allow.length > 0 &&
-        !params.selection.allow.some((entry) => matchesPluginToolId(params.pluginId, params.toolName, entry))) {
-        return false;
-    }
-    return !params.selection.deny.some((entry) => matchesPluginToolId(params.pluginId, params.toolName, entry));
-}
 function isRecord(value) {
     return !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -61,64 +30,12 @@ function unwrapPluginExport(rawModule) {
 function compiledCapabilityFromDeclaration(tool) {
     return {
         execute: tool.implementation,
+        ...(tool.prepareRequest ? { prepareRequest: tool.prepareRequest } : {}),
         ...(tool.adapter ? { adapter: tool.adapter } : {}),
         definition: tool.definition,
         normalInvocation: tool.normalInvocation,
     };
 }
-function validateManifestEntrypoint(params) {
-    if (!isRecord(params.raw) || !isRecord(params.raw.handlers)) {
-        throw new Error(`Runtime plugin ${params.pluginId} entrypoint must export handlers`);
-    }
-    const unexpectedEntrypointKeys = Object.keys(params.raw).filter((key) => key !== "handlers" && key !== "adapters");
-    if (unexpectedEntrypointKeys.length > 0) {
-        throw new Error(`Runtime plugin ${params.pluginId} entrypoint contains unsupported field ${unexpectedEntrypointKeys[0]}`);
-    }
-    const handlers = {};
-    for (const [capabilityId, handler] of Object.entries(params.raw.handlers)) {
-        if (typeof handler !== "function") {
-            throw new Error(`Runtime plugin ${params.pluginId} handler ${capabilityId} must be a function`);
-        }
-        handlers[capabilityId] = handler;
-    }
-    const expected = new Set(params.expectedCapabilityIds);
-    const missing = params.expectedCapabilityIds.filter((capabilityId) => !handlers[capabilityId]);
-    const unexpected = Object.keys(handlers).filter((capabilityId) => !expected.has(capabilityId));
-    if (missing.length > 0 || unexpected.length > 0) {
-        throw new Error(`Runtime plugin ${params.pluginId} handler mismatch: missing=${missing.join(",") || "none"}; unexpected=${unexpected.join(",") || "none"}`);
-    }
-    const adapters = {};
-    if (params.raw.adapters !== undefined) {
-        if (!isRecord(params.raw.adapters)) {
-            throw new Error(`Runtime plugin ${params.pluginId} entrypoint adapters must be an object`);
-        }
-        for (const [capabilityId, rawAdapter] of Object.entries(params.raw.adapters)) {
-            if (!expected.has(capabilityId)) {
-                throw new Error(`Runtime plugin ${params.pluginId} adapter ${capabilityId} has no declared capability`);
-            }
-            if (!isRecord(rawAdapter)) {
-                throw new Error(`Runtime plugin ${params.pluginId} adapter ${capabilityId} must be an object`);
-            }
-            const unexpectedAdapterKeys = Object.keys(rawAdapter).filter((key) => key !== "normalizeCall" && key !== "validateCall");
-            if (unexpectedAdapterKeys.length > 0) {
-                throw new Error(`Runtime plugin ${params.pluginId} adapter ${capabilityId} contains unsupported field ${unexpectedAdapterKeys[0]}`);
-            }
-            if (rawAdapter.normalizeCall !== undefined &&
-                typeof rawAdapter.normalizeCall !== "function") {
-                throw new Error(`Runtime plugin ${params.pluginId} adapter ${capabilityId}.normalizeCall must be a function`);
-            }
-            if (rawAdapter.validateCall !== undefined &&
-                typeof rawAdapter.validateCall !== "function") {
-                throw new Error(`Runtime plugin ${params.pluginId} adapter ${capabilityId}.validateCall must be a function`);
-            }
-            adapters[capabilityId] = rawAdapter;
-        }
-    }
-    return {
-        handlers,
-        ...(Object.keys(adapters).length > 0 ? { adapters } : {}),
-    };
-}
 function createManifestSecretAccessor(pluginId, declarations) {
     if (!declarations || Object.keys(declarations).length === 0) {
         return undefined;
@@ -180,6 +97,9 @@ function loadManifestRuntimePlugin(host, discovered, selectedCapabilityIds) {
         definition,
         normalInvocation,
         implementation: entrypoint.handlers[definition.name],
+        ...(entrypoint.prepareRequest
+            ? { prepareRequest: entrypoint.prepareRequest }
+            : {}),
         ...(entrypoint.adapters?.[definition.name]
             ? { adapter: entrypoint.adapters[definition.name] }
             : {}),
@@ -201,42 +121,9 @@ function loadManifestRuntimePlugin(host, discovered, selectedCapabilityIds) {
         capabilitySkills: projection.capabilitySkills,
     };
 }
-function canonicalPluginDiscoveryRoot(rootDir) {
-    const absoluteRoot = resolve(rootDir);
-    try {
-        return realpathSync(absoluteRoot);
-    }
-    catch (error) {
-        if (error.code !== "ENOENT") {
-            throw error;
-        }
-        return absoluteRoot;
-    }
-}
-function assertUniquePluginManifestIds(plugins) {
-    const manifestPathsByPluginId = new Map();
-    for (const plugin of plugins) {
-        const pluginId = plugin.manifest.name;
-        const previousManifestPath = manifestPathsByPluginId.get(pluginId);
-        if (previousManifestPath) {
-            throw new Error(`Duplicate runtime plugin id: ${pluginId}; manifests: ${previousManifestPath}, ${plugin.manifestPath}`);
-        }
-        manifestPathsByPluginId.set(pluginId, plugin.manifestPath);
-    }
-}
-function discoverConfiguredRuntimePluginManifests(consumerRoot) {
-    const bundledRoot = resolveBundledRuntimeRoot();
-    const roots = canonicalPluginDiscoveryRoot(bundledRoot) ===
-        canonicalPluginDiscoveryRoot(consumerRoot)
-        ? [consumerRoot]
-        : [bundledRoot, consumerRoot];
-    const plugins = roots.flatMap((rootDir) => discoverAgentPluginManifests(rootDir));
-    assertUniquePluginManifestIds(plugins);
-    return Object.freeze(plugins);
-}
 export function loadConfiguredRuntimePlugins(config) {
     const selection = normalizePluginSelection(config.plugins);
-    if (!selection.enabled) {
+    if (isPluginCatalogDisabled(selection)) {
         return [];
     }
     const cacheKey = pluginSelectionCacheKey(selection);
@@ -251,7 +138,7 @@ export function loadConfiguredRuntimePlugins(config) {
         agentBridgeUrl: config.agentBridgeUrl,
         runtimePaths: config.paths,
     };
-    const manifestPlugins = discoverConfiguredRuntimePluginManifests(config.paths.rootDir)
+    const manifestPlugins = discoverConfiguredRuntimePluginManifests(config.paths.rootDir, { excludedPluginIds: new Set(selection.deny) })
         .map((plugin) => ({
         plugin,
         selectedCapabilityIds: Object.keys(plugin.manifest.extensions[ABOT_RUNTIME_EXTENSION].capabilities).filter((capabilityId) => isPluginToolSelected({
@@ -330,6 +217,7 @@ export function runtimePluginsToToolModules(plugins) {
 function toolModuleDeclarationFromRuntimePlugin(tool) {
     return {
         implementation: tool.execute,
+        ...(tool.prepareRequest ? { prepareRequest: tool.prepareRequest } : {}),
         ...(tool.adapter ? { adapter: tool.adapter } : {}),
         definition: tool.definition,
         normalInvocation: tool.normalInvocation,

package/dist/src/runtime/plugins/manifest-discovery.d.ts

@@ -1,8 +1,11 @@
 import type { DiscoveredAgentPluginManifest } from "./discovered-manifest.js";
+export type AgentPluginManifestDiscoveryOptions = Readonly<{
+    excludedPluginIds?: ReadonlySet<string>;
+}>;
 export declare function resolveContainedPluginFile(params: {
     pluginRoot: string;
     configuredPath: string;
     label: string;
 }): string;
 export declare function readAgentPluginSkills(plugin: DiscoveredAgentPluginManifest, selectedSkillNames?: ReadonlySet<string>): Record<string, string>;
-export declare function discoverAgentPluginManifests(rootDir: string): DiscoveredAgentPluginManifest[];
+export declare function discoverAgentPluginManifests(rootDir: string, options?: AgentPluginManifestDiscoveryOptions): DiscoveredAgentPluginManifest[];

package/dist/src/runtime/plugins/manifest-discovery.js

@@ -2,6 +2,9 @@ import { existsSync, readFileSync, readdirSync, realpathSync, statSync, } from "
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { traceDebug } from "../observability/debug-logger.js";
 import { parseAgentPluginManifest } from "./manifest-validator.js";
+function isPluginManifestExcluded(pluginId, options) {
+    return options.excludedPluginIds?.has(pluginId) ?? false;
+}
 function isContained(root, candidate) {
     const relativePath = relative(root, candidate);
     return (relativePath === "" ||
@@ -62,7 +65,7 @@ export function readAgentPluginSkills(plugin, selectedSkillNames) {
     }
     return skills;
 }
-export function discoverAgentPluginManifests(rootDir) {
+export function discoverAgentPluginManifests(rootDir, options = {}) {
     const pluginsPath = resolve(rootDir, "plugins");
     traceDebug("runtime.plugins", "manifest_discovery.started", {
         pluginsPath,
@@ -80,6 +83,10 @@ export function discoverAgentPluginManifests(rootDir) {
     }).sort((left, right) => left.name.localeCompare(right.name));
     const discovered = [];
     for (const entry of entries) {
+        // A valid manifest must use its directory name as the plugin ID. An
+        // explicitly denied package needs no filesystem traversal or validation.
+        if (isPluginManifestExcluded(entry.name, options))
+            continue;
         const candidateRoot = join(resolvedPluginsPath, entry.name);
         if (!statSync(candidateRoot).isDirectory()) {
             continue;

package/dist/src/runtime/plugins/manifest-projection.js

@@ -40,6 +40,9 @@ export function projectManifestRuntimeContract(discovered, selectedCapabilityIds
         declarations.push({
             definition: {
                 name: capabilityId,
+                ...(capability.requiredPermissionMode
+                    ? { requiredPermissionMode: capability.requiredPermissionMode }
+                    : {}),
                 description: capability.description,
                 routingCapability: capability.routingCapability,
                 ...(capability.controlsRefinement

package/dist/src/runtime/plugins/manifest-validator.js

@@ -1,5 +1,7 @@
+import { parseRequiredToolPermissionMode } from "../../capabilities/tool-permission-mode.js";
 import { isToolCatalogGroupId } from "../../capabilities/tool-types.js";
 import { parseEventResultMetadata } from "../../capabilities/tool-definition-validator/event-result-metadata.js";
+import { parseEventInputTextOptions } from "../../capabilities/tool-definition-validator/event-input-text-options.js";
 import { ABOT_RUNTIME_EXTENSION, ABOT_RUNTIME_EXTENSION_VERSION, AGENT_PLUGIN_MANIFEST_SCHEMA, } from "../../plugin-contract/manifest.js";
 const PLUGIN_NAME_PATTERN = /^(?!.*(?:--|\.\.))[a-z0-9][a-z0-9.-]{0,62}[a-z0-9]$|^[a-z0-9]$/u;
 const SECRET_ENV_PATTERN = /^[A-Z][A-Z0-9_]*$/u;
@@ -20,6 +22,7 @@ const DEVELOPMENT_ROLES = [
 const EVENT_PROJECTION_KINDS = [
     "string",
     "number",
+    "boolean",
     "string_array",
     "length",
 ];
@@ -211,7 +214,7 @@ function parseEventPresentation(value, path) {
                 throw new Error(`${path}.metadata contains an empty key`);
             }
             const projection = expectRecord(rawProjection, `${path}.metadata.${key}`);
-            rejectUnknownKeys(projection, ["param", "kind", "default"], `${path}.metadata.${key}`);
+            rejectUnknownKeys(projection, ["param", "kind", "default", "maxLength", "preserveWhitespace"], `${path}.metadata.${key}`);
             if (!nonEmptyString(projection.param)) {
                 throw new Error(`${path}.metadata.${key}.param must be non-empty`);
             }
@@ -228,6 +231,7 @@ function parseEventPresentation(value, path) {
             return [
                 key,
                 {
+                    ...parseEventInputTextOptions(projection, `${path}.metadata.${key}`),
                     param: projection.param.trim(),
                     kind: projection.kind,
                     ...(fallback !== undefined ? { default: fallback } : {}),
@@ -349,6 +353,7 @@ function parseCapabilities(value, path) {
         }
         const capability = expectRecord(rawCapability, `${path}.${capabilityId}`);
         rejectUnknownKeys(capability, [
+            "requiredPermissionMode",
             "description",
             "routingCapability",
             "controlsRefinement",
@@ -393,6 +398,7 @@ function parseCapabilities(value, path) {
         return [
             capabilityId,
             {
+                requiredPermissionMode: parseRequiredToolPermissionMode(capability.requiredPermissionMode, `${path}.${capabilityId}.requiredPermissionMode`),
                 description: capability.description.trim(),
                 routingCapability: capability.routingCapability,
                 ...(controlsRefinement === "mechanical_when_complete"

package/dist/src/runtime/plugins/runtime-capability-plugins.d.ts

@@ -0,0 +1,4 @@
+import type { RuntimeConfig } from "../ports.js";
+import type { CompiledRuntimePlugin } from "./compiled-catalog.js";
+/** Tools and skills share the same selected catalog and compiled instances. */
+export declare function loadRuntimeCapabilityPlugins(config?: RuntimeConfig): readonly CompiledRuntimePlugin[];

package/dist/src/runtime/plugins/runtime-capability-plugins.js

@@ -0,0 +1,7 @@
+import { loadBundledRuntimePlugins, loadConfiguredRuntimePlugins, } from "./loader.js";
+/** Tools and skills share the same selected catalog and compiled instances. */
+export function loadRuntimeCapabilityPlugins(config) {
+    return config
+        ? loadConfiguredRuntimePlugins(config)
+        : loadBundledRuntimePlugins();
+}

package/dist/src/runtime/plugins/selection.d.ts

@@ -0,0 +1,14 @@
+import type { RuntimePluginConfig } from "../ports.js";
+export type PluginSelection = Readonly<{
+    enabled: boolean;
+    allow: readonly string[];
+    deny: readonly string[];
+}>;
+export declare function normalizePluginSelection(config: RuntimePluginConfig | undefined): PluginSelection;
+export declare function pluginSelectionCacheKey(selection: PluginSelection): string;
+export declare function isPluginCatalogDisabled(selection: PluginSelection): boolean;
+export declare function isPluginToolSelected(params: {
+    pluginId: string;
+    toolName: string;
+    selection: PluginSelection;
+}): boolean;

package/dist/src/runtime/plugins/selection.js

@@ -0,0 +1,38 @@
+function uniqueSorted(values) {
+    return [
+        ...new Set((values ?? [])
+            .map((value) => value.trim())
+            .filter((value) => value.length > 0)),
+    ].sort((left, right) => left.localeCompare(right));
+}
+export function normalizePluginSelection(config) {
+    return Object.freeze({
+        enabled: config?.enabled !== false,
+        allow: Object.freeze(uniqueSorted(config?.allow)),
+        deny: Object.freeze(uniqueSorted(config?.deny)),
+    });
+}
+export function pluginSelectionCacheKey(selection) {
+    return JSON.stringify([selection.enabled, selection.allow, selection.deny]);
+}
+export function isPluginCatalogDisabled(selection) {
+    if (!selection.enabled)
+        return true;
+    return selection.deny.includes("*");
+}
+function matchesPluginToolId(pluginId, toolName, configuredId) {
+    return (configuredId === "*" ||
+        configuredId === pluginId ||
+        configuredId === toolName ||
+        configuredId === `${pluginId}.${toolName}`);
+}
+export function isPluginToolSelected(params) {
+    if (!params.selection.enabled) {
+        return false;
+    }
+    if (params.selection.allow.length > 0 &&
+        !params.selection.allow.some((entry) => matchesPluginToolId(params.pluginId, params.toolName, entry))) {
+        return false;
+    }
+    return !params.selection.deny.some((entry) => matchesPluginToolId(params.pluginId, params.toolName, entry));
+}

package/dist/src/runtime/ports.d.ts

@@ -1,4 +1,5 @@
 import type WebSocket from "ws";
+import type { SessionCreationOptions } from "../sessions/project-binding.js";
 import type { AgentMode, ModelReasoningLevel, ModelStep } from "../shared/types.js";
 import type { ContextBuckets, ModelContextMessage } from "../sessions/context-window.js";
 import type { SessionArtifactPathInput, SessionContextEntryKind, SessionDeleteResult, SessionListResult, SessionMessageDeleteResult, SessionMessageGrounding, SessionMessageObservationMeta, SessionMessageRole, SessionMessageSource, SessionMessageTaskType, SessionMessagesClearResult, SessionRecord, SessionRequestReplay, SessionSnapshot, SessionThinkingTraceEntry } from "../sessions/types.js";
@@ -111,7 +112,7 @@ export type AppendSessionContextEntryOptions = {
     requestId?: string;
 };
 export type SessionStore = SessionMemoryRepository & {
-    getOrCreateSession: (sessionId: string) => Promise<SessionRecord>;
+    getOrCreateSession: (sessionId: string, options?: SessionCreationOptions) => Promise<SessionRecord>;
     getAllSessions: () => Promise<SessionRecord[]>;
     listSessions: (params?: {
         limit?: number;
@@ -147,11 +148,14 @@ export type ConversationContextProvider = {
     buildContextWindow: (session: SessionRecord, maxMessages?: number) => ModelContextMessage[];
 };
 export type ToolExecutionOptions = {
+    /** Trusted request snapshot, never parsed from a model tool payload. */
+    requestWorkingDirectory?: string;
     abortSignal?: AbortSignal;
     sharedState?: ToolExecutionContext["sharedState"];
     modelInvoker?: ToolExecutionContext["modelInvoker"];
+    reportFileOutput?: ToolExecutionContext["reportFileOutput"];
 };
-export type ToolPermissionMode = "full_access" | "ask";
+export type { ToolPermissionMode } from "../capabilities/tool-permission-mode.js";
 export type ToolApprovalRequest = {
     requestId: string;
     approvalId: string;
@@ -168,6 +172,8 @@ export type ToolApprovalController = {
     }) => Promise<ToolApprovalDecision>;
 };
 export type ToolRegistry = {
+    /** Build an isolated availability/execution snapshot before model projection. */
+    prepareRequest?: () => Promise<ToolRegistry>;
     listDefinitions: () => ToolDefinition[];
     /** The sole config-filtered availability snapshot for ordinary invocation. */
     listNormalInvocations?: () => readonly RegisteredToolNormalInvocation[];

package/dist/src/runtime/projects/contracts.d.ts

@@ -0,0 +1,40 @@
+import type { SessionProject } from "../../sessions/project-binding.js";
+export type RuntimeProject = SessionProject & Readonly<{
+    createdAt: string;
+}>;
+export type ProjectFolder = Readonly<{
+    name: string;
+    path: string;
+}>;
+export type ProjectFolderPage = Readonly<{
+    directory: string;
+    parent: string | null;
+    entries: readonly ProjectFolder[];
+    nextCursor: string | null;
+    roots: readonly Readonly<{
+        label: string;
+        path: string;
+    }>[];
+    hostPlatform: NodeJS.Platform;
+}>;
+export type RuntimeProjectService = Readonly<{
+    list: () => Promise<readonly RuntimeProject[]>;
+    get: (id: string) => Promise<RuntimeProject | null>;
+    create: (input: {
+        name?: string;
+        directory: string;
+    }) => Promise<RuntimeProject>;
+    browseFolders: (input?: {
+        path?: string;
+        cursor?: string;
+    }) => Promise<ProjectFolderPage>;
+    createSession: (projectId: string) => Promise<{
+        sessionId: string;
+        project: SessionProject;
+    }>;
+}>;
+export declare class ProjectOperationError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status?: number);
+}

package/dist/src/runtime/projects/contracts.js

@@ -0,0 +1,10 @@
+export class ProjectOperationError extends Error {
+    code;
+    status;
+    constructor(code, message, status = 400) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "ProjectOperationError";
+    }
+}

package/dist/src/runtime/projects/folders.d.ts

@@ -0,0 +1,7 @@
+import { type ProjectFolderPage } from "./contracts.js";
+export declare function resolveProjectDirectory(input: string): Promise<string>;
+export declare function browseProjectFolders(defaultDirectory: string, input?: {
+    path?: string;
+    cursor?: string;
+}): Promise<ProjectFolderPage>;
+export declare function projectDisplayName(input: string | undefined, directory: string): string;

package/dist/src/runtime/projects/folders.js

@@ -0,0 +1,110 @@
+import { homedir } from "node:os";
+import { readdir, realpath, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, parse } from "node:path";
+import { ProjectOperationError } from "./contracts.js";
+function isAbsoluteProjectDirectory(input) {
+    if (typeof input !== "string")
+        return false;
+    if (!input.trim())
+        return false;
+    return isAbsolute(input);
+}
+export async function resolveProjectDirectory(input) {
+    if (!isAbsoluteProjectDirectory(input))
+        throw new ProjectOperationError("project_directory_absolute_required", "Choose an absolute folder path on this Runtime host.");
+    if (input.includes("\0"))
+        throw new ProjectOperationError("project_directory_invalid", "The folder path is invalid.");
+    try {
+        const canonical = await realpath(input);
+        if (!(await directoryExists(canonical)))
+            throw new ProjectOperationError("project_directory_required", "Choose a directory.");
+        return canonical;
+    }
+    catch (error) {
+        if (error instanceof ProjectOperationError)
+            throw error;
+        throw new ProjectOperationError("project_directory_unavailable", "This folder is unavailable to the Runtime host.", 404);
+    }
+}
+async function directoryExists(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function isProjectDirectoryEntry(child, path) {
+    if (child.isDirectory())
+        return true;
+    if (!child.isSymbolicLink())
+        return false;
+    return directoryExists(path);
+}
+function resolveFolderPageStart(names, cursor) {
+    if (!cursor)
+        return 0;
+    const index = names.indexOf(cursor);
+    if (index < 0)
+        throw new ProjectOperationError("project_folder_cursor_stale", "Folder contents changed. Browse this folder again.", 409);
+    return index + 1;
+}
+async function initialProjectBrowserDirectory(defaultDirectory, selected) {
+    if (selected)
+        return resolveProjectDirectory(selected);
+    if (await directoryExists(defaultDirectory))
+        return resolveProjectDirectory(defaultDirectory);
+    return resolveProjectDirectory(homedir());
+}
+export async function browseProjectFolders(defaultDirectory, input = {}) {
+    const directory = await initialProjectBrowserDirectory(defaultDirectory, input.path);
+    const roots = [
+        { label: "Default workspace", path: defaultDirectory },
+        { label: "Home", path: homedir() },
+        { label: "Desktop", path: join(homedir(), "Desktop") },
+        { label: "Filesystem", path: parse(directory).root },
+    ];
+    const availableRoots = [];
+    for (const root of roots) {
+        if (await directoryExists(root.path))
+            availableRoots.push(root);
+    }
+    let children;
+    try {
+        children = await readdir(directory, { withFileTypes: true });
+    }
+    catch {
+        throw new ProjectOperationError("project_directory_unreadable", "The Runtime host cannot list this folder.", 403);
+    }
+    const folders = [];
+    for (const child of children) {
+        const path = join(directory, child.name);
+        if (await isProjectDirectoryEntry(child, path))
+            folders.push({ name: child.name, path });
+    }
+    folders.sort((left, right) => left.name.localeCompare(right.name));
+    const start = resolveFolderPageStart(folders.map((folder) => folder.name), input.cursor);
+    const entries = folders.slice(start, start + 100);
+    const parent = dirname(directory);
+    return {
+        directory,
+        parent: parent === directory ? null : parent,
+        entries,
+        nextCursor: start + entries.length < folders.length ? entries.at(-1).name : null,
+        roots: availableRoots,
+        hostPlatform: process.platform,
+    };
+}
+function isProjectDisplayName(name) {
+    if (!name)
+        return false;
+    if (name.length > 120)
+        return false;
+    return !/[\u0000-\u001f]/.test(name);
+}
+export function projectDisplayName(input, directory) {
+    const name = input?.trim() || basename(directory) || directory;
+    if (!isProjectDisplayName(name))
+        throw new ProjectOperationError("project_name_invalid", "Choose a project name of 1 to 120 characters.");
+    return name;
+}

package/dist/src/runtime/projects/repository.d.ts

@@ -0,0 +1,10 @@
+import type { RuntimeProject } from "./contracts.js";
+/** One environment owner serializes updates; rename publishes a complete registry. */
+export declare class FileProjectRepository {
+    private readonly filename;
+    private tail;
+    constructor(filename: string);
+    list(): Promise<RuntimeProject[]>;
+    create(project: RuntimeProject): Promise<RuntimeProject>;
+    private save;
+}

package/dist/src/runtime/projects/repository.js

@@ -0,0 +1,54 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { copySessionProject } from "../../sessions/project-binding.js";
+/** One environment owner serializes updates; rename publishes a complete registry. */
+export class FileProjectRepository {
+    filename;
+    tail = Promise.resolve();
+    constructor(filename) {
+        this.filename = filename;
+    }
+    async list() {
+        try {
+            const input = JSON.parse(await readFile(this.filename, "utf8"));
+            if (!Array.isArray(input))
+                throw new Error("project_registry_invalid");
+            return input.map((entry) => {
+                const project = copySessionProject(entry);
+                if (typeof entry.createdAt !== "string")
+                    throw new Error("project_registry_created_at_invalid");
+                return { ...project, createdAt: entry.createdAt };
+            });
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        }
+    }
+    create(project) {
+        const result = this.tail.then(async () => {
+            const projects = await this.list();
+            const existing = projects.find((entry) => entry.directory === project.directory);
+            if (existing)
+                return existing;
+            await this.save([...projects, project]);
+            return project;
+        });
+        this.tail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    async save(projects) {
+        await mkdir(dirname(this.filename), { recursive: true });
+        const temporary = `${this.filename}.${process.pid}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporary, JSON.stringify(projects, null, 2), "utf8");
+            await rename(temporary, this.filename);
+        }
+        catch (error) {
+            await rm(temporary, { force: true }).catch(() => undefined);
+            throw error;
+        }
+    }
+}

package/dist/src/runtime/projects/service.d.ts

@@ -0,0 +1,3 @@
+import type { RuntimeConfig, SessionStore } from "../ports.js";
+import { type RuntimeProjectService } from "./contracts.js";
+export declare function createRuntimeProjectService(config: RuntimeConfig, sessions: Pick<SessionStore, "getOrCreateSession">): RuntimeProjectService;