@abot-ai/runtime 1.4.0 → 1.6.0

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 {};

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

@@ -0,0 +1,162 @@
+import { assertValidSessionId } from "../../sessions/record/rules.js";
+import { loadSessionFile } from "../../sessions/session-store.js";
+import { NotificationDeliveryQueue } from "./delivery-queue.js";
+import { projectNotificationEvent } from "./event-projection.js";
+import { WebNotificationStore, notificationStorePath } from "./store.js";
+function isSuppressedReply(item, options) {
+    if (item.kind !== "reply")
+        return false;
+    return options.isViewing(item.environmentId, item.sessionId);
+}
+function hasValidPersistedSessionReference(sessionId) {
+    try {
+        assertValidSessionId(sessionId);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isCompletedConversationNotification(event, item) {
+    if (event.type !== "completed")
+        return false;
+    return item.kind !== "automation";
+}
+function permitsDesktopNotification(preferences, item) {
+    if (!preferences.desktopEnabled)
+        return false;
+    return preferences.kinds[item.kind];
+}
+/** Owns UI notification records, never session history or model execution. */
+export class WebNotificationService {
+    options;
+    stores = new Map();
+    queue = Promise.resolve();
+    deliveries = new NotificationDeliveryQueue();
+    abort = new AbortController();
+    now;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? Date.now;
+    }
+    hasEnvironment = (id) => {
+        return this.options.hasEnvironment(id);
+    };
+    store(environmentId) {
+        const { paths } = this.options.environment(environmentId).services.config;
+        const path = notificationStorePath({
+            environmentId,
+            runtimeDir: paths.runtimeDir,
+            sessionsDir: paths.sessionsDir,
+        });
+        const existing = this.stores.get(path);
+        if (existing)
+            return existing;
+        const store = new WebNotificationStore(path, environmentId);
+        const opening = this.reconcileInterruptedDelivery(store).catch((error) => {
+            this.stores.delete(path);
+            throw error;
+        });
+        this.stores.set(path, opening);
+        return opening;
+    }
+    async reconcileInterruptedDelivery(store) {
+        await store.reconcilePendingDeliveries();
+        return store;
+    }
+    observe(event) {
+        if (this.abort.signal.aborted)
+            return;
+        const observedAt = this.now();
+        const item = projectNotificationEvent(event, observedAt);
+        if (!item || isSuppressedReply(item, this.options))
+            return;
+        if (!this.hasEnvironment(item.environmentId))
+            return;
+        if (item.kind !== "automation" &&
+            !hasValidPersistedSessionReference(item.sessionId))
+            return;
+        this.queue = this.queue
+            .then(async () => {
+            if (item.kind === "automation")
+                return this.record(item);
+            const { sessionsDir } = this.options.environment(item.environmentId).services.config.paths;
+            const persisted = await loadSessionFile(sessionsDir, item.sessionId);
+            const hasPersistedConversation = persisted !== null;
+            if (!hasPersistedConversation && isCompletedConversationNotification(event, item))
+                return;
+            const projected = projectNotificationEvent(event, observedAt, persisted);
+            if (projected)
+                await this.record(projected);
+        })
+            .catch((error) => this.reportFailure(item.environmentId, error));
+    }
+    async record(item) {
+        const store = await this.store(item.environmentId);
+        const preferences = await store.getPreferences();
+        const shouldDeliver = permitsDesktopNotification(preferences, item);
+        const result = await store.upsert({
+            ...item,
+            delivery: { status: shouldDeliver ? "pending" : "disabled" },
+        });
+        if (!result.created)
+            return;
+        this.options.changed(item.environmentId);
+        if (!shouldDeliver)
+            return;
+        void this.deliveries
+            .enqueue(() => this.deliver(store, result.item))
+            .catch((error) => this.reportFailure(item.environmentId, error));
+    }
+    canSubmitDesktopNotification() {
+        return !this.abort.signal.aborted;
+    }
+    async desktopOutcome(item, preferences) {
+        if (!this.canSubmitDesktopNotification())
+            return {
+                status: "unavailable",
+                error: "ABot stopped before desktop delivery started.",
+            };
+        if (!permitsDesktopNotification(preferences, item))
+            return { status: "disabled" };
+        try {
+            return await this.options.deliver(item, this.abort.signal);
+        }
+        catch {
+            return {
+                status: "unknown",
+                error: "Desktop delivery was not confirmed.",
+            };
+        }
+    }
+    async deliver(store, item) {
+        const preferences = await store.getPreferences();
+        const delivery = await this.desktopOutcome(item, preferences);
+        await store.updateDelivery(item.id, delivery);
+        this.options.changed(item.environmentId);
+    }
+    reportFailure(environmentId, error) {
+        console.error(`Notification history unavailable for ${environmentId}:`, error);
+    }
+    list = async (environmentId, query) => (await this.store(environmentId)).list(query);
+    desktop = (_environmentId) => this.options.desktop();
+    markRead = async (environmentId, change) => {
+        const result = await (await this.store(environmentId)).markRead(change, this.now());
+        if (result.updated)
+            this.options.changed(environmentId);
+        return result;
+    };
+    setPreferences = async (environmentId, preferences) => {
+        const result = await (await this.store(environmentId)).setPreferences(preferences);
+        this.options.changed(environmentId);
+        return result;
+    };
+    async flush() {
+        await this.queue;
+        await this.deliveries.flush();
+    }
+    async stop() {
+        this.abort.abort();
+        await this.flush();
+    }
+}

package/dist/src/web-ui/notifications/storage-schema.d.ts

@@ -0,0 +1,15 @@
+import type { NotificationDelivery, NotificationPreferences, WebNotification } from "./contracts.js";
+export type NotificationStoreState = {
+    version: 1;
+    environmentId: string;
+    items: WebNotification[];
+    preferences: NotificationPreferences;
+};
+export declare function isNotificationRecord(value: unknown): value is Record<string, unknown>;
+export declare function hasOnlyNotificationFields(value: Record<string, unknown>, allowed: readonly string[]): boolean;
+export declare function isNotificationIdentifier(value: unknown): value is string;
+export declare function isNotificationTimestamp(value: unknown): value is number;
+export declare function isNotificationPreferences(value: unknown): value is NotificationPreferences;
+export declare function isNotificationDelivery(value: unknown): value is NotificationDelivery;
+export declare function isWebNotification(value: unknown, environmentId: string): value is WebNotification;
+export declare function decodeNotificationState(raw: string, environmentId: string): NotificationStoreState;

package/dist/src/web-ui/notifications/storage-schema.js

@@ -0,0 +1,267 @@
+import { SPARK_SESSION_ID } from "../../sessions/spark-session.js";
+export function isNotificationRecord(value) {
+    if (value === null)
+        return false;
+    if (typeof value !== "object")
+        return false;
+    return !Array.isArray(value);
+}
+export function hasOnlyNotificationFields(value, allowed) {
+    return Object.keys(value).every((key) => allowed.includes(key));
+}
+export function isNotificationIdentifier(value) {
+    if (typeof value !== "string")
+        return false;
+    if (value.trim() !== value)
+        return false;
+    if (!value.length)
+        return false;
+    if (value.length > 512)
+        return false;
+    return !/[\u0000-\u001f\u007f]/u.test(value);
+}
+export function isNotificationTimestamp(value) {
+    if (typeof value !== "number")
+        return false;
+    if (!Number.isSafeInteger(value))
+        return false;
+    return value >= 0;
+}
+function isNotificationText(value, maximum) {
+    if (typeof value !== "string")
+        return false;
+    return value.length <= maximum;
+}
+export function isNotificationPreferences(value) {
+    if (!isNotificationRecord(value))
+        return false;
+    if (!hasOnlyNotificationFields(value, ["desktopEnabled", "kinds"]))
+        return false;
+    if (typeof value.desktopEnabled !== "boolean")
+        return false;
+    if (!isNotificationRecord(value.kinds))
+        return false;
+    const kinds = ["reply", "failure", "approval", "proposal", "automation"];
+    const preferences = value.kinds;
+    if (!hasOnlyNotificationFields(preferences, kinds))
+        return false;
+    return kinds.every((kind) => typeof preferences[kind] === "boolean");
+}
+function normalizeStoredNotificationPreferences(value) {
+    if (isNotificationPreferences(value))
+        return value;
+    if (!isNotificationRecord(value))
+        return null;
+    if (!hasOnlyNotificationFields(value, ["desktopEnabled", "kinds"]))
+        return null;
+    if (typeof value.desktopEnabled !== "boolean")
+        return null;
+    if (!isNotificationRecord(value.kinds))
+        return null;
+    const kinds = value.kinds;
+    const legacyKinds = ["reply", "failure", "approval", "proposal"];
+    if (!hasOnlyNotificationFields(kinds, legacyKinds))
+        return null;
+    if (!legacyKinds.every((kind) => typeof kinds[kind] === "boolean"))
+        return null;
+    return {
+        desktopEnabled: value.desktopEnabled,
+        kinds: {
+            reply: kinds.reply,
+            failure: kinds.failure,
+            approval: kinds.approval,
+            proposal: kinds.proposal,
+            automation: true,
+        },
+    };
+}
+export function isNotificationDelivery(value) {
+    if (!isNotificationRecord(value))
+        return false;
+    if (!hasOnlyNotificationFields(value, ["status", "error"]))
+        return false;
+    const statuses = [
+        "pending",
+        "submitted",
+        "disabled",
+        "unavailable",
+        "failed",
+        "unknown",
+    ];
+    if (typeof value.status !== "string")
+        return false;
+    if (!statuses.includes(value.status))
+        return false;
+    if (value.error === undefined)
+        return true;
+    return isNotificationText(value.error, 4096);
+}
+function sparkNotificationSourceTarget(value, source) {
+    if (value.sessionKind !== "spark")
+        return null;
+    if (value.sessionId !== SPARK_SESSION_ID)
+        return null;
+    const parameters = {
+        environment: value.environmentId,
+        spark: "1",
+    };
+    const message = source.get("message");
+    const createdAt = source.get("messageCreatedAt");
+    const request = source.get("request");
+    if (message === null && createdAt === null && request === null)
+        return { path: "/home", parameters };
+    if (!isNotificationIdentifier(message))
+        return null;
+    if (createdAt === null || !isNotificationTimestamp(Number(createdAt)))
+        return null;
+    if (String(Number(createdAt)) !== createdAt)
+        return null;
+    parameters.message = message;
+    parameters.messageCreatedAt = createdAt;
+    if (request !== (value.requestId ?? null))
+        return null;
+    if (request !== null)
+        parameters.request = request;
+    return { path: "/home", parameters };
+}
+function notificationSourceTarget(value, source) {
+    if (value.kind === "automation") {
+        if (!isNotificationIdentifier(value.automationId))
+            return null;
+        if (!isNotificationIdentifier(value.runId))
+            return null;
+        if (value.sessionId !== undefined)
+            return null;
+        if (value.sessionKind !== undefined)
+            return null;
+        if (value.requestId !== undefined)
+            return null;
+        return {
+            path: "/automations",
+            parameters: {
+                environment: value.environmentId,
+                automation: value.automationId,
+                run: value.runId,
+            },
+        };
+    }
+    if (!isNotificationIdentifier(value.sessionId))
+        return null;
+    if (value.automationId !== undefined)
+        return null;
+    if (value.runId !== undefined)
+        return null;
+    if (value.requestId !== undefined && !isNotificationIdentifier(value.requestId))
+        return null;
+    if (value.sessionKind !== undefined)
+        return sparkNotificationSourceTarget(value, source);
+    return {
+        path: "/chat",
+        parameters: {
+            environment: value.environmentId,
+            session: value.sessionId,
+        },
+    };
+}
+function hasBoundNotificationSource(value) {
+    if (typeof value.sourceUrl !== "string")
+        return false;
+    try {
+        const url = new URL(value.sourceUrl, "http://notification.local");
+        const target = notificationSourceTarget(value, url.searchParams);
+        if (!target)
+            return false;
+        if (!value.sourceUrl.startsWith(`${target.path}?`))
+            return false;
+        if (url.origin !== "http://notification.local")
+            return false;
+        if (url.pathname !== target.path)
+            return false;
+        if (url.hash)
+            return false;
+        const expectedKeys = Object.keys(target.parameters);
+        for (const key of expectedKeys) {
+            if (url.searchParams.getAll(key).length !== 1)
+                return false;
+            if (url.searchParams.get(key) !== target.parameters[key])
+                return false;
+        }
+        return [...url.searchParams.keys()].every((key) => expectedKeys.includes(key));
+    }
+    catch {
+        return false;
+    }
+}
+export function isWebNotification(value, environmentId) {
+    if (!isNotificationRecord(value))
+        return false;
+    const fields = [
+        "id",
+        "kind",
+        "title",
+        "body",
+        "createdAt",
+        "readAt",
+        "environmentId",
+        "sessionId",
+        "sessionKind",
+        "requestId",
+        "automationId",
+        "runId",
+        "sourceUrl",
+        "delivery",
+    ];
+    if (!hasOnlyNotificationFields(value, fields))
+        return false;
+    if (!isNotificationIdentifier(value.id))
+        return false;
+    if (typeof value.kind !== "string")
+        return false;
+    if (!["reply", "failure", "approval", "proposal", "automation"].includes(value.kind))
+        return false;
+    if (!isNotificationText(value.title, 1024))
+        return false;
+    if (!value.title.trim())
+        return false;
+    if (!isNotificationText(value.body, 16384))
+        return false;
+    if (!isNotificationTimestamp(value.createdAt))
+        return false;
+    if (value.readAt !== null && !isNotificationTimestamp(value.readAt))
+        return false;
+    if (value.environmentId !== environmentId)
+        return false;
+    if (!hasBoundNotificationSource(value))
+        return false;
+    return isNotificationDelivery(value.delivery);
+}
+export function decodeNotificationState(raw, environmentId) {
+    const value = JSON.parse(raw);
+    if (!isNotificationRecord(value))
+        throw new Error("Invalid notification storage.");
+    if (value.version !== 1)
+        throw new Error("Unsupported notification storage version.");
+    if (value.environmentId !== environmentId)
+        throw new Error("Notification storage environment mismatch.");
+    if (!hasOnlyNotificationFields(value, [
+        "version",
+        "environmentId",
+        "items",
+        "preferences",
+    ]))
+        throw new Error("Unexpected notification storage fields.");
+    const preferences = normalizeStoredNotificationPreferences(value.preferences);
+    if (!preferences)
+        throw new Error("Invalid notification preferences.");
+    if (!Array.isArray(value.items))
+        throw new Error("Invalid notification history.");
+    const seen = new Set();
+    for (const item of value.items) {
+        if (!isWebNotification(item, environmentId))
+            throw new Error("Invalid stored notification.");
+        if (seen.has(item.id))
+            throw new Error("Duplicate stored notification.");
+        seen.add(item.id);
+    }
+    return { ...value, preferences };
+}

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

@@ -0,0 +1,26 @@
+import { type NotificationDelivery, type NotificationListQuery, type NotificationPage, type NotificationPreferences, type NotificationReadChange, type NotificationReadResult, type WebNotification } from "./contracts.js";
+export declare function notificationStorePath(input: {
+    runtimeDir: string;
+    sessionsDir: string;
+    environmentId: string;
+}): string;
+/** Web UI history only: no writes to Runtime sessions or model-visible context. */
+export declare class WebNotificationStore {
+    private readonly environmentId;
+    private readonly path;
+    constructor(path: string, environmentId: string);
+    private load;
+    private save;
+    private transaction;
+    initialize(): Promise<void>;
+    reconcilePendingDeliveries(): Promise<void>;
+    upsert(item: WebNotification): Promise<{
+        item: WebNotification;
+        created: boolean;
+    }>;
+    list(query?: NotificationListQuery): Promise<NotificationPage>;
+    updateDelivery(id: string, delivery: NotificationDelivery): Promise<boolean>;
+    markRead(change: NotificationReadChange, now?: number): Promise<NotificationReadResult>;
+    getPreferences(): Promise<NotificationPreferences>;
+    setPreferences(preferences: NotificationPreferences): Promise<NotificationPreferences>;
+}