@agimon-ai/po-core 0.0.0-alpha.2 → 0.0.0-alpha.21

package/dist/headlessServer.mjs

@@ -1,9 +1,10 @@
 import "./src/constants/contextApi.mjs";
-import { isDoomSessionSetupError } from "./src/schemas/headless.mjs";
+import { isPoSessionSetupError } from "./src/schemas/headless.mjs";
+import { normalizeSessionGroups } from "./src/schemas/sessionProtocol.mjs";
 import { harnessErrorMessage } from "./src/server/harnessErrorMessage.mjs";
 import { readContextDetail } from "./contextDetailStore.mjs";
 import { observe } from "./serverTelemetry.mjs";
-import { DOOM_API_CALLER_HEADERS, DOOM_API_CALLER_LOCALITY_HEADER, DOOM_API_CALLER_STEP_UP_HEADER, parseDoomSocketPath } from "./src/schemas/packageApi.mjs";
+import { PO_API_CALLER_HEADERS, PO_API_CALLER_LOCALITY_HEADER, PO_API_CALLER_STEP_UP_HEADER, parsePoSocketPath } from "./src/schemas/packageApi.mjs";
 import "./packageApi.mjs";
 import { SESSION_FILE_CONTENT_TYPES } from "./src/constants/sessionFiles.mjs";
 import { writeSessionAttachment } from "./src/services/sessionAttachments/index.mjs";
@@ -11,13 +12,14 @@ import { createSessionMcpActivityStore } from "./src/services/sessionMcpActivity
 import { createSessionMcpConversationStore } from "./src/services/sessionMcpConversations/index.mjs";
 import { createSessionMcpRegistrationStore } from "./src/services/sessionMcpRegistrationStore/index.mjs";
 import { createContextApi } from "./runtimeContextApi.mjs";
-import { createHeadlessProtocol } from "./src/server/headlessProtocol.mjs";
+import { createHeadlessProtocol } from "./headlessProtocol.mjs";
 import { createSessionMcpRoutes, isPublicSessionMcpRoute, isSessionMcpHostRoute } from "./src/server/sessionMcpRoutes.mjs";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { createServer } from "node:http";
 import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { webSocketLink } from "@earendil-works/chord";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { WebSocketServer } from "ws";
@@ -35,7 +37,7 @@ import { WebSocketServer } from "ws";
 * service worker answers an unrecognised path out of the signed bundle cache,
 * so the symptom appears nowhere near the cause.
 */
-const DOOM_PACKAGE_API_PATH_PATTERN = /^\/api(?:\/workspaces\/([^/]+)(?:\/sessions\/([^/]+))?)?\/(?:plugins\/([^/]+)|settings)(?:\/(.*))?$/u;
+const PO_PACKAGE_API_PATH_PATTERN = /^\/api(?:\/workspaces\/([^/]+)(?:\/sessions\/([^/]+))?)?\/(?:plugins\/([^/]+)|settings)(?:\/(.*))?$/u;
 const HEALTH_ROLE = "hub";
 const PROTOCOL_VERSION = 1;
 const MAX_BODY_BYTES = 8388608;
@@ -63,10 +65,12 @@ function sessionView(session) {
 		everPrompted: session.everPrompted ?? false,
 		awaitingInput: session.awaitingInput ?? false,
 		...session.lastSettledAt === void 0 ? {} : { lastSettledAt: session.lastSettledAt },
+		...session.backgroundWorkActive === void 0 ? {} : { backgroundWorkActive: session.backgroundWorkActive },
 		...session.git === void 0 ? {} : { git: { ...session.git } },
 		...session.profile === void 0 ? {} : { profile: { ...session.profile } },
 		...session.parentSessionId === void 0 ? {} : { parentSessionId: session.parentSessionId },
 		...session.sessionProvenance === void 0 ? {} : { sessionProvenance: session.sessionProvenance },
+		...session.groups === void 0 || session.groups.length === 0 ? {} : { groups: [...session.groups] },
 		...session.pendingSetups === void 0 ? {} : { pendingSetups: session.pendingSetups },
 		...session.activity === void 0 ? {} : { activity: { ...session.activity } }
 	};
