@abot-ai/runtime 1.4.0 → 1.6.0

package/dist/src/web-ui/local-runtime/spark-chat-admission.d.ts

@@ -0,0 +1,7 @@
+import type { RuntimeEnvironment, JsonObject } from "./contracts.js";
+export declare function publicSparkChatAdmissionFailure(error: unknown): {
+    error: string;
+    message: string;
+};
+/** A marked companion uses the owner's current settings, never a stale tab's defaults. */
+export declare function resolveSparkChatRequest(environment: RuntimeEnvironment, sessionId: string, body: JsonObject): Promise<JsonObject>;

package/dist/src/web-ui/local-runtime/spark-chat-admission.js

@@ -0,0 +1,37 @@
+import { isSparkSession, SPARK_SESSION_ID } from "../../sessions/spark-session.js";
+import { loadSparkChatConfiguration } from "./spark-chat-configuration.js";
+export function publicSparkChatAdmissionFailure(error) {
+    if (error instanceof Error && error.message === "spark_chat_session_unavailable")
+        return {
+            error: error.message, message: "The SPARK conversation is unavailable. Open SPARK before sending a message.",
+        };
+    if (error instanceof Error && error.message === "spark_chat_model_required")
+        return {
+            error: error.message, message: "Choose a chat and initiative model in SPARK settings before sending a message.",
+        };
+    if (error instanceof Error && error.message === "spark_chat_model_unavailable")
+        return {
+            error: error.message, message: "The selected SPARK model is unavailable. Choose an available model in SPARK settings.",
+        };
+    return { error: "spark_chat_unavailable", message: "SPARK chat settings could not be loaded." };
+}
+/** A marked companion uses the owner's current settings, never a stale tab's defaults. */
+export async function resolveSparkChatRequest(environment, sessionId, body) {
+    if (sessionId !== SPARK_SESSION_ID)
+        return body;
+    const session = await environment.services.sessions.getSessionById(sessionId);
+    if (!session)
+        throw new Error("spark_chat_session_unavailable");
+    if (!isSparkSession(session))
+        throw new Error("spark_chat_session_unavailable");
+    const settings = await loadSparkChatConfiguration(environment.services.passiveLearning);
+    if (!settings.modelProfileId)
+        throw new Error("spark_chat_model_required");
+    if (!environment.services.config.models?.profiles?.[settings.modelProfileId])
+        throw new Error("spark_chat_model_unavailable");
+    return {
+        ...body,
+        modelPreference: { profileId: settings.modelProfileId, scope: "all" },
+        toolPermissionMode: settings.toolPermissionMode,
+    };
+}

package/dist/src/web-ui/local-runtime/spark-chat-configuration.d.ts

@@ -0,0 +1,8 @@
+import type { PassiveLearningManagement } from "../../runtime/local-host/client-learning.js";
+export declare function loadSparkChatConfiguration(learning: Pick<PassiveLearningManagement, "status">): Promise<{
+    toolPermissionMode: import("../../capabilities/tool-permission-mode.js").ToolPermissionMode;
+    modelProfileId: string | null;
+}>;
+export declare function readSparkChatConfigurationUpdate(body: Record<string, unknown> | null): {
+    sparkToolPermissionMode: import("../../capabilities/tool-permission-mode.js").ToolPermissionMode;
+};

package/dist/src/web-ui/local-runtime/spark-chat-configuration.js

@@ -0,0 +1,16 @@
+import { readSparkToolPermissionMode } from "../../runtime/passive-learning/spark-chat-preferences.js";
+export async function loadSparkChatConfiguration(learning) {
+    const { preferences } = await learning.status();
+    return {
+        toolPermissionMode: readSparkToolPermissionMode(preferences.sparkToolPermissionMode),
+        modelProfileId: preferences.proactiveModelProfileId ?? preferences.modelProfileId ?? null,
+    };
+}
+export function readSparkChatConfigurationUpdate(body) {
+    if (!body || body.toolPermissionMode === undefined)
+        throw new Error("spark_chat_preferences_invalid");
+    const allowed = ["environment", "environmentId", "toolPermissionMode"];
+    if (Object.keys(body).some((key) => !allowed.includes(key)))
+        throw new Error("spark_chat_preferences_invalid");
+    return { sparkToolPermissionMode: readSparkToolPermissionMode(body.toolPermissionMode) };
+}

