@abot-ai/runtime 1.3.1 → 1.4.0

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

@@ -0,0 +1,150 @@
+import { realpathSync } from "node:fs";
+import { ConfigFileConflictError, withConfigFileTransaction, } from "../runtime/adapters/config-file-transaction.js";
+import { inspectRuntimeConfigFileWithMeta } from "../runtime/config/loader.js";
+import { isRecord } from "../runtime/config/utils.js";
+import { validatePluginConfig } from "../runtime/config/validation/runtime-root-section-validation.js";
+import { ABOT_RUNTIME_EXTENSION } from "../plugin-contract/manifest.js";
+import { discoverConfiguredRuntimePluginManifests } from "../runtime/plugins/configured-manifests.js";
+import { normalizePluginSelection } from "../runtime/plugins/selection.js";
+import { capabilityPolicyBlockReason } from "./plugin-capability-selection.js";
+import { projectPluginSnapshot, } from "./plugin-management-catalog.js";
+import { saveConfigDashboardFile } from "./config-dashboard-backend.js";
+import { pluginSelectionEscapesRequestedScope, updatePluginSelection, } from "./plugin-management-selection.js";
+export class PluginManagementError extends Error {
+    code;
+    statusCode;
+    constructor(code, message, statusCode = 400) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+    }
+}
+function readPluginSelection(value) {
+    if (value === undefined)
+        return {};
+    if (!isRecord(value)) {
+        throw new PluginManagementError("invalid_plugin_configuration", "The plugin configuration must be an object.");
+    }
+    const issues = [];
+    validatePluginConfig(issues, value);
+    if (issues.length > 0) {
+        throw new PluginManagementError("invalid_plugin_configuration", "The plugin configuration is invalid. Review it in Advanced settings.");
+    }
+    return value;
+}
+export function getRuntimePluginSnapshot(options) {
+    const source = inspectRuntimeConfigFileWithMeta(options.rootDir, options.configPath);
+    return projectPluginSnapshot(discoverConfiguredRuntimePluginManifests(options.rootDir), readPluginSelection(source.config.plugins));
+}
+function isPluginSelectionIdentifier(value) {
+    if (typeof value !== "string")
+        return false;
+    return value.trim().length > 0;
+}
+function parsePluginToggle(input) {
+    if (!isRecord(input))
+        throw new PluginManagementError("invalid_plugin_update", "Choose a plugin and whether it should be enabled.");
+    const hasUnsupportedSelectionFields = Object.keys(input).some((key) => !["pluginId", "capabilityId", "enabled"].includes(key));
+    if (hasUnsupportedSelectionFields) {
+        throw new PluginManagementError("invalid_plugin_update", "The plugin update contains unsupported fields.");
+    }
+    if (!isPluginSelectionIdentifier(input.pluginId)) {
+        throw new PluginManagementError("invalid_plugin_update", "A plugin ID is required.");
+    }
+    if (typeof input.enabled !== "boolean") {
+        throw new PluginManagementError("invalid_plugin_update", "The enabled value must be true or false.");
+    }
+    if (input.capabilityId === undefined) {
+        return { pluginId: input.pluginId.trim(), enabled: input.enabled };
+    }
+    if (!isPluginSelectionIdentifier(input.capabilityId)) {
+        throw new PluginManagementError("invalid_plugin_update", "A capability ID must be a non-empty string.");
+    }
+    return {
+        pluginId: input.pluginId.trim(),
+        capabilityId: input.capabilityId.trim(),
+        enabled: input.enabled,
+    };
+}
+function requireCapabilityUpdateAllowed(plugin, toggle, current) {
+    const capabilityId = toggle.capabilityId;
+    if (capabilityId === undefined)
+        return;
+    const capabilities = plugin.manifest.extensions[ABOT_RUNTIME_EXTENSION].capabilities;
+    const isDeclaredCapability = Object.hasOwn(capabilities, capabilityId);
+    if (!isDeclaredCapability) {
+        throw new PluginManagementError("plugin_capability_not_found", "The selected capability does not belong to this plugin.", 404);
+    }
+    if (!toggle.enabled)
+        return;
+    const blockedReason = capabilityPolicyBlockReason({
+        pluginId: plugin.manifest.name,
+        capabilityId,
+        selection: normalizePluginSelection(current),
+    });
+    if (!blockedReason)
+        return;
+    throw new PluginManagementError("plugin_capability_blocked", blockedReason, 409);
+}
+function configuredPluginSource(options) {
+    const source = inspectRuntimeConfigFileWithMeta(options.rootDir, options.configPath);
+    if (!source.exists) {
+        throw new PluginManagementError("runtime_setup_required", "Complete Runtime setup before changing plugins.", 409);
+    }
+    return source;
+}
+export async function setRuntimePluginEnabled(options, input) {
+    const toggle = parsePluginToggle(input);
+    const source = configuredPluginSource(options);
+    const configPath = realpathSync(source.path);
+    const canonicalOptions = {
+        rootDir: realpathSync(options.rootDir),
+        configPath,
+    };
+    try {
+        return await withConfigFileTransaction(configPath, (transaction) => savePluginSelection(canonicalOptions, toggle, transaction));
+    }
+    catch (error) {
+        if (error instanceof ConfigFileConflictError)
+            throw new PluginManagementError("config_changed", error.message, 409);
+        throw error;
+    }
+}
+async function savePluginSelection(options, toggle, transaction) {
+    const source = configuredPluginSource(options);
+    const manifests = discoverConfiguredRuntimePluginManifests(options.rootDir);
+    const plugin = manifests.find((entry) => entry.manifest.name === toggle.pluginId);
+    if (!plugin)
+        throw new PluginManagementError("plugin_not_found", "The selected plugin is not installed.", 404);
+    const current = readPluginSelection(source.config.plugins);
+    const capabilityId = toggle.capabilityId;
+    requireCapabilityUpdateAllowed(plugin, toggle, current);
+    const next = updatePluginSelection({
+        current,
+        ...(capabilityId ? { capabilityId } : {}),
+        pluginId: toggle.pluginId,
+        capabilityIds: Object.keys(plugin.manifest.extensions[ABOT_RUNTIME_EXTENSION].capabilities),
+        enabled: toggle.enabled,
+    });
+    const escapesRequestedScope = pluginSelectionEscapesRequestedScope({
+        manifests,
+        pluginId: toggle.pluginId,
+        ...(capabilityId ? { capabilityId } : {}),
+        before: current,
+        after: next,
+    });
+    if (escapesRequestedScope) {
+        throw new PluginManagementError("plugin_selection_conflict", "This selection would also change other capabilities. Review the selection in Advanced settings.", 409);
+    }
+    const result = await saveConfigDashboardFile({
+        ...options,
+        kind: "runtime",
+        config: { ...source.config, plugins: next },
+        transaction,
+    });
+    return {
+        ...projectPluginSnapshot(manifests, next),
+        restartRequired: true,
+        ...(result.backupPath ? { backupPath: result.backupPath } : {}),
+    };
+}

