@pi-in-go/pigpen-ahp 0.1.0

package/proof/oracle/src/pi/resource-watch.ts

@@ -0,0 +1,357 @@
+/**
+ * Filesystem watchers — the `ahp-resource-watch:` channel.
+ *
+ * A watch has no dispose command. The protocol ties its lifetime to interest:
+ * the receiver releases it once its subscribers go away, after a grace window
+ * that lets a disconnected client reclaim the channel.
+ *
+ * The state itself never changes: `resourceWatchReducer` returns the same
+ * object for `resourceWatch/changed`. Changes are transient event traffic.
+ *
+ * @see https://microsoft.github.io/agent-host-protocol/specification/resource-watch-channel
+ */
+
+import { randomUUID } from "node:crypto";
+import { realpath, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+	ActionType,
+	AhpErrorCodes,
+	type CreateResourceWatchParams,
+	type CreateResourceWatchResult,
+	JsonRpcErrorCodes,
+	type ResourceChange,
+	ResourceChangeType,
+	type ResourceWatchState,
+	type URI,
+} from "@microsoft/agent-host-protocol";
+import { type FSWatcher, watch } from "chokidar";
+import { RESOURCE_WATCH_SCHEME } from "../core/channels.ts";
+import type { AhpHost } from "../core/host.ts";
+import { ProtocolError } from "../protocol/errors.ts";
+import { ResourcePathPolicy } from "./resource-paths.ts";
+import { isExcluded, matchesPatterns, mergeChange, relativeWatchPath } from "./resource-watch-policy.ts";
+
+export interface ResourceWatchOptions {
+	/** Shared access policy for the request/response and watch resource surfaces. */
+	readonly pathPolicy?: ResourcePathPolicy;
+	/** How long an unsubscribed watch remains available for reconnect. */
+	readonly graceMs?: number;
+	/** Maximum time to collect changes into one protocol action. */
+	readonly debounceMs?: number;
+	readonly log?: (message: string) => void;
+}
+
+const DEFAULT_GRACE_MS = 30_000;
+const DEFAULT_DEBOUNCE_MS = 50;
+
+interface ActiveWatch {
+	readonly channel: URI;
+	/** The path clients addressed; emitted event URIs retain this spelling. */
+	readonly resourceRoot: string;
+	/** The canonical path passed to chokidar. */
+	readonly watchedRoot: string;
+	readonly watcher: FSWatcher;
+	readonly excludes: readonly string[];
+	readonly includes: readonly string[];
+	pending: Map<string, ResourceChangeType>;
+	flushTimer: NodeJS.Timeout | undefined;
+	graceTimer: NodeJS.Timeout | undefined;
+}
+
+function errorCodeOf(error: unknown): string | undefined {
+	return (error as NodeJS.ErrnoException | undefined)?.code;
+}
+
+function watchError(error: unknown, uri: string): ProtocolError {
+	if (error instanceof ProtocolError) return error;
+	switch (errorCodeOf(error)) {
+		case "ENOENT":
+			return ProtocolError.notFound(uri);
+		case "EACCES":
+		case "EPERM":
+			return new ProtocolError(AhpErrorCodes.PermissionDenied, `Permission denied: ${uri}`);
+		case "EINVAL":
+		case "ENOTDIR":
+			return ProtocolError.invalidParams(`Cannot watch ${uri}`);
+		default:
+			return new ProtocolError(
+				JsonRpcErrorCodes.InternalError,
+				`Cannot watch ${uri}: ${error instanceof Error ? error.message : String(error)}`,
+			);
+	}
+}
+
+function readPatterns(value: unknown, name: string): string[] {
+	if (value === undefined) return [];
+	if (typeof value !== "object" || value === null || !("items" in value)) {
+		throw ProtocolError.invalidParams(`${name} must contain an items array`);
+	}
+	const { items } = value;
+	if (!Array.isArray(items) || items.some((item) => typeof item !== "string")) {
+		throw ProtocolError.invalidParams(`${name}.items must be an array of strings`);
+	}
+	return [...items];
+}
+
+function waitUntilReady(watcher: FSWatcher): Promise<void> {
+	return new Promise((resolveReady, rejectReady) => {
+		const cleanup = (): void => {
+			watcher.removeListener("ready", onReady);
+			watcher.removeListener("error", onError);
+		};
+		const onReady = (): void => {
+			cleanup();
+			resolveReady();
+		};
+		const onError = (error: unknown): void => {
+			cleanup();
+			rejectReady(error);
+		};
+		watcher.once("ready", onReady);
+		watcher.once("error", onError);
+	});
+}
+
+/**
+ * Owns native watcher handles and their lifetime. `StateStore` remains the
+ * authority for protocol watch resources; this service retains only OS handles,
+ * filters, and unpublished event batches.
+ */
+export class ResourceWatchService {
+	readonly #host: AhpHost;
+	readonly #options: ResourceWatchOptions;
+	readonly #paths: ResourcePathPolicy;
+	readonly #watches = new Map<URI, ActiveWatch>();
+	readonly #unhook: () => void;
+	/** Native setup/close operations that shutdown must drain, not protocol state. */
+	readonly #pending = new Set<Promise<unknown>>();
+	#disposed = false;
+	#disposal: Promise<void> | undefined;
+
+	constructor(host: AhpHost, options: ResourceWatchOptions = {}) {
+		this.#host = host;
+		this.#options = options;
+		this.#paths = options.pathPolicy ?? new ResourcePathPolicy();
+		this.#unhook = host.onSubscriberCountChanged((channel, count) => {
+			this.#onSubscriberCount(channel, count);
+		});
+	}
+
+	/** Releases every native watcher. Safe to call more than once. */
+	dispose(): Promise<void> {
+		if (this.#disposal) return this.#disposal;
+		this.#disposed = true;
+		this.#unhook();
+		const releases = [...this.#watches.keys()].map((channel) => this.#release(channel));
+		this.#disposal = Promise.allSettled([...this.#pending, ...releases]).then(() => {});
+		return this.#disposal;
+	}
+
+	get activeCount(): number {
+		return this.#watches.size;
+	}
+
+	create(params: CreateResourceWatchParams): Promise<CreateResourceWatchResult> {
+		return this.#track(this.#create(params));
+	}
+
+	#track<T>(operation: Promise<T>): Promise<T> {
+		const pending = operation.finally(() => this.#pending.delete(pending));
+		this.#pending.add(pending);
+		return pending;
+	}
+
+	async #create(params: CreateResourceWatchParams): Promise<CreateResourceWatchResult> {
+		if (this.#disposed) {
+			throw new Error("ResourceWatchService is disposed");
+		}
+		if (!params || typeof params !== "object") {
+			throw ProtocolError.invalidParams("createResourceWatch params must be an object");
+		}
+		if (params.recursive !== undefined && typeof params.recursive !== "boolean") {
+			throw ProtocolError.invalidParams("recursive must be a boolean");
+		}
+		const uri = params.uri;
+		const recursive = params.recursive ?? false;
+		const excludes = readPatterns(params.excludes, "excludes");
+		const includes = readPatterns(params.includes, "includes");
+		const resourceRoot = await this.#paths.pathFor(uri);
+
+		let directory: boolean;
+		let watchedRoot: string;
+		try {
+			const stats = await stat(resourceRoot);
+			directory = stats.isDirectory();
+			if (!directory && recursive) {
+				throw ProtocolError.invalidParams(`Cannot watch a file recursively: ${uri}`);
+			}
+			// Watch the stable target but map events back to the URI spelling the
+			// client supplied. This makes a directory symlink usable without letting
+			// recursive watches follow further symlinks out of the permitted tree.
+			watchedRoot = await realpath(resourceRoot);
+		} catch (error) {
+			throw watchError(error, uri);
+		}
+
+		if (this.#disposed) throw new Error("ResourceWatchService is disposed");
+
+		// Starting from the parent keeps the watch alive when an editor replaces a
+		// file—or the watched directory itself—by rename. The ignored predicate
+		// prevents siblings from entering chokidar's watched tree.
+		const watchRoot = dirname(watchedRoot);
+		const depth = !directory ? 0 : recursive ? undefined : watchRoot === watchedRoot ? 0 : 1;
+		// Keep Chokidar's default persistent watcher: overlapping watches then
+		// share native handles and forward asynchronous watcher errors. Polling or
+		// `awaitWriteFinish` would change delivery timing rather than add protocol
+		// state guarantees.
+		const watcher = watch(watchRoot, {
+			atomic: true,
+			followSymlinks: false,
+			ignoreInitial: true,
+			...(depth === undefined ? {} : { depth }),
+			ignored: (path: string) => {
+				if (resolve(path) === watchRoot) return false;
+				const rel = relativeWatchPath(watchedRoot, path);
+				return rel === undefined || isExcluded(rel, excludes);
+			},
+		});
+		try {
+			// Let startup settle before closing: closing a not-yet-ready watcher
+			// does not settle its ready waiter. Shutdown drains this creation task.
+			await waitUntilReady(watcher);
+			if (this.#disposed) throw new Error("ResourceWatchService is disposed");
+		} catch (error) {
+			await watcher.close();
+			throw watchError(error, uri);
+		}
+
+		const channel: URI = `${RESOURCE_WATCH_SCHEME}/${randomUUID()}`;
+		const active: ActiveWatch = {
+			channel,
+			resourceRoot,
+			watchedRoot,
+			watcher,
+			excludes,
+			includes,
+			pending: new Map(),
+			flushTimer: undefined,
+			graceTimer: undefined,
+		};
+		const record = (path: string, type: ResourceChangeType): void => this.#record(active, path, type);
+		watcher
+			.on("add", (path) => record(path, ResourceChangeType.Added))
+			.on("addDir", (path) => record(path, ResourceChangeType.Added))
+			.on("change", (path) => record(path, ResourceChangeType.Updated))
+			.on("unlink", (path) => record(path, ResourceChangeType.Deleted))
+			.on("unlinkDir", (path) => record(path, ResourceChangeType.Deleted))
+			.on("error", (error) => {
+				this.#options.log?.(`watch ${channel} failed: ${String(error)}`);
+				void this.#release(channel);
+			});
+
+		const state: ResourceWatchState = {
+			root: uri,
+			recursive,
+			...(excludes.length > 0 ? { excludes: { items: [...excludes] } } : {}),
+			...(includes.length > 0 ? { includes: { items: [...includes] } } : {}),
+		};
+		this.#host.store.create(channel, state as never);
+		this.#watches.set(channel, active);
+
+		// The client subscribes after this request returns. Start a grace timer so
+		// an abandoned create cannot retain filesystem handles forever.
+		this.#startGrace(active);
+		return { channel };
+	}
+
+	// ── Change collection ───────────────────────────────────────────────────
+
+	#record(active: ActiveWatch, watchedPath: string, type: ResourceChangeType): void {
+		if (this.#watches.get(active.channel) !== active) return;
+		const rel = relativeWatchPath(active.watchedRoot, watchedPath);
+		if (rel === undefined || !matchesPatterns(rel, active.includes, active.excludes)) return;
+
+		const path = rel.length === 0 ? active.resourceRoot : join(active.resourceRoot, rel);
+		const merged = mergeChange(active.pending.get(path), type);
+		if (merged === undefined) {
+			active.pending.delete(path);
+		} else {
+			active.pending.set(path, merged);
+		}
+
+		if (active.pending.size === 0) {
+			if (active.flushTimer) clearTimeout(active.flushTimer);
+			active.flushTimer = undefined;
+			return;
+		}
+		if (active.flushTimer) return;
+		const timer = setTimeout(() => {
+			active.flushTimer = undefined;
+			this.#flush(active);
+		}, this.#options.debounceMs ?? DEFAULT_DEBOUNCE_MS);
+		timer.unref?.();
+		active.flushTimer = timer;
+	}
+
+	#flush(active: ActiveWatch): void {
+		if (this.#watches.get(active.channel) !== active) {
+			active.pending.clear();
+			return;
+		}
+		const items: ResourceChange[] = [...active.pending]
+			.sort(([left], [right]) => left.localeCompare(right))
+			.map(([path, type]) => ({ uri: pathToFileURL(path).toString(), type }));
+		active.pending.clear();
+		if (items.length === 0) return;
+
+		this.#host.dispatchServerAction(active.channel, {
+			type: ActionType.ResourceWatchChanged,
+			changes: { items },
+		});
+	}
+
+	// ── Lifetime ────────────────────────────────────────────────────────────
+
+	#onSubscriberCount(channel: URI, count: number): void {
+		const active = this.#watches.get(channel);
+		if (!active) return;
+		if (count > 0) {
+			if (active.graceTimer) {
+				clearTimeout(active.graceTimer);
+				active.graceTimer = undefined;
+			}
+			return;
+		}
+		this.#startGrace(active);
+	}
+
+	#startGrace(active: ActiveWatch): void {
+		if (active.graceTimer) return;
+		const timer = setTimeout(() => {
+			active.graceTimer = undefined;
+			if (this.#host.subscriberCount(active.channel) === 0) {
+				this.#options.log?.(`releasing unwatched ${active.channel}`);
+				void this.#release(active.channel);
+			}
+		}, this.#options.graceMs ?? DEFAULT_GRACE_MS);
+		timer.unref?.();
+		active.graceTimer = timer;
+	}
+
+	async #release(channel: URI): Promise<void> {
+		const active = this.#watches.get(channel);
+		if (!active) return;
+		this.#watches.delete(channel);
+		if (active.flushTimer) clearTimeout(active.flushTimer);
+		if (active.graceTimer) clearTimeout(active.graceTimer);
+		active.pending.clear();
+		this.#host.store.delete(channel);
+		try {
+			await this.#track(active.watcher.close());
+		} catch (error) {
+			this.#options.log?.(`closing watch ${channel} failed: ${String(error)}`);
+		}
+	}
+}