package/dist/src/web-ui/local-runtime/spark-chat-handoff.d.ts

@@ -0,0 +1,4 @@
+import type { RuntimeEnvironment } from "./contracts.js";
+import type { SparkChatRouteRequest } from "./spark-chat-routes.js";
+import type { WorkspaceChangeNotifier } from "./workspace-notifications.js";
+export declare function handleSparkChatHandoff(input: SparkChatRouteRequest, resolveEnvironment: (id: string) => RuntimeEnvironment, notify?: WorkspaceChangeNotifier): Promise<boolean>;

package/dist/src/web-ui/local-runtime/spark-chat-handoff.js

@@ -0,0 +1,84 @@
+import { createHash } from "node:crypto";
+import { isAssistantInitiativeMessage } from "../../sessions/assistant-initiative.js";
+import { toSnapshotMessage } from "../../sessions/record/projection.js";
+import { isSparkSession, SPARK_SESSION_ID } from "../../sessions/spark-session.js";
+import { isSparkHandoffBrief } from "../../sessions/spark-handoff-brief.js";
+import { acceptConfigMutationRequest } from "./config-mutation-request.js";
+import { sendJson } from "./http.js";
+const failures = {
+    spark_handoff_reference_invalid: { status: 400, message: "The SPARK message reference is invalid. Refresh the chat and try again." },
+    spark_handoff_source_unavailable: { status: 409, message: "This SPARK insight is no longer in the chat. Refresh the chat to see the current messages." },
+    spark_handoff_brief_unavailable: { status: 409, message: "This older SPARK insight does not have saved context for a new session." },
+    spark_handoff_target_conflict: { status: 409, message: "The session for this insight was cleared or changed and cannot be reopened from this message." },
+    spark_handoff_unavailable: { status: 503, message: "Opening a session from SPARK is unavailable in this environment." },
+    spark_handoff_failed: { status: 500, message: "The session could not be opened. Try again." },
+};
+function readMessageReference(body) {
+    const input = body?.message;
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new Error("spark_handoff_reference_invalid");
+    const value = input;
+    const validId = typeof value.id === "string" && value.id.length > 0 && value.id.length <= 200;
+    const validTimestamp = typeof value.createdAt === "number" && Number.isFinite(value.createdAt);
+    const validRequest = value.requestId === null || (typeof value.requestId === "string" && value.requestId.length > 0 && value.requestId.length <= 200);
+    if (!validId || !validTimestamp || !validRequest)
+        throw new Error("spark_handoff_reference_invalid");
+    return { id: value.id, createdAt: value.createdAt, requestId: value.requestId };
+}
+function findSourceMessage(session, reference) {
+    if (!session || !isSparkSession(session))
+        throw new Error("spark_handoff_source_unavailable");
+    const message = session.messages.find((candidate) => {
+        if (!isAssistantInitiativeMessage(candidate))
+            return false;
+        const projected = toSnapshotMessage(session.id, candidate, session.requests ?? []);
+        return String(projected.id) === reference.id && projected.createdAt === reference.createdAt && projected.requestId === reference.requestId;
+    });
+    if (!message)
+        throw new Error("spark_handoff_source_unavailable");
+    return message;
+}
+function handoffFailure(error) {
+    const original = error instanceof Error ? error.message : "";
+    const deleted = !!error && typeof error === "object" && "code" in error && error.code === "session_deleted";
+    if (deleted || original === "assistant_conversation_identity_conflict")
+        return "spark_handoff_target_conflict";
+    return Object.hasOwn(failures, original) ? original : "spark_handoff_failed";
+}
+export async function handleSparkChatHandoff(input, resolveEnvironment, notify) {
+    if (input.route !== "runtime/spark/chat/sessions")
+        return false;
+    input.response.setHeader("cache-control", "no-store");
+    if (input.method !== "POST") {
+        input.response.setHeader("allow", "POST");
+        sendJson(input.response, 405, { ok: false, error: "method_not_allowed" });
+        return true;
+    }
+    if (!acceptConfigMutationRequest(input.request, input.response))
+        return true;
+    try {
+        const reference = readMessageReference(input.body);
+        const { sessions } = resolveEnvironment(input.environmentId).services;
+        const source = findSourceMessage(await sessions.getSessionById(SPARK_SESSION_ID), reference);
+        const initiative = source.initiative;
+        const brief = initiative.handoffBrief;
+        const title = initiative.handoffTitle;
+        const validTitle = typeof title === "string" && title.trim().length > 0 && title.length <= 160;
+        if (!isSparkHandoffBrief(brief) || !validTitle)
+            throw new Error("spark_handoff_brief_unavailable");
+        if (!sessions.createAssistantConversation)
+            throw new Error("spark_handoff_unavailable");
+        const identity = createHash("sha256").update(initiative.proposalId).digest("hex").slice(0, 32);
+        const session = await sessions.createAssistantConversation(`spark-work-${identity}`, { title, content: brief, initiative });
+        if (session.kind || session.automationOrigin)
+            throw new Error("spark_handoff_target_conflict");
+        notify?.(input.environmentId, ["sessions"]);
+        sendJson(input.response, 200, { ok: true, sessionId: session.id });
+    }
+    catch (error) {
+        const code = handoffFailure(error);
+        const failure = failures[code];
+        sendJson(input.response, failure.status, { ok: false, error: code, message: failure.message });
+    }
+    return true;
+}

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

