@abot-ai/runtime 1.4.0 → 1.5.0

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

@@ -0,0 +1,109 @@
+import { executeHostOperation, readHostStatus, } from "../../computer-access/companion/broker-client.js";
+import { DESKTOP_NOTIFICATION_CAPABILITY } from "../../computer-access/companion/notification-protocol.js";
+function hasConnectedNotificationTarget(status) {
+    if (!status.connected)
+        return false;
+    if (!status.hostId)
+        return false;
+    if (!status.connectionId)
+        return false;
+    return status.identity !== undefined;
+}
+function desktopAvailability(status) {
+    if (!status.paired)
+        return {
+            available: false,
+            message: "Set up Computer access to receive notifications on this computer.",
+        };
+    if (!status.connected)
+        return {
+            available: false,
+            message: "Computer access is disconnected. Notifications remain in your history.",
+        };
+    if (!status.capabilities?.includes(DESKTOP_NOTIFICATION_CAPABILITY))
+        return {
+            available: false,
+            computerName: status.identity?.name,
+            message: status.companion?.updateAvailable
+                ? "Update Computer access to enable desktop notifications."
+                : "Complete desktop notification setup in Computer access on this computer.",
+        };
+    return { available: true, computerName: status.identity?.name };
+}
+/** Dispatch once to the observed paired host; an uncertain result is not retried. */
+export class DesktopNotificationDelivery {
+    rootDir;
+    host;
+    constructor(rootDir, host = {
+        status: readHostStatus,
+        execute: executeHostOperation,
+    }) {
+        this.rootDir = rootDir;
+        this.host = host;
+    }
+    async status() {
+        try {
+            return desktopAvailability(await this.host.status(this.rootDir));
+        }
+        catch {
+            return {
+                available: false,
+                message: "Computer access status is unavailable. Notifications remain in your history.",
+            };
+        }
+    }
+    async send(item, signal) {
+        let status;
+        try {
+            status = await this.host.status(this.rootDir);
+        }
+        catch {
+            return {
+                status: "unavailable",
+                error: "Computer access status is unavailable.",
+            };
+        }
+        const availability = desktopAvailability(status);
+        if (!availability.available)
+            return { status: "unavailable", error: availability.message };
+        if (!hasConnectedNotificationTarget(status))
+            return {
+                status: "unavailable",
+                error: "Computer access is unavailable.",
+            };
+        if (signal.aborted)
+            return { status: "unavailable", error: "ABot is stopping." };
+        const result = await this.host.execute(this.rootDir, {
+            hostId: status.hostId,
+            connectionId: status.connectionId,
+            operation: "desktop_notification",
+            params: {
+                target: status.identity.os,
+                notificationId: item.id,
+                title: item.title,
+                body: [...item.body].slice(0, 240).join(""),
+                url: item.sourceUrl,
+            },
+            abortSignal: AbortSignal.any([signal, AbortSignal.timeout(15_000)]),
+        });
+        if (result.ok)
+            return { status: "submitted" };
+        if (result.errorCode === "system_host_outcome_unknown" ||
+            result.errorCode === "notification_outcome_unknown")
+            return {
+                status: "unknown",
+                error: "The computer did not confirm the result. This notification was not sent again.",
+            };
+        if (result.errorCode === "system_host_unavailable")
+            return {
+                status: "unavailable",
+                error: "Computer access disconnected before delivery.",
+            };
+        const hasNativeErrorText = typeof result.error === "string";
+        const nativeErrorText = hasNativeErrorText ? result.error : "";
+        const error = nativeErrorText?.slice(0, 500) ||
+            result.output?.slice(0, 500) ||
+            "The computer could not submit the notification.";
+        return { status: "failed", error };
+    }
+}

package/dist/src/web-ui/notifications/event-projection.d.ts

@@ -0,0 +1,3 @@
+import type { WebNotification } from "./contracts.js";
+/** Observe committed client output; replay and progress never create new records. */
+export declare function projectNotificationEvent(event: Record<string, unknown>, now: number): WebNotification | undefined;

package/dist/src/web-ui/notifications/event-projection.js

