@abot-ai/runtime 1.4.0 → 1.5.0

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

@@ -0,0 +1,8 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RuntimeEnvironment } from "./contracts.js";
+export declare function cancelWebRequest(input: {
+    request: IncomingMessage;
+    response: ServerResponse;
+    body: Record<string, unknown> | null;
+    environment: RuntimeEnvironment;
+}): Promise<void>;

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

@@ -0,0 +1,34 @@
+import { acceptConfigMutationRequest } from "./config-mutation-request.js";
+import { getString, sendJson } from "./http.js";
+export async function cancelWebRequest(input) {
+    if (!acceptConfigMutationRequest(input.request, input.response))
+        return;
+    const requestId = getString(input.body?.requestId).trim();
+    const sessionId = getString(input.body?.sessionId).trim();
+    if (!requestId || !sessionId) {
+        sendJson(input.response, 400, {
+            ok: false,
+            error: "request_identity_required",
+        });
+        return;
+    }
+    const cancel = input.environment.requests.cancel;
+    if (!cancel) {
+        sendJson(input.response, 409, {
+            ok: false,
+            error: "cancellation_unavailable",
+        });
+        return;
+    }
+    const body = input.body;
+    const wait = typeof body?.waitId === "string"
+        ? {
+            waitId: body.waitId,
+            generation: getString(body.generation),
+            revision: Number(body.revision),
+            commandId: getString(body.commandId),
+        }
+        : undefined;
+    const result = await cancel(requestId, sessionId, wait);
+    sendJson(input.response, 200, { ok: true, ...result });
+}

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

@@ -3,10 +3,12 @@ import type { SchedulerRun } from "../../runtime/scheduler/contracts.js";
 import type { RuntimeRequestOptions } from "../../runtime/composition.js";
 import type { JsonObject, RuntimeEnvironment } from "./contracts.js";
 import { RealtimeClientHub } from "./realtime-hub.js";
