@openclaw/acpx 2026.8.1-beta.2 → 2026.8.1

package/dist/{pi-session-catalog-runtime-BiTQtT7s.js → pi-session-catalog-runtime-g6A6ADEf.js}

@@ -1,15 +1,17 @@
-import { a as PI_SESSION_READ_COMMAND, i as PI_SESSIONS_LIST_COMMAND, n as piSessionStore, o as PI_TERMINAL_RESUME_COMMAND, r as piSessionStoreAvailable, t as piAcpSessionStoreRoot } from "./pi-session-paths-DgYt8LUg.js";
+import { c as PI_SESSION_READ_COMMAND, i as PI_LOCAL_SESSION_HOST_ID, l as PI_TERMINAL_RESUME_COMMAND, n as piSessionStore, o as PI_SESSIONS_LIST_COMMAND, r as piSessionStoreAvailable, s as PI_SESSION_ID_PATTERN, t as piAcpSessionStoreRoot } from "./pi-session-paths-EMbd4Hkz.js";
 import { parseDateFirstTimestampMs } from "openclaw/plugin-sdk/number-runtime";
-import { decodeNodePtyResumeParams, resolveNodeHostExecutable, runNodePtyCommand } from "openclaw/plugin-sdk/node-host";
+import { resolveNodeHostExecutable } from "openclaw/plugin-sdk/node-host";
+import { createSessionCatalogFamily, importSessionCatalogHistory, isExternalUserText, listAdoptedSessionCatalogSessions, sessionCatalogAdoptedSessionKey, sessionCatalogPaging } from "openclaw/plugin-sdk/session-catalog";
 import { isRecord, normalizeBoundedOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { createReadStream } from "node:fs";
 import path from "node:path";
 import fs$1 from "node:fs/promises";
 import process from "node:process";
 import { resolveAcpSessionAvailability } from "openclaw/plugin-sdk/acp-runtime";
-import { resolveDefaultAgentId } from "openclaw/plugin-sdk/agent-runtime";
-import { createSessionCatalogAdoptionCoordinator, importSessionCatalogHistory, isExternalUserText, listAdoptedSessionCatalogSessions, sessionCatalogAdoptedSessionKey, sessionCatalogAdoptedSourceKey } from "openclaw/plugin-sdk/session-catalog";
+import { resolveSessionAgentIdsStrict } from "openclaw/plugin-sdk/agent-scope-runtime";
 import { truncateUtf16Safe } from "openclaw/plugin-sdk/text-utility-runtime";
+import { runTasksWithConcurrency } from "openclaw/plugin-sdk/concurrency-runtime";
+import { isPathStrictlyInside } from "openclaw/plugin-sdk/file-access-runtime";
 //#region extensions/acpx/src/pi-session-timestamp.ts
 /** Preserve Pi JSONL's date-first string contract while accepting numeric millisecond values. */
 function parsePiSessionTimestampMs(value) {
@@ -26,7 +28,7 @@ const APPEND_PROOF_EDGE_BYTES = 64 * 1024;
 const IO_CONCURRENCY = 8;
 const PI_FILE_CANDIDATE_CACHE_TTL_MS = 32e3;
 const PI_FILE_CANDIDATE_CACHE_MAX_ENTRIES = 8;
-const SESSION_ID_PATTERN$2 = /^(?!-)[A-Za-z0-9._:-]{1,256}$/u;
+const SESSION_ID_PATTERN = /^(?!-)[A-Za-z0-9._:-]{1,256}$/u;
 const summaryCache = /* @__PURE__ */ new Map();
 const threadFileCache = /* @__PURE__ */ new Map();
 const piFileCandidateCache = /* @__PURE__ */ new Map();
@@ -94,38 +96,30 @@ async function realpathOrResolve(value) {
 		return path.resolve(value);
 	}
 }
-async function mapConcurrent(values, limit, mapper) {
-	const results = [];
-	results.length = values.length;
-	let nextIndex = 0;
-	const workers = Array.from({ length: Math.min(limit, values.length) }, async () => {
-		while (nextIndex < values.length) {
-			const index = nextIndex++;
-			results[index] = await mapper(values[index]);
-		}
-	});
-	await Promise.all(workers);
-	return results;
-}
 async function scanPiFileCandidates(env) {
 	const { root, files } = await discoverPiSessionFiles(env);
 	const configuredAcpRoot = piAcpSessionStoreRoot(env);
 	const acpRoot = configuredAcpRoot ? await realpathOrResolve(configuredAcpRoot) : void 0;
-	return (await mapConcurrent(files, IO_CONCURRENCY, async (file) => {
-		try {
-			const stats = await fs$1.stat(file);
-			return stats.isFile() ? {
-				file,
-				storeRoot: root,
-				identity: `${String(stats.dev)}:${String(stats.ino)}:${String(stats.birthtimeMs)}`,
-				mtimeMs: stats.mtimeMs,
-				size: stats.size,
-				resumable: acpRoot ? pathIsWithin(acpRoot, file) : false
-			} : void 0;
-		} catch {
-			return;
-		}
-	})).filter((candidate) => candidate !== void 0).toSorted((left, right) => right.mtimeMs - left.mtimeMs);
+	const { results: candidates } = await runTasksWithConcurrency({
+		tasks: files.map((file) => async () => {
+			try {
+				const stats = await fs$1.stat(file);
+				return stats.isFile() ? {
+					file,
+					storeRoot: root,
+					identity: `${String(stats.dev)}:${String(stats.ino)}:${String(stats.birthtimeMs)}`,
+					mtimeMs: stats.mtimeMs,
+					size: stats.size,
+					resumable: acpRoot ? isPathStrictlyInside(acpRoot, file) : false
+				} : void 0;
+			} catch {
+				return;
+			}
+		}),
+		limit: IO_CONCURRENCY,
+		throwOnError: true
+	});
+	return candidates.filter((candidate) => candidate !== void 0).toSorted((left, right) => right.mtimeMs - left.mtimeMs);
 }
 async function piFileCandidates(env) {
 	const store = piSessionStore(env);
@@ -155,10 +149,6 @@ async function piFileCandidates(env) {
 		throw error;
 	}
 }
-function pathIsWithin(root, candidate) {
-	const relative = path.relative(root, candidate);
-	return relative !== "" && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
-}
 function parsePiJsonLines(content) {
 	return content.split(/\r?\n/u).flatMap((line) => {
 		if (!line.trim()) return [];
@@ -277,7 +267,7 @@ async function readPiSessionSummary(candidate) {
 		const { header, name, firstMessage } = projectedState;
 		const version = header?.type === "session" && typeof header.version === "number" ? header.version : 1;
 		const threadId = header?.type === "session" ? normalizeBoundedOptionalString(header.id, 256) : void 0;
-		if (header && threadId && SESSION_ID_PATTERN$2.test(threadId)) {
+		if (header && threadId && SESSION_ID_PATTERN.test(threadId)) {
 			const cwd = normalizeBoundedOptionalString(header.cwd, 4096);
 			const createdAt = parsePiSessionTimestampMs(header.timestamp);
 			summary = {
@@ -326,7 +316,11 @@ async function listPiSummaryPage(env, params) {
 	const matches = [];
 	const needle = params.searchTerm?.toLocaleLowerCase();
 	for (let index = 0; index < candidates.length && matches.length < target; index += SUMMARY_SCAN_BATCH_SIZE) {
-		const summaries = await mapConcurrent(candidates.slice(index, index + SUMMARY_SCAN_BATCH_SIZE), IO_CONCURRENCY, readPiSessionSummary);
+		const { results: summaries } = await runTasksWithConcurrency({
+			tasks: candidates.slice(index, index + SUMMARY_SCAN_BATCH_SIZE).map((candidate) => () => readPiSessionSummary(candidate)),
+			limit: IO_CONCURRENCY,
+			throwOnError: true
+		});
 		for (const summary of summaries) if (summary && summaryMatches(summary, needle)) {
 			matches.push(summary);
 			if (matches.length >= target) break;
@@ -340,7 +334,12 @@ async function listPiSummaryPage(env, params) {
 async function findPiSummary(threadId, env) {
 	const candidates = await piFileCandidates(env);
 	for (let index = 0; index < candidates.length; index += SUMMARY_SCAN_BATCH_SIZE) {
-		const match = (await mapConcurrent(candidates.slice(index, index + SUMMARY_SCAN_BATCH_SIZE), IO_CONCURRENCY, readPiSessionSummary)).find((summary) => summary?.threadId === threadId);
+		const { results: summaries } = await runTasksWithConcurrency({
+			tasks: candidates.slice(index, index + SUMMARY_SCAN_BATCH_SIZE).map((candidate) => () => readPiSessionSummary(candidate)),
+			limit: IO_CONCURRENCY,
+			throwOnError: true
+		});
+		const match = summaries.find((summary) => summary?.threadId === threadId);
 		if (match) return match;
 	}
 }
@@ -380,86 +379,8 @@ async function readPiSessionById(threadId, env) {
 }
 //#endregion
 //#region extensions/acpx/src/pi-session-catalog.ts
-const LOCAL_HOST_ID$1 = "gateway";
-const DEFAULT_PAGE_LIMIT = 20;
-const MAX_PAGE_LIMIT$1 = 100;
 const MAX_SEARCH_LENGTH = 500;
-const MAX_CURSOR_LENGTH = 128;
-const MAX_TRANSCRIPT_ITEM_BYTES = 512 * 1024;
-const MAX_TRANSCRIPT_PAGE_BYTES = 20 * 1024 * 1024;
-const SESSION_ID_PATTERN$1 = /^(?!-)[A-Za-z0-9._:-]{1,256}$/u;
-function boundedLimit(value, fallback = DEFAULT_PAGE_LIMIT) {
-	if (value === void 0) return fallback;
-	if (!Number.isInteger(value) || Number(value) < 1 || Number(value) > MAX_PAGE_LIMIT$1) throw new Error(`limit must be an integer between 1 and ${String(MAX_PAGE_LIMIT$1)}`);
-	return Number(value);
-}
-function encodeCursor(offset) {
-	return Buffer.from(JSON.stringify({ offset }), "utf8").toString("base64url");
-}
-function optionalRawCursor(value) {
-	if (value === void 0) return;
-	if (typeof value !== "string" || value.length === 0 || value.length > MAX_CURSOR_LENGTH) throw new Error("cursor is invalid");
-	return value;
-}
-function decodeCursor(value) {
-	const cursor = optionalRawCursor(value);
-	if (cursor === void 0) return 0;
-	try {
-		const bytes = Buffer.from(cursor, "base64url");
-		if (bytes.toString("base64url") !== cursor) throw new Error("non-canonical base64url");
-		const parsed = JSON.parse(bytes.toString("utf8"));
-		if (!isRecord(parsed) || !Number.isSafeInteger(parsed.offset) || Number(parsed.offset) < 0) throw new Error("invalid offset");
-		const offset = Number(parsed.offset);
-		if (encodeCursor(offset) !== cursor) throw new Error("non-canonical cursor payload");
-		return offset;
-	} catch (error) {
-		throw new Error("cursor is invalid", { cause: error });
-	}
-}
-function isExactPiSessionCursor(value) {
-	if (typeof value !== "string") return false;
-	try {
-		decodeCursor(value);
-		return true;
-	} catch {
-		return false;
-	}
-}
-function truncateUtf8(text, maxBytes) {
-	if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
-	let low = 0;
-	let high = text.length;
-	while (low < high) {
-		const middle = Math.ceil((low + high) / 2);
-		if (Buffer.byteLength(text.slice(0, middle), "utf8") <= maxBytes - 3) low = middle;
-		else high = middle - 1;
-	}
-	const end = low > 0 && /[\uD800-\uDBFF]/u.test(text.charAt(low - 1)) ? low - 1 : low;
-	return `${text.slice(0, end)}…`;
-}
-function transcriptPage(items, limit, offset) {
-	const end = Math.max(0, items.length - offset);
-	const start = Math.max(0, end - limit);
-	const page = [];
-	let pageBytes = 2;
-	for (let index = end - 1; index >= start; index -= 1) {
-		const item = items[index];
-		if (!item) continue;
-		const bounded = {
-			...item,
-			text: truncateUtf8(item.text ?? "", MAX_TRANSCRIPT_ITEM_BYTES)
-		};
-		const itemBytes = Buffer.byteLength(JSON.stringify(bounded), "utf8") + 1;
-		if (page.length > 0 && pageBytes + itemBytes > MAX_TRANSCRIPT_PAGE_BYTES) break;
-		page.unshift(bounded);
-		pageBytes += itemBytes;
-	}
-	const consumed = offset + page.length;
-	return {
-		items: page,
-		...consumed < items.length ? { nextCursor: encodeCursor(consumed) } : {}
-	};
-}
+const isExactPiSessionCursor = sessionCatalogPaging.isExactCursor;
 function textFromContent$1(content) {
 	if (typeof content === "string") return content;
 	if (!Array.isArray(content)) return "";
@@ -473,44 +394,20 @@ function textFromContent$1(content) {
 		return [];
 	}).join("\n");
 }
-function parseListParams(value) {
-	if (value === void 0 || value === null) return { limit: DEFAULT_PAGE_LIMIT };
-	if (!isRecord(value)) throw new Error("Pi session list parameters must be an object");
-	const unknown = Object.keys(value).find((key) => ![
-		"searchTerm",
-		"limit",
-		"cursor"
-	].includes(key));
-	if (unknown) throw new Error(`unknown Pi session list parameter: ${unknown}`);
-	const searchTerm = normalizeBoundedOptionalString(value.searchTerm, MAX_SEARCH_LENGTH);
-	if (value.searchTerm !== void 0 && !searchTerm) throw new Error("searchTerm is invalid");
-	const cursor = optionalRawCursor(value.cursor);
-	return {
-		limit: boundedLimit(value.limit),
-		...searchTerm ? { searchTerm } : {},
-		...cursor ? { cursor } : {}
-	};
-}
-function parseReadParams(value) {
-	if (!isRecord(value)) throw new Error("Pi session read parameters must be an object");
-	const unknown = Object.keys(value).find((key) => ![
-		"threadId",
-		"limit",
-		"cursor"
-	].includes(key));
-	if (unknown) throw new Error(`unknown Pi session read parameter: ${unknown}`);
-	const threadId = normalizeBoundedOptionalString(value.threadId, 256);
-	if (!threadId || !SESSION_ID_PATTERN$1.test(threadId)) throw new Error("threadId is invalid");
-	const cursor = optionalRawCursor(value.cursor);
-	return {
-		threadId,
-		limit: boundedLimit(value.limit),
-		...cursor ? { cursor } : {}
-	};
-}
+const PI_PARAMETER_MESSAGES = {
+	listNotObject: "Pi session list parameters must be an object",
+	unknownListParameter: (key) => `unknown Pi session list parameter: ${key}`,
+	invalidSearchTerm: "searchTerm is invalid",
+	readNotObject: "Pi session read parameters must be an object",
+	unknownReadParameter: (key) => `unknown Pi session read parameter: ${key}`,
+	invalidThreadId: "threadId is invalid"
+};
 async function listLocalPiSessionPage(value) {
-	const params = parseListParams(value);
-	const offset = decodeCursor(params.cursor);
+	const params = sessionCatalogPaging.parseListParams(value, {
+		searchMaxLength: MAX_SEARCH_LENGTH,
+		messages: PI_PARAMETER_MESSAGES
+	});
+	const offset = sessionCatalogPaging.decodeCursor(params.cursor);
 	const { summaries, hasMore } = await listPiSummaryPage(process.env, {
 		offset,
 		limit: params.limit,
@@ -519,7 +416,7 @@ async function listLocalPiSessionPage(value) {
 	const page = summaries.map(({ file: _file, version: _version, ...session }) => session);
 	return {
 		sessions: page,
-		...hasMore ? { nextCursor: encodeCursor(offset + page.length) } : {}
+		...hasMore ? { nextCursor: sessionCatalogPaging.encodeCursor(offset + page.length) } : {}
 	};
 }
 function isoTimestamp(message, entry) {
@@ -670,11 +567,16 @@ function piTranscriptItems(entries) {
 	});
 }
 async function readLocalPiTranscriptPage(value) {
-	const params = parseReadParams(value);
-	const offset = decodeCursor(params.cursor);
-	const page = transcriptPage(piTranscriptItems(await readPiSessionById(params.threadId, process.env)), params.limit, offset);
+	const params = sessionCatalogPaging.parseReadParams(value, {
+		threadIdMaxLength: 256,
+		threadIdPattern: PI_SESSION_ID_PATTERN,
+		messages: PI_PARAMETER_MESSAGES
+	});
+	const offset = sessionCatalogPaging.decodeCursor(params.cursor);
+	const items = piTranscriptItems(await readPiSessionById(params.threadId, process.env));
+	const page = sessionCatalogPaging.boundTranscriptPage(items, params.limit, offset);
 	return {
-		hostId: LOCAL_HOST_ID$1,
+		hostId: PI_LOCAL_SESSION_HOST_ID,
 		label: "Local Pi",
 		threadId: params.threadId,
 		...page
@@ -798,201 +700,17 @@ async function checkPiUpstreamActivity(probes) {
 }
 //#endregion
 //#region extensions/acpx/src/pi-session-catalog-runtime.ts
-const LOCAL_HOST_ID = "gateway";
-const MAX_PAGE_LIMIT = 100;
-const MAX_HOSTS = 100;
 const NODE_TIMEOUT_MS = 2e4;
-const SESSION_ID_PATTERN = /^(?!-)[A-Za-z0-9._:-]{1,256}$/u;
-const TRANSCRIPT_ITEM_TYPES = /* @__PURE__ */ new Set([
-	"userMessage",
-	"agentMessage",
-	"reasoning",
-	"toolCall",
-	"toolResult",
-	"other"
-]);
 const ACPX_BACKEND_ID = "acpx";
 const PI_ACP_AGENT_ID = "pi";
 const PI_ADOPTED_SESSION_KEY_PREFIX = "plugin:acpx:catalog-adopt:pi:";
-var PiCatalogParamsError = class extends Error {};
-const continueAdoption = createSessionCatalogAdoptionCoordinator();
-function validatePiThreadId(value) {
-	if (typeof value !== "string" || !SESSION_ID_PATTERN.test(value)) throw new Error("INVALID_REQUEST: threadId is invalid");
-	return value;
-}
-function isOptionalString(value) {
-	return value === void 0 || typeof value === "string";
-}
-function isOptionalNumber(value) {
-	return value === void 0 || typeof value === "number";
-}
-function isNodeSession(value) {
-	return isRecord(value) && typeof value.threadId === "string" && SESSION_ID_PATTERN.test(value.threadId) && typeof value.status === "string" && value.status.length > 0 && typeof value.archived === "boolean" && typeof value.canContinue === "boolean" && typeof value.canArchive === "boolean" && isOptionalString(value.name) && isOptionalString(value.cwd) && isOptionalString(value.source) && isOptionalString(value.modelProvider) && isOptionalString(value.cliVersion) && isOptionalString(value.gitBranch) && isOptionalString(value.sessionKey) && isOptionalNumber(value.createdAt) && isOptionalNumber(value.updatedAt) && isOptionalNumber(value.recencyAt);
-}
-function isNodeTranscriptItem(value) {
-	return isRecord(value) && typeof value.type === "string" && TRANSCRIPT_ITEM_TYPES.has(value.type) && isOptionalString(value.id) && isOptionalString(value.text) && isOptionalString(value.timestamp) && isOptionalString(value.model) && (value.truncated === void 0 || typeof value.truncated === "boolean");
-}
-function parseNodeParams(paramsJSON) {
-	if (!paramsJSON) return;
-	try {
-		return JSON.parse(paramsJSON);
-	} catch (error) {
-		throw new Error("Pi session parameters must be valid JSON", { cause: error });
-	}
-}
-function nodeLabel(node) {
-	return node.displayName?.trim() || node.remoteIp?.trim() || node.nodeId;
-}
-function unwrapNodePayload(value) {
-	return isRecord(value) && typeof value.payloadJSON === "string" ? JSON.parse(value.payloadJSON) : value;
-}
-function setCatalogCapabilities(page, capabilities) {
-	for (const session of page.sessions) {
-		session.canContinue = capabilities.canContinue && session.canContinue;
-		session.canOpenTerminal = capabilities.canOpenTerminal;
-	}
-	return page;
-}
-function projectPiAdoptedSessions(page, adopted) {
-	return {
-		...page,
-		sessions: page.sessions.map((session) => {
-			const sessionKey = adopted.get(sessionCatalogAdoptedSourceKey(LOCAL_HOST_ID, session.threadId));
-			return sessionKey ? {
-				...session,
-				sessionKey
-			} : session;
-		})
-	};
-}
-async function listPiNodeHost(runtime, query, node) {
-	const hostId = `node:${node.nodeId}`;
-	const common = {
-		hostId,
-		label: nodeLabel(node),
-		kind: "node",
-		connected: node.connected === true,
-		nodeId: node.nodeId
-	};
-	if (node.connected !== true) return {
-		...common,
-		sessions: [],
-		error: {
-			code: "NODE_OFFLINE",
-			message: "Paired node is offline"
-		}
-	};
-	try {
-		const cursor = query.cursors?.[hostId];
-		if (cursor !== void 0 && !isExactPiSessionCursor(cursor)) throw new Error("cursor is invalid");
-		const page = parseNodeSessionPage(unwrapNodePayload(await runtime.nodes.invoke({
-			nodeId: node.nodeId,
-			command: PI_SESSIONS_LIST_COMMAND,
-			params: {
-				...query.limitPerHost ? { limit: query.limitPerHost } : {},
-				...query.search ? { searchTerm: query.search } : {},
-				...cursor !== void 0 ? { cursor } : {}
-			},
-			timeoutMs: NODE_TIMEOUT_MS,
-			scopes: ["operator.write"]
-		})));
-		const canOpenTerminal = (node.invocableCommands ?? node.commands)?.includes(PI_TERMINAL_RESUME_COMMAND) === true;
-		return {
-			...common,
-			...setCatalogCapabilities(page, {
-				canContinue: false,
-				canOpenTerminal
-			})
-		};
-	} catch {
-		return {
-			...common,
-			sessions: [],
-			error: {
-				code: "NODE_INVOKE_FAILED",
-				message: "Paired node Pi sessions are unavailable"
-			}
-		};
-	}
-}
-function parseNodeSessionPage(value) {
-	if (!isRecord(value) || !Array.isArray(value.sessions) || value.sessions.length > MAX_PAGE_LIMIT) throw new Error("Pi node returned an invalid session page");
-	if (!value.sessions.every(isNodeSession)) throw new Error("Pi node returned an invalid session page");
-	const sessions = value.sessions;
-	const nextCursor = value.nextCursor;
-	if (nextCursor !== void 0 && !isExactPiSessionCursor(nextCursor)) throw new Error("Pi node returned an invalid cursor");
-	return {
-		sessions,
-		...nextCursor !== void 0 ? { nextCursor } : {}
-	};
-}
-function parseNodeTranscriptPage(value, threadId) {
-	if (!isRecord(value) || value.threadId !== threadId || !Array.isArray(value.items) || value.items.length > MAX_PAGE_LIMIT || !value.items.every(isNodeTranscriptItem)) throw new Error("Pi node returned an invalid transcript page");
-	const nextCursor = value.nextCursor;
-	if (nextCursor !== void 0 && !isExactPiSessionCursor(nextCursor)) throw new Error("Pi node returned an invalid cursor");
-	return {
-		hostId: LOCAL_HOST_ID,
-		threadId,
-		items: value.items,
-		...nextCursor !== void 0 ? { nextCursor } : {}
-	};
-}
-async function listPiHosts(api, query) {
-	const runtime = api.runtime;
-	const canContinue = resolvePiContinuationAvailability(api).available;
-	const adopted = query.sessionEntries ? listAdoptedPiSessions(api, query.sessionEntries) : /* @__PURE__ */ new Map();
-	const requested = query.hostIds ? new Set(query.hostIds) : void 0;
-	const hosts = [];
-	const localStore = !requested || requested.has(LOCAL_HOST_ID) ? piSessionStore(process.env) : void 0;
-	if (localStore && (query.allowProcessHomeFallback !== false || !localStore.usesProcessHomeFallback) && piSessionStoreAvailable(process.env, localStore)) try {
-		hosts.push({
-			hostId: LOCAL_HOST_ID,
-			label: "Local Pi",
-			kind: "gateway",
-			connected: true,
-			...await listLocalPiSessionPage({
-				limit: query.limitPerHost,
-				...query.search ? { searchTerm: query.search } : {},
-				cursor: query.cursors?.[LOCAL_HOST_ID]
-			}).then((page) => projectPiAdoptedSessions(setCatalogCapabilities(page, {
-				canContinue,
-				canOpenTerminal: resolveNodeHostExecutable("pi", {
-					env: process.env,
-					pathEnv: process.env.PATH ?? "",
-					strategy: "fallback"
-				}) !== void 0
-			}), adopted))
-		});
-	} catch {
-		hosts.push({
-			hostId: LOCAL_HOST_ID,
-			label: "Local Pi",
-			kind: "gateway",
-			connected: true,
-			sessions: [],
-			error: {
-				code: "LOCAL_READ_FAILED",
-				message: "Local Pi sessions are unavailable"
-			}
-		});
-	}
-	let nodes;
-	try {
-		nodes = (await (query.listNodes?.() ?? runtime.nodes.list())).nodes;
-	} catch {
-		return hosts;
-	}
-	const eligible = nodes.filter((node) => node.commands?.includes("acpx.pi.sessions.list.v1") && (!requested || requested.has(`node:${node.nodeId}`))).toSorted((left, right) => nodeLabel(left).localeCompare(nodeLabel(right))).slice(0, MAX_HOSTS - hosts.length);
-	const nodeHosts = await Promise.all(eligible.map((node) => listPiNodeHost(runtime, query, node)));
-	return [...hosts, ...nodeHosts];
-}
 async function requireLocalPiSession(threadId) {
-	const record = (await listLocalPiSessionPage({
+	const session = (await listLocalPiSessionPage({
 		searchTerm: threadId,
-		limit: MAX_PAGE_LIMIT
-	})).sessions.find((session) => session.threadId === threadId);
-	if (!record) throw new Error("Pi session is unavailable");
-	return record;
+		limit: 100
+	})).sessions.find((candidate) => candidate.threadId === threadId);
+	if (!session) throw new Error("Pi session is unavailable");
+	return session;
 }
 function currentPiCatalogConfig(api) {
 	return api.runtime.config?.current?.() ?? api.config ?? {};
@@ -1013,8 +731,9 @@ function resolvePiContinuationAvailability(api) {
 		message: "Pi CLI is unavailable"
 	};
 }
-function listAdoptedPiSessions(api, sessionEntries) {
+function listAdoptedPiSessions(api, agentId, sessionEntries) {
 	return listAdoptedSessionCatalogSessions({
+		...agentId ? { agentId } : {},
 		config: currentPiCatalogConfig(api),
 		pluginId: api.id,
 		runtime: api.runtime,
@@ -1023,198 +742,148 @@ function listAdoptedPiSessions(api, sessionEntries) {
 			const acpx = isRecord(entry.pluginExtensions?.acpx) ? entry.pluginExtensions.acpx : void 0;
 			const marker = acpx && isRecord(acpx.piSessionCatalog) ? acpx.piSessionCatalog : void 0;
 			return marker && typeof marker.sourceThreadId === "string" ? {
-				hostId: LOCAL_HOST_ID,
+				hostId: PI_LOCAL_SESSION_HOST_ID,
 				threadId: marker.sourceThreadId
 			} : void 0;
 		}
 	});
 }
-async function continuePiSession(api, hostId, threadId) {
-	if (hostId.startsWith("node:")) throw new PiCatalogParamsError("paired-node Pi session rows are view-only");
-	if (hostId !== LOCAL_HOST_ID) throw new PiCatalogParamsError("Pi session catalog hostId is invalid");
-	const availability = resolvePiContinuationAvailability(api);
-	if (!availability.available) throw new PiCatalogParamsError(availability.message);
-	const sourceKey = sessionCatalogAdoptedSourceKey(hostId, threadId);
-	return await continueAdoption({
-		sourceKey,
-		findExisting: () => listAdoptedPiSessions(api).get(sourceKey),
-		create: async () => {
-			const record = await requireLocalPiSession(threadId).catch(() => void 0);
-			if (!record) throw new PiCatalogParamsError("Pi session is unavailable");
-			if (!record.canContinue) throw new PiCatalogParamsError("Pi session is outside the session store supported by pi-acp");
-			const currentAvailability = resolvePiContinuationAvailability(api);
-			if (!currentAvailability.available) throw new PiCatalogParamsError(currentAvailability.message);
-			const config = currentPiCatalogConfig(api);
-			const marker = { sourceThreadId: threadId };
-			return { sessionKey: (await api.runtime.agent.session.createSessionEntry({
-				cfg: config,
-				key: sessionCatalogAdoptedSessionKey(PI_ADOPTED_SESSION_KEY_PREFIX, threadId),
-				agentId: resolveDefaultAgentId(config),
-				recoverMatchingInitialEntry: true,
-				...record.name ? { label: record.name } : {},
-				...record.cwd ? { spawnedCwd: record.cwd } : {},
-				initialEntry: {
-					acpBackendId: ACPX_BACKEND_ID,
-					acpSessionBinding: {
-						acpAgentId: PI_ACP_AGENT_ID,
-						agentSessionId: threadId
-					},
-					pluginExtensions: { acpx: { piSessionCatalog: marker } }
-				},
-				afterCreate: async (entry) => {
-					await importSessionCatalogHistory({
-						catalogId: "pi",
-						threadId,
-						read: async ({ cursor, limit }) => await readPiTranscript(api.runtime, {
-							hostId,
-							threadId,
-							limit,
-							...cursor ? { cursor } : {}
-						}),
-						sessionId: entry.sessionId,
-						sessionKey: entry.key,
-						agentId: entry.agentId,
-						...record.cwd ? { cwd: record.cwd } : {},
-						config
-					});
-					return { pluginExtensions: { acpx: { piSessionCatalog: marker } } };
-				}
-			})).key };
-		},
-		complete: async (continued) => await linkContinuedPiSession(continued.sessionKey, threadId)
-	});
-}
-async function resolveNodePiSession(params) {
-	const record = parseNodeSessionPage(unwrapNodePayload(await params.runtime.nodes.invoke({
-		nodeId: params.nodeId,
-		command: PI_SESSIONS_LIST_COMMAND,
-		params: {
-			searchTerm: params.threadId,
-			limit: MAX_PAGE_LIMIT
-		},
-		timeoutMs: NODE_TIMEOUT_MS,
-		scopes: ["operator.write"]
-	}))).sessions.find((session) => session.threadId === params.threadId);
-	if (!record) throw new Error("Pi session is unavailable");
-	return record;
-}
-async function openPiTerminal(params) {
-	const title = `pi --session ${params.threadId.slice(0, 12)}…`;
-	if (params.hostId === LOCAL_HOST_ID) {
-		const record = await requireLocalPiSession(params.threadId);
-		const resolution = resolveNodeHostExecutable("pi", {
-			env: process.env,
-			pathEnv: process.env.PATH ?? "",
-			strategy: "fallback"
-		});
-		if (!resolution) throw new Error("Pi CLI is unavailable");
-		return {
-			kind: "local",
-			argv: [
-				resolution.executable,
-				"--session",
-				params.threadId
-			],
-			...record.cwd ? { cwd: record.cwd } : {},
-			...resolution.pathEnv ? { pathEnv: resolution.pathEnv } : {},
-			title
-		};
-	}
-	if (!params.hostId.startsWith("node:")) throw new Error("hostId is invalid");
-	const nodeId = params.hostId.slice(5);
-	if (!(await params.runtime.nodes.list()).nodes.find((candidate) => {
-		const commands = candidate.invocableCommands ?? candidate.commands;
-		return candidate.nodeId === nodeId && candidate.connected === true && commands?.includes("acpx.pi.sessions.list.v1") === true && commands.includes("acpx.pi.terminal.resume.v1");
-	})) throw new Error("paired-node Pi terminal is unavailable");
-	const record = await resolveNodePiSession({
-		runtime: params.runtime,
-		nodeId,
-		threadId: params.threadId
-	});
-	return {
-		kind: "node",
-		nodeId,
-		command: PI_TERMINAL_RESUME_COMMAND,
-		paramsJSON: JSON.stringify({ threadId: params.threadId }),
-		...record.cwd ? { cwd: record.cwd } : {},
-		title
-	};
-}
-async function readPiTranscript(runtime, request) {
-	const cursor = request.cursor;
-	if (cursor !== void 0 && !isExactPiSessionCursor(cursor)) throw new Error("cursor is invalid");
-	if (request.hostId === LOCAL_HOST_ID) {
-		assertPiLocalAccess(request.hostId, request.allowProcessHomeFallback);
-		return await readLocalPiTranscriptPage({
-			threadId: request.threadId,
-			...request.limit ? { limit: request.limit } : {},
-			...cursor !== void 0 ? { cursor } : {}
-		});
-	}
-	if (!request.hostId.startsWith("node:")) throw new Error("hostId is invalid");
-	const nodeId = request.hostId.slice(5);
-	const node = (await runtime.nodes.list()).nodes.find((candidate) => candidate.nodeId === nodeId && candidate.connected === true && candidate.commands?.includes("acpx.pi.sessions.read.v1"));
-	if (!node) throw new Error("paired-node Pi session host is unavailable");
-	return {
-		...parseNodeTranscriptPage(unwrapNodePayload(await runtime.nodes.invoke({
-			nodeId,
-			command: PI_SESSION_READ_COMMAND,
-			params: {
-				threadId: request.threadId,
-				...request.limit ? { limit: request.limit } : {},
-				...cursor !== void 0 ? { cursor } : {}
+async function createAdoptedPiSession(params) {
+	const config = currentPiCatalogConfig(params.api);
+	const marker = { sourceThreadId: params.threadId };
+	return { sessionKey: (await params.api.runtime.agent.session.createSessionEntry({
+		cfg: config,
+		key: sessionCatalogAdoptedSessionKey(PI_ADOPTED_SESSION_KEY_PREFIX, params.threadId),
+		agentId: params.agentId,
+		recoverMatchingInitialEntry: true,
+		...params.session.name ? { displayName: params.session.name } : {},
+		...params.session.cwd ? { spawnedCwd: params.session.cwd } : {},
+		initialEntry: {
+			acpBackendId: ACPX_BACKEND_ID,
+			acpSessionBinding: {
+				acpAgentId: PI_ACP_AGENT_ID,
+				agentSessionId: params.threadId
 			},
-			timeoutMs: NODE_TIMEOUT_MS,
-			scopes: ["operator.write"]
-		})), request.threadId),
-		hostId: request.hostId,
-		label: nodeLabel(node)
-	};
+			pluginExtensions: { acpx: { piSessionCatalog: marker } }
+		},
+		afterCreate: async (entry) => {
+			await importSessionCatalogHistory({
+				catalogId: "pi",
+				threadId: params.threadId,
+				read: async ({ cursor, limit }) => await readLocalPiTranscriptPage({
+					threadId: params.threadId,
+					limit,
+					...cursor ? { cursor } : {}
+				}),
+				sessionId: entry.sessionId,
+				sessionKey: entry.key,
+				agentId: entry.agentId,
+				...params.session.cwd ? { cwd: params.session.cwd } : {},
+				config
+			});
+			return { pluginExtensions: { acpx: { piSessionCatalog: marker } } };
+		}
+	})).key };
 }
 function assertPiLocalAccess(hostId, allowProcessHomeFallback) {
-	if (hostId === LOCAL_HOST_ID && allowProcessHomeFallback === false && piSessionStore(process.env).usesProcessHomeFallback) throw new PiCatalogParamsError("local Pi sessions are unavailable in isolated state");
+	if (hostId === "gateway" && allowProcessHomeFallback === false && piSessionStore(process.env).usesProcessHomeFallback) throw new Error("local Pi sessions are unavailable in isolated state");
 }
-async function listPiSessions(paramsJSON) {
-	return JSON.stringify(await listLocalPiSessionPage(parseNodeParams(paramsJSON)));
+async function listPiSessions(params) {
+	return await listLocalPiSessionPage(params);
 }
-async function readPiSession(paramsJSON) {
-	return JSON.stringify(await readLocalPiTranscriptPage(parseNodeParams(paramsJSON)));
-}
-async function resumePiSession(paramsJSON, io) {
-	if (!io) throw new Error("Pi terminal command requires duplex transport");
-	const params = decodeNodePtyResumeParams(paramsJSON, validatePiThreadId);
-	const record = await requireLocalPiSession(params.threadId);
-	const resolution = resolveNodeHostExecutable("pi", {
-		env: process.env,
-		pathEnv: process.env.PATH ?? process.env.Path ?? "",
-		strategy: "direct"
-	});
-	if (!resolution) throw new Error("Pi CLI is unavailable");
-	return JSON.stringify(await runNodePtyCommand({
-		file: resolution.executable,
-		args: ["--session", params.threadId],
-		cwd: record.cwd,
-		cols: params.cols,
-		rows: params.rows
-	}, io));
+async function readPiSession(params) {
+	return await readLocalPiTranscriptPage(params);
 }
 function createPiSessionCatalogRuntime(api) {
-	return {
-		list: async (query) => await listPiHosts(api, query),
-		read: async (request) => await readPiTranscript(api.runtime, request),
-		continueSession: async (request) => {
-			assertPiLocalAccess(request.hostId, request.allowProcessHomeFallback);
-			return await continuePiSession(api, request.hostId, request.threadId);
+	return createSessionCatalogFamily({
+		runtime: api.runtime,
+		local: {
+			hostId: PI_LOCAL_SESSION_HOST_ID,
+			label: "Local Pi",
+			available: (query) => {
+				const store = piSessionStore(process.env);
+				return (query.allowProcessHomeFallback !== false || !store.usesProcessHomeFallback) && piSessionStoreAvailable(process.env, store);
+			},
+			list: async (query) => await listLocalPiSessionPage({
+				limit: query.limitPerHost,
+				...query.search ? { searchTerm: query.search } : {},
+				cursor: query.cursors?.[PI_LOCAL_SESSION_HOST_ID]
+			}),
+			read: async (request) => await readLocalPiTranscriptPage({
+				threadId: request.threadId,
+				...request.limit ? { limit: request.limit } : {},
+				...request.cursor !== void 0 ? { cursor: request.cursor } : {}
+			}),
+			assertAccess: assertPiLocalAccess
 		},
-		checkUpstreamActivity: (probes, policy) => checkPiUpstreamActivity(probes.filter((probe) => probe.hostId !== LOCAL_HOST_ID || policy?.allowProcessHomeFallback !== false || !piSessionStore(process.env).usesProcessHomeFallback)),
-		openTerminal: async (request) => {
-			assertPiLocalAccess(request.hostId, request.allowProcessHomeFallback);
-			return await openPiTerminal({
-				runtime: api.runtime,
-				...request
-			});
-		}
-	};
+		node: {
+			listCommand: PI_SESSIONS_LIST_COMMAND,
+			readCommand: PI_SESSION_READ_COMMAND,
+			terminalCommand: PI_TERMINAL_RESUME_COMMAND,
+			timeoutMs: NODE_TIMEOUT_MS,
+			maxHosts: 100,
+			maxPageLimit: 100,
+			sessionIdPattern: PI_SESSION_ID_PATTERN
+		},
+		capabilities: {
+			local: () => ({
+				canContinue: resolvePiContinuationAvailability(api).available,
+				canOpenTerminal: resolveNodeHostExecutable("pi", {
+					env: process.env,
+					pathEnv: process.env.PATH ?? "",
+					strategy: "fallback"
+				}) !== void 0
+			}),
+			node: (node) => {
+				return {
+					canContinue: false,
+					canOpenTerminal: (node.invocableCommands ?? node.commands)?.includes(PI_TERMINAL_RESUME_COMMAND) === true
+				};
+			},
+			project: (session, capabilities) => ({
+				...session,
+				canContinue: capabilities.canContinue && session.canContinue,
+				canOpenTerminal: capabilities.canOpenTerminal
+			})
+		},
+		messages: {
+			invalidNodeCursor: "Pi node returned an invalid cursor",
+			invalidNodeSessionPage: "Pi node returned an invalid session page",
+			invalidNodeTranscriptPage: "Pi node returned an invalid transcript page",
+			invalidHostId: "Pi session catalog hostId is invalid",
+			localReadFailed: "Local Pi sessions are unavailable",
+			nodeInvokeFailed: "Paired node Pi sessions are unavailable",
+			nodeReadUnavailable: "paired-node Pi session host is unavailable",
+			nodeTerminalUnavailable: "paired-node Pi terminal is unavailable",
+			sessionUnavailable: "Pi session is unavailable"
+		},
+		continuation: {
+			resolveAgentId: (agentId) => resolveSessionAgentIdsStrict({
+				config: api.config,
+				agentId
+			}).sessionAgentId,
+			availability: () => resolvePiContinuationAvailability(api),
+			listAdopted: (agentId, sessionEntries) => listAdoptedPiSessions(api, agentId, sessionEntries),
+			loadSession: requireLocalPiSession,
+			validateSession: (session) => {
+				if (!session.canContinue) throw new Error("Pi session is outside the session store supported by pi-acp");
+			},
+			create: async (params) => await createAdoptedPiSession({
+				api,
+				...params
+			}),
+			complete: async (continued, threadId) => await linkContinuedPiSession(continued.sessionKey, threadId),
+			nodeReadOnlyMessage: "paired-node Pi session rows are view-only"
+		},
+		terminal: {
+			executable: "pi",
+			args: (threadId) => ["--session", threadId],
+			title: (threadId) => `pi --session ${threadId.slice(0, 12)}…`,
+			requireLocalSession: requireLocalPiSession,
+			unavailableMessage: "Pi CLI is unavailable"
+		},
+		checkUpstreamActivity: (probes, policy) => checkPiUpstreamActivity(probes.filter((probe) => probe.hostId !== "gateway" || policy?.allowProcessHomeFallback !== false || !piSessionStore(process.env).usesProcessHomeFallback))
+	}, isExactPiSessionCursor);
 }
 //#endregion
-export { createPiSessionCatalogRuntime, listPiSessions, readPiSession, resumePiSession };
+export { createPiSessionCatalogRuntime, listPiSessions, readPiSession, requireLocalPiSession };