@abot-ai/runtime 1.5.0 → 1.7.0

package/dist/src/web-ui/runtime-setup-gateway.js

@@ -1,5 +1,6 @@
 import { isLoopbackGateway, hasGatewayListener, } from "./runtime-setup-gateway-address.js";
 import { createModelGatewayServer, } from "../model-gateway/server.js";
+import { captureModelGatewayConfiguration } from "../model-gateway/server/configuration.js";
 import { loadRuntimeConfig } from "../runtime/config.js";
 import { closeHttpServerImmediately } from "../shared/http-server-shutdown.js";
 function listenGateway(server, port, host) {
@@ -35,7 +36,22 @@ export class RuntimeSetupGateway {
         const port = Number(url.port || "80");
         return { url, host, port };
     }
-    async checkActivation(configPath) {
+    captureConfiguration(configPath) {
+        return captureModelGatewayConfiguration({ ...this.options, configPath });
+    }
+    matchesAppliedConfiguration(configPath, applied) {
+        if (this.owned)
+            return false;
+        if (!applied?.length)
+            return false;
+        const candidate = this.captureConfiguration(configPath);
+        return (candidate !== null && applied.every((previous) => previous === candidate));
+    }
+    async checkActivation(configPath, applied) {
+        const plan = await this.planActivation(configPath, applied);
+        return plan.status === "ready" ? { status: "ready" } : plan;
+    }
+    async planActivation(configPath, applied) {
         this.requireGatewayOpen();
         const { url, host, port } = this.configuredBinding(configPath);
         if (!isLoopbackGateway(url)) {
@@ -49,13 +65,14 @@ export class RuntimeSetupGateway {
         const ownedHost = ownsTargetPort ? ownAddress.address : undefined;
         const externalListener = await hasGatewayListener(port, host, ownedHost);
         this.requireGatewayOpen();
-        if (externalListener) {
-            return {
-                status: "restart_required",
-                message: "Configuration saved. An existing model gateway owns this address; restart that gateway to load its new configuration.",
-            };
-        }
-        return { status: "ready" };
+        if (!externalListener)
+            return { status: "ready", retainExternal: false };
+        if (this.matchesAppliedConfiguration(configPath, applied))
+            return { status: "ready", retainExternal: true };
+        return {
+            status: "restart_required",
+            message: "Configuration saved. An existing model gateway owns this address; restart that gateway to load its new configuration.",
+        };
     }
     captureGatewayCheckpoint() {
         this.requireGatewayOpen();
@@ -135,15 +152,18 @@ export class RuntimeSetupGateway {
             this.owned = undefined;
         throw error;
     }
-    activate(configPath) {
+    activate(configPath, applied) {
         return this.runGatewayTransition(async () => {
             const checkpoint = this.captureGatewayCheckpoint();
             this.checkpoint = undefined;
             try {
-                const allowed = await this.checkActivation(configPath);
+                const allowed = await this.planActivation(configPath, applied);
                 this.requireGatewayOpen();
                 if (allowed.status !== "ready")
                     return allowed;
+                // Unchanged requirements do not grant ownership of the external listener.
+                if (allowed.retainExternal)
+                    return { status: "ready" };
                 const { host, port } = this.configuredBinding(configPath);
                 const server = createModelGatewayServer({
                     ...this.options,

package/dist/src/web-ui/server.js

@@ -148,7 +148,8 @@ export function startWebUiServer(overrides = {}) {
         rootDir,
         providerAdapters: options.providerAdapters,
     });
-    const activateSetup = overrides.onRuntimeSetup ?? ((path) => setupGateway.activate(path));
+    const activateSetup = overrides.onRuntimeSetup ??
+        ((path, applied) => setupGateway.activate(path, applied));
     const wss = new WebSocketServer({ noServer: true });
     const localRuntimeBackend = options.backend === "runtime"
         ? new LocalRuntimeWebBackend({
@@ -168,6 +169,9 @@ export function startWebUiServer(overrides = {}) {
                 };
             },
             onRuntimeSetup: activateSetup,
+            captureRuntimeSetupConfiguration: overrides.onRuntimeSetup
+                ? undefined
+                : (path) => setupGateway.captureConfiguration(path),
             createRuntimeSetupRestorePoint: overrides.createRuntimeSetupRestorePoint ??
                 (overrides.onRuntimeSetup
                     ? undefined
@@ -175,7 +179,7 @@ export function startWebUiServer(overrides = {}) {
             checkRuntimeSetupActivation: overrides.checkRuntimeSetupActivation ??
                 (overrides.onRuntimeSetup
                     ? undefined
-                    : (path) => setupGateway.checkActivation(path)),
+                    : (path, applied) => setupGateway.checkActivation(path, applied)),
             ...(options.providerAdapters
                 ? { providerAdapters: options.providerAdapters }
                 : {}),
@@ -203,7 +207,7 @@ export function startWebUiServer(overrides = {}) {
     }
     const handleLinkPreview = createLinkPreviewRouteHandler();
     const systemHost = localRuntimeBackend
-        ? new WebSystemHostService(rootDir, () => localRuntimeBackend.notifyHostConnectionChanged())
+        ? new WebSystemHostService(rootDir, () => localRuntimeBackend.notifyHostConnectionChanged(), (environmentId) => localRuntimeBackend.nativePermissions(environmentId))
         : null;
     const allowPublishedLoopback = allowsPublishedLoopbackAuthority(options.host);
     const server = createServer((req, res) => {

package/dist/src/web-ui/session-read-state/overview.d.ts

@@ -0,0 +1,42 @@
+import type { SessionMetadata } from "../../sessions/metadata/projection.js";
+import type { WebReadState } from "./store.js";
+/** The home dashboard's count and three recent chats must not become page-local. */
+export declare function sessionListOverview(records: SessionMetadata[], archivedIds: unknown, state?: WebReadState): {
+    sessions: ({
+        sessionId: string;
+        readStateStatus: "available";
+        unreadCount: number;
+        hasUnread: boolean;
+        lastReadMessageId: string | null;
+        lastReadAt: number;
+        latestMessageId: string | number | null;
+        latestAssistantMessageId: string | number | null;
+        kind?: import("../../sessions/spark-session.js").SessionKind;
+        project?: import("../../sessions/project-binding.js").SessionProject;
+        id: string;
+        title: string;
+        createdAt: number;
+        updatedAt: number;
+        lastMessagePreview: string;
+        lastMessageAt: number | null;
+    } | {
+        sessionId: string;
+        readStateStatus: "unavailable";
+        unreadCount: null;
+        hasUnread: null;
+        lastReadAt: null;
+        lastReadMessageId: null;
+        kind?: import("../../sessions/spark-session.js").SessionKind;
+        project?: import("../../sessions/project-binding.js").SessionProject;
+        id: string;
+        title: string;
+        createdAt: number;
+        updatedAt: number;
+        lastMessagePreview: string;
+        lastMessageAt: number | null;
+        latestMessageId: string | number | null;
+        latestAssistantMessageId: string | number | null;
+    })[];
+    unreadCount: number;
+    hasUnavailableReadState: boolean;
+};

package/dist/src/web-ui/session-read-state/overview.js

@@ -0,0 +1,16 @@
+import { projectSessionReadState } from "./projection.js";
+import { unavailableSessionReadState } from "./availability.js";
+/** The home dashboard's count and three recent chats must not become page-local. */
+export function sessionListOverview(records, archivedIds, state) {
+    const archived = new Set(Array.isArray(archivedIds) ? archivedIds : []);
+    const visible = records.filter(({ summary }) => !archived.has(summary.id));
+    let unreadCount = 0;
+    const recent = visible.slice(0, 3).map(({ summary, messages }) => ({
+        ...summary,
+        ...(state ? projectSessionReadState(state, summary.id, messages) : unavailableSessionReadState(summary.id)),
+    }));
+    if (state)
+        for (const { summary, messages } of visible)
+            unreadCount += projectSessionReadState(state, summary.id, messages).unreadCount;
+    return { sessions: recent, unreadCount, hasUnavailableReadState: !state };
+}

package/dist/src/web-ui/session-read-state/pagination.d.ts

@@ -0,0 +1,15 @@
+import type { SessionMetadata } from "../../sessions/metadata/projection.js";
+export type SessionPageQuery = {
+    cursor?: string | null;
+    query?: string;
+    archived?: boolean;
+    pinnedSessionIds?: string[];
+    orderedSessionIds?: string[];
+    archivedSessionIds?: string[];
+};
+export declare function sessionMetadataPage(records: SessionMetadata[], input: SessionPageQuery, limit: number): {
+    records: SessionMetadata[];
+    total: number;
+    archivedCount: number;
+    nextCursor: string | null;
+};

package/dist/src/web-ui/session-read-state/pagination.js

@@ -0,0 +1,42 @@
+function compareKeys(left, right) {
+    return left[0] - right[0] || left[1] - right[1] || left[2] - right[2] || left[3].localeCompare(right[3]);
+}
+function readCursor(cursor) {
+    try {
+        const key = JSON.parse(Buffer.from(cursor, "base64url").toString());
+        if (!Array.isArray(key) || key.length !== 4)
+            throw new Error();
+        if (!key.slice(0, 3).every(Number.isFinite) || typeof key[3] !== "string")
+            throw new Error();
+        return key;
+    }
+    catch {
+        throw new Error("session_cursor_invalid");
+    }
+}
+function readIds(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((id) => typeof id === "string");
+}
+export function sessionMetadataPage(records, input, limit) {
+    const archived = new Set(readIds(input.archivedSessionIds));
+    const pinned = new Map(readIds(input.pinnedSessionIds).map((id, index) => [id, index]));
+    const ordered = new Map(readIds(input.orderedSessionIds).map((id, index) => [id, index]));
+    const query = typeof input.query === "string" ? input.query.trim().toLowerCase() : "";
+    const archivedCount = records.filter(({ summary }) => archived.has(summary.id)).length;
+    const entries = records.filter(({ summary }) => archived.has(summary.id) === (input.archived === true))
+        .filter(({ summary }) => [summary.id, summary.title, summary.lastMessagePreview].some((text) => text.toLowerCase().includes(query)))
+        .map((record) => {
+        const { id, updatedAt } = record.summary;
+        const key = [pinned.has(id) ? 0 : 1, pinned.get(id) ?? ordered.get(id) ?? -1, -updatedAt, id];
+        return { record, key };
+    }).sort((left, right) => compareKeys(left.key, right.key));
+    const anchor = input.cursor ? readCursor(input.cursor) : null;
+    const remaining = anchor ? entries.filter(({ key }) => compareKeys(key, anchor) > 0) : entries;
+    const page = remaining.slice(0, limit);
+    return {
+        records: page.map(({ record }) => record), total: entries.length, archivedCount,
+        nextCursor: remaining.length > limit ? Buffer.from(JSON.stringify(page.at(-1).key)).toString("base64url") : null,
+    };
+}

package/dist/src/web-ui/session-read-state/projection.d.ts

@@ -1,11 +1,12 @@
-import type { SessionSnapshotMessage } from "../../sessions/types.js";
+import type { SessionMessageIdentity } from "../../sessions/snapshot.js";
+import type { SessionMessageMetadata } from "../../sessions/metadata/projection.js";
 import type { WebReadState } from "./store.js";
 export type ReadBoundary = {
     readThroughMessageId?: unknown;
     readThroughRequestId?: unknown;
 };
-export declare function advanceReadCursor(state: WebReadState, sessionId: string, messages: SessionSnapshotMessage[], boundary: ReadBoundary, now: number): void;
-export declare function projectSessionReadState(state: WebReadState, sessionId: string, messages: SessionSnapshotMessage[]): {
+export declare function advanceReadCursor(state: WebReadState, sessionId: string, messages: SessionMessageIdentity[], boundary: ReadBoundary, now: number): void;
+export declare function projectSessionReadState(state: WebReadState, sessionId: string, messages: SessionMessageMetadata[]): {
     sessionId: string;
     readStateStatus: "available";
     unreadCount: number;

package/dist/src/web-ui/session-read-state/service.d.ts

@@ -1,3 +1,4 @@
+import { type SessionPageQuery } from "./pagination.js";
 import type { RuntimeConfig, SessionStore } from "../../runtime/ports.js";
 import type { SessionSnapshot } from "../../sessions/types.js";
 import { type ReadBoundary } from "./projection.js";
@@ -19,12 +20,46 @@ export declare class WebSessionReadStates {
     forget(environmentId: string, sessionId: string): Promise<void>;
     reset(environmentId: string, sessionId: string): Promise<void>;
     project(environmentId: string, snapshot: SessionSnapshot): Promise<{
+        sessionId: string;
+        readStateStatus: "available";
+        unreadMessageIds: (string | number)[];
+        unreadCount: number;
+        hasUnread: boolean;
+        readRevision: number;
+        readGeneration: string;
+        lastReadAt: number;
+        lastReadMessageId: string | number | null;
+        latestMessageId: string | number | null;
+        latestAssistantMessageId: string | number | null;
+    } | {
+        sessionId: string;
+        readStateStatus: "available";
+        unreadCount: number;
+        hasUnread: boolean;
+        lastReadMessageId: string | null;
+        lastReadAt: number;
+        latestMessageId: string | number | null;
+        latestAssistantMessageId: string | number | null;
+    } | {
         sessionId: string;
         readStateStatus: "unavailable";
         unreadCount: null;
         hasUnread: null;
         lastReadAt: null;
         lastReadMessageId: null;
+    }>;
+    mark(environmentId: string, sessionId: string, boundary: ReadBoundary): Promise<{
+        sessionId: string;
+        readStateStatus: "available";
+        unreadMessageIds: (string | number)[];
+        unreadCount: number;
+        hasUnread: boolean;
+        readRevision: number;
+        readGeneration: string;
+        lastReadAt: number;
+        lastReadMessageId: string | number | null;
+        latestMessageId: string | number | null;
+        latestAssistantMessageId: string | number | null;
     } | {
         sessionId: string;
         readStateStatus: "available";
@@ -34,18 +69,63 @@ export declare class WebSessionReadStates {
         lastReadAt: number;
         latestMessageId: string | number | null;
         latestAssistantMessageId: string | number | null;
-    }>;
-    mark(environmentId: string, sessionId: string, boundary: ReadBoundary): Promise<{
+    } | null>;
+    markVisible(environmentId: string, sessionId: string, input: unknown, generation: unknown, visibleMessages: unknown): Promise<{
         sessionId: string;
         readStateStatus: "available";
+        unreadMessageIds: (string | number)[];
         unreadCount: number;
         hasUnread: boolean;
-        lastReadMessageId: string | null;
+        readRevision: number;
+        readGeneration: string;
         lastReadAt: number;
+        lastReadMessageId: string | number | null;
         latestMessageId: string | number | null;
         latestAssistantMessageId: string | number | null;
     } | null>;
-    list(environmentId: string): Promise<{
+    list(environmentId: string, query?: SessionPageQuery): Promise<{
+        overview?: {
+            sessions: ({
+                sessionId: string;
+                readStateStatus: "available";
+                unreadCount: number;
+                hasUnread: boolean;
+                lastReadMessageId: string | null;
+                lastReadAt: number;
+                latestMessageId: string | number | null;
+                latestAssistantMessageId: string | number | null;
+                kind?: import("../../sessions/spark-session.js").SessionKind;
+                project?: import("../../sessions/project-binding.js").SessionProject;
+                id: string;
+                title: string;
+                createdAt: number;
+                updatedAt: number;
+                lastMessagePreview: string;
+                lastMessageAt: number | null;
+            } | {
+                sessionId: string;
+                readStateStatus: "unavailable";
+                unreadCount: null;
+                hasUnread: null;
+                lastReadAt: null;
+                lastReadMessageId: null;
+                kind?: import("../../sessions/spark-session.js").SessionKind;
+                project?: import("../../sessions/project-binding.js").SessionProject;
+                id: string;
+                title: string;
+                createdAt: number;
+                updatedAt: number;
+                lastMessagePreview: string;
+                lastMessageAt: number | null;
+                latestMessageId: string | number | null;
+                latestAssistantMessageId: string | number | null;
+            })[];
+            unreadCount: number;
+            hasUnavailableReadState: boolean;
+        } | undefined;
+        total: number;
+        archivedCount: number;
+        nextCursor: string | null;
         sessions: {
             sessionId: string;
             readStateStatus: "available";
@@ -55,20 +135,117 @@ export declare class WebSessionReadStates {
             lastReadAt: number;
             latestMessageId: string | number | null;
             latestAssistantMessageId: string | number | null;
+            kind?: import("../../sessions/spark-session.js").SessionKind;
+            project?: import("../../sessions/project-binding.js").SessionProject;
+            id: string;
             title: string;
             createdAt: number;
             updatedAt: number;
             lastMessagePreview: string;
             lastMessageAt: number | null;
-            project?: Readonly<{
+        }[];
+    } | {
+        overview?: {
+            sessions: ({
+                sessionId: string;
+                readStateStatus: "available";
+                unreadCount: number;
+                hasUnread: boolean;
+                lastReadMessageId: string | null;
+                lastReadAt: number;
+                latestMessageId: string | number | null;
+                latestAssistantMessageId: string | number | null;
+                kind?: import("../../sessions/spark-session.js").SessionKind;
+                project?: import("../../sessions/project-binding.js").SessionProject;
+                id: string;
+                title: string;
+                createdAt: number;
+                updatedAt: number;
+                lastMessagePreview: string;
+                lastMessageAt: number | null;
+            } | {
+                sessionId: string;
+                readStateStatus: "unavailable";
+                unreadCount: null;
+                hasUnread: null;
+                lastReadAt: null;
+                lastReadMessageId: null;
+                kind?: import("../../sessions/spark-session.js").SessionKind;
+                project?: import("../../sessions/project-binding.js").SessionProject;
                 id: string;
-                name: string;
-                directory: string;
-            }> | undefined;
+                title: string;
+                createdAt: number;
+                updatedAt: number;
+                lastMessagePreview: string;
+                lastMessageAt: number | null;
+                latestMessageId: string | number | null;
+                latestAssistantMessageId: string | number | null;
+            })[];
+            unreadCount: number;
+            hasUnavailableReadState: boolean;
+        } | undefined;
+        nextCursor: null;
+        sessions: {
+            sessionId: string;
+            readStateStatus: "available";
+            unreadCount: number;
+            hasUnread: boolean;
+            lastReadMessageId: string | null;
+            lastReadAt: number;
+            latestMessageId: string | number | null;
+            latestAssistantMessageId: string | number | null;
+            kind?: import("../../sessions/spark-session.js").SessionKind;
+            project?: import("../../sessions/project-binding.js").SessionProject;
             id: string;
+            title: string;
+            createdAt: number;
+            updatedAt: number;
+            lastMessagePreview: string;
+            lastMessageAt: number | null;
         }[];
-        nextCursor: null;
     } | {
+        overview?: {
+            sessions: ({
+                sessionId: string;
+                readStateStatus: "available";
+                unreadCount: number;
+                hasUnread: boolean;
+                lastReadMessageId: string | null;
+                lastReadAt: number;
+                latestMessageId: string | number | null;
+                latestAssistantMessageId: string | number | null;
+                kind?: import("../../sessions/spark-session.js").SessionKind;
+                project?: import("../../sessions/project-binding.js").SessionProject;
+                id: string;
+                title: string;
+                createdAt: number;
+                updatedAt: number;
+                lastMessagePreview: string;
+                lastMessageAt: number | null;
+            } | {
+                sessionId: string;
+                readStateStatus: "unavailable";
+                unreadCount: null;
+                hasUnread: null;
+                lastReadAt: null;
+                lastReadMessageId: null;
+                kind?: import("../../sessions/spark-session.js").SessionKind;
+                project?: import("../../sessions/project-binding.js").SessionProject;
+                id: string;
+                title: string;
+                createdAt: number;
+                updatedAt: number;
+                lastMessagePreview: string;
+                lastMessageAt: number | null;
+                latestMessageId: string | number | null;
+                latestAssistantMessageId: string | number | null;
+            })[];
+            unreadCount: number;
+            hasUnavailableReadState: boolean;
+        } | undefined;
+        total: number;
+        archivedCount: number;
+        nextCursor: string | null;
         sessions: {
             sessionId: string;
             readStateStatus: "unavailable";
@@ -76,6 +253,9 @@ export declare class WebSessionReadStates {
             hasUnread: null;
             lastReadAt: null;
             lastReadMessageId: null;
+            kind?: import("../../sessions/spark-session.js").SessionKind;
+            project?: import("../../sessions/project-binding.js").SessionProject;
+            id: string;
             title: string;
             createdAt: number;
             updatedAt: number;
@@ -83,14 +263,66 @@ export declare class WebSessionReadStates {
             lastMessageAt: number | null;
             latestMessageId: string | number | null;
             latestAssistantMessageId: string | number | null;
-            project?: Readonly<{
+        }[];
+    } | {
+        overview?: {
+            sessions: ({
+                sessionId: string;
+                readStateStatus: "available";
+                unreadCount: number;
+                hasUnread: boolean;
+                lastReadMessageId: string | null;
+                lastReadAt: number;
+                latestMessageId: string | number | null;
+                latestAssistantMessageId: string | number | null;
+                kind?: import("../../sessions/spark-session.js").SessionKind;
+                project?: import("../../sessions/project-binding.js").SessionProject;
+                id: string;
+                title: string;
+                createdAt: number;
+                updatedAt: number;
+                lastMessagePreview: string;
+                lastMessageAt: number | null;
+            } | {
+                sessionId: string;
+                readStateStatus: "unavailable";
+                unreadCount: null;
+                hasUnread: null;
+                lastReadAt: null;
+                lastReadMessageId: null;
+                kind?: import("../../sessions/spark-session.js").SessionKind;
+                project?: import("../../sessions/project-binding.js").SessionProject;
                 id: string;
-                name: string;
-                directory: string;
-            }> | undefined;
+                title: string;
+                createdAt: number;
+                updatedAt: number;
+                lastMessagePreview: string;
+                lastMessageAt: number | null;
+                latestMessageId: string | number | null;
+                latestAssistantMessageId: string | number | null;
+            })[];
+            unreadCount: number;
+            hasUnavailableReadState: boolean;
+        } | undefined;
+        nextCursor: null;
+        sessions: {
+            sessionId: string;
+            readStateStatus: "unavailable";
+            unreadCount: null;
+            hasUnread: null;
+            lastReadAt: null;
+            lastReadMessageId: null;
+            kind?: import("../../sessions/spark-session.js").SessionKind;
+            project?: import("../../sessions/project-binding.js").SessionProject;
             id: string;
+            title: string;
+            createdAt: number;
+            updatedAt: number;
+            lastMessagePreview: string;
+            lastMessageAt: number | null;
+            latestMessageId: string | number | null;
+            latestAssistantMessageId: string | number | null;
         }[];
-        nextCursor: null;
     }>;
 }
 export {};

package/dist/src/web-ui/session-read-state/service.js

@@ -1,7 +1,11 @@
+import { sessionListOverview } from "./overview.js";
+import { sessionMetadataPage } from "./pagination.js";
+import { webPageSize } from "../local-runtime/history-pagination.js";
 import { createHash } from "node:crypto";
 import { join, resolve } from "node:path";
-import { SessionService } from "../../sessions/session-service.js";
-import { clientVisibleMessages, toSessionListItem, toSnapshotMessage, } from "../../sessions/record/projection.js";
+import { listSessionMetadata } from "../../sessions/metadata/store.js";
+import { isSparkSession } from "../../sessions/spark-session.js";
+import { markVisibleAssistantMessages, projectVisibleSessionReadState, visibleReadMessageIds, visibleReadObservations } from "./visible-messages.js";
 import { WebReadStateStore } from "./store.js";
 import { captureReadStateAvailability, unavailableSessionReadState, } from "./availability.js";
 import { advanceReadCursor, projectSessionReadState, } from "./projection.js";
@@ -39,7 +43,9 @@ export class WebSessionReadStates {
         await captureReadStateAvailability(() => this.store(environmentId).reset(sessionId, this.now()));
     }
     async project(environmentId, snapshot) {
-        const result = await captureReadStateAvailability(() => this.store(environmentId).transaction((state) => projectSessionReadState(state, snapshot.sessionId, snapshot.messages)));
+        const result = await captureReadStateAvailability(() => this.store(environmentId).transaction((state) => isSparkSession(snapshot)
+            ? projectVisibleSessionReadState(state, snapshot.sessionId, (snapshot.messageIndex ?? snapshot.messages))
+            : projectSessionReadState(state, snapshot.sessionId, (snapshot.messageIndex ?? snapshot.messages))));
         if (result.readStateStatus === "unavailable")
             return unavailableSessionReadState(snapshot.sessionId);
         return result.value;
@@ -50,39 +56,53 @@ export class WebSessionReadStates {
         const sessions = this.getEnvironment(environmentId).services.sessions;
         return store.transaction(async (state) => {
             const snapshot = await sessions.getSessionSnapshot(sessionId, {
-                includeRequests: false,
+                includeRequests: false, identitiesOnly: true,
             });
             if (!snapshot)
                 return null;
-            advanceReadCursor(state, sessionId, snapshot.messages, boundary, this.now());
-            return projectSessionReadState(state, sessionId, snapshot.messages);
+            if (isSparkSession(snapshot))
+                return projectVisibleSessionReadState(state, sessionId, (snapshot.messageIndex ?? snapshot.messages));
+            advanceReadCursor(state, sessionId, (snapshot.messageIndex ?? snapshot.messages), boundary, this.now());
+            return projectSessionReadState(state, sessionId, (snapshot.messageIndex ?? snapshot.messages));
         });
     }
-    async list(environmentId) {
+    async markVisible(environmentId, sessionId, input, generation, visibleMessages) {
+        const ids = visibleReadMessageIds(input);
+        const observations = visibleReadObservations(ids, visibleMessages);
+        const sessions = this.getEnvironment(environmentId).services.sessions;
+        return this.store(environmentId).transaction(async (state) => {
+            const snapshot = await sessions.getSessionSnapshot(sessionId, { includeRequests: false, identitiesOnly: true });
+            if (!snapshot || !isSparkSession(snapshot))
+                return null;
+            markVisibleAssistantMessages(state, sessionId, (snapshot.messageIndex ?? snapshot.messages), observations, generation, this.now());
+            return projectVisibleSessionReadState(state, sessionId, (snapshot.messageIndex ?? snapshot.messages));
+        });
+    }
+    async list(environmentId, query) {
         const { sessionsDir } = this.getEnvironment(environmentId).services.config.paths;
-        // One canonical disk enumeration avoids mutable offset pages and sending
-        // every request event across the managed Runtime's bounded RPC transport.
-        const records = await new SessionService({ sessionsDir }).getAllSessions();
-        const projectedSessions = records.map((record) => ({
-            summary: toSessionListItem(record),
-            messages: clientVisibleMessages(record.messages).map((message) => toSnapshotMessage(record.id, message, record.requests ?? [])),
-        }));
+        const records = await listSessionMetadata(sessionsDir);
+        const projectedSessions = records.filter((record) => record.interactive)
+            .filter((record) => !isSparkSession(record.summary));
+        const page = query ? sessionMetadataPage(projectedSessions, query, webPageSize(this.getEnvironment(environmentId).services.config))
+            : { records: projectedSessions, nextCursor: null };
+        const { records: selected, ...pageInfo } = page;
         const result = await captureReadStateAvailability(() => this.store(environmentId).transaction((state) => {
-            const sessions = projectedSessions.map(({ summary, messages }) => {
+            const sessions = selected.map(({ summary, messages }) => {
                 return {
                     ...summary,
                     ...projectSessionReadState(state, summary.id, messages),
                 };
             });
-            return { sessions, nextCursor: null };
+            return { sessions, ...pageInfo, ...(query && !query.cursor ? { overview: sessionListOverview(projectedSessions, query.archivedSessionIds, state) } : {}) };
         }));
         if (result.readStateStatus === "unavailable")
             return {
-                sessions: projectedSessions.map(({ summary }) => ({
+                sessions: selected.map(({ summary }) => ({
                     ...summary,
                     ...unavailableSessionReadState(summary.id),
                 })),
-                nextCursor: null,
+                ...pageInfo,
+                ...(query && !query.cursor ? { overview: sessionListOverview(projectedSessions, query.archivedSessionIds) } : {}),
             };
         return result.value;
     }