@abot-ai/runtime 1.6.0 → 1.7.0

package/dist/src/web-ui/local-runtime/history-pagination.js

@@ -0,0 +1,20 @@
+import { DEFAULT_WEB_UI_PAGE_SIZE } from "../../runtime/config/web-ui.js";
+export function webPageSize(config) {
+    return config.webUi?.pageSize ?? DEFAULT_WEB_UI_PAGE_SIZE;
+}
+export function historyPageOptions(url, config) {
+    if (url?.searchParams.get("page") !== "1")
+        return { includeRequests: true };
+    return { includeRequests: true, page: {
+            limit: webPageSize(config), cursor: url.searchParams.get("cursor"),
+            targetMessageId: url.searchParams.get("targetMessageId") ?? undefined,
+            targetCreatedAt: url.searchParams.has("targetCreatedAt") ? Number(url.searchParams.get("targetCreatedAt")) : undefined,
+            targetRequestId: url.searchParams.get("targetRequestId") ?? undefined,
+            waitingRequestId: url.searchParams.get("waitingRequestId") ?? undefined,
+        } };
+}
+/** Compact identities stay between the session service and the read-state owner. */
+export function publicHistorySnapshot(snapshot) {
+    const { messageIndex: _index, ...publicSnapshot } = snapshot;
+    return publicSnapshot;
+}

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

@@ -0,0 +1,16 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare class PluginConfigurationRoutes {
+    private readonly options;
+    constructor(options: {
+        rootDir: string;
+        requireMutationIdle?: () => void;
+        getConfigPath?: () => string | undefined;
+    });
+    handle(params: {
+        method: string;
+        route: string;
+        body: Record<string, unknown> | null;
+        request?: IncomingMessage;
+        response: ServerResponse;
+    }): Promise<boolean>;
+}

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

@@ -0,0 +1,68 @@
+import { PluginConfigurationError } from "../../runtime/plugins/configuration-store.js";
+import { getRuntimePluginConfiguration, saveRuntimePluginConfiguration, } from "../plugin-configuration-service.js";
+import { PluginManagementError } from "../plugin-management-service.js";
+import { acceptConfigMutationRequest } from "./config-mutation-request.js";
+import { sendJson } from "./http.js";
+export class PluginConfigurationRoutes {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async handle(params) {
+        const prefix = "runtime/plugins/configuration/";
+        if (!params.route.startsWith(prefix))
+            return false;
+        params.response.setHeader("Cache-Control", "no-store");
+        try {
+            const pluginId = decodeURIComponent(params.route.slice(prefix.length));
+            const options = {
+                ...this.options,
+                configPath: this.options.getConfigPath?.(),
+            };
+            if (params.method === "GET") {
+                sendJson(params.response, 200, {
+                    ok: true,
+                    configuration: getRuntimePluginConfiguration(options, pluginId),
+                });
+                return true;
+            }
+            if (params.method !== "PUT") {
+                sendJson(params.response, 405, {
+                    ok: false,
+                    error: "method_not_allowed",
+                });
+                return true;
+            }
+            if (!params.request) {
+                sendJson(params.response, 403, {
+                    ok: false,
+                    error: "request_origin_required",
+                });
+                return true;
+            }
+            if (!acceptConfigMutationRequest(params.request, params.response))
+                return true;
+            const saved = await saveRuntimePluginConfiguration(options, {
+                pluginId,
+                input: params.body,
+            });
+            sendJson(params.response, 200, {
+                ok: true,
+                configuration: saved.configuration,
+                restartRequired: true,
+            });
+        }
+        catch (error) {
+            const known = error instanceof PluginConfigurationError ||
+                error instanceof PluginManagementError;
+            sendJson(params.response, known ? error.statusCode : 500, {
+                ok: false,
+                error: known ? error.code : "plugin_configuration_failed",
+                message: known
+                    ? error.message
+                    : "Plugin configuration could not be loaded or saved.",
+            });
+        }
+        return true;
+    }
+}

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

@@ -0,0 +1,16 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare class PluginInstallationRoutes {
+    private readonly options;
+    constructor(options: {
+        rootDir: string;
+        requireMutationIdle?: () => void;
+        getConfigPath?: () => string | undefined;
+    });
+    handle(params: {
+        method: string;
+        route: string;
+        body: Record<string, unknown> | null;
+        request?: IncomingMessage;
+        response: ServerResponse;
+    }): Promise<boolean>;
+}

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