@@ -0,0 +1,19 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RuntimeEnvironment, JsonObject } from "./contracts.js";
+import type { WebSessionReadStates } from "../session-read-state/service.js";
+import type { WorkspaceChangeNotifier } from "./workspace-notifications.js";
+export type SparkChatRouteRequest = {
+    method: string;
+    route: string;
+    body: JsonObject | null;
+    environmentId: string;
+    request: IncomingMessage;
+    response: ServerResponse;
+};
+export declare class SparkChatRoutes {
+    private readonly environment;
+    private readonly reads;
+    private readonly notify?;
+    constructor(environment: (id: string) => RuntimeEnvironment, reads: WebSessionReadStates, notify?: WorkspaceChangeNotifier | undefined);
+    handle(input: SparkChatRouteRequest): Promise<boolean>;
+}

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

@@ -0,0 +1,62 @@
+import { ensureSparkSession } from "../../sessions/spark-session.js";
+import { acceptConfigMutationRequest } from "./config-mutation-request.js";
+import { loadSparkChatConfiguration, readSparkChatConfigurationUpdate } from "./spark-chat-configuration.js";
+import { sendJson } from "./http.js";
+import { handleSparkChatHandoff } from "./spark-chat-handoff.js";
+export class SparkChatRoutes {
+    environment;
+    reads;
+    notify;
+    constructor(environment, reads, notify) {
+        this.environment = environment;
+        this.reads = reads;
+        this.notify = notify;
+    }
+    async handle(input) {
+        if (await handleSparkChatHandoff(input, this.environment, this.notify))
+            return true;
+        if (!["runtime/spark/chat", "runtime/spark/chat/read"].includes(input.route))
+            return false;
+        input.response.setHeader("cache-control", "no-store");
+        const readReceipt = input.route.endsWith("/read");
+        const allowed = readReceipt ? ["POST"] : ["GET", "PUT"];
+        if (!allowed.includes(input.method)) {
+            input.response.setHeader("allow", allowed.join(", "));
+            sendJson(input.response, 405, { ok: false, error: "method_not_allowed" });
+            return true;
+        }
+        if (input.method !== "GET" && !acceptConfigMutationRequest(input.request, input.response))
+            return true;
+        try {
+            const update = input.method === "PUT" ? readSparkChatConfigurationUpdate(input.body) : undefined;
+            const environment = this.environment(input.environmentId);
+            const session = await ensureSparkSession(environment.services.sessions);
+            if (readReceipt) {
+                const readState = await this.reads.markVisible(input.environmentId, session.id, input.body?.visibleMessageIds, input.body?.readGeneration, input.body?.visibleMessages);
+                this.notify?.(input.environmentId, ["sessions"]);
+                sendJson(input.response, 200, { ok: true, readState });
+                return true;
+            }
+            if (update)
+                await environment.services.passiveLearning.configure(update);
+            const configuration = await loadSparkChatConfiguration(environment.services.passiveLearning);
+            const snapshot = await environment.services.sessions.getSessionSnapshot(session.id, { includeRequests: true });
+            if (!snapshot)
+                throw new Error("spark_chat_unavailable");
+            sendJson(input.response, 200, {
+                ok: true, sessionId: session.id, ...configuration, snapshot,
+                readState: await this.reads.project(input.environmentId, snapshot),
+            });
+            return true;
+        }
+        catch (error) {
+            const code = error instanceof Error ? error.message : "spark_chat_unavailable";
+            const invalid = ["spark_chat_preferences_invalid", "invalid_spark_tool_permission_mode", "visible_message_ids_invalid", "visible_message_receipts_invalid"].includes(code);
+            const stale = ["read_generation_changed", "visible_message_receipt_stale"].includes(code);
+            sendJson(input.response, invalid ? 400 : 409, {
+                ok: false, error: invalid || stale ? code : "spark_chat_unavailable",
+            });
+            return true;
+        }
+    }
+}

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,14 +4,22 @@ 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;
+    nativePermissions(environmentId: string): Readonly<{
+        status(): Promise<import("../computer-access/native-permission-contract.js").NativePermissionStatus>;
+        prepare(input: import("../computer-access/native-permission-contract.js").NativePermissionInput): Promise<import("../computer-access/native-permission-contract.js").NativePermissionResult>;
+    }> | 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,11 @@ export class LocalRuntimeWebBackend {
     environmentConfig() {
         return this.environments.environmentConfig();
     }
-    stop() {
-        return this.environments.stop();
+    nativePermissions(environmentId) {
+        return this.environments.existingNativePermissions(environmentId);
+    }
+    async stop() {
+        await this.notifications.stop();
+        await this.environments.stop();
     }
 }

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

@@ -0,0 +1,3 @@
+import type { WebNotification } from "./contracts.js";
+/** A committed scheduler transition points to its canonical run report. */
+export declare function projectAutomationRunNotificationEvent(event: Record<string, unknown>, now: number): WebNotification | undefined;

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

@@ -0,0 +1,57 @@
+import { createHash } from "node:crypto";
+import { eventText, hasNotificationIdentity, notificationBody } from "./event-fields.js";
+const TERMINAL_TITLES = {
+    succeeded: "Automation completed",
+    completed_with_skips: "Automation completed with skipped steps",
+    failed: "Automation failed",
+    cancelled: "Automation stopped",
+    interrupted: "Automation interrupted",
+    missed: "Automation run missed",
+};
+function terminalAutomationStatus(value) {
+    return Object.hasOwn(TERMINAL_TITLES, value);
+}
+function automationNotificationPhase(name) {
+    if (name === "automation.run.started")
+        return "started";
+    if (name === "automation.run.finished")
+        return "finished";
+    return null;
+}
+/** A committed scheduler transition points to its canonical run report. */
+export function projectAutomationRunNotificationEvent(event, now) {
+    if (event.type !== "event")
+        return;
+    const phase = automationNotificationPhase(event.name);
+    if (!phase)
+        return;
+    const status = eventText(event.status);
+    if (phase === "started" && status !== "running")
+        return;
+    if (phase === "finished" && !terminalAutomationStatus(status))
+        return;
+    const environmentId = eventText(event.environment) || eventText(event.environmentId);
+    const automationId = eventText(event.automationId);
+    const runId = eventText(event.runId);
+    if (![environmentId, automationId, runId].every(hasNotificationIdentity))
+        return;
+    const name = notificationBody(eventText(event.title)) || "Automation";
+    const title = phase === "started" ? "Automation started" : TERMINAL_TITLES[status];
+    const parameters = new URLSearchParams({ environment: environmentId, automation: automationId, run: runId });
+    const id = createHash("sha256")
+        .update(JSON.stringify([environmentId, "automation", runId, phase]))
+        .digest("hex");
+    return {
+        id,
+        kind: "automation",
+        title,
+        body: name,
+        createdAt: now,
+        readAt: null,
+        environmentId,
+        automationId,
+        runId,
+        sourceUrl: `/automations?${parameters}`,
+        delivery: { status: "pending" },
+    };
+}

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

@@ -0,0 +1,66 @@
+import type { SessionKind } from "../../sessions/spark-session.js";
+export type NotificationKind = "reply" | "failure" | "approval" | "proposal" | "automation";
+export type NotificationDelivery = {
+    status: "pending" | "submitted" | "disabled" | "unavailable" | "failed" | "unknown";
+    error?: string;
+};
+type NotificationDetails = {
+    id: string;
+    title: string;
+    body: string;
+    createdAt: number;
+    readAt: number | null;
+    environmentId: string;
+    sourceUrl: string;
+    delivery: NotificationDelivery;
+};
+export type WebNotification = NotificationDetails & ({
+    kind: "automation";
+    automationId: string;
+    runId: string;
+    sessionId?: never;
+    sessionKind?: never;
+    requestId?: never;
+} | {
+    kind: Exclude<NotificationKind, "automation">;
+    sessionId: string;
+    /** Copied only from the canonical persisted session. */
+    sessionKind?: SessionKind;
+    requestId?: string;
+    automationId?: never;
+    runId?: never;
+});
+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;
+export {};

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

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

package/dist/src/web-ui/notifications/conversation-source.d.ts

@@ -0,0 +1,6 @@
+import type { SessionRecord } from "../../sessions/types.js";
+export type NotificationSession = Partial<Pick<SessionRecord, "kind" | "messages" | "requests">> & {
+    automationOrigin?: unknown;
+};
+/** Navigation follows the stored session kind; titles never identify SPARK. */
+export declare function conversationNotificationSource(environmentId: string, sessionId: string, event: Record<string, unknown>, persisted?: NotificationSession | null): string;

package/dist/src/web-ui/notifications/conversation-source.js

@@ -0,0 +1,26 @@
+import { isSparkSession } from "../../sessions/spark-session.js";
+import { toSnapshotMessage } from "../../sessions/record/projection.js";
+/** Navigation follows the stored session kind; titles never identify SPARK. */
+export function conversationNotificationSource(environmentId, sessionId, event, persisted) {
+    const parameters = new URLSearchParams({ environment: environmentId, session: sessionId });
+    if (!persisted || !isSparkSession(persisted))
+        return `/chat?${parameters}`;
+    parameters.delete("session");
+    parameters.set("spark", "1");
+    const proposal = event.event;
+    const message = [...(persisted.messages ?? [])].reverse().find((item) => {
+        if (item.role !== "assistant")
+            return false;
+        if (proposal?.type === "proposal_delivered")
+            return item.initiative?.proposalId === proposal.proposalId;
+        return typeof event.requestId === "string" && item.requestId === event.requestId;
+    });
+    if (message) {
+        const reference = toSnapshotMessage(sessionId, message, persisted.requests ?? []);
+        parameters.set("message", String(reference.id));
+        parameters.set("messageCreatedAt", String(reference.createdAt));
+        if (reference.requestId)
+            parameters.set("request", reference.requestId);
+    }
+    return `/home?${parameters}`;
+}