package/proof/oracle/src/pi/session-catalogue.ts

@@ -0,0 +1,318 @@
+/**
+ * The session catalogue, backed by pi's on-disk session files.
+ *
+ * Production points it at pi's default per-directory JSONL tree under
+ * `getAgentDir()/sessions`; tests and embeddings provide their root explicitly.
+ * It does not resolve pi's optional custom `sessionDir` setting. Parsing a
+ * summary reads the session file, so `listSessions` stats and sorts the corpus
+ * but parses only the requested page.
+ *
+ * @see https://microsoft.github.io/agent-host-protocol/specification/root-channel
+ */
+
+import { closeSync, openSync, readSync } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { type ListSessionsResult, SessionStatus, type SessionSummary, type URI } from "@microsoft/agent-host-protocol";
+import { sessionUri } from "../core/channels.ts";
+import { pathToFileUri } from "../core/uri.ts";
+import { ProtocolError } from "../protocol/errors.ts";
+import { PI_PROVIDER } from "./provider.ts";
+import { sessionDisplayTitle } from "./session-title.ts";
+import { textFromPiUserContent } from "./user-message.ts";
+
+/** Page size when the client does not ask for one. */
+const DEFAULT_PAGE_SIZE = 30;
+/** Upper bound regardless of what the client asks for; each entry costs a file parse. */
+const MAX_PAGE_SIZE = 100;
+/** Enough for pi's session header line, which is written first. */
+const HEADER_SCAN_BYTES = 8192;
+
+interface SessionFile {
+	readonly path: string;
+	readonly mtimeMs: number;
+}
+
+/** In-memory summary for a session that may not have reached disk yet. */
+export interface LiveSessionCatalogueEntry {
+	readonly file?: string;
+	readonly summary: SessionSummary;
+}
+
+/** Read lazily so a turn ending during disk discovery wins before the response is built. */
+export type LiveSessionCatalogueSource = () => readonly LiveSessionCatalogueEntry[];
+
+interface CatalogueEntry extends SessionFile {
+	/** Real file to parse; absent for a live session with no backing path. */
+	readonly file?: string;
+	/** Whether the file existed in this catalogue scan and is safe to cache. */
+	readonly onDisk?: boolean;
+	/** Present when live state is more authoritative than the file. */
+	readonly summary?: SessionSummary;
+}
+
+/**
+ * Every session file with its mtime, newest first.
+ *
+ * `stat` only — no parsing. mtime is a good proxy for pi's own "last activity"
+ * ordering because the file is appended on every message.
+ */
+async function listSessionFiles(root: string): Promise<SessionFile[]> {
+	let directories: string[];
+	try {
+		directories = await readdir(root);
+	} catch (error) {
+		// No sessions directory yet is an empty catalogue, not an error.
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+			return [];
+		}
+		throw error;
+	}
+
+	const files: SessionFile[] = [];
+	await Promise.all(
+		directories.map(async (directory) => {
+			const directoryPath = join(root, directory);
+			let entries: string[];
+			try {
+				entries = await readdir(directoryPath);
+			} catch {
+				return; // A file (not a directory) at the top level, or a race with deletion.
+			}
+			await Promise.all(
+				entries
+					.filter((name) => name.endsWith(".jsonl"))
+					.map(async (name) => {
+						const path = join(directoryPath, name);
+						try {
+							const stats = await stat(path);
+							files.push({ path, mtimeMs: stats.mtimeMs });
+						} catch {
+							// Deleted between readdir and stat.
+						}
+					}),
+			);
+		}),
+	);
+
+	// Ties broken by path so the keyset cursor is total and stable.
+	files.sort((a, b) => b.mtimeMs - a.mtimeMs || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+	return files;
+}
+
+/** Cursors are opaque to clients; this is just a keyset encoding. */
+function encodeCursor(file: SessionFile): string {
+	return Buffer.from(`${file.mtimeMs}\u0000${file.path}`, "utf8").toString("base64url");
+}
+
+function decodeCursor(cursor: string): SessionFile {
+	const decoded = Buffer.from(cursor, "base64url").toString("utf8");
+	const separator = decoded.indexOf("\u0000");
+	const mtimeMs = Number(decoded.slice(0, separator));
+	const path = decoded.slice(separator + 1);
+	if (separator < 0 || !Number.isFinite(mtimeMs) || path.length === 0) {
+		throw ProtocolError.invalidParams("Unrecognised listSessions cursor");
+	}
+	return { path, mtimeMs };
+}
+
+/**
+ * Reads just the session id from a file's header line.
+ *
+ * pi writes the `session` header first, so this never parses the transcript.
+ */
+function readSessionId(path: string): string | undefined {
+	let handle: number | undefined;
+	try {
+		handle = openSync(path, "r");
+		const buffer = Buffer.allocUnsafe(HEADER_SCAN_BYTES);
+		const read = readSync(handle, buffer, 0, buffer.length, 0);
+		const newline = buffer.indexOf(0x0a, 0);
+		const line = buffer.toString("utf8", 0, newline >= 0 && newline < read ? newline : read);
+		const header = JSON.parse(line) as { type?: string; id?: string };
+		return header.type === "session" && typeof header.id === "string" ? header.id : undefined;
+	} catch {
+		return undefined;
+	} finally {
+		if (handle !== undefined) {
+			closeSync(handle);
+		}
+	}
+}
+
+/**
+ * Parses one session file into a summary.
+ *
+ * Returns `undefined` for a file that is not a readable pi session so a single
+ * corrupt file cannot break the whole catalogue.
+ */
+function readSessionSummary(file: SessionFile): SessionSummary | undefined {
+	let manager: SessionManager;
+	try {
+		manager = SessionManager.open(file.path);
+	} catch {
+		return undefined;
+	}
+
+	const sessionId = manager.getSessionId();
+	if (!sessionId) {
+		return undefined;
+	}
+
+	const entries = manager.getEntries();
+	let firstUserMessage: string | undefined;
+	let createdAt: string | undefined;
+	for (const entry of entries) {
+		createdAt ??= entry.timestamp;
+		if (entry.type !== "message") {
+			continue;
+		}
+		const message = (entry as { message?: { role?: string; content?: unknown } }).message;
+		if (message?.role === "user") {
+			const text = textFromPiUserContent(message.content).trim();
+			if (text) {
+				firstUserMessage = text;
+				break;
+			}
+		}
+	}
+
+	const cwd = manager.getCwd();
+	return {
+		resource: sessionUri(sessionId),
+		provider: PI_PROVIDER,
+		title: sessionDisplayTitle(manager.getSessionName(), firstUserMessage),
+		// Idle by definition, and reported as read.
+		//
+		// Read/unread is not modelled: pi has no such concept, so tracking it
+		// would mean this host inventing durable state of its own — and without
+		// archiving to go with it, a catalogue where everything is permanently
+		// unread is worse than one that is quiet. The chat reducer may still clear
+		// its chat-local bit on `chat/turnStarted`; the session catalogue remains
+		// read because this host does not implement mutable session read state.
+		status: SessionStatus.Idle | SessionStatus.IsRead,
+		createdAt: createdAt ?? new Date(file.mtimeMs).toISOString(),
+		modifiedAt: new Date(file.mtimeMs).toISOString(),
+		...(cwd ? { workingDirectories: [pathToFileUri(cwd)] } : {}),
+		_meta: { piSessionFile: file.path },
+	};
+}
+
+/**
+ * Serves `listSessions`, newest first, parsing only the requested page.
+ */
+export class PiSessionCatalogue {
+	readonly #root: string;
+	/** Session URI → file path, populated as pages are read. Purely a cache. */
+	readonly #index = new Map<URI, string>();
+	constructor(root: string) {
+		this.#root = root;
+	}
+
+	/** The pi session file backing a URI, if a page has surfaced it. */
+	fileFor(uri: URI): string | undefined {
+		return this.#index.get(uri);
+	}
+
+	/**
+	 * Locates the file backing a session id, scanning if necessary.
+	 *
+	 * A client can subscribe to a session it learned about on an earlier
+	 * connection, so the in-memory index built while paging is not enough. The
+	 * scan reads headers only — `stat` plus the first line — and stops at the
+	 * first match, ordered newest-first so a recently-touched session is found
+	 * almost immediately.
+	 */
+	async findSessionFile(sessionId: string): Promise<string | undefined> {
+		const uri = sessionUri(sessionId);
+		const cached = this.#index.get(uri);
+		if (cached) {
+			// The cache is only an index hint: deletion by this host, pi, or the
+			// user must invalidate a path before it is returned again.
+			if (readSessionId(cached) === sessionId) {
+				return cached;
+			}
+			this.#index.delete(uri);
+		}
+		for (const file of await listSessionFiles(this.#root)) {
+			const id = readSessionId(file.path);
+			if (id) {
+				this.#index.set(sessionUri(id), file.path);
+			}
+			if (id === sessionId) {
+				return file.path;
+			}
+		}
+		return undefined;
+	}
+
+	async list(
+		limit: number | undefined,
+		cursor: string | undefined,
+		live: LiveSessionCatalogueSource = () => [],
+	): Promise<ListSessionsResult> {
+		const pageSize = Math.min(Math.max(1, limit ?? DEFAULT_PAGE_SIZE), MAX_PAGE_SIZE);
+		const entries = new Map<string, CatalogueEntry>();
+		for (const file of await listSessionFiles(this.#root)) {
+			entries.set(file.path, { ...file, file: file.path, onDisk: true });
+		}
+		// Read live state after asynchronous disk discovery. From here through
+		// response construction there is no await, so a turn transition cannot
+		// make the returned page older than a notification sent before it.
+		for (const item of live()) {
+			const parsed = Date.parse(item.summary.modifiedAt);
+			const path = item.file ?? `live:${item.summary.resource}`;
+			const existing = entries.get(path);
+			entries.set(path, {
+				path,
+				mtimeMs: Number.isFinite(parsed) ? parsed : 0,
+				...(item.file ? { file: item.file } : {}),
+				...(existing?.onDisk ? { onDisk: true } : {}),
+				summary: item.summary,
+			});
+		}
+		const ordered = [...entries.values()].sort(
+			(a, b) => b.mtimeMs - a.mtimeMs || (a.path < b.path ? -1 : a.path > b.path ? 1 : 0),
+		);
+
+		let start = 0;
+		if (cursor !== undefined) {
+			const after = decodeCursor(cursor);
+			const index = ordered.findIndex((entry) => entry.path === after.path);
+			if (index < 0) {
+				// The entry the cursor named is gone (deleted between pages).
+				// Fall back to the position it would have occupied rather than
+				// failing the whole call.
+				start = ordered.findIndex(
+					(entry) => entry.mtimeMs < after.mtimeMs || (entry.mtimeMs === after.mtimeMs && entry.path > after.path),
+				);
+				if (start < 0) {
+					return { items: [] };
+				}
+			} else {
+				start = index + 1;
+			}
+		}
+
+		const page = ordered.slice(start, start + pageSize);
+		const items: SessionSummary[] = [];
+		for (const entry of page) {
+			const summary =
+				entry.summary ?? (entry.file ? readSessionSummary({ path: entry.file, mtimeMs: entry.mtimeMs }) : undefined);
+			if (summary) {
+				if (entry.file && entry.onDisk) {
+					this.#index.set(summary.resource, entry.file);
+				}
+				items.push(summary);
+			}
+		}
+
+		const last = page[page.length - 1];
+		const hasMore = start + page.length < ordered.length;
+		return {
+			items,
+			...(hasMore && last ? { nextCursor: encodeCursor(last) } : {}),
+		};
+	}
+}