@@ -0,0 +1,126 @@
+import { createHash } from "node:crypto";
+function eventText(value) {
+    return typeof value === "string" ? value : "";
+}
+function hasNotificationIdentity(value) {
+    if (!value.trim() || value.length > 512)
+        return false;
+    return !/[\u0000-\u001f\u007f]/u.test(value);
+}
+function notificationBody(value) {
+    const readable = value.replace(/[\u0000-\u001f\u007f]/gu, " ");
+    return [...readable.replace(/\s+/gu, " ").trim()].slice(0, 600).join("");
+}
+function stoppedResponse(event) {
+    const details = event.details;
+    if (!details || typeof details !== "object" || Array.isArray(details))
+        return "";
+    return notificationBody(eventText(details.stoppedResponse));
+}
+function isCancelledRequestEvent(event) {
+    if (event.errorCode === "request_cancelled")
+        return true;
+    return event.error === "request_cancelled";
+}
+function failedNotification(event) {
+    const sessionId = eventText(event.sessionId);
+    const key = eventText(event.requestId);
+    if (!isCancelledRequestEvent(event))
+        return {
+            kind: "failure",
+            key,
+            sessionId,
+            title: "Request could not finish",
+            body: "Open the conversation to review what happened.",
+        };
+    const body = stoppedResponse(event);
+    if (!body)
+        return;
+    return { kind: "reply", key, sessionId, title: "Task stopped", body };
+}
+function readNotificationEvent(event) {
+    const sessionId = eventText(event.sessionId);
+    const requestId = eventText(event.requestId);
+    if (event.type === "completed") {
+        const output = notificationBody(eventText(event.output));
+        if (!output)
+            return;
+        return {
+            kind: "reply",
+            key: requestId,
+            sessionId,
+            title: "New agent reply",
+            body: output,
+        };
+    }
+    if (event.type === "failed")
+        return failedNotification(event);
+    if (event.name === "tool.approval.required") {
+        const approvalId = eventText(event.approvalId);
+        if (!hasNotificationIdentity(requestId))
+            return;
+        if (!hasNotificationIdentity(approvalId))
+            return;
+        const key = createHash("sha256")
+            .update(JSON.stringify([requestId, approvalId]))
+            .digest("hex");
+        return {
+            kind: "approval",
+            key,
+            sessionId,
+            title: "Your approval is needed",
+            body: "The agent is waiting for your decision. Open the conversation to review the action.",
+        };
+    }
+    if (event.type !== "learning.changed")
+        return;
+    const change = event.event;
+    if (!change || typeof change !== "object" || Array.isArray(change))
+        return;
+    const proposal = change;
+    if (proposal.type !== "proposal_delivered")
+        return;
+    return {
+        kind: "proposal",
+        key: eventText(proposal.proposalId),
+        sessionId: eventText(proposal.sessionId),
+        title: "New Co-worker suggestion",
+        body: "Co-worker has a new suggestion for you. Open the conversation to review it.",
+    };
+}
+/** Observe committed client output; replay and progress never create new records. */
+export function projectNotificationEvent(event, now) {
+    if (event.sessionDeleted === true)
+        return;
+    const environmentId = eventText(event.environment) || eventText(event.environmentId);
+    if (!hasNotificationIdentity(environmentId))
+        return;
+    const projected = readNotificationEvent(event);
+    if (!projected)
+        return;
+    if (!hasNotificationIdentity(projected.key))
+        return;
+    if (!hasNotificationIdentity(projected.sessionId))
+        return;
+    const id = createHash("sha256")
+        .update(JSON.stringify([environmentId, projected.kind, projected.key]))
+        .digest("hex");
+    const parameters = new URLSearchParams({
+        environment: environmentId,
+        session: projected.sessionId,
+    });
+    const requestId = eventText(event.requestId);
+    return {
+        id,
+        kind: projected.kind,
+        title: projected.title,
+        body: projected.body,
+        createdAt: now,
+        readAt: null,
+        environmentId,
+        sessionId: projected.sessionId,
+        ...(hasNotificationIdentity(requestId) ? { requestId } : {}),
+        sourceUrl: `/chat?${parameters}`,
+        delivery: { status: "pending" },
+    };
+}

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

