@abot-ai/runtime 1.6.0 → 1.7.0

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

@@ -4,7 +4,8 @@ import { getNumber, getString, sendJson } from "./http.js";
 import { PendingToolApprovals } from "./pending-tool-approvals.js";
 import { createWorkspaceChangeNotifier } from "./workspace-notifications.js";
 import { attachApprovalRequest } from "./approval-request-attachment.js";
-import { publicSparkChatAdmissionFailure, resolveSparkChatRequest } from "./spark-chat-admission.js";
+import { publicSparkChatAdmissionFailure, resolveSparkChatRequest, } from "./spark-chat-admission.js";
+import { traceWebProjection, webSteerRoute, WebSteerObservation, } from "./request-control-observation.js";
 function createRequestId() {
     const random = Math.random().toString(36).slice(2, 8);
     return `web-${Date.now()}-${random}`;
@@ -26,6 +27,7 @@ export class LocalRequestExecution {
     scheduledRequestOptions(run) {
         const requestSteering = createRequestSteeringInbox({
             requestId: run.requestId,
+            diagnostics: { origin: "web_projection" },
         });
         this.activeRequests.set(run.requestId, {
             requestId: run.requestId,
@@ -38,6 +40,7 @@ export class LocalRequestExecution {
             finalState: null,
             requestSteering,
         });
+        traceWebProjection("projection.opened", run.requestId, this.activeRequests.get(run.requestId), "schedule");
         return {
             toolApprovalController: this.toolApprovals,
             requestSteering,
@@ -51,7 +54,10 @@ export class LocalRequestExecution {
         if (payload.sessionDeleted !== true)
             this.publish(outbound);
         if (isTerminal) {
-            this.activeRequests.delete(getString(payload.requestId));
+            const requestId = getString(payload.requestId);
+            const active = this.activeRequests.get(requestId);
+            const removed = this.activeRequests.delete(requestId);
+            traceWebProjection("projection.removed", requestId, active, "published_terminal", removed);
         }
     }
     async start(res, body, environmentId, environment) {
@@ -78,10 +84,16 @@ export class LocalRequestExecution {
             body = await resolveSparkChatRequest(environment, sessionId, body);
         }
         catch (error) {
-            sendJson(res, 409, { ok: false, ...publicSparkChatAdmissionFailure(error) });
+            sendJson(res, 409, {
+                ok: false,
+                ...publicSparkChatAdmissionFailure(error),
+            });
             return;
         }
-        const requestSteering = createRequestSteeringInbox({ requestId });
+        const requestSteering = createRequestSteeringInbox({
+            requestId,
+            diagnostics: { origin: "web_projection" },
+        });
         const request = {
             type: "run_request",
             requestId,
@@ -103,6 +115,7 @@ export class LocalRequestExecution {
             finalState: null,
             requestSteering,
         });
+        traceWebProjection("projection.opened", requestId, this.activeRequests.get(requestId), "ordinary");
         void this.run(environment, request, environmentId, sessionId, requestSteering)
             .catch((error) => {
             this.publish({
@@ -113,7 +126,11 @@ export class LocalRequestExecution {
                 error: error instanceof Error ? error.message : String(error),
             });
         })
-            .finally(() => this.activeRequests.delete(requestId));
+            .finally(() => {
+            const active = this.activeRequests.get(requestId);
+            const removed = this.activeRequests.delete(requestId);
+            traceWebProjection("projection.removed", requestId, active, "run_handle_settled", removed);
+        });
         sendJson(res, 200, { ok: true, requestId, sessionId });
     }
     activeReplay(requestId, afterSeq) {
@@ -151,45 +168,60 @@ export class LocalRequestExecution {
         const steerId = getString(message.steerId).trim();
         const text = getString(message.text).trim();
         const active = requestId ? this.activeRequests.get(requestId) : undefined;
-        if (active) {
-            const sessions = resolveEnvironment(active.environmentId).services.sessions;
-            try {
-                await sessions.assertInteractiveSession?.(active.sessionId);
+        const observation = new WebSteerObservation(requestId, steerId, getString(message.environment), text.length, active, () => this.activeRequests.get(requestId));
+        try {
+            if (active) {
+                observation.selectRoute("interactive_session_check");
+                const sessions = resolveEnvironment(active.environmentId).services
+                    .sessions;
+                try {
+                    await sessions.assertInteractiveSession?.(active.sessionId);
+                }
+                catch (error) {
+                    if (!isAutomationSessionLockedError(error))
+                        throw error;
+                    const acknowledgement = {
+                        type: "steer_ack",
+                        requestId,
+                        steerId,
+                        accepted: false,
+                        reason: "automation_session_locked",
+                    };
+                    observation.result(acknowledgement);
+                    return acknowledgement;
+                }
             }
-            catch (error) {
-                if (!isAutomationSessionLockedError(error))
-                    throw error;
-                return {
+            observation.selectRoute("environment_resolution");
+            const steer = active
+                ? resolveEnvironment(active.environmentId).requests.steer
+                : undefined;
+            observation.selectRoute(webSteerRoute(active, steer));
+            const result = (steer
+                ? await steer(requestId, { steerId, text })
+                : active?.requestSteering.append({ steerId, text })) ??
+                { ok: false, reason: "request_not_active" };
+            const acknowledgement = result.ok
+                ? {
+                    type: "steer_ack",
+                    requestId,
+                    steerId,
+                    accepted: true,
+                    acceptedSequence: result.update.sequence,
+                }
+                : {
                     type: "steer_ack",
                     requestId,
                     steerId,
                     accepted: false,
-                    reason: "automation_session_locked",
+                    reason: result.reason,
                 };
-            }
+            observation.result(acknowledgement);
+            return acknowledgement;
+        }
+        catch (error) {
+            observation.failed(error);
+            throw error;
         }
-        const steer = active
-            ? resolveEnvironment(active.environmentId).requests.steer
-            : undefined;
-        const result = (steer
-            ? await steer(requestId, { steerId, text })
-            : active?.requestSteering.append({ steerId, text })) ??
-            { ok: false, reason: "request_not_active" };
-        return result.ok
-            ? {
-                type: "steer_ack",
-                requestId,
-                steerId,
-                accepted: true,
-                acceptedSequence: result.update.sequence,
-            }
-            : {
-                type: "steer_ack",
-                requestId,
-                steerId,
-                accepted: false,
-                reason: result.reason,
-            };
     }
     resolveToolApproval(message) {
         this.toolApprovals.resolveRealtime(message);

package/dist/src/web-ui/local-runtime/runtime-setup-context-window.d.ts

@@ -0,0 +1,20 @@
+import type { ModelContextCapacityIssue } from "../../runtime/config/model-context-capacity.js";
+import { RuntimeSetupError } from "./runtime-setup-input.js";
+export type RuntimeSetupContextWindowIssue = Readonly<{
+    field: "contextWindowTokens";
+    declaredTokens: number;
+    effectiveTokens: number;
+    reservedTokens: number;
+    minimumTokens: number;
+    allocationTokens?: number;
+    environmentId?: string;
+}>;
+export declare class RuntimeSetupContextWindowError extends RuntimeSetupError {
+    readonly contextWindow: RuntimeSetupContextWindowIssue;
+    constructor(issue: ModelContextCapacityIssue, environmentId?: string);
+}
+/** Project only known capacity evidence; other exceptions keep their redaction. */
+export declare function throwRuntimeSetupValidationError(error: unknown, environmentId?: string): never;
+export declare function runtimeSetupContextWindowErrorDetails(error: unknown): {
+    contextWindow?: RuntimeSetupContextWindowIssue;
+};

package/dist/src/web-ui/local-runtime/runtime-setup-context-window.js

@@ -0,0 +1,44 @@
+import { RuntimeConfigValidationError } from "../../runtime/config/validation.js";
+import { RuntimeSetupError } from "./runtime-setup-input.js";
+function setupContextWindowMessage(issue) {
+    const capacity = `The effective context window is ${issue.effectiveTokens} tokens, but the configured reserves require more than ${issue.reservedTokens} tokens. Use a model-supported context window of at least ${issue.minimumTokens} tokens or adjust the configured reserves.`;
+    if (issue.allocationTokens === undefined)
+        return capacity;
+    if (issue.allocationTokens >= issue.minimumTokens)
+        return capacity;
+    return `${capacity} The Ollama num_ctx allocation of ${issue.allocationTokens} tokens must also support that window.`;
+}
+export class RuntimeSetupContextWindowError extends RuntimeSetupError {
+    contextWindow;
+    constructor(issue, environmentId) {
+        super("context_window_too_small", setupContextWindowMessage(issue));
+        this.contextWindow = {
+            field: "contextWindowTokens",
+            declaredTokens: issue.declaredTokens,
+            effectiveTokens: issue.effectiveTokens,
+            reservedTokens: issue.reservedTokens,
+            minimumTokens: issue.minimumTokens,
+            ...(issue.allocationTokens === undefined
+                ? {}
+                : { allocationTokens: issue.allocationTokens }),
+            ...(environmentId === undefined ? {} : { environmentId }),
+        };
+    }
+}
+function readSetupContextCapacityIssue(error) {
+    if (!(error instanceof RuntimeConfigValidationError))
+        return undefined;
+    return error.capacityIssues.find((issue) => issue.profileId === "default");
+}
+/** Project only known capacity evidence; other exceptions keep their redaction. */
+export function throwRuntimeSetupValidationError(error, environmentId) {
+    const issue = readSetupContextCapacityIssue(error);
+    if (!issue)
+        throw error;
+    throw new RuntimeSetupContextWindowError(issue, environmentId);
+}
+export function runtimeSetupContextWindowErrorDetails(error) {
+    if (!(error instanceof RuntimeSetupContextWindowError))
+        return {};
+    return { contextWindow: error.contextWindow };
+}

package/dist/src/web-ui/local-runtime/runtime-setup-routes.js

@@ -1,6 +1,7 @@
 import { assertConfigMutationRequest, ConfigMutationRequestError, } from "./config-mutation-request.js";
 import { readBody, readJsonBody, sendJson } from "./http.js";
 import { RuntimeSetupError } from "./runtime-setup-input.js";
+import { runtimeSetupContextWindowErrorDetails } from "./runtime-setup-context-window.js";
 export class RuntimeSetupRoutes {
     service;
     constructor(service) {
@@ -43,6 +44,7 @@ export class RuntimeSetupRoutes {
                 error instanceof ConfigMutationRequestError;
             sendJson(params.response, isPublicError ? error.statusCode : 400, {
                 ok: false,
+                ...runtimeSetupContextWindowErrorDetails(error),
                 error: error instanceof RuntimeSetupError
                     ? error.code
                     : "runtime_setup_failed",

package/dist/src/web-ui/local-runtime/runtime-setup-validation.js

@@ -2,6 +2,7 @@ import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { loadRuntimeConfig } from "../../runtime/config.js";
 import { isRecord } from "../../runtime/config/utils.js";
+import { throwRuntimeSetupValidationError } from "./runtime-setup-context-window.js";
 /** Validate complete effective configuration in isolation before replacing local files. */
 export async function validateRuntimeSetupPlan(params) {
     const staging = await mkdtemp(join(params.rootDir, ".runtime-setup-validation-"));
@@ -26,8 +27,14 @@ export async function validateRuntimeSetupPlan(params) {
             ? Object.keys(environment.profiles)
             : [];
         const environments = profileIds.length ? profileIds : [undefined];
-        for (const profileId of environments)
-            loadRuntimeConfig({ rootDir: params.rootDir, configPath, profileId });
+        for (const profileId of environments) {
+            try {
+                loadRuntimeConfig({ rootDir: params.rootDir, configPath, profileId });
+            }
+            catch (error) {
+                throwRuntimeSetupValidationError(error, profileId);
+            }
+        }
     }
     finally {
         await rm(staging, { recursive: true, force: true });

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

@@ -3,6 +3,7 @@ import type { RuntimeEnvironment, JsonObject } from "./contracts.js";
 import { WebSessionReadStates } from "../session-read-state/service.js";
 import type { WorkspaceChangeNotifier } from "./workspace-notifications.js";
 type SessionRouteRequest = {
+    url?: URL;
     method: string;
     segments: string[];
     body: JsonObject | null;

package/dist/src/web-ui/local-runtime/session-routes.js

@@ -1,3 +1,4 @@
+import { historyPageOptions, publicHistorySnapshot } from "./history-pagination.js";
 import { deleteSessionWithAttachments } from "../../runtime/session/session-attachment-deletion.js";
 import { deleteSessionAttachmentsIfSupported } from "./attachment-routes.js";
 import { sendJson } from "./http.js";
@@ -34,13 +35,24 @@ export class WebSessionRoutes {
             });
             return true;
         }
+        if (method === "POST" && sessionId === "page" && !action) {
+            sendJson(response, 200, { ok: true, ...(await this.readStates.list(environmentId, body ?? {})) });
+            return true;
+        }
         if (!sessionId)
             return false;
         const sessions = environment.services.sessions;
         if (method === "GET" && action === "messages") {
-            const snapshot = await sessions.getSessionSnapshot(sessionId, {
-                includeRequests: true,
-            });
+            let snapshot;
+            try {
+                snapshot = await sessions.getSessionSnapshot(sessionId, historyPageOptions(request.url, environment.services.config));
+            }
+            catch (error) {
+                if (!(error instanceof Error) || error.message !== "history_cursor_stale")
+                    throw error;
+                sendJson(response, 409, { ok: false, error: error.message });
+                return true;
+            }
             if (!snapshot) {
                 sendJson(response, 404, {
                     ok: false,
@@ -52,7 +64,7 @@ export class WebSessionRoutes {
             }
             sendJson(response, 200, {
                 ok: true,
-                ...snapshot,
+                ...publicHistorySnapshot(snapshot),
                 readState: await this.readStates.project(environmentId, snapshot),
             });
             return true;

package/dist/src/web-ui/local-runtime/spark-chat-routes.js

@@ -1,3 +1,4 @@
+import { historyPageOptions, publicHistorySnapshot } from "./history-pagination.js";
 import { ensureSparkSession } from "../../sessions/spark-session.js";
 import { acceptConfigMutationRequest } from "./config-mutation-request.js";
 import { loadSparkChatConfiguration, readSparkChatConfigurationUpdate } from "./spark-chat-configuration.js";
@@ -40,11 +41,11 @@ export class SparkChatRoutes {
             if (update)
                 await environment.services.passiveLearning.configure(update);
             const configuration = await loadSparkChatConfiguration(environment.services.passiveLearning);
-            const snapshot = await environment.services.sessions.getSessionSnapshot(session.id, { includeRequests: true });
+            const snapshot = await environment.services.sessions.getSessionSnapshot(session.id, historyPageOptions(new URL(input.request.url ?? "/", "http://localhost"), environment.services.config));
             if (!snapshot)
                 throw new Error("spark_chat_unavailable");
             sendJson(input.response, 200, {
-                ok: true, sessionId: session.id, ...configuration, snapshot,
+                ok: true, sessionId: session.id, ...configuration, snapshot: publicHistorySnapshot(snapshot),
                 readState: await this.reads.project(input.environmentId, snapshot),
             });
             return true;
@@ -52,7 +53,7 @@ export class SparkChatRoutes {
         catch (error) {
             const code = error instanceof Error ? error.message : "spark_chat_unavailable";
             const invalid = ["spark_chat_preferences_invalid", "invalid_spark_tool_permission_mode", "visible_message_ids_invalid", "visible_message_receipts_invalid"].includes(code);
-            const stale = ["read_generation_changed", "visible_message_receipt_stale"].includes(code);
+            const stale = ["read_generation_changed", "visible_message_receipt_stale", "history_cursor_stale"].includes(code);
             sendJson(input.response, invalid ? 400 : 409, {
                 ok: false, error: invalid || stale ? code : "spark_chat_unavailable",
             });

package/dist/src/web-ui/plugin-capability-selection.js

@@ -1,9 +1,11 @@
-import { isPluginToolSelected, normalizePluginSelection, } from "../runtime/plugins/selection.js";
+import { isPluginToolSelected, isPluginDisabledById, normalizePluginSelection, } from "../runtime/plugins/selection.js";
 export function pluginParentBlockReason(pluginId, selection) {
     if (!selection.enabled)
         return "Plugins are disabled globally.";
     if (selection.deny.includes("*"))
         return "The global deny rule blocks all plugins.";
+    if (isPluginDisabledById(pluginId, selection))
+        return "Enable this plugin before changing its capabilities.";
     if (selection.deny.includes(pluginId))
         return "Enable this plugin before changing its capabilities.";
     return undefined;
@@ -25,6 +27,7 @@ function isCapabilityAllowed(params) {
             ...params.current,
             enabled: true,
             deny: [],
+            disabledPluginIds: [],
         }),
     });
 }

package/dist/src/web-ui/plugin-configuration-input.d.ts

@@ -0,0 +1,12 @@
+import type { PluginConfigurationDeclaration } from "../runtime/plugins/configuration-context.js";
+import { type PluginLocalConfiguration } from "../runtime/plugins/configuration-store.js";
+export declare function parsePluginConfigurationUpdate(input: unknown, declaration: PluginConfigurationDeclaration, previous?: PluginLocalConfiguration): {
+    revision: string;
+    configuration: {
+        settings: Record<string, unknown>;
+        secrets: Record<string, {
+            env: string;
+            value: string | null;
+        }>;
+    };
+};

package/dist/src/web-ui/plugin-configuration-input.js

@@ -0,0 +1,68 @@
+import { clearRetainedPluginSecrets, requireRetainedSecretClearedBeforeReplacement, } from "./plugin-configuration-retained-secrets.js";
+import { pluginSettingMatchesDefault } from "../runtime/plugins/configuration-settings.js";
+import { isRecord } from "../runtime/config/utils.js";
+import { PluginConfigurationError, } from "../runtime/plugins/configuration-store.js";
+function invalidConfiguration(message) {
+    throw new PluginConfigurationError("invalid_plugin_configuration", message);
+}
+function parseSettings(input, declaration) {
+    if (!isRecord(input))
+        return invalidConfiguration("Plugin settings must be an object.");
+    const defaults = declaration.settings?.defaults ?? {};
+    for (const [name, value] of Object.entries(input)) {
+        if (!Object.hasOwn(defaults, name))
+            return invalidConfiguration("Only declared plugin settings can be edited.");
+        if (!pluginSettingMatchesDefault(value, defaults[name]))
+            return invalidConfiguration(`The value for ${name} must match its default type.`);
+    }
+    return input;
+}
+function parseSecretChanges(input, declaration, previous) {
+    if (!isRecord(input))
+        return invalidConfiguration("Plugin secrets must be an object.");
+    const declarations = declaration.secrets ?? {};
+    const changes = Object.entries(input).map(([name, change]) => {
+        if (!Object.hasOwn(declarations, name))
+            return invalidConfiguration("Only declared plugin secrets can be edited.");
+        requireRetainedSecretClearedBeforeReplacement(name, declaration, previous);
+        if (!isRecord(change))
+            return invalidConfiguration("Choose how to update each secret.");
+        if (change.action === "clear") {
+            if (Object.keys(change).length !== 1)
+                return invalidConfiguration("Clear accepts no secret value.");
+            return [name, { env: declarations[name].env, value: null }];
+        }
+        if (change.action !== "set")
+            return invalidConfiguration("A secret change must be set or clear; omit it to keep the current value.");
+        if (Object.keys(change).some((key) => !["action", "value"].includes(key)))
+            return invalidConfiguration("Unsupported secret change.");
+        if (typeof change.value !== "string" || !change.value.trim())
+            return invalidConfiguration("Enter a non-empty secret or explicitly clear it.");
+        return [
+            name,
+            { env: declarations[name].env, value: change.value },
+        ];
+    });
+    return { ...previous?.secrets, ...Object.fromEntries(changes) };
+}
+export function parsePluginConfigurationUpdate(input, declaration, previous) {
+    if (!isRecord(input))
+        return invalidConfiguration("Reload plugin configuration before saving.");
+    if (Object.keys(input).some((key) => !["revision", "settings", "secrets", "clearRetainedSecrets"].includes(key)))
+        return invalidConfiguration("Unsupported plugin configuration fields.");
+    if (typeof input.revision !== "string" || !input.revision)
+        return invalidConfiguration("Reload plugin configuration before saving.");
+    if (Buffer.byteLength(JSON.stringify(input)) > 128 * 1024)
+        return invalidConfiguration("Plugin configuration is too large.");
+    const kept = {
+        settings: previous?.settings ?? {},
+        secrets: clearRetainedPluginSecrets(input.clearRetainedSecrets, declaration, previous),
+    };
+    return {
+        revision: input.revision,
+        configuration: {
+            settings: parseSettings(input.settings, declaration),
+            secrets: parseSecretChanges(input.secrets ?? {}, declaration, kept),
+        },
+    };
+}

package/dist/src/web-ui/plugin-configuration-retained-secrets.d.ts

@@ -0,0 +1,9 @@
+import type { PluginConfigurationDeclaration } from "../runtime/plugins/configuration-context.js";
+import { type PluginLocalConfiguration } from "../runtime/plugins/configuration-store.js";
+export declare function retainedPluginSecrets(declaration: PluginConfigurationDeclaration, local?: PluginLocalConfiguration): {
+    name: string;
+    env: string;
+    configured: boolean;
+}[];
+export declare function clearRetainedPluginSecrets(input: unknown, declaration: PluginConfigurationDeclaration, previous?: PluginLocalConfiguration): PluginLocalConfiguration["secrets"];
+export declare function requireRetainedSecretClearedBeforeReplacement(name: string, declaration: PluginConfigurationDeclaration, previous?: PluginLocalConfiguration): void;

package/dist/src/web-ui/plugin-configuration-retained-secrets.js

@@ -0,0 +1,48 @@
+import { isRecord } from "../runtime/config/utils.js";
+import { PluginConfigurationError, } from "../runtime/plugins/configuration-store.js";
+function isDeclaredSecretBinding(declaration, name, env) {
+    const secrets = declaration.secrets ?? {};
+    if (!Object.hasOwn(secrets, name))
+        return false;
+    return secrets[name].env === env;
+}
+export function retainedPluginSecrets(declaration, local) {
+    return Object.entries(local?.secrets ?? {})
+        .filter(([name, saved]) => !isDeclaredSecretBinding(declaration, name, saved.env))
+        .map(([name, saved]) => ({
+        name,
+        env: saved.env,
+        configured: Boolean(saved.value?.trim()),
+    }));
+}
+function invalidRetainedSecretChange(message) {
+    throw new PluginConfigurationError("invalid_plugin_configuration", message);
+}
+export function clearRetainedPluginSecrets(input, declaration, previous) {
+    const kept = { ...previous?.secrets };
+    if (input === undefined)
+        return kept;
+    if (!Array.isArray(input))
+        return invalidRetainedSecretChange("Choose which unused saved keys to delete.");
+    for (const entry of input) {
+        if (!isRecord(entry))
+            return invalidRetainedSecretChange("Choose an unused saved key to delete.");
+        if (Object.keys(entry).some((key) => !["name", "env"].includes(key)))
+            return invalidRetainedSecretChange("An unused key removal accepts only its name and environment binding.");
+        if (typeof entry.name !== "string" || typeof entry.env !== "string")
+            return invalidRetainedSecretChange("An unused key removal requires its name and environment binding.");
+        if (!Object.hasOwn(kept, entry.name) || kept[entry.name].env !== entry.env)
+            return invalidRetainedSecretChange("The unused saved key changed. Reload the form before deleting it.");
+        if (isDeclaredSecretBinding(declaration, entry.name, entry.env))
+            return invalidRetainedSecretChange("Use the declared key's Clear value action to clear it.");
+        delete kept[entry.name];
+    }
+    return kept;
+}
+export function requireRetainedSecretClearedBeforeReplacement(name, declaration, previous) {
+    if (!previous || !Object.hasOwn(previous.secrets, name))
+        return;
+    if (isDeclaredSecretBinding(declaration, name, previous.secrets[name].env))
+        return;
+    throw new PluginConfigurationError("invalid_plugin_configuration", `Delete the unused saved key ${name} explicitly before configuring its new environment binding.`);
+}

package/dist/src/web-ui/plugin-configuration-service.d.ts

@@ -0,0 +1,52 @@
+import type { ConfigFileTransaction } from "../runtime/adapters/config-file-transaction.js";
+import type { PluginManagementOptions } from "./plugin-management-service.js";
+export declare function getRuntimePluginConfiguration(options: PluginManagementOptions, pluginId: string): {
+    pluginId: string;
+    revision: string;
+    scope: "installation";
+    defaults: Readonly<Record<string, unknown>>;
+    settings: Record<string, unknown>;
+    settingOverrides: string[];
+    retainedSecrets: {
+        name: string;
+        env: string;
+        configured: boolean;
+    }[];
+    secrets: {
+        name: string;
+        env: string;
+        required: boolean;
+        configured: boolean;
+        locallyConfigured: boolean;
+    }[];
+};
+/** Configuration and package selection commit under the same locks as Apply. */
+export declare function saveRuntimePluginConfiguration<T>(options: PluginManagementOptions, params: {
+    pluginId: string;
+    input: unknown;
+    transaction?: ConfigFileTransaction;
+    installation?: boolean;
+    commit?: () => Promise<T>;
+}): Promise<{
+    result: Awaited<T> | undefined;
+    configuration: {
+        pluginId: string;
+        revision: string;
+        scope: "installation";
+        defaults: Readonly<Record<string, unknown>>;
+        settings: Record<string, unknown>;
+        settingOverrides: string[];
+        retainedSecrets: {
+            name: string;
+            env: string;
+            configured: boolean;
+        }[];
+        secrets: {
+            name: string;
+            env: string;
+            required: boolean;
+            configured: boolean;
+            locallyConfigured: boolean;
+        }[];
+    };
+}>;

package/dist/src/web-ui/plugin-configuration-service.js

@@ -0,0 +1,66 @@
+import { realpathSync } from "node:fs";
+import { inspectRuntimeConfigFileWithMeta } from "../runtime/config/loader.js";
+import { ABOT_RUNTIME_EXTENSION } from "../plugin-contract/manifest.js";
+import { discoverConfiguredRuntimePluginManifests } from "../runtime/plugins/configured-manifests.js";
+import { configuredPluginSecret, } from "../runtime/plugins/configuration-context.js";
+import { PluginConfigurationError, readPluginConfigurationStore, } from "../runtime/plugins/configuration-store.js";
+import { commitPluginConfigurationStore, withPluginConfigurationLock, } from "../runtime/plugins/configuration-write.js";
+import { withConfigDashboardRootTransaction } from "./config-dashboard-save-transaction.js";
+import { parsePluginConfigurationUpdate } from "./plugin-configuration-input.js";
+import { pluginConfigurationRevision, projectPluginConfiguration, } from "./plugin-configuration-view.js";
+function installedPluginDeclaration(rootDir, pluginId) {
+    const plugin = discoverConfiguredRuntimePluginManifests(rootDir).find((entry) => entry.manifest.name === pluginId);
+    if (!plugin)
+        throw new PluginConfigurationError("plugin_not_found", "The selected plugin is not installed.", 404);
+    const extension = plugin.manifest.extensions[ABOT_RUNTIME_EXTENSION];
+    return { settings: extension.settings, secrets: extension.secrets };
+}
+export function getRuntimePluginConfiguration(options, pluginId) {
+    return projectPluginConfiguration(pluginId, installedPluginDeclaration(options.rootDir, pluginId), readPluginConfigurationStore(options.rootDir));
+}
+function requireInstallationSecrets(declaration, configuration) {
+    for (const [name, secret] of Object.entries(declaration.secrets ?? {})) {
+        if (!secret.required)
+            continue;
+        if (configuredPluginSecret(name, secret, configuration))
+            continue;
+        throw new PluginConfigurationError("plugin_secret_required", `Configure the required secret ${name} before installing.`);
+    }
+}
+/** Configuration and package selection commit under the same locks as Apply. */
+export async function saveRuntimePluginConfiguration(options, params) {
+    const source = inspectRuntimeConfigFileWithMeta(options.rootDir, options.configPath);
+    if (!source.exists)
+        throw new PluginConfigurationError("runtime_setup_required", "Complete Runtime setup before configuring plugins.", 409);
+    const rootDir = realpathSync(options.rootDir);
+    return withConfigDashboardRootTransaction(realpathSync(source.path), params.transaction, () => withPluginConfigurationLock(rootDir, async () => {
+        options.requireMutationIdle?.();
+        const declaration = installedPluginDeclaration(rootDir, params.pluginId);
+        const previous = readPluginConfigurationStore(rootDir);
+        const local = Object.hasOwn(previous.plugins, params.pluginId)
+            ? previous.plugins[params.pluginId]
+            : undefined;
+        if (params.installation && params.input === undefined) {
+            requireInstallationSecrets(declaration, local);
+            return {
+                result: await params.commit?.(),
+                configuration: projectPluginConfiguration(params.pluginId, declaration, previous),
+            };
+        }
+        const update = parsePluginConfigurationUpdate(params.input, declaration, local);
+        if (update.revision !==
+            pluginConfigurationRevision(params.pluginId, declaration, previous))
+            throw new PluginConfigurationError("plugin_configuration_changed", "Plugin configuration changed. Reload the form before saving.", 409);
+        if (params.installation)
+            requireInstallationSecrets(declaration, update.configuration);
+        options.requireMutationIdle?.();
+        const result = await commitPluginConfigurationStore(rootDir, previous, {
+            ...previous.plugins,
+            [params.pluginId]: update.configuration,
+        }, async () => params.commit?.());
+        return {
+            result,
+            configuration: projectPluginConfiguration(params.pluginId, declaration, readPluginConfigurationStore(rootDir)),
+        };
+    }));
+}