@abot-ai/runtime 1.3.0 → 1.4.0

package/dist/src/web-ui/local-runtime/api-router.js

@@ -1,3 +1,15 @@
+import { ProjectRoutes } from "./project-routes.js";
+import { ConversationFileRoutes } from "./conversation-file-routes.js";
+import { ConfigFileConflictError } from "../../runtime/adapters/config-file-transaction.js";
+import { ModelSetupRoutes } from "./model-setup-routes.js";
+import { ModelSetupService } from "./model-setup-service.js";
+import { SetupEmbeddingRoutes } from "./setup-embedding-routes.js";
+import { SetupEmbeddingService } from "./setup-embedding-service.js";
+import { RuntimeSetupRoutes } from "./runtime-setup-routes.js";
+import { RuntimeSetupService } from "./runtime-setup-service.js";
+import { applyAndCompleteRuntimeSetup, pendingRuntimeSetupCatalog, } from "./runtime-setup-completion.js";
+import { PluginManagementRoutes } from "./plugin-management-routes.js";
+import { acceptConfigMutationRequest } from "./config-mutation-request.js";
 import { WebSessionRoutes } from "./session-routes.js";
 import { WebSessionReadStates } from "../session-read-state/service.js";
 import { getRuntimeConfig, getRuntimeConfigSchema, } from "../../runtime/admin/config-control.js";