@@ -0,0 +1,9 @@
+/** Browser attention is a short lease, never durable session read state. */
+export declare class NotificationPresence {
+    private readonly now;
+    private readonly clients;
+    constructor(now?: () => number);
+    update(client: object, message: Record<string, unknown>): void;
+    remove(client: object): void;
+    isViewing(environmentId: string, sessionId: string): boolean;
+}

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

@@ -0,0 +1,46 @@
+function isPresenceIdentity(value) {
+    if (typeof value !== "string")
+        return false;
+    if (!value.trim() || value.length > 512)
+        return false;
+    return !/[\u0000-\u001f\u007f]/u.test(value);
+}
+/** Browser attention is a short lease, never durable session read state. */
+export class NotificationPresence {
+    now;
+    clients = new Map();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    update(client, message) {
+        this.clients.delete(client);
+        if (message.active !== true)
+            return;
+        if (!isPresenceIdentity(message.environment))
+            return;
+        if (!isPresenceIdentity(message.sessionId))
+            return;
+        this.clients.set(client, {
+            environmentId: message.environment,
+            sessionId: message.sessionId,
+            expiresAt: this.now() + 60_000,
+        });
+    }
+    remove(client) {
+        this.clients.delete(client);
+    }
+    isViewing(environmentId, sessionId) {
+        const now = this.now();
+        for (const [client, presence] of this.clients) {
+            if (presence.expiresAt <= now) {
+                this.clients.delete(client);
+                continue;
+            }
+            if (presence.environmentId !== environmentId)
+                continue;
+            if (presence.sessionId === sessionId)
+                return true;
+        }
+        return false;
+    }
+}

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

@@ -0,0 +1,14 @@
+import { type NotificationListQuery, type WebNotification } from "./contracts.js";
+type NotificationCursor = {
+    version: 1;
+    environmentId: string;
+    createdAt: number;
+    id: string;
+};
+export declare function parseNotificationListQuery(params: URLSearchParams): NotificationListQuery;
+export declare function notificationPageLimit(query: NotificationListQuery): number;
+export declare function decodeNotificationCursor(raw: string | undefined, environmentId: string): NotificationCursor | null;
+export declare function encodeNotificationCursor(item: WebNotification): string;
+export declare function compareNotificationsNewestFirst(left: WebNotification, right: WebNotification): number;
+export declare function isNotificationBeforeCursor(item: WebNotification, cursor: NotificationCursor | null): boolean;
+export {};

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