@@ -88,7 +92,8 @@ function dormantView(record) {
 		awaitingInput: false,
 		dormant: true,
 		...record.parentSessionId === void 0 ? {} : { parentSessionId: record.parentSessionId },
-		...record.sessionProvenance === void 0 ? {} : { sessionProvenance: record.sessionProvenance }
+		...record.sessionProvenance === void 0 ? {} : { sessionProvenance: record.sessionProvenance },
+		...record.groups === void 0 || record.groups.length === 0 ? {} : { groups: [...record.groups] }
 	};
 }
 function json(response, status, value) {
@@ -278,6 +283,39 @@ async function directoryChildren(requested) {
 		directories
 	};
 }
+const PO_FOLDER_SCAN_DEPTH = 3;
+const PO_FOLDER_SCAN_VISIT_LIMIT = 2e3;
+const PO_FOLDER_LIMIT = 20;
+const PO_FOLDER_SKIP = /* @__PURE__ */ new Set(["node_modules", "Library"]);
+/**
+* Folders under home that already hold a `.po` folder, for first-run onboarding.
+* Home itself is skipped: its `.po` is Po's own home, not a workspace.
+*/
+async function poFolders() {
+	const found = [];
+	let level = [os.homedir()];
+	let visited = 0;
+	for (let depth = 1; depth <= PO_FOLDER_SCAN_DEPTH && level.length > 0; depth++) {
+		const next = [];
+		for (const parent of level) {
+			if (visited++ >= PO_FOLDER_SCAN_VISIT_LIMIT || found.length >= PO_FOLDER_LIMIT) return found;
+			let entries;
+			try {
+				entries = await fs.promises.readdir(parent, { withFileTypes: true });
+			} catch {
+				continue;
+			}
+			for (const entry of entries) {
+				if (!entry.isDirectory() || entry.name.startsWith(".") || PO_FOLDER_SKIP.has(entry.name)) continue;
+				const child = path.join(parent, entry.name);
+				if (fs.existsSync(path.join(child, ".po"))) found.push(child);
+				else next.push(child);
+			}
+		}
+		level = next;
+	}
+	return found.slice(0, PO_FOLDER_LIMIT);
+}
 var RequestBodyTooLargeError = class extends Error {
 	constructor() {
 		super("Request body is too large.");
@@ -319,41 +357,6 @@ async function writeResponse(response, result) {
 	}
 	await pipeline(Readable.fromWeb(result.body), response);
 }
-function eventFrame(event) {
-	switch (event.kind) {
-		case "upsert": return {
-			type: "session_upsert",
-			session: sessionView(event.session)
-		};
-		case "removed": return {
-			type: "session_removed",
-			sessionId: event.sessionId
-		};
-		case "workspace_upsert": return {
-			type: "workspace_upsert",
-			workspace: event.workspace
-		};
-		case "workspace_removed": return {
-			type: "workspace_removed",
-			workspaceId: event.workspaceId
-		};
-		case "channel": return {
-			type: "channel_frame",
-			frameType: event.frameType,
-			sessionId: event.sessionId,
-			payload: event.payload,
-			...event.connectionId === void 0 ? {} : { connectionId: event.connectionId }
-		};
-		case "frame": return {
-			type: "session_frame",
-			sessionId: event.sessionId,
-			frame: event.frame
-		};
-	}
-}
-function writeSse(response, event, value) {
-	response.write(`event: ${event}\ndata: ${JSON.stringify(value)}\n\n`);
-}
 /**
 * Client-neutral HTTP and WebSocket boundary for the process-local headless hub.
 * It deliberately delegates every session operation to HeadlessHub, so transport
@@ -361,8 +364,6 @@ function writeSse(response, event, value) {
 */
 async function serveHeadlessServer(options) {
 	const clients = /* @__PURE__ */ new Set();
-	const scopedProtocols = /* @__PURE__ */ new Set();
-	const sse = /* @__PURE__ */ new Map();
 	const desktopAuthorized = (request) => {
 		const proof = request.headers["x-po-desktop"];
 		return typeof proof === "string" && options.headlessHub.computerUse?.authorize?.(new Headers({ "x-po-desktop": proof })) === true;
@@ -399,7 +400,7 @@ async function serveHeadlessServer(options) {
 	* id, so reviving one needs no bookkeeping beyond the hub itself.
 	*/
 	const dormant = () => (options.dormantSessions?.() ?? []).filter((record) => options.headlessHub.session(record.sessionId) === void 0);
-	const protocol = await createHeadlessProtocol({
+	const protocol = createHeadlessProtocol({
 		hub: options.headlessHub,
 		telemetry: options.telemetry,
 		onNotice: options.onNotice,
@@ -421,6 +422,22 @@ async function serveHeadlessServer(options) {
 	});
 	/** Sessions being restarted, keyed by id, settled once the reopen succeeds or fails. */
 	const restarting = /* @__PURE__ */ new Map();
+	/**
+	* Stores already-normalized groups where a session keeps them: the journal of a live
+	* session, which announces the change itself, or the record of a dormant one.
+	*/
+	const writeGroups = async (sessionId, groups) => {
+		const runtime = options.headlessHub.runtime(sessionId);
+		if (runtime !== void 0) {
+			await runtime.setGroups(groups);
+			return true;
+		}
+		const record = dormant().find((candidate) => candidate.sessionId === sessionId);
+		if (record === void 0 || options.setDormantGroups === void 0) return false;
+		await options.setDormantGroups(record, groups);
+		options.headlessHub.notifyDormantChanged(sessionId);
+		return true;
+	};
 	const server = createServer((request, response) => {
 		handleRequest(request, response).catch((error) => {
 			if (response.headersSent) {
@@ -428,20 +445,10 @@ async function serveHeadlessServer(options) {
 				return;
 			}
 			options.onNotice?.(`Headless request failed: ${harnessErrorMessage(error)}`);
-			if (isDoomSessionSetupError(error)) json(response, 422, { error: error.message });
+			if (isPoSessionSetupError(error)) json(response, 422, { error: error.message });
 			else json(response, 500, { error: "Internal server error." });
 		});
 	});
-	const unsubscribe = options.headlessHub.onEvent((event) => {
-		const frame = eventFrame(event);
-		const sessionId = event.kind === "upsert" ? event.session.id : "sessionId" in event ? event.sessionId : void 0;
-		for (const [response, native] of sse) {
-			if (sessionId !== void 0 && options.headlessHub.computerUse?.ownsSession?.(sessionId) || frame.type === "computer_use_state") {
-				if (!native(sessionId)) continue;
-			}
-			writeSse(response, String(frame.type), frame);
-		}
-	});
 	async function handleRequest(request, response) {
 		const url = requestPath(request);
 		if (url.pathname === "/api/health" && request.method === "GET") {
@@ -531,6 +538,10 @@ async function serveHeadlessServer(options) {
 			else json(response, 200, listing);
 			return;
 		}
+		if (url.pathname === "/api/directories/po" && request.method === "GET") {
+			json(response, 200, { directories: await poFolders() });
+			return;
+		}
 		if (url.pathname === "/api/directories" && request.method === "GET") {
 			json(response, 200, { directories: await directorySuggestions(url.searchParams.get("q") ?? "", options.headlessHub.snapshot()) });
 			return;
@@ -576,22 +587,38 @@ async function serveHeadlessServer(options) {
 				return;
 			}
 		}
-		if (url.pathname === "/api/events" && request.method === "GET") {
-			response.writeHead(200, {
-				"cache-control": "no-cache",
-				connection: "keep-alive",
-				"content-type": "text/event-stream; charset=utf-8"
-			});
-			sse.set(response, (sessionId) => sessionId === void 0 ? desktopAuthorized(request) : computerUseAuthorized(sessionId, request));
-			response.on("close", () => sse.delete(response));
-			writeSse(response, "sessions_snapshot", {
-				type: "sessions_snapshot",
-				sessions: [...options.headlessHub.snapshot().filter((session) => !options.headlessHub.computerUse?.ownsSession?.(session.id) || computerUseAuthorized(session.id, request)).map(sessionView), ...dormant().filter((record) => !options.headlessHub.computerUse?.ownsSession?.(record.sessionId) || computerUseAuthorized(record.sessionId, request)).map(dormantView)]
-			});
-			writeSse(response, "workspaces_snapshot", {
-				type: "workspaces_snapshot",
-				workspaces: options.headlessHub.workspaces()
-			});
+		const groupMatch = /^\/api\/session-groups\/([^/]+)$/u.exec(url.pathname);
+		if (groupMatch && (request.method === "PATCH" || request.method === "DELETE")) {
+			const from = decodeURIComponent(groupMatch[1]);
+			let to = [];
+			if (request.method === "PATCH") {
+				const body = parseJson(await readBody(request));
+				const name = body && typeof body === "object" && "name" in body ? body.name : void 0;
+				if (typeof name !== "string" || name.trim() === "") {
+					json(response, 400, { error: "A group needs a new name." });
+					return;
+				}
+				to = [name];
+			}
+			const members = [...options.headlessHub.snapshot().map((session) => ({
+				id: session.id,
+				groups: session.groups ?? []
+			})), ...dormant().map((record) => ({
+				id: record.sessionId,
+				groups: record.groups ?? []
+			}))].filter((member) => member.groups.includes(from) && (!options.headlessHub.computerUse?.ownsSession?.(member.id) || computerUseAuthorized(member.id, request)));
+			let updates;
+			try {
+				updates = members.map((member) => ({
+					id: member.id,
+					groups: normalizeSessionGroups(member.groups.flatMap((group) => group === from ? to : [group]))
+				}));
+			} catch (error) {
+				json(response, 400, { error: error instanceof Error ? error.message : String(error) });
+				return;
+			}
+			for (const update of updates) await writeGroups(update.id, update.groups);
+			json(response, 200, { sessions: updates.length });
 			return;
 		}
 		if (url.pathname === "/api/workspaces") {
@@ -672,7 +699,7 @@ async function serveHeadlessServer(options) {
 			json(response, 200, { ok: true });
 			return;
 		}
-		const pluginMatch = DOOM_PACKAGE_API_PATH_PATTERN.exec(url.pathname);
+		const pluginMatch = PO_PACKAGE_API_PATH_PATTERN.exec(url.pathname);
 		if (pluginMatch !== null && request.method !== "CONNECT") {
 			const workspaceId = pluginMatch[1] === void 0 ? void 0 : decodeURIComponent(pluginMatch[1]);
 			const sessionId = pluginMatch[2] === void 0 ? void 0 : decodeURIComponent(pluginMatch[2]);
@@ -716,10 +743,10 @@ async function serveHeadlessServer(options) {
 				"host",
 				"authorization",
 				"x-po-token"
-			].includes(name) && (trustedCaller || !DOOM_API_CALLER_HEADERS.includes(name))) headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+			].includes(name) && (trustedCaller || !PO_API_CALLER_HEADERS.includes(name))) headers.set(name, Array.isArray(value) ? value.join(", ") : value);
 			if (!trustedCaller) {
-				headers.set(DOOM_API_CALLER_LOCALITY_HEADER, "local");
-				headers.set(DOOM_API_CALLER_STEP_UP_HEADER, "not-required");
+				headers.set(PO_API_CALLER_LOCALITY_HEADER, "local");
+				headers.set(PO_API_CALLER_STEP_UP_HEADER, "not-required");
 			}
 			const abort = new AbortController();
 			const disconnected = () => {
@@ -783,6 +810,26 @@ async function serveHeadlessServer(options) {
 			}
 			return;
 		}
+		if (suffix === "/groups" && request.method === "PUT") {
+			if (!(session?.workspaceId === workspaceId || dormant().some((candidate) => candidate.sessionId === sessionId && candidate.workspaceId === workspaceId))) {
+				json(response, 404, { error: "Session not found." });
+				return;
+			}
+			const body = parseJson(await readBody(request));
+			let groups;
+			try {
+				groups = normalizeSessionGroups(body && typeof body === "object" && "groups" in body ? body.groups : void 0);
+			} catch (error) {
+				json(response, 400, { error: error instanceof Error ? error.message : String(error) });
+				return;
+			}
+			if (!await writeGroups(sessionId, groups)) {
+				json(response, 404, { error: "Session not found." });
+				return;
+			}
+			json(response, 200, { groups });
+			return;
+		}
 		if (sessionMatch[3] === "revive" && request.method === "POST" && options.reviveSession) {
 			const record = dormant().find((candidate) => candidate.sessionId === sessionId && candidate.workspaceId === workspaceId);
 			if (record === void 0) {
@@ -795,8 +842,9 @@ async function serveHeadlessServer(options) {
 		}
 		if (session === void 0 || session.workspaceId !== workspaceId) {
 			const record = dormant().find((candidate) => candidate.sessionId === sessionId && candidate.workspaceId === workspaceId);
-			if (request.method === "DELETE" && record !== void 0 && options.removeDormantSession !== void 0) {
+			if (suffix === "" && request.method === "DELETE" && record !== void 0 && options.removeDormantSession !== void 0) {
 				sessionMcp.closeSessionBinding(record.sessionId);
+				await options.headlessHub.closeSession(record.sessionId, { keepDormant: true });
 				await options.removeDormantSession(record);
 				options.headlessHub.notifySessionRemoved(record.sessionId);
 				json(response, 200, { ok: true });
@@ -811,7 +859,11 @@ async function serveHeadlessServer(options) {
 		}
 		if (suffix === "" && request.method === "DELETE") {
 			sessionMcp.closeSessionBinding(sessionId);
-			await options.headlessHub.closeSession(sessionId);
+			await options.headlessHub.closeSession(sessionId, options.removeSessionFiles ? { keepDormant: true } : void 0);
+			if (options.removeSessionFiles) {
+				await options.removeSessionFiles(sessionId);
+				options.headlessHub.notifySessionRemoved(sessionId);
+			}
 			json(response, 200, { ok: true });
 			return;
 		}
@@ -881,84 +933,35 @@ async function serveHeadlessServer(options) {
 			json(response, 200, { sessionId: await options.resumeSession(session, targetSessionId) });
 			return;
 		}
-		if (suffix === "/channels" && request.method === "GET") {
-			json(response, 200, { channels: options.headlessHub.channelFrames(sessionId).filter((frame) => frame.type !== "computer_use_state" || computerUseAuthorized(sessionId, request)) });
-			return;
-		}
-		const channelMatch = /^\/channel\/([^/]+)$/u.exec(suffix);
-		if (channelMatch !== null && request.method === "POST") {
-			const frameType = decodeURIComponent(channelMatch[1]);
-			const connectionId = request.headers["x-po-connection"];
-			options.headlessHub.receiveChannel(sessionId, frameType, parseJson(await readBody(request)), typeof connectionId === "string" ? connectionId : "http", desktopAuthorized(request), computerUseAuthorized(sessionId, request));
-			json(response, 202, { ok: true });
-			return;
-		}
 		json(response, 404, { error: "Not found." });
 	}
-	server.on("upgrade", (request, socket, head) => {
-		const url = requestPath(request);
-		const mount = parseDoomSocketPath(url.pathname);
-		if (!mount) {
-			socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
-			socket.destroy();
-			return;
-		}
-		if (!authorized(request, options.token)) {
-			socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
-			socket.destroy();
-			return;
-		}
-		if (mount.scope !== "global" && (!options.headlessHub.workspaces().some((entry) => entry.id === mount.workspaceId && entry.available !== false) || mount.scope === "session" && options.headlessHub.session(mount.sessionId)?.workspaceId !== mount.workspaceId)) {
-			socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
-			socket.destroy();
-			return;
-		}
-		(mount.scope === "global" && options.headlessHub.computerUse === void 0 ? Promise.resolve(protocol) : createHeadlessProtocol({
-			hub: options.headlessHub,
+	/** Checks one connection request against its mount; the result says why it may not connect. */
+	const accessFor = (request) => {
+		const mount = parsePoSocketPath(requestPath(request).pathname);
+		if (!mount) return 404;
+		if (!authorized(request, options.token)) return 401;
+		if (mount.scope !== "global" && (!options.headlessHub.workspaces().some((entry) => entry.id === mount.workspaceId && entry.available !== false) || mount.scope === "session" && options.headlessHub.session(mount.sessionId)?.workspaceId !== mount.workspaceId)) return 404;
+		return {
 			mount,
-			telemetry: options.telemetry,
-			onNotice: options.onNotice,
-			dormantSessions: dormant,
 			authorizeSession: (id) => !options.headlessHub.computerUse?.ownsSession?.(id) || computerUseAuthorized(id, request),
 			authorizeComputerUse: (id) => computerUseAuthorized(id, request),
 			authorizeDesktop: () => desktopAuthorized(request)
-		})).then(async (selected) => {
-			if (closed || socket.destroyed) {
-				if (selected !== protocol) await selected.close();
-				socket.destroy();
-				return;
-			}
-			if (selected !== protocol) {
-				scopedProtocols.add(selected);
-				socket.once("close", () => {
-					selected.close().finally(() => scopedProtocols.delete(selected));
-				});
-			}
-			webSockets.handleUpgrade(request, socket, head, (client) => {
-				webSockets.emit("connection", client, selected);
-			});
-		}).catch(() => {
-			socket.destroy();
-		});
-	});
-	webSockets.on("connection", (socket, selected) => {
-		const handler = selected.accept(socket);
-		if (!handler) return;
-		const client = {
-			socket,
-			handler
 		};
-		clients.add(client);
-		socket.on("message", (data) => {
-			if (Buffer.isBuffer(data)) handler.onData(data);
-			else if (Array.isArray(data)) handler.onData(Buffer.concat(data));
-			else handler.onData(new Uint8Array(data));
-		});
-		socket.on("close", () => {
-			clients.delete(client);
-			handler.onClose();
+	};
+	server.on("upgrade", (request, socket, head) => {
+		const access = accessFor(request);
+		if (typeof access === "number" || closed) {
+			if (access === 401) socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+			else if (access === 404) socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
+			socket.destroy();
+			return;
+		}
+		webSockets.handleUpgrade(request, socket, head, (client) => {
+			const entry = { socket: client };
+			clients.add(entry);
+			client.on("close", () => clients.delete(entry));
+			protocol.accept(webSocketLink(client, { acceptPacked: false }), access);
 		});
-		socket.on("error", (error) => handler.onError(error));
 	});
 	await new Promise((resolve, reject) => {
 		server.once("error", reject);
@@ -972,12 +975,24 @@ async function serveHeadlessServer(options) {
 	return {
 		url: `http://${options.host ?? "127.0.0.1"}:${address.port}`,
 		sessionReservations: sessionMcp.reservations,
+		acceptProtocol(pathname, link, headers) {
+			const access = accessFor({
+				url: pathname,
+				headers: {
+					...headers,
+					...options.token === void 0 ? {} : { "x-po-token": options.token }
+				}
+			});
+			if (typeof access === "number" || closed) {
+				link.close(access === 401 ? "unauthorized" : "not found");
+				return false;
+			}
+			protocol.accept(link, access);
+			return true;
+		},
 		async close() {
 			if (closed) return;
 			closed = true;
-			unsubscribe();
-			for (const response of sse.keys()) response.end();
-			sse.clear();
 			for (const client of clients) client.socket.terminate();
 			clients.clear();
 			sessionMcp.close();
@@ -985,7 +1000,7 @@ async function serveHeadlessServer(options) {
 				recursive: true,
 				force: true
 			});
-			await Promise.all([protocol.close(), ...[...scopedProtocols].map((selected) => selected.close())]);
+			await protocol.close();
 			webSockets.close();
 			server.closeAllConnections();
 			await new Promise((resolve, reject) => server.close((error) => error === void 0 ? resolve() : reject(error)));
@@ -993,6 +1008,6 @@ async function serveHeadlessServer(options) {
 	};
 }
 //#endregion
-export { DOOM_PACKAGE_API_PATH_PATTERN, RESTART_WHILE_RUNNING_ERROR, serveHeadlessServer };
+export { PO_PACKAGE_API_PATH_PATTERN, RESTART_WHILE_RUNNING_ERROR, serveHeadlessServer };
 
 //# sourceMappingURL=headlessServer.mjs.map