@abot-ai/runtime 1.5.0 → 1.7.0

package/dist/src/web-ui/local-runtime/runtime-setup-context-window.d.ts

@@ -0,0 +1,20 @@
+import type { ModelContextCapacityIssue } from "../../runtime/config/model-context-capacity.js";
+import { RuntimeSetupError } from "./runtime-setup-input.js";
+export type RuntimeSetupContextWindowIssue = Readonly<{
+    field: "contextWindowTokens";
+    declaredTokens: number;
+    effectiveTokens: number;
+    reservedTokens: number;
+    minimumTokens: number;
+    allocationTokens?: number;
+    environmentId?: string;
+}>;
+export declare class RuntimeSetupContextWindowError extends RuntimeSetupError {
+    readonly contextWindow: RuntimeSetupContextWindowIssue;
+    constructor(issue: ModelContextCapacityIssue, environmentId?: string);
+}
+/** Project only known capacity evidence; other exceptions keep their redaction. */
+export declare function throwRuntimeSetupValidationError(error: unknown, environmentId?: string): never;
+export declare function runtimeSetupContextWindowErrorDetails(error: unknown): {
+    contextWindow?: RuntimeSetupContextWindowIssue;
+};

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

@@ -0,0 +1,44 @@
+import { RuntimeConfigValidationError } from "../../runtime/config/validation.js";
+import { RuntimeSetupError } from "./runtime-setup-input.js";
+function setupContextWindowMessage(issue) {
+    const capacity = `The effective context window is ${issue.effectiveTokens} tokens, but the configured reserves require more than ${issue.reservedTokens} tokens. Use a model-supported context window of at least ${issue.minimumTokens} tokens or adjust the configured reserves.`;
+    if (issue.allocationTokens === undefined)
+        return capacity;
+    if (issue.allocationTokens >= issue.minimumTokens)
+        return capacity;
+    return `${capacity} The Ollama num_ctx allocation of ${issue.allocationTokens} tokens must also support that window.`;
+}
+export class RuntimeSetupContextWindowError extends RuntimeSetupError {
+    contextWindow;
+    constructor(issue, environmentId) {
+        super("context_window_too_small", setupContextWindowMessage(issue));
+        this.contextWindow = {
+            field: "contextWindowTokens",
+            declaredTokens: issue.declaredTokens,
+            effectiveTokens: issue.effectiveTokens,
+            reservedTokens: issue.reservedTokens,
+            minimumTokens: issue.minimumTokens,
+            ...(issue.allocationTokens === undefined
+                ? {}
+                : { allocationTokens: issue.allocationTokens }),
+            ...(environmentId === undefined ? {} : { environmentId }),
+        };
+    }
+}
+function readSetupContextCapacityIssue(error) {
+    if (!(error instanceof RuntimeConfigValidationError))
+        return undefined;
+    return error.capacityIssues.find((issue) => issue.profileId === "default");
+}
+/** Project only known capacity evidence; other exceptions keep their redaction. */
+export function throwRuntimeSetupValidationError(error, environmentId) {
+    const issue = readSetupContextCapacityIssue(error);
+    if (!issue)
+        throw error;
+    throw new RuntimeSetupContextWindowError(issue, environmentId);
+}
+export function runtimeSetupContextWindowErrorDetails(error) {
+    if (!(error instanceof RuntimeSetupContextWindowError))
+        return {};
+    return { contextWindow: error.contextWindow };
+}

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

@@ -1,6 +1,7 @@
 import { assertConfigMutationRequest, ConfigMutationRequestError, } from "./config-mutation-request.js";
 import { readBody, readJsonBody, sendJson } from "./http.js";
 import { RuntimeSetupError } from "./runtime-setup-input.js";