package/dist/src/web-ui/request-authority.d.ts

@@ -0,0 +1,8 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Duplex } from "node:stream";
+/** Trust the configured listener and local interface, never request DNS or proxy headers. */
+export declare function hasTrustedWebUiAuthority(request: IncomingMessage, listenHost: string, allowPublishedLoopback?: boolean): boolean;
+/** A native client may use a Docker-published loopback port unlike the listener port. */
+export declare function hasLoopbackRequestAuthority(request: IncomingMessage): boolean;
+export declare function acceptWebUiHttpAuthority(request: IncomingMessage, response: ServerResponse, listenHost: string, allowPublishedLoopback?: boolean): boolean;
+export declare function acceptWebUiUpgradeAuthority(request: IncomingMessage, socket: Duplex, listenHost: string, allowPublishedLoopback?: boolean): boolean;

package/dist/src/web-ui/request-authority.js

@@ -0,0 +1,129 @@
+import { isIP } from "node:net";
+function normalizeIpAddress(value) {
+    const address = value.replace(/^\[|\]$/g, "");
+    const family = isIP(address);
+    if (!family)
+        return undefined;
+    const ipv6 = family === 4 ? "::ffff:" + address : address;
+    try {
+        return new URL("http://[" + ipv6 + "]").hostname;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isLoopbackAddress(address) {
+    if (!address)
+        return false;
+    if (address === "[::1]")
+        return true;
+    return /^\[::ffff:7f[0-9a-f]{2}:/.test(address);
+}
+function hasSingleHostHeader(request) {
+    let count = 0;
+    for (let index = 0; index < request.rawHeaders.length; index += 2) {
+        if (request.rawHeaders[index].toLowerCase() === "host")
+            count += 1;
+    }
+    return count === 1;
+}
+function readRequestAuthority(request) {
+    if (!hasSingleHostHeader(request))
+        return undefined;
+    const host = request.headers.host;
+    if (!host || /[\s,/\\?#@]/u.test(host))
+        return undefined;
+    const encrypted = "encrypted" in request.socket && request.socket.encrypted;
+    try {
+        return new URL((encrypted ? "https://" : "http://") + host);
+    }
+    catch {
+        return undefined;
+    }
+}
+function hasListenerPort(authority, request) {
+    const defaultPort = authority.protocol === "https:" ? 443 : 80;
+    const port = authority.port ? Number(authority.port) : defaultPort;
+    return port === request.socket.localPort;
+}
+function normalizeHostname(hostname) {
+    return hostname.toLowerCase().replace(/\.$/, "");
+}
+function isConfiguredHostname(hostname, listenHost) {
+    const configured = normalizeHostname(listenHost.trim());
+    if (["*", "0.0.0.0", "::", "[::]"].includes(configured))
+        return false;
+    return normalizeHostname(hostname) === configured;
+}
+function hasTrustedListenerHostname(hostname, localAddress, listenHost) {
+    const localIp = normalizeIpAddress(localAddress);
+    const hostIp = normalizeIpAddress(hostname);
+    if (hostIp && hostIp === localIp)
+        return true;
+    if (isConfiguredHostname(hostname, listenHost))
+        return true;
+    if (!isLoopbackAddress(localIp))
+        return false;
+    if (normalizeHostname(hostname) === "localhost")
+        return true;
+    return isLoopbackAddress(hostIp);
+}
+function hasPublishedLoopbackAuthority(request, allowed) {
+    if (!allowed)
+        return false;
+    return hasLoopbackRequestAuthority(request);
+}
+/** Trust the configured listener and local interface, never request DNS or proxy headers. */
+export function hasTrustedWebUiAuthority(request, listenHost, allowPublishedLoopback = false) {
+    const authority = readRequestAuthority(request);
+    if (!authority)
+        return false;
+    const localAddress = request.socket.localAddress;
+    if (!localAddress)
+        return false;
+    if (hasPublishedLoopbackAuthority(request, allowPublishedLoopback))
+        return true;
+    if (!hasListenerPort(authority, request))
+        return false;
+    return hasTrustedListenerHostname(authority.hostname, localAddress, listenHost);
+}
+/** A native client may use a Docker-published loopback port unlike the listener port. */
+export function hasLoopbackRequestAuthority(request) {
+    const authority = readRequestAuthority(request);
+    if (!authority)
+        return false;
+    const hostname = normalizeHostname(authority.hostname);
+    if (hostname === "localhost")
+        return true;
+    if (hostname.endsWith(".localhost"))
+        return true;
+    return isLoopbackAddress(normalizeIpAddress(hostname));
+}
+export function acceptWebUiHttpAuthority(request, response, listenHost, allowPublishedLoopback = false) {
+    if (hasTrustedWebUiAuthority(request, listenHost, allowPublishedLoopback))
+        return true;
+    response.writeHead(403, {
+        "content-type": "application/json; charset=utf-8",
+        "cache-control": "no-store",
+    });
+    response.end(JSON.stringify({
+        ok: false,
+        error: "web_ui_authority_rejected",
+        message: "Use the configured Web UI hostname or a local listener address.",
+    }));
+    return false;
+}
+function hasTrustedWebUiUpgrade(request, listenHost, allowPublishedLoopback) {
+    if (!hasTrustedWebUiAuthority(request, listenHost, allowPublishedLoopback))
+        return false;
+    const origin = request.headers.origin;
+    if (origin === undefined)
+        return true;
+    return origin === readRequestAuthority(request)?.origin;
+}
+export function acceptWebUiUpgradeAuthority(request, socket, listenHost, allowPublishedLoopback = false) {
+    if (hasTrustedWebUiUpgrade(request, listenHost, allowPublishedLoopback))
+        return true;
+    socket.destroy();
+    return false;
+}

package/dist/src/web-ui/runtime-setup-gateway-address.d.ts

@@ -0,0 +1,3 @@
+export declare function isLoopbackGateway(url: URL): boolean;
+/** Probe all configured hostname addresses; net's ADDRCONFIG can hide IPv6 loopback. */
+export declare function hasGatewayListener(port: number, host: string, ownedHost?: string): Promise<boolean>;

package/dist/src/web-ui/runtime-setup-gateway-address.js

@@ -0,0 +1,26 @@
+import { lookup } from "node:dns/promises";
+import { createConnection } from "node:net";
+export function isLoopbackGateway(url) {
+    if (url.protocol !== "http:")
+        return false;
+    return ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+}
+function probeGatewayAddress(port, host) {
+    return new Promise((resolve) => {
+        const socket = createConnection({ port, host });
+        const finish = (connected) => {
+            socket.destroy();
+            resolve(connected);
+        };
+        socket.once("connect", () => finish(true));
+        socket.once("error", () => finish(false));
+        socket.setTimeout(750, () => finish(false));
+    });
+}
+/** Probe all configured hostname addresses; net's ADDRCONFIG can hide IPv6 loopback. */
+export async function hasGatewayListener(port, host, ownedHost) {
+    const resolved = await lookup(host, { all: true, verbatim: true });
+    const addresses = [...new Set(resolved.map(({ address }) => address))].filter((address) => address !== ownedHost);
+    const listeners = await Promise.all(addresses.map((address) => probeGatewayAddress(port, address)));
+    return listeners.some(Boolean);
+}

package/dist/src/web-ui/runtime-setup-gateway.d.ts

@@ -0,0 +1,29 @@
+import { type ModelGatewayHandlerOptions } from "../model-gateway/server.js";
+import type { RuntimeSetupActivation } from "./local-runtime/runtime-setup-input.js";
+export type RuntimeSetupGatewayRestorePoint = {
+    restore(): Promise<void>;
+};
+/** Owns only a gateway started by this Web/CLI process, never an external service. */
+export declare class RuntimeSetupGateway {
+    private readonly options;
+    private owned;
+    private checkpoint;
+    private transition;
+    private closed;
+    constructor(options: ModelGatewayHandlerOptions & {
+        rootDir: string;
+    });
+    private requireGatewayOpen;
+    private configuredBinding;
+    checkActivation(configPath?: string): Promise<RuntimeSetupActivation>;
+    private captureGatewayCheckpoint;
+    /** Retains the old server's compiled handlers, without rereading saved config. */
+    createRestorePoint(): RuntimeSetupGatewayRestorePoint;
+    private restoreGatewayCheckpoint;
+    private runGatewayTransition;
+    private replaceOwnedGateway;
+    private closeGatewayListener;
+    private failAfterGatewayCleanup;
+    activate(configPath?: string): Promise<RuntimeSetupActivation>;
+    close(): Promise<void>;
+}

package/dist/src/web-ui/runtime-setup-gateway.js

@@ -0,0 +1,177 @@
+import { isLoopbackGateway, hasGatewayListener, } from "./runtime-setup-gateway-address.js";
+import { createModelGatewayServer, } from "../model-gateway/server.js";
+import { loadRuntimeConfig } from "../runtime/config.js";
+import { closeHttpServerImmediately } from "../shared/http-server-shutdown.js";
+function listenGateway(server, port, host) {
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+}
+/** Owns only a gateway started by this Web/CLI process, never an external service. */
+export class RuntimeSetupGateway {
+    options;
+    owned;
+    checkpoint;
+    transition;
+    closed = false;
+    constructor(options) {
+        this.options = options;
+    }
+    requireGatewayOpen() {
+        if (this.closed)
+            throw new Error("setup_gateway_closed");
+    }
+    configuredBinding(configPath) {
+        const config = loadRuntimeConfig({
+            rootDir: this.options.rootDir,
+            configPath,
+        });
+        const url = new URL(config.modelGatewayUrl);
+        const host = url.hostname === "[::1]" ? "::1" : url.hostname;
+        const port = Number(url.port || "80");
+        return { url, host, port };
+    }
+    async checkActivation(configPath) {
+        this.requireGatewayOpen();
+        const { url, host, port } = this.configuredBinding(configPath);
+        if (!isLoopbackGateway(url)) {
+            return {
+                status: "restart_required",
+                message: "Configuration saved. The configured model gateway is managed outside this Web UI.",
+            };
+        }
+        const ownAddress = this.owned?.server.address();
+        const ownsTargetPort = ownAddress && typeof ownAddress !== "string" && ownAddress.port === port;
+        const ownedHost = ownsTargetPort ? ownAddress.address : undefined;
+        const externalListener = await hasGatewayListener(port, host, ownedHost);
+        this.requireGatewayOpen();
+        if (externalListener) {
+            return {
+                status: "restart_required",
+                message: "Configuration saved. An existing model gateway owns this address; restart that gateway to load its new configuration.",
+            };
+        }
+        return { status: "ready" };
+    }
+    captureGatewayCheckpoint() {
+        this.requireGatewayOpen();
+        return (this.checkpoint ??= { owned: this.owned });
+    }
+    /** Retains the old server's compiled handlers, without rereading saved config. */
+    createRestorePoint() {
+        const checkpoint = this.captureGatewayCheckpoint();
+        return { restore: () => this.restoreGatewayCheckpoint(checkpoint) };
+    }
+    restoreGatewayCheckpoint(checkpoint, activationOwnsTransition = false) {
+        if (checkpoint.restoration)
+            return checkpoint.restoration;
+        if (this.checkpoint === checkpoint)
+            this.checkpoint = undefined;
+        const restore = () => this.replaceOwnedGateway(checkpoint.owned);
+        checkpoint.restoration = activationOwnsTransition
+            ? restore()
+            : this.runGatewayTransition(restore);
+        return checkpoint.restoration;
+    }
+    async runGatewayTransition(operation) {
+        this.requireGatewayOpen();
+        if (this.transition)
+            throw new Error("setup_gateway_transition_in_progress");
+        const pending = Promise.resolve().then(operation);
+        this.transition = pending;
+        try {
+            return await pending;
+        }
+        finally {
+            if (this.transition === pending)
+                this.transition = undefined;
+        }
+    }
+    async replaceOwnedGateway(target) {
+        this.requireGatewayOpen();
+        const isTargetAlreadyActive = target === this.owned && target?.server.listening === true;
+        if (isTargetAlreadyActive)
+            return;
+        const current = this.owned;
+        if (current?.server.listening) {
+            await closeHttpServerImmediately(current.server);
+            this.requireGatewayOpen();
+        }
+        this.owned = undefined;
+        if (!target)
+            return;
+        this.requireGatewayOpen();
+        this.owned = target;
+        try {
+            await listenGateway(target.server, target.port, target.host);
+            this.requireGatewayOpen();
+            const address = target.server.address();
+            if (address && typeof address !== "string") {
+                target.host = address.address;
+                target.port = address.port;
+            }
+        }
+        catch (error) {
+            return this.failAfterGatewayCleanup(target, error);
+        }
+    }
+    closeGatewayListener(owned) {
+        if (!owned.server.listening)
+            return Promise.resolve();
+        return closeHttpServerImmediately(owned.server);
+    }
+    async failAfterGatewayCleanup(target, error) {
+        try {
+            await this.closeGatewayListener(target);
+        }
+        catch (closeError) {
+            throw new AggregateError([error, closeError], "Model gateway activation failed and its listener could not be closed.");
+        }
+        if (this.owned === target)
+            this.owned = undefined;
+        throw error;
+    }
+    activate(configPath) {
+        return this.runGatewayTransition(async () => {
+            const checkpoint = this.captureGatewayCheckpoint();
+            this.checkpoint = undefined;
+            try {
+                const allowed = await this.checkActivation(configPath);
+                this.requireGatewayOpen();
+                if (allowed.status !== "ready")
+                    return allowed;
+                const { host, port } = this.configuredBinding(configPath);
+                const server = createModelGatewayServer({
+                    ...this.options,
+                    configPath,
+                });
+                await this.replaceOwnedGateway({ server, host, port });
+                this.requireGatewayOpen();
+                return { status: "ready" };
+            }
+            catch (error) {
+                if (this.closed)
+                    throw error;
+                try {
+                    await this.restoreGatewayCheckpoint(checkpoint, true);
+                }
+                catch (restoreError) {
+                    throw new AggregateError([error, restoreError], "Model gateway activation failed and the previous gateway could not be restored.");
+                }
+                throw error;
+            }
+        });
+    }
+    async close() {
+        this.closed = true;
+        await this.transition?.catch(() => { });
+        const owned = this.owned;
+        this.owned = undefined;
+        if (owned?.server.listening)
+            await closeHttpServerImmediately(owned.server);
+    }
+}

package/dist/src/web-ui/runtime-setup-shutdown.d.ts

@@ -0,0 +1,2 @@
+/** Fence both runtime owners immediately, then always release the owned gateway. */
+export declare function closeRuntimeSetupServices(closeRuntime: () => Promise<void>, closeGateway: () => Promise<void>, closeHost?: () => Promise<void>): Promise<void>;

package/dist/src/web-ui/runtime-setup-shutdown.js

@@ -0,0 +1,20 @@
+/** Fence both runtime owners immediately, then always release the owned gateway. */
+export async function closeRuntimeSetupServices(closeRuntime, closeGateway, closeHost) {
+    const failures = [];
+    const owners = closeHost ? [closeRuntime, closeHost] : [closeRuntime];
+    const outcomes = await Promise.allSettled(owners.map(async (close) => close()));
+    for (const outcome of outcomes) {
+        if (outcome.status === "rejected")
+            failures.push(outcome.reason);
+    }
+    try {
+        await closeGateway();
+    }
+    catch (error) {
+        failures.push(error);
+    }
+    if (failures.length === 1)
+        throw failures[0];
+    if (failures.length > 1)
+        throw new AggregateError(failures, "Runtime services and model gateway shutdown failed.");
+}

package/dist/src/web-ui/server.d.ts

@@ -1,10 +1,9 @@
+import type { RuntimeSetupGatewayRestorePoint } from "./runtime-setup-gateway.js";
+import type { RuntimeSetupActivation } from "./local-runtime/runtime-setup-input.js";
+import { type WebUiEnvironmentOption } from "./environment-config.js";
+export { resolveWebUiEnvironmentConfig, type WebUiEnvironmentOption, } from "./environment-config.js";
 import type { ModelProviderAdapterRegistry } from "../model-gateway/index.js";
 export type WebUiSetupCommandMode = "source" | "package";
-export type WebUiEnvironmentOption = {
-    id: string;
-    label: string;
-    isDefault: boolean;
-};
 type WebUiServerOptions = {
     host?: string;
     port?: number;
@@ -22,17 +21,11 @@ type WebUiServerOptions = {
     configPath?: string;
     setupCommandMode?: WebUiSetupCommandMode;
     providerAdapters?: ModelProviderAdapterRegistry;
+    onRuntimeSetup?: (configPath: string) => Promise<RuntimeSetupActivation>;
+    createRuntimeSetupRestorePoint?: () => RuntimeSetupGatewayRestorePoint;
+    checkRuntimeSetupActivation?: (configPath: string) => Promise<RuntimeSetupActivation>;
 };
 type WebUiServerHandle = {
     close: () => Promise<void>;
 };
-export declare function resolveWebUiEnvironmentConfig(params: {
-    rootDir: string;
-    configPath?: string;
-    defaultEnvironmentId?: string;
-}): {
-    defaultEnvironmentId: string;
-    environments: WebUiEnvironmentOption[];
-};
 export declare function startWebUiServer(overrides?: WebUiServerOptions): WebUiServerHandle;
-export {};