@@ -0,0 +1,96 @@
+import { projectPluginConfiguration } from "../plugin-configuration-view.js";
+import { saveRuntimePluginConfiguration } from "../plugin-configuration-service.js";
+import { PluginConfigurationError, readPluginConfigurationStore, } from "../../runtime/plugins/configuration-store.js";
+import { PluginInstallError } from "../../plugin-contract/install-source.js";
+import { inspectPluginPackage, installPluginPackage, } from "../../runtime/plugins/installation/service.js";
+import { inspectRuntimeConfigFileWithMeta } from "../../runtime/config/loader.js";
+import { PluginManagementError, setRuntimePluginEnabled, } from "../plugin-management-service.js";
+import { acceptConfigMutationRequest } from "./config-mutation-request.js";
+import { sendJson } from "./http.js";
+export class PluginInstallationRoutes {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async handle(params) {
+        if (!["runtime/plugins/inspect", "runtime/plugins/install"].includes(params.route))
+            return false;
+        if (params.method !== "POST") {
+            sendJson(params.response, 405, {
+                ok: false,
+                error: "method_not_allowed",
+            });
+            return true;
+        }
+        if (!params.request) {
+            sendJson(params.response, 403, {
+                ok: false,
+                error: "request_origin_required",
+            });
+            return true;
+        }
+        if (!acceptConfigMutationRequest(params.request, params.response))
+            return true;
+        try {
+            const configPath = this.options.getConfigPath?.();
+            const configuration = inspectRuntimeConfigFileWithMeta(this.options.rootDir, configPath);
+            if (!configuration.exists)
+                throw new PluginInstallError("runtime_setup_required", "Complete Runtime setup before installing plugins.", 409);
+            if (params.route === "runtime/plugins/inspect") {
+                const review = await inspectPluginPackage(this.options.rootDir, params.body);
+                const configuration = projectPluginConfiguration(review.id, {
+                    settings: { defaults: review.settings },
+                    secrets: Object.fromEntries(review.secrets.map(({ name, env, required }) => [
+                        name,
+                        { env, required },
+                    ])),
+                }, readPluginConfigurationStore(this.options.rootDir));
+                sendJson(params.response, 200, {
+                    ok: true,
+                    review: { ...review, configuration },
+                });
+                return true;
+            }
+            this.options.requireMutationIdle?.();
+            const result = await installPluginPackage({
+                requireMutationIdle: this.options.requireMutationIdle,
+                rootDir: this.options.rootDir,
+                configPath: configuration.path,
+                input: params.body,
+                saveSelection: async (pluginId, transaction) => {
+                    const options = {
+                        rootDir: this.options.rootDir,
+                        configPath,
+                        requireMutationIdle: this.options.requireMutationIdle,
+                    };
+                    const saved = await saveRuntimePluginConfiguration(options, {
+                        pluginId,
+                        input: params.body?.configuration,
+                        transaction,
+                        installation: true,
+                        commit: () => setRuntimePluginEnabled(options, { pluginId, enabled: true }, transaction),
+                    });
+                    return saved.result;
+                },
+            });
+            sendJson(params.response, 200, {
+                ok: true,
+                ...result.snapshot,
+                installed: result.installed,
+            });
+        }
+        catch (error) {
+            const known = error instanceof PluginConfigurationError ||
+                error instanceof PluginInstallError ||
+                error instanceof PluginManagementError;
+            sendJson(params.response, known ? error.statusCode : 500, {
+                ok: false,
+                error: known ? error.code : "plugin_installation_failed",
+                message: known
+                    ? error.message
+                    : "The plugin could not be installed. No existing plugin was replaced.",
+            });
+        }
+        return true;
+    }
+}

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

@@ -1,14 +1,21 @@
-import type { ServerResponse } from "node:http";
+import type { PluginRemovalRuntime } from "../plugin-removal-service.js";
+import type { IncomingMessage, ServerResponse } from "node:http";
 export declare class PluginManagementRoutes {
     private readonly options;
+    private readonly configuration;
+    private readonly removal;
+    private readonly installation;
     constructor(options: {
         rootDir: string;
+        requireMutationIdle?: () => void;
+        removalRuntime?: PluginRemovalRuntime;
         getConfigPath?: () => string | undefined;
     });
     handle(params: {
         method: string;
         route: string;
         body: Record<string, unknown> | null;
+        request?: IncomingMessage;
         response: ServerResponse;
     }): Promise<boolean>;
 }

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