+import { runtimeSetupContextWindowErrorDetails } from "./runtime-setup-context-window.js";
 export class RuntimeSetupRoutes {
     service;
     constructor(service) {
@@ -43,6 +44,7 @@ export class RuntimeSetupRoutes {
                 error instanceof ConfigMutationRequestError;
             sendJson(params.response, isPublicError ? error.statusCode : 400, {
                 ok: false,
+                ...runtimeSetupContextWindowErrorDetails(error),
                 error: error instanceof RuntimeSetupError
                     ? error.code
                     : "runtime_setup_failed",

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

@@ -2,6 +2,7 @@ import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { loadRuntimeConfig } from "../../runtime/config.js";
 import { isRecord } from "../../runtime/config/utils.js";
+import { throwRuntimeSetupValidationError } from "./runtime-setup-context-window.js";
 /** Validate complete effective configuration in isolation before replacing local files. */
 export async function validateRuntimeSetupPlan(params) {
     const staging = await mkdtemp(join(params.rootDir, ".runtime-setup-validation-"));
@@ -26,8 +27,14 @@ export async function validateRuntimeSetupPlan(params) {
             ? Object.keys(environment.profiles)
             : [];
         const environments = profileIds.length ? profileIds : [undefined];
-        for (const profileId of environments)
-            loadRuntimeConfig({ rootDir: params.rootDir, configPath, profileId });
+        for (const profileId of environments) {
+            try {
+                loadRuntimeConfig({ rootDir: params.rootDir, configPath, profileId });
+            }
+            catch (error) {
+                throwRuntimeSetupValidationError(error, profileId);
+            }
+        }
     }
     finally {
         await rm(staging, { recursive: true, force: true });

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

@@ -3,6 +3,7 @@ import type { RuntimeEnvironment, JsonObject } from "./contracts.js";
 import { WebSessionReadStates } from "../session-read-state/service.js";
 import type { WorkspaceChangeNotifier } from "./workspace-notifications.js";
 type SessionRouteRequest = {
+    url?: URL;
     method: string;
     segments: string[];
     body: JsonObject | null;

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

@@ -1,6 +1,19 @@
+import { historyPageOptions, publicHistorySnapshot } from "./history-pagination.js";
 import { deleteSessionWithAttachments } from "../../runtime/session/session-attachment-deletion.js";
 import { deleteSessionAttachmentsIfSupported } from "./attachment-routes.js";
 import { sendJson } from "./http.js";
+import { isSparkSession, SPARK_SESSION_ID } from "../../sessions/spark-session.js";
+async function isProtectedSparkSession(environment, sessionId) {
+    if (sessionId !== SPARK_SESSION_ID)
+        return false;
+    const session = await environment.services.sessions.getSessionById(sessionId);
+    if (!session)
+        return false;
+    return isSparkSession(session);
+}
+function isSparkChatBusy(error) {
+    return error instanceof Error && error.message === "spark_chat_busy";
+}
 export class WebSessionRoutes {
     readStates;
     notifyChanged;
@@ -22,13 +35,24 @@ export class WebSessionRoutes {
             });
             return true;
         }
+        if (method === "POST" && sessionId === "page" && !action) {
+            sendJson(response, 200, { ok: true, ...(await this.readStates.list(environmentId, body ?? {})) });
+            return true;
+        }
         if (!sessionId)
             return false;
         const sessions = environment.services.sessions;
         if (method === "GET" && action === "messages") {
-            const snapshot = await sessions.getSessionSnapshot(sessionId, {
-                includeRequests: true,
-            });
+            let snapshot;
+            try {
+                snapshot = await sessions.getSessionSnapshot(sessionId, historyPageOptions(request.url, environment.services.config));
+            }
+            catch (error) {
+                if (!(error instanceof Error) || error.message !== "history_cursor_stale")
+                    throw error;
+                sendJson(response, 409, { ok: false, error: error.message });
+                return true;
+            }
             if (!snapshot) {
                 sendJson(response, 404, {
                     ok: false,
@@ -40,7 +64,7 @@ export class WebSessionRoutes {
             }
             sendJson(response, 200, {
                 ok: true,
-                ...snapshot,
+                ...publicHistorySnapshot(snapshot),
                 readState: await this.readStates.project(environmentId, snapshot),
             });
             return true;
@@ -56,14 +80,28 @@ export class WebSessionRoutes {
             return true;
         }
         if (method === "DELETE" && action === "messages") {
-            const result = await sessions.clearSessionMessages(sessionId);
+            const protectedSpark = await isProtectedSparkSession(environment, sessionId);
+            let result;
+            try {
+                result = await sessions.clearSessionMessages(sessionId);
+            }
+            catch (error) {
+                if (!isSparkChatBusy(error))
+                    throw error;
+                sendJson(response, 409, {
+                    ok: false, error: "spark_chat_busy",
+                    message: "Stop the active request or resolve its approval before clearing SPARK chat.",
+                });
+                return true;
+            }
             if (!result) {
                 sendJson(response, 404, { ok: false, error: "session_not_found" });
                 return true;
             }
             try {
                 await this.readStates.reset(environmentId, sessionId);
-                await deleteSessionAttachmentsIfSupported(environment, sessionId);
+                if (!protectedSpark)
+                    await deleteSessionAttachmentsIfSupported(environment, sessionId);
             }
             finally {
                 this.notifyChanged?.(environmentId, ["sessions"]);
@@ -72,6 +110,10 @@ export class WebSessionRoutes {
             return true;
         }
         if (method === "DELETE" && !action) {
+            if (await isProtectedSparkSession(environment, sessionId)) {
+                sendJson(response, 409, { ok: false, error: "spark_session_requires_clear" });
+                return true;
+            }
             try {
                 const result = await deleteSessionWithAttachments(sessions, environment.services.attachments, sessionId);
                 await this.readStates.forget(environmentId, sessionId);

package/dist/src/web-ui/local-runtime/setup-embedding-config-repository.d.ts

@@ -0,0 +1,6 @@
+import type { LongTermMemoryOnboardingConfigRepository } from "../../runtime/long-term-memory/onboarding/contracts.js";
+/** Onboarding switches memory implementations in the same guarded config write. */
+export declare function createSetupEmbeddingConfigRepository(params: {
+    rootDir: string;
+    configPath?: string;
+}): LongTermMemoryOnboardingConfigRepository;

package/dist/src/web-ui/local-runtime/setup-embedding-config-repository.js

@@ -0,0 +1,25 @@
+import { createFileLongTermMemoryOnboardingConfigRepository } from "../../runtime/adapters/long-term-memory/onboarding-config-repository.js";
+import { isRecord } from "../../runtime/config/utils.js";
+import { updatePluginSelection } from "../plugin-management-selection.js";
+/** Onboarding switches memory implementations in the same guarded config write. */
+export function createSetupEmbeddingConfigRepository(params) {
+    const repository = createFileLongTermMemoryOnboardingConfigRepository(params);
+    return Object.freeze({
+        read: () => repository.read(),
+        write(config, expectedConfig) {
+            const enablesNativeMemory = isRecord(config.longTermMemory) &&
+                config.longTermMemory.enabled === true;
+            if (!enablesNativeMemory)
+                return repository.write(config, expectedConfig);
+            // The onboarding service validates this candidate before probing and saving.
+            const current = (config.plugins ?? {});
+            const plugins = updatePluginSelection({
+                current,
+                pluginId: "memory",
+                capabilityIds: [],
+                enabled: false,
+            });
+            return repository.write({ ...config, plugins }, expectedConfig);
+        },
+    });
+}

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

@@ -1,5 +1,6 @@
 import { createLocalLongTermMemoryOnboardingService } from "../../runtime/adapters/long-term-memory/onboarding-service.js";
 import { parseSetupEmbeddingInput } from "./setup-embedding-input.js";
+import { createSetupEmbeddingConfigRepository } from "./setup-embedding-config-repository.js";
 import { prepareSetupEmbeddingProvider, } from "./setup-embedding-provider.js";
 import { RuntimeSetupError } from "./runtime-setup-input.js";
 export class SetupEmbeddingFailure extends Error {
@@ -34,6 +35,7 @@ export class SetupEmbeddingService {
             const service = createLocalLongTermMemoryOnboardingService({
                 ...options,
                 providerAdapters: this.options.providerAdapters,
+                repository: createSetupEmbeddingConfigRepository(options),
             });
             const result = await service.enable({
                 providerId: prepared.providerId,

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,63 @@
+import { historyPageOptions, publicHistorySnapshot } from "./history-pagination.js";
+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, historyPageOptions(new URL(input.request.url ?? "/", "http://localhost"), environment.services.config));
+            if (!snapshot)
+                throw new Error("spark_chat_unavailable");
+            sendJson(input.response, 200, {
+                ok: true, sessionId: session.id, ...configuration, snapshot: publicHistorySnapshot(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", "history_cursor_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-backend.d.ts

@@ -17,5 +17,9 @@ export declare class LocalRuntimeWebBackend {
     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

@@ -108,6 +108,9 @@ export class LocalRuntimeWebBackend {
     environmentConfig() {
         return this.environments.environmentConfig();
     }
+    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

@@ -1,21 +1,35 @@
-export type NotificationKind = "reply" | "failure" | "approval" | "proposal";
+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;
 };
-export type WebNotification = {
+type NotificationDetails = {
     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 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>;
@@ -49,3 +63,4 @@ export type NotificationDesktopState = {
 export declare class NotificationInputError extends Error {
 }
 export declare function defaultNotificationPreferences(): NotificationPreferences;
+export {};