@@ -0,0 +1,91 @@
+import { NotificationInputError, } from "./contracts.js";
+import { hasOnlyNotificationFields, isNotificationIdentifier, isNotificationRecord, isNotificationTimestamp, } from "./storage-schema.js";
+function isNotificationPageLimit(value) {
+    if (typeof value !== "number")
+        return false;
+    if (!Number.isSafeInteger(value))
+        return false;
+    if (value < 1)
+        return false;
+    return value <= 100;
+}
+export function parseNotificationListQuery(params) {
+    for (const key of params.keys()) {
+        if (!["environment", "limit", "before"].includes(key))
+            throw new NotificationInputError("Unknown notification query parameter.");
+        if (params.getAll(key).length !== 1)
+            throw new NotificationInputError("Repeated notification query parameter.");
+    }
+    const rawLimit = params.get("limit");
+    if (rawLimit === null)
+        return { before: params.get("before") ?? undefined };
+    if (!/^[1-9]\d{0,2}$/u.test(rawLimit))
+        throw new NotificationInputError("Notification page limit must be 1 to 100.");
+    const limit = Number(rawLimit);
+    if (!isNotificationPageLimit(limit))
+        throw new NotificationInputError("Notification page limit must be 1 to 100.");
+    return { limit, before: params.get("before") ?? undefined };
+}
+export function notificationPageLimit(query) {
+    const limit = query.limit ?? 50;
+    if (!isNotificationPageLimit(limit))
+        throw new NotificationInputError("Notification page limit must be 1 to 100.");
+    return limit;
+}
+export function decodeNotificationCursor(raw, environmentId) {
+    if (raw === undefined)
+        return null;
+    if (typeof raw !== "string")
+        throw new NotificationInputError("Invalid notification cursor.");
+    if (raw.length > 2048)
+        throw new NotificationInputError("Invalid notification cursor.");
+    if (!/^[A-Za-z0-9_-]+$/u.test(raw))
+        throw new NotificationInputError("Invalid notification cursor.");
+    let cursor;
+    try {
+        cursor = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
+    }
+    catch {
+        throw new NotificationInputError("Invalid notification cursor.");
+    }
+    if (!isNotificationRecord(cursor))
+        throw new NotificationInputError("Invalid notification cursor.");
+    if (!hasOnlyNotificationFields(cursor, [
+        "version",
+        "environmentId",
+        "createdAt",
+        "id",
+    ]))
+        throw new NotificationInputError("Invalid notification cursor.");
+    if (cursor.version !== 1)
+        throw new NotificationInputError("Invalid notification cursor.");
+    if (cursor.environmentId !== environmentId)
+        throw new NotificationInputError("Notification cursor belongs to another environment.");
+    if (!isNotificationTimestamp(cursor.createdAt))
+        throw new NotificationInputError("Invalid notification cursor.");
+    if (!isNotificationIdentifier(cursor.id))
+        throw new NotificationInputError("Invalid notification cursor.");
+    return cursor;
+}
+export function encodeNotificationCursor(item) {
+    return Buffer.from(JSON.stringify({
+        version: 1,
+        environmentId: item.environmentId,
+        createdAt: item.createdAt,
+        id: item.id,
+    })).toString("base64url");
+}
+export function compareNotificationsNewestFirst(left, right) {
+    if (left.createdAt !== right.createdAt)
+        return right.createdAt - left.createdAt;
+    if (left.id === right.id)
+        return 0;
+    return left.id < right.id ? 1 : -1;
+}
+export function isNotificationBeforeCursor(item, cursor) {
+    if (cursor === null)
+        return true;
+    if (item.createdAt !== cursor.createdAt)
+        return item.createdAt < cursor.createdAt;
+    return item.id < cursor.id;
+}

package/dist/src/web-ui/notifications/request-input.d.ts

@@ -0,0 +1,11 @@
+import { type NotificationPreferences, type NotificationReadChange } from "./contracts.js";
+export declare function parseNotificationEnvironment(value: unknown): string;
+export declare function parseNotificationReadChange(value: unknown): NotificationReadChange;
+export declare function parseNotificationReadBody(body: Record<string, unknown>): {
+    environmentId: string;
+    change: NotificationReadChange;
+};
+export declare function parseNotificationPreferencesBody(body: Record<string, unknown>): {
+    environmentId: string;
+    preferences: NotificationPreferences;
+};

package/dist/src/web-ui/notifications/request-input.js

@@ -0,0 +1,47 @@
+import { NotificationInputError, } from "./contracts.js";
+import { hasOnlyNotificationFields, isNotificationIdentifier, isNotificationPreferences, isNotificationRecord, } from "./storage-schema.js";
+export function parseNotificationEnvironment(value) {
+    if (!isNotificationIdentifier(value))
+        throw new NotificationInputError("An explicit notification environment is required.");
+    return value;
+}
+export function parseNotificationReadChange(value) {
+    if (!isNotificationRecord(value))
+        throw new NotificationInputError("Invalid notification read selection.");
+    if (!hasOnlyNotificationFields(value, ["all", "ids", "read"]))
+        throw new NotificationInputError("Invalid notification read selection.");
+    if (typeof value.read !== "boolean")
+        throw new NotificationInputError("A notification read state is required.");
+    if (value.all === true) {
+        if (value.ids !== undefined)
+            throw new NotificationInputError("Choose all notifications or explicit identities.");
+        if (value.read !== true)
+            throw new NotificationInputError("All notifications can only be marked read.");
+        return { all: true, read: true };
+    }
+    if (value.all !== undefined)
+        throw new NotificationInputError("Invalid notification read selection.");
+    if (!Array.isArray(value.ids))
+        throw new NotificationInputError("Notification identities are required.");
+    if (!value.ids.length)
+        throw new NotificationInputError("Notification identities are required.");
+    if (value.ids.length > 1000)
+        throw new NotificationInputError("Too many notification identities.");
+    if (!value.ids.every(isNotificationIdentifier))
+        throw new NotificationInputError("Invalid notification identity.");
+    return { ids: [...new Set(value.ids)], read: value.read };
+}
+export function parseNotificationReadBody(body) {
+    const { environment, ...change } = body;
+    return {
+        environmentId: parseNotificationEnvironment(environment),
+        change: parseNotificationReadChange(change),
+    };
+}
+export function parseNotificationPreferencesBody(body) {
+    const { environment, ...preferences } = body;
+    const environmentId = parseNotificationEnvironment(environment);
+    if (!isNotificationPreferences(preferences))
+        throw new NotificationInputError("Complete notification preferences are required.");
+    return { environmentId, preferences };
+}

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