@@ -1,16 +1,32 @@
+import { PluginConfigurationRoutes } from "./plugin-configuration-routes.js";
+import { PluginRemovalRoutes } from "./plugin-removal-routes.js";
+import { PluginInstallationRoutes } from "./plugin-installation-routes.js";
 import { getRuntimePluginSnapshot, PluginManagementError, setRuntimePluginEnabled, } from "../plugin-management-service.js";
 import { sendJson } from "./http.js";
 export class PluginManagementRoutes {
     options;
+    configuration;
+    removal;
+    installation;
     constructor(options) {
         this.options = options;
+        this.configuration = new PluginConfigurationRoutes(options);
+        this.removal = new PluginRemovalRoutes(options);
+        this.installation = new PluginInstallationRoutes(options);
     }
     async handle(params) {
+        if (await this.configuration.handle(params))
+            return true;
+        if (await this.installation.handle(params))
+            return true;
+        if (await this.removal.handle(params))
+            return true;
         if (params.route !== "runtime/plugins")
             return false;
         const options = {
             rootDir: this.options.rootDir,
             configPath: this.options.getConfigPath?.(),
+            requireMutationIdle: this.options.requireMutationIdle,
         };
         try {
             if (params.method === "GET") {
@@ -21,6 +37,7 @@ export class PluginManagementRoutes {
                 return true;
             }
             if (params.method === "PUT") {
+                this.options.requireMutationIdle?.();
                 const result = await setRuntimePluginEnabled(options, params.body);
                 sendJson(params.response, 200, { ok: true, ...result });
                 return true;

package/dist/src/web-ui/local-runtime/plugin-mutation-admission.d.ts

@@ -0,0 +1,7 @@
+import type { RuntimeEnvironment } from "./contracts.js";
+/** A saved plugin change must not start while any owning Runtime is working. */
+export declare function requirePluginOwnersIdle(options: {
+    environments: Iterable<RuntimeEnvironment>;
+    busy: boolean;
+    unavailable: boolean;
+}): void;

package/dist/src/web-ui/local-runtime/plugin-mutation-admission.js

@@ -0,0 +1,17 @@
+import { PluginManagementError } from "../plugin-management-service.js";
+/** A saved plugin change must not start while any owning Runtime is working. */
+export function requirePluginOwnersIdle(options) {
+    if (options.unavailable)
+        throw new PluginManagementError("plugin_mutation_unavailable", "Apply Runtime configuration before changing plugins.", 409);
+    if (options.busy)
+        throw busyPluginMutation();
+    for (const environment of options.environments) {
+        if (environment.getOwnership() !== "owner")
+            throw new PluginManagementError("plugin_owner_unavailable", "This Web UI cannot verify that the owning Runtime is idle. Open Plugins in the Web UI that owns this Runtime.", 409);
+        if (!environment.isOwnerIdle())
+            throw busyPluginMutation();
+    }
+}
+function busyPluginMutation() {
+    return new PluginManagementError("plugin_runtime_busy", "Your agent is working. Wait for active conversations and Jobs to finish before changing plugins.", 409);
+}

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

@@ -0,0 +1,18 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type PluginRemovalRuntime } from "../plugin-removal-service.js";
+export declare class PluginRemovalRoutes {
+    private readonly options;
+    constructor(options: {
+        rootDir: string;
+        requireMutationIdle?: () => void;
+        getConfigPath?: () => string | undefined;
+        removalRuntime?: PluginRemovalRuntime;
+    });
+    handle(params: {
+        method: string;
+        route: string;
+        body: Record<string, unknown> | null;
+        request?: IncomingMessage;
+        response: ServerResponse;
+    }): Promise<boolean>;
+}

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

@@ -0,0 +1,60 @@
+import { ConfigFileConflictError } from "../../runtime/adapters/config-file-transaction.js";
+import { PluginRemovalActivationError } from "../plugin-removal-error.js";
+import { PluginManagementError } from "../plugin-management-service.js";
+import { removeRuntimePlugin, } from "../plugin-removal-service.js";
+import { acceptConfigMutationRequest } from "./config-mutation-request.js";
+import { sendJson } from "./http.js";
+export class PluginRemovalRoutes {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async handle(params) {
+        if (params.route !== "runtime/plugins/remove")
+            return false;
+        if (params.method !== "POST") {
+            sendJson(params.response, 405, {
+                ok: false,
+                error: "method_not_allowed",
+            });
+            return true;
+        }
+        if (!params.request) {
+            sendJson(params.response, 403, {
+                ok: false,
+                error: "request_origin_required",
+            });
+            return true;
+        }
+        if (!acceptConfigMutationRequest(params.request, params.response))
+            return true;
+        try {
+            if (!this.options.removalRuntime)
+                throw new PluginManagementError("plugin_removal_unavailable", "This Runtime cannot apply plugin removal.", 409);
+            this.options.requireMutationIdle?.();
+            const result = await removeRuntimePlugin({
+                rootDir: this.options.rootDir,
+                requireMutationIdle: this.options.requireMutationIdle,
+                configPath: this.options.getConfigPath?.(),
+                ...this.options.removalRuntime,
+            }, params.body);
+            sendJson(params.response, 200, { ok: true, ...result });
+        }
+        catch (error) {
+            const known = error instanceof PluginManagementError ||
+                error instanceof ConfigFileConflictError;
+            const status = error instanceof PluginManagementError ? error.statusCode : 500;
+            sendJson(params.response, error instanceof ConfigFileConflictError ? 409 : status, {
+                ok: false,
+                ...(error instanceof PluginRemovalActivationError
+                    ? { activation: error.activation }
+                    : {}),
+                error: known ? error.code : "plugin_removal_failed",
+                message: known
+                    ? error.message
+                    : "Plugin removal could not complete. Refresh plugins before trying again.",
+            });
+        }
+        return true;
+    }
+}

package/dist/src/web-ui/local-runtime/realtime-controller.js

@@ -1,5 +1,7 @@
 import { getNumber, getString, requestEnvironmentId } from "./http.js";
 import { ManagedWebToolApprovals } from "./managed-tool-approvals.js";
+import { diagnosticErrorType } from "../../runtime/observability/request-control-diagnostics.js";
+import { traceWebRequestControl } from "./request-control-observation.js";
 export class LocalRealtimeController {
     options;
     environments;
@@ -47,18 +49,42 @@ export class LocalRealtimeController {
             return;
         }
         if (message.type === "steer_request") {
-            this.clients.send(client, await this.requests.handleSteer(message, (id) => this.environments.get(id)));
+            const acknowledgement = await this.requests.handleSteer(message, (id) => this.environments.get(id));
+            traceWebRequestControl("steer.ack_dispatch_attempted", {
+                requestId: getString(acknowledgement.requestId),
+                steerId: getString(acknowledgement.steerId),
+                accepted: acknowledgement.accepted === true,
+                reason: getString(acknowledgement.reason) || undefined,
+                socketReadyState: client.readyState,
+            });
+            this.clients.send(client, acknowledgement);
             return;
         }
         if (message.type !== "resume_request")
             return;
-        await this.resume(client, message);
+        try {
+            await this.resume(client, message);
+        }
+        catch (error) {
+            traceWebRequestControl("resume.failed", {
+                requestId: getString(message.requestId),
+                requestedEnvironment: getString(message.environment),
+                errorType: diagnosticErrorType(error),
+            });
+            throw error;
+        }
     }
     async resume(client, message) {
         const requestId = getString(message.requestId);
         if (!requestId)
             return;
         const environmentId = requestEnvironmentId(new URL("/", "http://localhost"), message, this.options.defaultEnvironmentId);
+        const startedAt = Date.now();
+        traceWebRequestControl("resume.received", {
+            requestId,
+            environmentId,
+            afterSeq: getNumber(message.afterSeq),
+        });
         const environment = this.environments.get(environmentId);
         let replay = await environment.services.sessions.getRequestReplayById(requestId, getNumber(message.afterSeq));
         if (!replay?.finalState) {
@@ -86,5 +112,18 @@ export class LocalRealtimeController {
                 error: replay.finalState.error,
             });
         }
+        // A returned send call is not a browser delivery acknowledgement.
+        traceWebRequestControl("resume.dispatch_returned", {
+            requestId,
+            environmentId,
+            afterSeq: getNumber(message.afterSeq),
+            replayFound: replay !== null && replay !== undefined,
+            sessionId: replay?.sessionId,
+            eventCount: replay?.events.length ?? 0,
+            lifecycleStatus: replay?.lifecycle?.status,
+            finalStateStatus: replay?.finalState?.status,
+            socketReadyState: client.readyState,
+            elapsedMs: Date.now() - startedAt,
+        });
     }
 }

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

@@ -1,5 +1,7 @@
 import { acceptConfigMutationRequest } from "./config-mutation-request.js";
 import { getString, sendJson } from "./http.js";
+import { diagnosticErrorType } from "../../runtime/observability/request-control-diagnostics.js";
+import { traceWebRequestControl } from "./request-control-observation.js";
 export async function cancelWebRequest(input) {
     if (!acceptConfigMutationRequest(input.request, input.response))
         return;
@@ -29,6 +31,31 @@ export async function cancelWebRequest(input) {
             commandId: getString(body.commandId),
         }
         : undefined;
-    const result = await cancel(requestId, sessionId, wait);
+    const fields = {
+        requestId,
+        sessionId,
+        environmentId: input.environment.services?.config?.runtimeId,
+        hasWaitIdentity: wait !== undefined,
+    };
+    const startedAt = Date.now();
+    traceWebRequestControl("cancel.received", fields);
+    let result;
+    try {
+        result = await cancel(requestId, sessionId, wait);
+    }
+    catch (error) {
+        traceWebRequestControl("cancel.failed", {
+            ...fields,
+            errorType: diagnosticErrorType(error),
+            elapsedMs: Date.now() - startedAt,
+        });
+        throw error;
+    }
+    traceWebRequestControl("cancel.result", {
+        ...fields,
+        accepted: result.accepted,
+        reason: result.accepted ? undefined : result.reason,
+        elapsedMs: Date.now() - startedAt,
+    });
     sendJson(input.response, 200, { ok: true, ...result });
 }

package/dist/src/web-ui/local-runtime/request-control-observation.d.ts

@@ -0,0 +1,19 @@
+import { type RequestControlDiagnosticFields } from "../../runtime/observability/request-control-diagnostics.js";
+import type { ActiveRequest, JsonObject } from "./contracts.js";
+export declare function traceWebRequestControl(event: string, fields: RequestControlDiagnosticFields): void;
+export declare function traceWebProjection(event: "projection.opened" | "projection.removed", requestId: string, active: ActiveRequest | undefined, reason: string, removed?: boolean): void;
+export declare function webSteerRoute(active: ActiveRequest | undefined, steer: unknown): string;
+/** Observes the existing routing decision; it never queries or changes an owner. */
+export declare class WebSteerObservation {
+    private readonly requestId;
+    private readonly steerId;
+    private readonly active;
+    private readonly currentProjection;
+    private readonly startedAt;
+    private route;
+    constructor(requestId: string, steerId: string, requestedEnvironment: string, textLength: number, active: ActiveRequest | undefined, currentProjection: () => ActiveRequest | undefined);
+    selectRoute(route: string): void;
+    result(acknowledgement: JsonObject): void;
+    failed(error: unknown): void;
+    private trace;
+}

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

@@ -0,0 +1,80 @@
+import { diagnosticErrorType, traceRequestControl, } from "../../runtime/observability/request-control-diagnostics.js";
+import { getString } from "./http.js";
+export function traceWebRequestControl(event, fields) {
+    traceRequestControl("web.request_control", event, fields);
+}
+function projectionFields(active) {
+    return {
+        projectionPresent: active !== undefined,
+        environmentId: active?.environmentId,
+        sessionId: active?.sessionId,
+        projectionStartedAt: active?.startedAt,
+        lastEventAt: active?.lastEventAt,
+        finalStateStatus: getString(active?.finalState?.status) || undefined,
+    };
+}
+export function traceWebProjection(event, requestId, active, reason, removed) {
+    traceWebRequestControl(event, {
+        requestId,
+        ...projectionFields(active),
+        reason,
+        removed,
+    });
+}
+export function webSteerRoute(active, steer) {
+    if (!active)
+        return "web_projection_missing";
+    if (steer)
+        return "runtime_owner";
+    return "local_inbox";
+}
+/** Observes the existing routing decision; it never queries or changes an owner. */
+export class WebSteerObservation {
+    requestId;
+    steerId;
+    active;
+    currentProjection;
+    startedAt = Date.now();
+    route = "not_routed";
+    constructor(requestId, steerId, requestedEnvironment, textLength, active, currentProjection) {
+        this.requestId = requestId;
+        this.steerId = steerId;
+        this.active = active;
+        this.currentProjection = currentProjection;
+        traceWebRequestControl("steer.received", {
+            requestId,
+            steerId,
+            requestedEnvironment,
+            textLength,
+            ...projectionFields(active),
+        });
+    }
+    selectRoute(route) {
+        this.route = route;
+    }
+    result(acknowledgement) {
+        this.trace("steer.result", {
+            accepted: acknowledgement.accepted === true,
+            reason: getString(acknowledgement.reason) || undefined,
+            acceptedSequence: typeof acknowledgement.acceptedSequence === "number"
+                ? acknowledgement.acceptedSequence
+                : undefined,
+        });
+    }
+    failed(error) {
+        this.trace("steer.failed", { errorType: diagnosticErrorType(error) });
+    }
+    trace(event, fields) {
+        const current = this.currentProjection();
+        traceWebRequestControl(event, {
+            requestId: this.requestId,
+            steerId: this.steerId,
+            route: this.route,
+            ...projectionFields(this.active),
+            currentProjectionPresent: current !== undefined,
+            projectionStillCurrent: this.active !== undefined && current === this.active,
+            elapsedMs: Date.now() - this.startedAt,
+            ...fields,
+        });
+    }
+}