@@ -21,26 +33,70 @@ export class LocalRuntimeApiRouter {
     options;
     environments;
     requests;
+    conversationFiles;
     attachments = new LocalAttachmentRoutes();
+    setup;
+    modelSetup;
+    setupEmbedding;
+    plugins;
     memoryManagement;
     memoryOnboarding;
     schedules;
     readStates;
     sessions;
+    projects = new ProjectRoutes();
     constructor(options, environments, requests) {
         this.options = options;
         this.environments = environments;
         this.requests = requests;
+        this.conversationFiles = new ConversationFileRoutes(environments, requests, () => this.options.defaultEnvironmentId);
+        this.modelSetup = new ModelSetupRoutes(new ModelSetupService({
+            rootDir: options.rootDir ?? process.cwd(),
+            getConfigPath: () => options.configPath ?? process.env.LLM_RUNTIME_CONFIG_FILE,
+        }));
+        this.setup = new RuntimeSetupRoutes(new RuntimeSetupService({
+            rootDir: options.rootDir ?? process.cwd(),
+            getConfigPath: () => options.configPath ?? process.env.LLM_RUNTIME_CONFIG_FILE,
+            configure: (configPath) => this.environments.configure(configPath),
+            activate: async (_configPath) => {
+                const activation = await this.applyWhenRequestsIdle();
+                if (activation.status === "ready") {
+                    await this.initializeSessionReadState([
+                        options.defaultEnvironmentId,
+                    ]);
+                }
+                return activation;
+            },
+        }));
+        this.setupEmbedding = new SetupEmbeddingRoutes(new SetupEmbeddingService({
+            rootDir: options.rootDir ?? process.cwd(),
+            getConfigPath: () => options.configPath ?? process.env.LLM_RUNTIME_CONFIG_FILE,
+            providerAdapters: options.providerAdapters,
+        }));
+        this.plugins = new PluginManagementRoutes({
+            rootDir: options.rootDir ?? process.cwd(),
+            getConfigPath: () => options.configPath ?? process.env.LLM_RUNTIME_CONFIG_FILE,
+        });
         this.readStates = new WebSessionReadStates((id) => this.environments.get(id));
         this.sessions = new WebSessionRoutes(this.readStates);
         this.schedules = new ScheduleManagementRoutes((id) => this.environments.get(id));
-        this.memoryOnboarding = new LongTermMemoryOnboardingRoutes(createLocalLongTermMemoryOnboardingService({
+        this.memoryOnboarding = new LongTermMemoryOnboardingRoutes(() => createLocalLongTermMemoryOnboardingService({
             rootDir: options.rootDir ?? process.cwd(),
             providerAdapters: options.providerAdapters,
-            ...(options.configPath ? { configPath: options.configPath } : {}),
+            configPath: options.configPath ?? process.env.LLM_RUNTIME_CONFIG_FILE,
         }));
         this.memoryManagement = new LongTermMemoryManagementRoutes((environmentId) => this.environments.get(environmentId).services.longTermMemory);
     }
+    async applyWhenRequestsIdle() {
+        const hasAcknowledgedRequests = this.requests.healthDetails().length > 0;
+        if (hasAcknowledgedRequests) {
+            return {
+                status: "restart_required",
+                message: "Your agent is working. Wait for active conversations and Jobs to finish, then apply again.",
+            };
+        }
+        return this.environments.applyConfiguration();
+    }
     async initializeSessionReadState(environmentIds) {
         for (const id of environmentIds) {
             try {
@@ -59,6 +115,38 @@ export class LocalRuntimeApiRouter {
         const method = req.method || "GET";
         const segments = pathSegments(pathname);
         const route = segments.join("/");
+        if (await this.conversationFiles.handle(route, req, res))
+            return;
+        if (await this.modelSetup.handle({
+            method,
+            route,
+            request: req,
+            response: res,
+        }))
+            return;
+        if (await this.setup.handle({ method, route, request: req, response: res }))
+            return;
+        if (await this.setupEmbedding.handle({
+            method,
+            route,
+            request: req,
+            response: res,
+        }))
+            return;
+        if (method === "PUT" &&
+            ["runtime/plugins", "runtime/config/dashboard/file"].includes(route)) {
+            if (!acceptConfigMutationRequest(req, res))
+                return;
+        }
+        if (method === "POST" && route === "runtime/config/apply") {
+            if (!acceptConfigMutationRequest(req, res))
+                return;
+            sendJson(res, 200, {
+                ok: true,
+                activation: await applyAndCompleteRuntimeSetup(this.setup, () => this.applyWhenRequestsIdle()),
+            });
+            return;
+        }
         if (route === "chat/attachments") {
             const environmentId = requestEnvironmentId(url, null, this.options.defaultEnvironmentId);
             const setupRequirement = this.environments.setupRequirement(environmentId);
@@ -84,6 +172,8 @@ export class LocalRuntimeApiRouter {
             ? null
             : readJsonBody(await readBody(req));
         const environmentId = requestEnvironmentId(url, body, this.options.defaultEnvironmentId);
+        if (await this.plugins.handle({ method, route, body, response: res }))
+            return;
         if (segments[0] === "schedules")
             await this.initializeSessionReadState([environmentId]);
         if (await this.schedules.handle({
@@ -119,6 +209,7 @@ export class LocalRuntimeApiRouter {
             return;
         }
         if (method === "GET" && route === "runtime/config/dashboard") {
+            res.setHeader("cache-control", "no-store");
             sendJson(res, 200, {
                 ok: true,
                 dashboard: await getConfigDashboardSnapshot({
@@ -129,25 +220,48 @@ export class LocalRuntimeApiRouter {
             return;
         }
         if (method === "PUT" && route === "runtime/config/dashboard/file") {
+            res.setHeader("cache-control", "no-store");
             const kind = readConfigFileKind(body?.kind);
             if (!kind) {
                 sendJson(res, 400, { ok: false, error: "invalid_config_file_kind" });
                 return;
             }
-            const result = await saveConfigDashboardFile({
-                rootDir: this.options.rootDir ?? process.cwd(),
-                configPath: this.options.configPath,
-                kind,
-                id: getString(body?.id),
-                config: body?.config,
-            });
-            sendJson(res, 200, { ...result, restartRequired: true });
+            const expectedRevision = getString(body?.expectedRevision);
+            if (!expectedRevision) {
+                sendJson(res, 428, {
+                    ok: false,
+                    error: "config_revision_required",
+                    message: "Reload Configuration before saving this file.",
+                });
+                return;
+            }
+            try {
+                const result = await saveConfigDashboardFile({
+                    rootDir: this.options.rootDir ?? process.cwd(),
+                    configPath: this.options.configPath,
+                    kind,
+                    id: getString(body?.id),
+                    config: body?.config,
+                    expectedRevision,
+                });
+                sendJson(res, 200, { ...result, restartRequired: true });
+            }
+            catch (error) {
+                if (!(error instanceof ConfigFileConflictError))
+                    throw error;
+                sendJson(res, 409, {
+                    ok: false,
+                    error: error.code,
+                    message: error.message,
+                });
+            }
             return;
         }
         if (method === "GET" && route === "chat/models") {
+            const pendingSetup = await pendingRuntimeSetupCatalog(this.setup);
             sendJson(res, 200, {
                 ok: true,
-                ...this.environments.modelCatalog(environmentId),
+                ...(pendingSetup ?? this.environments.modelCatalog(environmentId)),
                 modes: [],
             });
             return;
@@ -169,6 +283,16 @@ export class LocalRuntimeApiRouter {
             }
         }
         const environment = this.environments.get(environmentId);
+        if (await this.projects.handle({
+            method,
+            segments,
+            url,
+            body,
+            environment,
+            request: req,
+            response: res,
+        }))
+            return;
         if (await this.sessions.handle({
             method,
             segments,
@@ -179,7 +303,7 @@ export class LocalRuntimeApiRouter {
         }))
             return;
         if (method === "POST" && route === "chat/messages") {
-            await this.requests.start(res, body ?? {}, environmentId, environment);
+            await this.requests.start(res, body ?? {}, environmentId, this.environments.get(environmentId));
             return;
         }
         if (method === "GET" &&

package/dist/src/web-ui/local-runtime/config-mutation-request.d.ts

@@ -0,0 +1,8 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare class ConfigMutationRequestError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode?: number);
+}
+/** Browser writes to machine-local configuration require same-origin JSON. */
+export declare function assertConfigMutationRequest(request: IncomingMessage): void;
+export declare function acceptConfigMutationRequest(request: IncomingMessage, response: ServerResponse): boolean;

package/dist/src/web-ui/local-runtime/config-mutation-request.js

@@ -0,0 +1,55 @@
+import { sendJson } from "./http.js";
+export class ConfigMutationRequestError extends Error {
+    statusCode;
+    constructor(message, statusCode = 403) {
+        super(message);
+        this.statusCode = statusCode;
+    }
+}
+function hasJsonContentType(request) {
+    const value = request.headers["content-type"] ?? "";
+    return value.split(";", 1)[0].trim().toLowerCase() === "application/json";
+}
+function hasSameOrigin(request) {
+    const origin = request.headers.origin;
+    if (!origin)
+        return true;
+    try {
+        const parsed = new URL(origin);
+        if (!["http:", "https:"].includes(parsed.protocol))
+            return false;
+        const encrypted = "encrypted" in request.socket && request.socket.encrypted;
+        const expectedOrigin = `${encrypted ? "https:" : "http:"}//${request.headers.host}`;
+        return parsed.origin === expectedOrigin;
+    }
+    catch {
+        return false;
+    }
+}
+/** Browser writes to machine-local configuration require same-origin JSON. */
+export function assertConfigMutationRequest(request) {
+    if (request.headers["sec-fetch-site"] === "cross-site") {
+        throw new ConfigMutationRequestError("Cross-site configuration changes are not allowed.");
+    }
+    if (!hasSameOrigin(request)) {
+        throw new ConfigMutationRequestError("Configuration changes require the same origin.");
+    }
+    if (!hasJsonContentType(request)) {
+        throw new ConfigMutationRequestError("Configuration changes require application/json.", 415);
+    }
+}
+export function acceptConfigMutationRequest(request, response) {
+    try {
+        assertConfigMutationRequest(request);
+        return true;
+    }
+    catch (error) {
+        const status = error instanceof ConfigMutationRequestError ? error.statusCode : 403;
+        sendJson(response, status, {
+            ok: false,
+            error: "configuration_request_rejected",
+            message: "Configuration changes require same-origin JSON requests.",
+        });
+        return false;
+    }
+}

package/dist/src/web-ui/local-runtime/configuration-activation-environments.d.ts

@@ -0,0 +1,22 @@
+import type { LocalRuntimeApplication } from "../../runtime/local-application.js";
+export type EnvironmentEntry = readonly [string, LocalRuntimeApplication];
+export type ActivationEnvironmentOptions = {
+    environments: Map<string, LocalRuntimeApplication>;
+    canContinue?: () => boolean;
+};
+export declare function requireActivationIntakeOpen(options: ActivationEnvironmentOptions): void;
+export declare function settleExistingEnvironments(options: ActivationEnvironmentOptions): Promise<EnvironmentEntry[]>;
+export type IdleEnvironmentShutdown = {
+    status: "closed";
+    closed: readonly EnvironmentEntry[];
+} | {
+    status: "failed";
+    closed: readonly EnvironmentEntry[];
+    error: unknown;
+    hasUncertainOwners: boolean;
+};
+/** Every outcome settles before reporting a partial shutdown to Apply. */
+export declare function closeIdleEnvironments(options: ActivationEnvironmentOptions, current: readonly EnvironmentEntry[]): Promise<IdleEnvironmentShutdown>;
+export declare function startReplacementEnvironments(options: ActivationEnvironmentOptions, replacements: readonly EnvironmentEntry[]): Promise<void>;
+/** Retire candidate owners before restoring the previous gateway policy. */
+export declare function closeReplacementEnvironments(options: ActivationEnvironmentOptions, previous: readonly EnvironmentEntry[]): Promise<void>;

package/dist/src/web-ui/local-runtime/configuration-activation-environments.js

@@ -0,0 +1,106 @@
+export function requireActivationIntakeOpen(options) {
+    if (options.canContinue?.() === false)
+        throw new Error("web_runtime_stopped");
+}
+async function disposeFailedEnvironment(options, entry, startupError) {
+    const [id, environment] = entry;
+    try {
+        await environment.stop();
+    }
+    catch (stopError) {
+        // LocalApplication.stop closes in finally, then may rethrow its original startup error.
+        if (stopError !== startupError)
+            throw new AggregateError([startupError, stopError], "Failed runtime startup could not be cleaned up.");
+    }
+    if (options.environments.get(id) === environment)
+        options.environments.delete(id);
+}
+export async function settleExistingEnvironments(options) {
+    const current = [...options.environments];
+    const starts = await Promise.allSettled(current.map(([, environment]) => environment.start()));
+    requireActivationIntakeOpen(options);
+    for (const [index, result] of starts.entries()) {
+        if (result.status !== "rejected")
+            continue;
+        await disposeFailedEnvironment(options, current[index], result.reason);
+    }
+    return current.filter(([id, environment]) => options.environments.get(id) === environment);
+}
+function requestIdleEnvironmentShutdown([, environment,]) {
+    try {
+        return environment.stopIfIdle();
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+}
+function isConfirmedIdleShutdown(result) {
+    if (result.status !== "fulfilled")
+        return false;
+    return result.value;
+}
+function isRefusedIdleShutdown(result) {
+    if (result.status !== "fulfilled")
+        return false;
+    return !result.value;
+}
+/** Every outcome settles before reporting a partial shutdown to Apply. */
+export async function closeIdleEnvironments(options, current) {
+    // No await separates the complete idle snapshot from closing every owner's intake.
+    const closes = current.map(requestIdleEnvironmentShutdown);
+    const results = await Promise.allSettled(closes);
+    const closed = current.filter((_, index) => isConfirmedIdleShutdown(results[index]));
+    for (const [id, environment] of closed) {
+        if (options.environments.get(id) === environment)
+            options.environments.delete(id);
+    }
+    const failed = results.find((result) => result.status === "rejected");
+    if (failed?.status === "rejected") {
+        return {
+            status: "failed",
+            closed,
+            error: failed.reason,
+            hasUncertainOwners: true,
+        };
+    }
+    if (results.some(isRefusedIdleShutdown)) {
+        return {
+            status: "failed",
+            closed,
+            error: new Error("Runtime ownership changed while applying configuration."),
+            hasUncertainOwners: false,
+        };
+    }
+    return { status: "closed", closed };
+}
+export async function startReplacementEnvironments(options, replacements) {
+    requireActivationIntakeOpen(options);
+    for (const [id, replacement] of replacements)
+        options.environments.set(id, replacement);
+    const starts = await Promise.allSettled(replacements.map(async (entry) => {
+        try {
+            await entry[1].start();
+        }
+        catch (error) {
+            await disposeFailedEnvironment(options, entry, error);
+            throw error;
+        }
+    }));
+    const failed = starts.find((result) => result.status === "rejected");
+    if (failed?.status === "rejected")
+        throw failed.reason;
+    requireActivationIntakeOpen(options);
+}
+/** Retire candidate owners before restoring the previous gateway policy. */
+export async function closeReplacementEnvironments(options, previous) {
+    const previousOwners = new Map(previous);
+    const candidates = [...options.environments].filter(([id, environment]) => previousOwners.get(id) !== environment);
+    const stops = await Promise.allSettled(candidates.map(async ([id, environment]) => {
+        await environment.stop();
+        if (options.environments.get(id) === environment)
+            options.environments.delete(id);
+    }));
+    const errors = stops.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+    if (errors.length > 0)
+        throw new AggregateError(errors, "Candidate runtime cleanup failed.");
+}

package/dist/src/web-ui/local-runtime/configuration-activation-source.d.ts

@@ -0,0 +1,7 @@
+import type { RuntimeSetupActivation } from "./runtime-setup-input.js";
+export type ConfigurationActivationPreparation = {
+    prepareConfiguration(): void;
+    restoreConfiguration(): void;
+};
+/** Cooperating root and linked-file saves wait for activation or restoration to finish. */
+export declare function withConfigurationActivationSource(configPath: string, operation: (preparation: ConfigurationActivationPreparation) => Promise<RuntimeSetupActivation>): Promise<RuntimeSetupActivation>;

package/dist/src/web-ui/local-runtime/configuration-activation-source.js

@@ -0,0 +1,36 @@
+import { withConfigFileTransaction } from "../../runtime/adapters/config-file-transaction.js";
+import { resolveRequestRunnerConfigReference } from "../../runtime/config/request-runner-config.js";
+import { invalidateRequestRunnerConfig } from "../../runtime/config/runner/loader.js";
+function restoreUnappliedRequestRunner(activation, preparation) {
+    if (activation.status === "ready")
+        return;
+    preparation.restoreConfiguration();
+}
+/** Cooperating root and linked-file saves wait for activation or restoration to finish. */
+export function withConfigurationActivationSource(configPath, operation) {
+    return withConfigFileTransaction(configPath, async (transaction) => {
+        const runner = resolveRequestRunnerConfigReference({
+            fileConfig: transaction.snapshot.config,
+            mainConfigPath: configPath,
+        });
+        let restoreRequestRunner = () => { };
+        const preparation = {
+            prepareConfiguration() {
+                if (runner)
+                    restoreRequestRunner = invalidateRequestRunnerConfig(runner);
+            },
+            restoreConfiguration() {
+                restoreRequestRunner();
+            },
+        };
+        try {
+            const activation = await operation(preparation);
+            restoreUnappliedRequestRunner(activation, preparation);
+            return activation;
+        }
+        catch (error) {
+            preparation.restoreConfiguration();
+            throw error;
+        }
+    });
+}

package/dist/src/web-ui/local-runtime/configuration-activation.d.ts

@@ -0,0 +1,20 @@
+import type { LocalRuntimeApplication } from "../../runtime/local-application.js";
+import type { RuntimeSetupActivation } from "./runtime-setup-input.js";
+import type { RuntimeSetupGatewayRestorePoint } from "../runtime-setup-gateway.js";
+type ActivationOptions = {
+    environments: Map<string, LocalRuntimeApplication>;
+    defaultEnvironmentId: string;
+    environmentIds?: readonly string[];
+    createEnvironment: (id: string) => LocalRuntimeApplication;
+    recreateEnvironment: (id: string, previous: LocalRuntimeApplication) => LocalRuntimeApplication;
+    createGatewayRestorePoint?: () => RuntimeSetupGatewayRestorePoint;
+    onRestorationFailure?: () => void;
+    prepareConfiguration?: () => void;
+    restoreConfiguration?: () => void;
+    checkGateway?: () => Promise<RuntimeSetupActivation>;
+    activateGateway: () => Promise<RuntimeSetupActivation>;
+    canContinue?: () => boolean;
+};
+/** Idle admission is checked at the owning host, never from a browser activity list. */
+export declare function applyRuntimeConfiguration(options: ActivationOptions): Promise<RuntimeSetupActivation>;
+export {};

package/dist/src/web-ui/local-runtime/configuration-activation.js

@@ -0,0 +1,107 @@
+import { closeIdleEnvironments, closeReplacementEnvironments, requireActivationIntakeOpen, settleExistingEnvironments, startReplacementEnvironments, } from "./configuration-activation-environments.js";
+function blockedActivation(message) {
+    return { status: "restart_required", message };
+}
+function ownerActivationBlock(current) {
+    const hasExternalOwner = current.some(([, environment]) => environment.getOwnership() !== "owner");
+    if (hasExternalOwner) {
+        return blockedActivation("Another process owns this runtime. Changes are saved and will apply when that process restarts.");
+    }
+    const hasBusyOwner = current.some(([, environment]) => !environment.isOwnerIdle());
+    if (hasBusyOwner) {
+        return blockedActivation("Your agent is working. Wait for active conversations and Jobs to finish, then apply again.");
+    }
+    return undefined;
+}
+function desiredEnvironmentIds(options) {
+    const ids = new Set(options.environmentIds ?? options.environments.keys());
+    if (ids.size === 0)
+        ids.add(options.defaultEnvironmentId);
+    return [...ids];
+}
+/** Idle admission is checked at the owning host, never from a browser activity list. */
+export async function applyRuntimeConfiguration(options) {
+    requireActivationIntakeOpen(options);
+    const ids = desiredEnvironmentIds(options);
+    const current = await settleExistingEnvironments(options);
+    const initialBlock = ownerActivationBlock(current);
+    if (initialBlock)
+        return initialBlock;
+    options.prepareConfiguration?.();
+    const gatewayCheck = await options.checkGateway?.();
+    requireActivationIntakeOpen(options);
+    if (gatewayCheck?.status === "restart_required")
+        return gatewayCheck;
+    // Config parsing is synchronous and cannot alter owner intake.
+    const replacements = ids.map((id) => [id, options.createEnvironment(id)]);
+    const finalBlock = ownerActivationBlock(current);
+    if (finalBlock)
+        return finalBlock;
+    const gatewayRestorePoint = options.createGatewayRestorePoint?.();
+    const shutdown = await closeIdleEnvironments(options, current);
+    if (shutdown.status === "failed") {
+        await restoreAfterIdleShutdownFailure(options, shutdown);
+        throw shutdown.error;
+    }
+    let activation;
+    try {
+        requireActivationIntakeOpen(options);
+        activation = await options.activateGateway();
+        requireActivationIntakeOpen(options);
+        if (isRuntimeActivationReady(activation))
+            await startReplacementEnvironments(options, replacements);
+    }
+    catch (error) {
+        await restoreConfigurationAfterFailure(options, current, gatewayRestorePoint, error);
+        throw error;
+    }
+    if (!isRuntimeActivationReady(activation)) {
+        await restoreConfigurationAfterFailure(options, current, gatewayRestorePoint, new Error(activation.message ?? "Runtime configuration was not activated."));
+    }
+    return activation;
+}
+async function restoreAfterIdleShutdownFailure(options, shutdown) {
+    if (isActivationStopped(options))
+        return;
+    // A rejected close does not prove that the previous owner's lease was released.
+    if (shutdown.hasUncertainOwners)
+        options.onRestorationFailure?.();
+    try {
+        options.restoreConfiguration?.();
+        const restored = shutdown.closed.map(([id, environment]) => [id, options.recreateEnvironment(id, environment)]);
+        await startReplacementEnvironments(options, restored);
+    }
+    catch (restorationError) {
+        if (isActivationStopped(options))
+            return;
+        options.onRestorationFailure?.();
+        throw new AggregateError([shutdown.error, restorationError], "Idle runtime shutdown failed and closed environments could not be restored.");
+    }
+}
+async function restoreConfigurationAfterFailure(options, previous, gateway, activationError) {
+    if (isActivationStopped(options))
+        return;
+    try {
+        await closeReplacementEnvironments(options, previous);
+        if (isActivationStopped(options))
+            return;
+        options.restoreConfiguration?.();
+        await gateway?.restore();
+        if (isActivationStopped(options))
+            return;
+        const restored = previous.map(([id, environment]) => [id, options.recreateEnvironment(id, environment)]);
+        await startReplacementEnvironments(options, restored);
+    }
+    catch (restorationError) {
+        if (isActivationStopped(options))
+            return;
+        options.onRestorationFailure?.();
+        throw new AggregateError([activationError, restorationError], "Configuration activation failed and the previous runtime could not be restored.");
+    }
+}
+function isActivationStopped(options) {
+    return options.canContinue?.() === false;
+}
+function isRuntimeActivationReady(activation) {
+    return activation.status === "ready";
+}

package/dist/src/web-ui/local-runtime/contracts.d.ts

@@ -1,3 +1,6 @@
+import type { RuntimeSetupGatewayRestorePoint } from "../runtime-setup-gateway.js";
+import type { WebUiEnvironmentConfig } from "../environment-config.js";
+import type { RuntimeSetupActivation } from "./runtime-setup-input.js";
 import type { LocalRuntimeApplication } from "../../runtime/local-application.js";
 import type { RequestSteeringInbox } from "../../runtime/request/request-steering.js";
 import type { ModelProviderAdapterRegistry } from "../../model-gateway/index.js";
@@ -6,7 +9,11 @@ export type LocalRuntimeBackendOptions = {
     rootDir?: string;
     configPath?: string;
     defaultEnvironmentId: string;
+    resolveEnvironmentConfig?: (configPath?: string) => WebUiEnvironmentConfig;
     providerAdapters?: ModelProviderAdapterRegistry;
+    onRuntimeSetup?: (configPath: string) => Promise<RuntimeSetupActivation>;
+    createRuntimeSetupRestorePoint?: () => RuntimeSetupGatewayRestorePoint;
+    checkRuntimeSetupActivation?: (configPath: string) => Promise<RuntimeSetupActivation>;
 };
 export type ResolvedLocalRuntimeBackendOptions = Omit<LocalRuntimeBackendOptions, "providerAdapters"> & {
     providerAdapters: ModelProviderAdapterRegistry;
@@ -16,6 +23,7 @@ export type RuntimeSetupRequirement = {
     status: "setup_required";
     code: "runtime_configuration_required";
     message: string;
+    recovery?: "configuration";
 };
 export type RuntimeAvailability = {
     status: "ready";

package/dist/src/web-ui/local-runtime/conversation-file-access.d.ts

@@ -0,0 +1,30 @@
+import type { RuntimeEnvironmentRegistry } from "./environment-registry.js";
+import type { LocalRequestExecution } from "./request-execution.js";
+export type ConversationFileReference = {
+    environmentId: string;
+    sessionId: string;
+    requestId: string;
+    executionId: string;
+};
+export declare function readConversationFileReference(url: URL): ConversationFileReference;
+/** The recorded completion and its request generation own every file action. */
+export declare class ConversationFileAccess {
+    private readonly environments;
+    private readonly requests;
+    private readonly defaultEnvironmentId;
+    constructor(environments: Pick<RuntimeEnvironmentRegistry, "environmentConfig" | "setupRequirement" | "get">, requests: LocalRequestExecution, defaultEnvironmentId: () => string);
+    authorize(reference: ConversationFileReference): Promise<{
+        receipt: Readonly<{
+            version: 1;
+            location: import("../../capabilities/file-output-presentation.js").ToolFileOutputLocation;
+            rootId: string;
+            relativePath: string;
+            logicalPath: string;
+            operation: import("../../capabilities/file-output-presentation.js").ToolFileOutputOperation;
+        }>;
+        paths: import("../../runtime/ports.js").RuntimePaths;
+        assertCurrent: () => Promise<void>;
+    }>;
+    private fileReceipt;
+    private resolveEnvironment;
+}