@@ -0,0 +1,15 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { type NotificationDesktopState, type NotificationListQuery, type NotificationPage, type NotificationPreferences, type NotificationReadChange, type NotificationReadResult } from "./contracts.js";
+export type WebNotificationAccess = {
+    hasEnvironment(id: string): boolean;
+    list(id: string, query: NotificationListQuery): Promise<NotificationPage>;
+    desktop(id: string): NotificationDesktopState | Promise<NotificationDesktopState>;
+    markRead(id: string, change: NotificationReadChange): Promise<NotificationReadResult>;
+    setPreferences(id: string, preferences: NotificationPreferences): Promise<NotificationPreferences>;
+};
+export declare class WebNotificationRoutes {
+    private readonly access;
+    constructor(access: WebNotificationAccess);
+    handle(request: IncomingMessage, response: ServerResponse, pathname?: string): Promise<boolean>;
+    private dispatch;
+}

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

@@ -0,0 +1,125 @@
+import { acceptConfigMutationRequest } from "../local-runtime/config-mutation-request.js";
+import { readBody, readJsonBody, sendJson } from "../local-runtime/http.js";
+import { NotificationInputError, } from "./contracts.js";
+import { parseNotificationListQuery } from "./query.js";
+import { parseNotificationEnvironment, parseNotificationPreferencesBody, parseNotificationReadBody, } from "./request-input.js";
+const notificationPaths = [
+    "/web-api/notifications",
+    "/web-api/notifications/read",
+    "/web-api/notifications/preferences",
+];
+function isNotificationListRequest(path, method) {
+    if (path !== "/web-api/notifications")
+        return false;
+    return method === "GET";
+}
+function isNotificationReadRequest(path, method) {
+    if (path !== "/web-api/notifications/read")
+        return false;
+    return method === "POST";
+}
+function isNotificationPreferencesRequest(path, method) {
+    if (path !== "/web-api/notifications/preferences")
+        return false;
+    return method === "PUT";
+}
+function assertNotificationMutationHasNoQuery(url) {
+    if (!url.search)
+        return;
+    throw new NotificationInputError("Notification mutations accept their environment in the JSON body.");
+}
+function rejectUnknownNotificationEnvironment(access, id, response) {
+    if (access.hasEnvironment(id))
+        return false;
+    sendJson(response, 404, {
+        ok: false,
+        error: "notification_environment_not_found",
+        message: "Notification environment not found.",
+    });
+    return true;
+}
+async function readNotificationMutationBody(request) {
+    try {
+        return readJsonBody(await readBody(request, { maxBytes: 64 * 1024 }));
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === "request_body_too_large")
+            throw new NotificationInputError("Notification request is too large.");
+        throw new NotificationInputError("A JSON object body is required.");
+    }
+}
+export class WebNotificationRoutes {
+    access;
+    constructor(access) {
+        this.access = access;
+    }
+    async handle(request, response, pathname) {
+        const url = new URL(request.url ?? "/", "http://notification.local");
+        const path = pathname ?? url.pathname;
+        if (!notificationPaths.includes(path))
+            return false;
+        response.setHeader("cache-control", "private, no-store");
+        try {
+            await this.dispatch(request, response, url, path);
+        }
+        catch (error) {
+            if (error instanceof NotificationInputError) {
+                sendJson(response, 400, {
+                    ok: false,
+                    error: "invalid_notification_request",
+                    message: error.message,
+                });
+                return true;
+            }
+            sendJson(response, 503, {
+                ok: false,
+                error: "notification_storage_unavailable",
+                message: "Notification history is unavailable. Stored history has been preserved.",
+            });
+        }
+        return true;
+    }
+    async dispatch(request, response, url, path) {
+        if (isNotificationListRequest(path, request.method)) {
+            const query = parseNotificationListQuery(url.searchParams);
+            const environmentId = parseNotificationEnvironment(url.searchParams.get("environment"));
+            if (rejectUnknownNotificationEnvironment(this.access, environmentId, response))
+                return;
+            const page = await this.access.list(environmentId, query);
+            const desktop = await this.access.desktop(environmentId);
+            sendJson(response, 200, { ok: true, ...page, desktop });
+            return;
+        }
+        if (isNotificationReadRequest(path, request.method)) {
+            if (!acceptConfigMutationRequest(request, response))
+                return;
+            assertNotificationMutationHasNoQuery(url);
+            const { environmentId, change } = parseNotificationReadBody(await readNotificationMutationBody(request));
+            if (rejectUnknownNotificationEnvironment(this.access, environmentId, response))
+                return;
+            sendJson(response, 200, {
+                ok: true,
+                ...(await this.access.markRead(environmentId, change)),
+            });
+            return;
+        }
+        if (isNotificationPreferencesRequest(path, request.method)) {
+            if (!acceptConfigMutationRequest(request, response))
+                return;
+            assertNotificationMutationHasNoQuery(url);
+            const { environmentId, preferences } = parseNotificationPreferencesBody(await readNotificationMutationBody(request));
+            if (rejectUnknownNotificationEnvironment(this.access, environmentId, response))
+                return;
+            sendJson(response, 200, {
+                ok: true,
+                preferences: await this.access.setPreferences(environmentId, preferences),
+            });
+            return;
+        }
+        sendJson(response, 405, {
+            ok: false,
+            error: "notification_method_not_allowed",
+            message: "Notification method not allowed.",
+        });
+    }
+}

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