+import { PendingToolApprovals } from "./pending-tool-approvals.js";
+import type { LocalPendingToolApproval } from "../../runtime/local-host/request-approval-contracts.js";
 export declare class LocalRequestExecution {
     private readonly realtime;
     private readonly activeRequests;
-    private readonly pendingToolApprovals;
+    readonly toolApprovals: PendingToolApprovals;
     constructor(realtime: RealtimeClientHub);
     scheduledRequestOptions(run: SchedulerRun): RuntimeRequestOptions;
     publishScheduled(payload: JsonObject): void;
@@ -16,8 +18,8 @@ export declare class LocalRequestExecution {
     healthDetails(): JsonObject[];
     handleSteer(message: JsonObject, resolveEnvironment: (id: string) => RuntimeEnvironment): Promise<JsonObject>;
     resolveToolApproval(message: JsonObject): void;
+    attachToolApproval(environmentId: string, environment: RuntimeEnvironment, pending: LocalPendingToolApproval, events: readonly JsonObject[]): Promise<void>;
     private run;
-    private createToolApprovalController;
     private publishRaw;
     private publish;
 }

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

@@ -1,5 +1,8 @@
 import { createRequestSteeringInbox, } from "../../runtime/request/request-steering.js";
 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";
 function createRequestId() {
     const random = Math.random().toString(36).slice(2, 8);
     return `web-${Date.now()}-${random}`;
@@ -7,9 +10,16 @@ function createRequestId() {
 export class LocalRequestExecution {
     realtime;
     activeRequests = new Map();
-    pendingToolApprovals = new Map();
+    toolApprovals;
     constructor(realtime) {
         this.realtime = realtime;
+        const notify = createWorkspaceChangeNotifier(realtime);
+        this.toolApprovals = new PendingToolApprovals((requestId) => this.activeRequests.get(requestId), (requestId) => {
+            const active = this.activeRequests.get(requestId);
+            if (!active)
+                return;
+            notify(active.environmentId, ["approvals"]);
+        });
     }
     scheduledRequestOptions(run) {
         const requestSteering = createRequestSteeringInbox({
@@ -27,13 +37,13 @@ export class LocalRequestExecution {
             requestSteering,
         });
         return {
-            toolApprovalController: this.createToolApprovalController(),
+            toolApprovalController: this.toolApprovals,
             requestSteering,
         };
     }
     publishScheduled(payload) {
         const isTerminal = payload.type === "completed" || payload.type === "failed";
-        const outbound = isTerminal
+        const outbound = isTerminal && payload.requestOrigin !== "approval"
             ? { ...payload, requestOrigin: "schedule" }
             : payload;
         if (payload.sessionDeleted !== true)
@@ -147,15 +157,17 @@ export class LocalRequestExecution {
             };
     }
     resolveToolApproval(message) {
-        const approvalId = getString(message.approvalId);
-        if (!approvalId)
-            return;
-        const pending = this.pendingToolApprovals.get(approvalId);
-        if (!pending)
-            return;
-        pending.resolve({
-            approved: message.approved === true,
-            reason: getString(message.reason).trim() || undefined,
+        this.toolApprovals.resolveRealtime(message);
+    }
+    attachToolApproval(environmentId, environment, pending, events) {
+        return attachApprovalRequest({
+            environmentId,
+            environment,
+            pending,
+            events,
+            activeRequests: this.activeRequests,
+            toolApprovals: this.toolApprovals,
+            publish: (data) => this.publishRaw(data, { environmentId, sessionId: pending.sessionId }),
         });
     }
     async run(environment, request, environmentId, sessionId, requestSteering) {
@@ -163,39 +175,11 @@ export class LocalRequestExecution {
             send: (data) => this.publishRaw(data, { environmentId, sessionId }),
         };
         await environment.requests.handle(localWs, request, {
-            toolApprovalController: this.createToolApprovalController(),
+            toolApprovalController: this.toolApprovals,
             requestSteering,
+            durableApprovals: true,
         });
     }
-    createToolApprovalController() {
-        return {
-            requestToolApproval: (request, options) => new Promise((resolve) => {
-                if (options?.abortSignal?.aborted) {
-                    resolve({
-                        approved: false,
-                        reason: "Tool approval was cancelled.",
-                    });
-                    return;
-                }
-                const complete = (decision) => {
-                    this.pendingToolApprovals.delete(request.approvalId);
-                    options?.abortSignal?.removeEventListener("abort", onAbort);
-                    resolve(decision);
-                };
-                const onAbort = () => complete({
-                    approved: false,
-                    reason: "Tool approval was cancelled.",
-                });
-                options?.abortSignal?.addEventListener("abort", onAbort, {
-                    once: true,
-                });
-                this.pendingToolApprovals.set(request.approvalId, {
-                    requestId: request.requestId,
-                    resolve: complete,
-                });
-            }),
-        };
-    }
     publishRaw(data, context) {
         try {
             const parsed = JSON.parse(data);
@@ -239,5 +223,12 @@ export class LocalRequestExecution {
             }
         }
         this.realtime.broadcast(payload);
+        if (payload.name === "request.lifecycle.changed") {
+            this.realtime.broadcast({
+                type: "workspace_changed",
+                environment: payload.environment,
+                resources: ["approvals", "sessions"],
+            });
+        }
     }
 }

package/dist/src/web-ui/local-runtime/runtime-availability.js

@@ -14,7 +14,7 @@ function setupRequired(source, message) {
         status: "setup_required",
         code: "runtime_configuration_required",
         message: hasExistingProfiles
-            ? "Existing model profiles need attention. Open Configuration to repair their provider, model and request-runner settings."
+            ? "Existing model profiles need attention. Open Models to repair their provider, model and request-runner settings."
             : message,
         ...(hasExistingProfiles ? { recovery: "configuration" } : {}),
     };

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

@@ -93,7 +93,7 @@ export class RuntimeSetupService {
             const source = this.source();
             const requirement = inspectRuntimeSetupRequirement(source);
             if (requirement?.recovery === "configuration")
-                throw new RuntimeSetupError("setup_configuration_exists", "Existing model profiles need repair in Configuration before setup can continue.", 409);
+                throw new RuntimeSetupError("setup_configuration_exists", "Existing model profiles need repair in Models before setup can continue.", 409);
             const existingModel = requirement
                 ? undefined
                 : configuredSetupModel(source);

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

@@ -1,6 +1,7 @@
 import type { ServerResponse } from "node:http";
 import type { RuntimeEnvironment, JsonObject } from "./contracts.js";
 import { WebSessionReadStates } from "../session-read-state/service.js";
+import type { WorkspaceChangeNotifier } from "./workspace-notifications.js";
 type SessionRouteRequest = {
     method: string;
     segments: string[];
@@ -11,7 +12,8 @@ type SessionRouteRequest = {
 };
 export declare class WebSessionRoutes {
     private readonly readStates;
-    constructor(readStates: WebSessionReadStates);
+    private readonly notifyChanged?;
+    constructor(readStates: WebSessionReadStates, notifyChanged?: WorkspaceChangeNotifier | undefined);
     handle(request: SessionRouteRequest): Promise<boolean>;
 }
 export {};

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

@@ -3,8 +3,10 @@ import { deleteSessionAttachmentsIfSupported } from "./attachment-routes.js";
 import { sendJson } from "./http.js";
 export class WebSessionRoutes {
     readStates;
-    constructor(readStates) {
+    notifyChanged;
+    constructor(readStates, notifyChanged) {
         this.readStates = readStates;
+        this.notifyChanged = notifyChanged;
     }
     async handle(request) {
         const { method, segments, body, environmentId, environment, response } = request;
@@ -49,6 +51,7 @@ export class WebSessionRoutes {
                 sendJson(response, 404, { ok: false, error: "session_not_found" });
                 return true;
             }
+            this.notifyChanged?.(environmentId, ["sessions"]);
             sendJson(response, 200, { ok: true, readState });
             return true;
         }
@@ -58,15 +61,26 @@ export class WebSessionRoutes {
                 sendJson(response, 404, { ok: false, error: "session_not_found" });
                 return true;
             }
-            await this.readStates.reset(environmentId, sessionId);
-            await deleteSessionAttachmentsIfSupported(environment, sessionId);
+            try {
+                await this.readStates.reset(environmentId, sessionId);
+                await deleteSessionAttachmentsIfSupported(environment, sessionId);
+            }
+            finally {
+                this.notifyChanged?.(environmentId, ["sessions"]);
+            }
             sendJson(response, 200, { ok: true, ...result });
             return true;
         }
         if (method === "DELETE" && !action) {
-            const result = await deleteSessionWithAttachments(sessions, environment.services.attachments, sessionId);
-            await this.readStates.forget(environmentId, sessionId);
-            sendJson(response, 200, { ok: true, ...result });
+            try {
+                const result = await deleteSessionWithAttachments(sessions, environment.services.attachments, sessionId);
+                await this.readStates.forget(environmentId, sessionId);
+                sendJson(response, 200, { ok: true, ...result });
+            }
+            finally {
+                // Cleanup can reject after deletion commits. Request a reread, not a success claim.
+                this.notifyChanged?.(environmentId, ["sessions"]);
+            }
             return true;
         }
         return false;

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

@@ -0,0 +1,21 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { JsonObject } from "./contracts.js";
+import type { PendingWebToolApproval, WebToolApprovalDecision } from "./pending-tool-approvals.js";
+export type WebToolApprovalAccess = {
+    list(environmentId: string): Promise<PendingWebToolApproval[]>;
+    decide(decision: WebToolApprovalDecision): Promise<boolean>;
+};
+type ApprovalRouteRequest = {
+    method: string;
+    segments: string[];
+    body: JsonObject | null;
+    environmentId: string;
+    request: IncomingMessage;
+    response: ServerResponse;
+};
+export declare class ToolApprovalRoutes {
+    private readonly approvals;
+    constructor(approvals: WebToolApprovalAccess);
+    handle(input: ApprovalRouteRequest): Promise<boolean>;
+}
+export {};

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

@@ -0,0 +1,70 @@
+import { acceptConfigMutationRequest } from "./config-mutation-request.js";
+import { getString, sendJson } from "./http.js";
+function hasApprovalDecisionScope(body) {
+    if (!getString(body?.environment).trim())
+        return false;
+    if (!getString(body?.sessionId).trim())
+        return false;
+    if (!getString(body?.requestId).trim())
+        return false;
+    return typeof body?.approved === "boolean";
+}
+export class ToolApprovalRoutes {
+    approvals;
+    constructor(approvals) {
+        this.approvals = approvals;
+    }
+    async handle(input) {
+        const { method, segments, body, environmentId, request, response } = input;
+        if (segments[0] !== "chat" || segments[1] !== "approvals")
+            return false;
+        response.setHeader("cache-control", "no-store");
+        if (method === "GET" && segments.length === 2) {
+            sendJson(response, 200, {
+                ok: true,
+                approvals: await this.approvals.list(environmentId),
+            });
+            return true;
+        }
+        if (method !== "POST" || segments.length !== 3)
+            return false;
+        if (!acceptConfigMutationRequest(request, response))
+            return true;
+        if (!hasApprovalDecisionScope(body)) {
+            sendJson(response, 400, {
+                ok: false,
+                error: "invalid_tool_approval_decision",
+                message: "The approval decision is missing its conversation or request.",
+            });
+            return true;
+        }
+        const accepted = await this.approvals.decide({
+            approvalId: segments[2],
+            environmentId,
+            sessionId: getString(body?.sessionId),
+            requestId: getString(body?.requestId),
+            approved: body?.approved === true,
+            ...(typeof body?.generation === "string"
+                ? { generation: body.generation }
+                : {}),
+            ...(typeof body?.waitId === "string" ? { waitId: body.waitId } : {}),
+            ...(typeof body?.revision === "number"
+                ? { revision: body.revision }
+                : {}),
+            ...(typeof body?.commandId === "string"
+                ? { commandId: body.commandId }
+                : {}),
+            ...(typeof body?.reason === "string" ? { reason: body.reason } : {}),
+        });
+        if (!accepted) {
+            sendJson(response, 409, {
+                ok: false,
+                error: "tool_approval_not_pending",
+                message: "This action is no longer waiting for your decision. Refresh to see current approvals.",
+            });
+            return true;
+        }
+        sendJson(response, 200, { ok: true, approvalId: segments[2] });
+        return true;
+    }
+}

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

@@ -0,0 +1,4 @@
+import type { RealtimeClientHub } from "./realtime-hub.js";
+export type WorkspaceChangeNotifier = (environmentId: string, resources: readonly ("sessions" | "approvals")[]) => void;
+/** Invalidate client projections only; a disconnected observer cannot undo a commit. */
+export declare function createWorkspaceChangeNotifier(realtime: Pick<RealtimeClientHub, "broadcast">): WorkspaceChangeNotifier;

package/dist/src/web-ui/local-runtime/workspace-notifications.js

@@ -0,0 +1,15 @@
+/** Invalidate client projections only; a disconnected observer cannot undo a commit. */
+export function createWorkspaceChangeNotifier(realtime) {
+    return (environmentId, resources) => {
+        try {
+            realtime.broadcast({
+                type: "workspace_changed",
+                environment: environmentId,
+                resources: [...resources],
+            });
+        }
+        catch {
+            // Reconnecting clients fetch the canonical state again.
+        }
+    };
+}

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

@@ -4,13 +4,17 @@ import type { LocalRuntimeBackendOptions } from "./local-runtime/contracts.js";
 export type { LocalRuntimeBackendOptions } from "./local-runtime/contracts.js";
 /** Stable server-facing facade for the direct Runtime Web UI backend. */
 export declare class LocalRuntimeWebBackend {
+    private readonly clients;
     private readonly environments;
     private readonly api;
     private readonly realtime;
     private readonly controls;
+    private readonly notifications;
+    private readonly notificationRoutes;
     constructor(options: LocalRuntimeBackendOptions);
     handleHttp(req: IncomingMessage, res: ServerResponse, pathname: string): Promise<boolean>;
     handleRealtimeConnection(client: WebSocket): void;
+    notifyHostConnectionChanged(): void;
     start(environmentIds: readonly string[]): Promise<void>;
     environmentConfig(): import("./environment-config.js").WebUiEnvironmentConfig | undefined;
     stop(): Promise<void>;

package/dist/src/web-ui/local-runtime-backend.js

@@ -6,12 +6,20 @@ import { sendJson } from "./local-runtime/http.js";
 import { LocalRealtimeController } from "./local-runtime/realtime-controller.js";
 import { RealtimeClientHub } from "./local-runtime/realtime-hub.js";
 import { LocalRequestExecution } from "./local-runtime/request-execution.js";
+import { createWorkspaceChangeNotifier } from "./local-runtime/workspace-notifications.js";
+import { createLearningChangeNotifier } from "./local-runtime/learning-notifications.js";
+import { WebNotificationService } from "./notifications/service.js";
+import { WebNotificationRoutes } from "./notifications/routes.js";
+import { DesktopNotificationDelivery } from "./notifications/desktop-delivery.js";
 /** Stable server-facing facade for the direct Runtime Web UI backend. */
 export class LocalRuntimeWebBackend {
+    clients;
     environments;
     api;
     realtime;
     controls;
+    notifications;
+    notificationRoutes;
     constructor(options) {
         const resolvedOptions = {
             ...options,
@@ -19,18 +27,41 @@ export class LocalRuntimeWebBackend {
                 providerAdapters: options.providerAdapters,
             }),
         };
-        const clients = new RealtimeClientHub();
+        const clients = new RealtimeClientHub((event) => this.notifications.observe(event));
+        this.clients = clients;
         const requests = new LocalRequestExecution(clients);
         this.environments = new RuntimeEnvironmentRegistry(resolvedOptions, {
             requestOptions: (run) => requests.scheduledRequestOptions(run),
             publish: (event) => requests.publishScheduled(event),
+            publishLearning: createLearningChangeNotifier(clients),
         });
-        this.api = new LocalRuntimeApiRouter(resolvedOptions, this.environments, requests);
+        const desktop = new DesktopNotificationDelivery(options.rootDir ?? process.cwd());
+        this.notifications = new WebNotificationService({
+            hasEnvironment: (id) => {
+                const configured = this.environments.environmentConfig();
+                if (!configured)
+                    return id === options.defaultEnvironmentId;
+                return configured.environments.some((environment) => environment.id === id);
+            },
+            environment: (id) => this.environments.get(id),
+            isViewing: (environment, session) => clients.presence.isViewing(environment, session),
+            changed: (environment) => clients.broadcast({
+                type: "workspace_changed",
+                environment,
+                resources: ["notifications"],
+            }),
+            desktop: () => desktop.status(),
+            deliver: (item, signal) => desktop.send(item, signal),
+        });
+        this.notificationRoutes = new WebNotificationRoutes(this.notifications);
+        this.api = new LocalRuntimeApiRouter(resolvedOptions, this.environments, requests, createWorkspaceChangeNotifier(clients));
         this.realtime = new LocalRealtimeController(resolvedOptions, this.environments, requests, clients);
         this.controls = new LocalRuntimeControlRoutes(requests);
     }
     async handleHttp(req, res, pathname) {
         try {
+            if (await this.notificationRoutes.handle(req, res, pathname))
+                return true;
             if (pathname === "/web-health" || pathname === "/web-api/health") {
                 this.controls.health(res);
                 return true;
@@ -67,6 +98,9 @@ export class LocalRuntimeWebBackend {
     handleRealtimeConnection(client) {
         this.realtime.connect(client);
     }
+    notifyHostConnectionChanged() {
+        this.clients.broadcast({ type: "system-host.changed" });
+    }
     async start(environmentIds) {
         await this.api.initializeSessionReadState(environmentIds);
         await this.environments.start(environmentIds);
@@ -74,7 +108,8 @@ export class LocalRuntimeWebBackend {
     environmentConfig() {
         return this.environments.environmentConfig();
     }
-    stop() {
-        return this.environments.stop();
+    async stop() {
+        await this.notifications.stop();
+        await this.environments.stop();
     }
 }

package/dist/src/web-ui/notifications/contracts.d.ts

@@ -0,0 +1,51 @@
+export type NotificationKind = "reply" | "failure" | "approval" | "proposal";
+export type NotificationDelivery = {
+    status: "pending" | "submitted" | "disabled" | "unavailable" | "failed" | "unknown";
+    error?: string;
+};
+export type WebNotification = {
+    id: string;
+    kind: NotificationKind;
+    title: string;
+    body: string;
+    createdAt: number;
+    readAt: number | null;
+    environmentId: string;
+    sessionId: string;
+    requestId?: string;
+    sourceUrl: string;
+    delivery: NotificationDelivery;
+};
+export type NotificationPreferences = {
+    desktopEnabled: boolean;
+    kinds: Record<NotificationKind, boolean>;
+};
+export type NotificationListQuery = {
+    limit?: number;
+    before?: string;
+};
+export type NotificationPage = {
+    items: WebNotification[];
+    unreadCount: number;
+    nextCursor: string | null;
+    preferences: NotificationPreferences;
+};
+export type NotificationReadChange = {
+    ids: string[];
+    read: boolean;
+} | {
+    all: true;
+    read: true;
+};
+export type NotificationReadResult = {
+    updated: number;
+    unreadCount: number;
+};
+export type NotificationDesktopState = {
+    available: boolean;
+    message?: string;
+    computerName?: string;
+};
+export declare class NotificationInputError extends Error {
+}
+export declare function defaultNotificationPreferences(): NotificationPreferences;

package/dist/src/web-ui/notifications/contracts.js

@@ -0,0 +1,8 @@
+export class NotificationInputError extends Error {
+}
+export function defaultNotificationPreferences() {
+    return {
+        desktopEnabled: true,
+        kinds: { reply: true, failure: true, approval: true, proposal: true },
+    };
+}

package/dist/src/web-ui/notifications/delivery-queue.d.ts

@@ -0,0 +1,6 @@
+/** Serializes desktop notifications across environments sharing one companion. */
+export declare class NotificationDeliveryQueue {
+    private pending;
+    enqueue(deliver: () => Promise<void>): Promise<void>;
+    flush(): Promise<void>;
+}

package/dist/src/web-ui/notifications/delivery-queue.js

@@ -0,0 +1,12 @@
+/** Serializes desktop notifications across environments sharing one companion. */
+export class NotificationDeliveryQueue {
+    pending = Promise.resolve();
+    enqueue(deliver) {
+        const delivery = this.pending.then(deliver);
+        this.pending = delivery.catch(() => undefined);
+        return delivery;
+    }
+    flush() {
+        return this.pending;
+    }
+}

package/dist/src/web-ui/notifications/desktop-delivery.d.ts

@@ -0,0 +1,14 @@
+import { executeHostOperation, readHostStatus } from "../../computer-access/companion/broker-client.js";
+import type { NotificationDelivery, NotificationDesktopState, WebNotification } from "./contracts.js";
+export type NotificationHostPort = {
+    status: typeof readHostStatus;
+    execute: typeof executeHostOperation;
+};
+/** Dispatch once to the observed paired host; an uncertain result is not retried. */
+export declare class DesktopNotificationDelivery {
+    private readonly rootDir;
+    private readonly host;
+    constructor(rootDir: string, host?: NotificationHostPort);
+    status(): Promise<NotificationDesktopState>;
+    send(item: WebNotification, signal: AbortSignal): Promise<NotificationDelivery>;
+}