@@ -0,0 +1,42 @@
+import type { RuntimeConfig } from "../../runtime/ports.js";
+import type { NotificationDelivery, NotificationDesktopState, NotificationListQuery, NotificationPreferences, NotificationReadChange, WebNotification } from "./contracts.js";
+type NotificationEnvironment = {
+    services: {
+        config: RuntimeConfig;
+    };
+};
+export type NotificationServiceOptions = {
+    hasEnvironment(id: string): boolean;
+    environment(id: string): NotificationEnvironment;
+    isViewing(environmentId: string, sessionId: string): boolean;
+    changed(environmentId: string): void;
+    desktop(): Promise<NotificationDesktopState>;
+    deliver(item: WebNotification, signal: AbortSignal): Promise<NotificationDelivery>;
+    now?: () => number;
+};
+/** Owns UI notification records, never session history or model execution. */
+export declare class WebNotificationService {
+    private readonly options;
+    private readonly stores;
+    private queue;
+    private readonly deliveries;
+    private readonly abort;
+    private readonly now;
+    constructor(options: NotificationServiceOptions);
+    hasEnvironment: (id: string) => boolean;
+    private store;
+    private reconcileInterruptedDelivery;
+    observe(event: Record<string, unknown>): void;
+    private record;
+    private canSubmitDesktopNotification;
+    private desktopOutcome;
+    private deliver;
+    private reportFailure;
+    list: (environmentId: string, query?: NotificationListQuery) => Promise<import("./contracts.js").NotificationPage>;
+    desktop: (_environmentId: string) => Promise<NotificationDesktopState>;
+    markRead: (environmentId: string, change: NotificationReadChange) => Promise<import("./contracts.js").NotificationReadResult>;
+    setPreferences: (environmentId: string, preferences: NotificationPreferences) => Promise<NotificationPreferences>;
+    flush(): Promise<void>;
+    stop(): Promise<void>;
+}
+export {};