@agimon-ai/po-core 0.0.0-alpha.0

package/dist/headlessServer.mjs

@@ -0,0 +1,949 @@
+import "./src/constants/contextApi.mjs";
+import { isDoomSessionSetupError } from "./src/schemas/headless.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 "./packageApi.mjs";
+import { SESSION_FILE_CONTENT_TYPES } from "./src/constants/sessionFiles.mjs";
+import { writeSessionAttachment } from "./src/services/sessionAttachments/index.mjs";
+import { createSessionMcpActivityStore } from "./src/services/sessionMcpActivity/index.mjs";
+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 { createSessionMcpRoutes, isPublicSessionMcpRoute, isSessionMcpHostRoute } from "./src/server/sessionMcpRoutes.mjs";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { WebSocketServer } from "ws";
+//#region src/server/headlessServer.ts
+/**
+* The canonical public shape of a package API request, as dispatch reads it.
+*
+* Groups: workspace id, session id, plugin base path, and the remainder handed
+* to the package. `settings` is the host's own API and sits beside `plugins`
+* rather than under it.
+*
+* Exported so the browser's URL construction can be pinned against it. The two
+* are written independently, in halves of this package that may not import each
+* other, and a disagreement between them is not a 404 from the route: the
+* 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 HEALTH_ROLE = "hub";
+const PROTOCOL_VERSION = 1;
+const MAX_BODY_BYTES = 8388608;
+const DIRECTORY_SUGGESTION_LIMIT = 12;
+const DIRECTORY_CHILDREN_LIMIT = 500;
+const HOME_PREFIX = "~";
+const WORKSPACE_NAME_MAX_LENGTH = 80;
+const WORKSPACE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9 ._-]*$/u;
+/** Restart closes the session host, which aborts a running turn, so it waits for idle. */
+const RESTART_WHILE_RUNNING_ERROR = "The session is running a turn. Stop it or wait for it to finish before reloading extensions.";
+function sessionView(session) {
+	return {
+		id: session.id,
+		workspaceId: session.workspaceId,
+		webComposition: session.webComposition,
+		nativeComposition: session.nativeComposition,
+		name: session.name,
+		cwd: session.cwd,
+		createdAt: session.createdAt,
+		updatedAt: session.updatedAt ?? session.createdAt,
+		phase: session.phase ?? "idle",
+		phaseSince: session.phaseSince ?? session.createdAt,
+		attach: "attached",
+		pendingMessageCount: session.pendingMessageCount ?? 0,
+		everPrompted: session.everPrompted ?? false,
+		awaitingInput: session.awaitingInput ?? false,
+		...session.lastSettledAt === void 0 ? {} : { lastSettledAt: session.lastSettledAt },
+		...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.pendingSetups === void 0 ? {} : { pendingSetups: session.pendingSetups },
+		...session.activity === void 0 ? {} : { activity: { ...session.activity } }
+	};
+}
+/** The dormant counterpart of `sessionView`; same shape, no runtime behind it. */
+function dormantView(record) {
+	return {
+		id: record.sessionId,
+		workspaceId: record.workspaceId,
+		name: record.name,
+		cwd: record.cwd,
+		createdAt: record.createdAt,
+		updatedAt: record.createdAt,
+		phase: "idle",
+		phaseSince: record.createdAt,
+		attach: "detached",
+		pendingMessageCount: 0,
+		everPrompted: false,
+		awaitingInput: false,
+		dormant: true,
+		...record.parentSessionId === void 0 ? {} : { parentSessionId: record.parentSessionId },
+		...record.sessionProvenance === void 0 ? {} : { sessionProvenance: record.sessionProvenance }
+	};
+}
+function json(response, status, value) {
+	const body = JSON.stringify(value);
+	response.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"content-length": Buffer.byteLength(body)
+	});
+	response.end(body);
+}
+function authorized(request, token) {
+	if (token === void 0) return true;
+	const authorization = request.headers.authorization;
+	if (authorization?.startsWith("Bearer ") && authorization.slice(7) === token) return true;
+	const header = request.headers["x-po-token"];
+	if (typeof header === "string" && header === token) return true;
+	try {
+		return new URL(request.url ?? "/", "http://po.local").searchParams.get("token") === token;
+	} catch {
+		return false;
+	}
+}
+function requestPath(request) {
+	return new URL(request.url ?? "/", "http://po.local");
+}
+function parseTranscriptRequest(url) {
+	const request = {};
+	const cursor = url.searchParams.get("cursor");
+	const direction = url.searchParams.get("direction");
+	const limit = url.searchParams.get("limit");
+	if (cursor !== null) request.cursor = cursor;
+	if (direction !== null) {
+		if (direction !== "older" && direction !== "newer") throw new Error("Invalid transcript direction");
+		request.direction = direction;
+	}
+	if (limit !== null) {
+		if (!/^\d+$/u.test(limit)) throw new Error("Invalid transcript page limit");
+		const parsed = Number(limit);
+		if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > 100) throw new Error("Invalid transcript page limit");
+		request.limit = parsed;
+	}
+	return request;
+}
+async function sessionFile(session, requestedPath) {
+	if (!requestedPath || requestedPath.includes("\0")) return Response.json({ error: "Invalid session file path." }, { status: 400 });
+	let root;
+	let filePath;
+	try {
+		root = await fs.promises.realpath(session.cwd);
+		filePath = await fs.promises.realpath(path.resolve(root, requestedPath));
+	} catch {
+		return Response.json({ error: "Session file not found." }, { status: 404 });
+	}
+	const contained = path.relative(root, filePath);
+	if (contained === ".." || contained.startsWith(`..${path.sep}`) || path.isAbsolute(contained)) return Response.json({ error: "Session file is outside the working directory." }, { status: 403 });
+	let handle;
+	try {
+		handle = await fs.promises.open(filePath, "r");
+	} catch {
+		return Response.json({ error: "Session file not found." }, { status: 404 });
+	}
+	try {
+		const stat = await handle.stat();
+		if (!stat.isFile()) return Response.json({ error: "Session file not found." }, { status: 404 });
+		if (stat.size > 26214400) return Response.json({ error: "Session file is too large." }, { status: 413 });
+		const bytes = await handle.readFile();
+		if (bytes.byteLength > 26214400) return Response.json({ error: "Session file is too large." }, { status: 413 });
+		return new Response(bytes, { headers: {
+			"content-type": SESSION_FILE_CONTENT_TYPES[path.extname(filePath).toLowerCase()] ?? "application/octet-stream",
+			"content-length": String(bytes.byteLength),
+			"cache-control": "no-store",
+			"x-content-type-options": "nosniff"
+		} });
+	} finally {
+		await handle.close();
+	}
+}
+/** Expands a leading `~` the way a shell would, so typed paths match what the user sees in a terminal. */
+function expandHome(value) {
+	if (value === HOME_PREFIX) return os.homedir();
+	return value.startsWith(`${HOME_PREFIX}${path.sep}`) ? path.join(os.homedir(), value.slice(2)) : value;
+}
+/**
+* Validates an add-workspace request. A name alone asks for a new default folder,
+* so it must be safe to use as one folder name.
+*/
+function parseWorkspaceAdmission(body) {
+	if (typeof body !== "object" || body === null) return { error: "A workspace root or name is required." };
+	const record = body;
+	if (record.root !== void 0 && typeof record.root !== "string") return { error: "The workspace root must be text." };
+	if (record.name !== void 0 && typeof record.name !== "string") return { error: "The workspace name must be text." };
+	const root = typeof record.root === "string" && record.root.trim() !== "" ? expandHome(record.root.trim()) : void 0;
+	const name = typeof record.name === "string" && record.name.trim() !== "" ? record.name.trim() : void 0;
+	if (root === void 0 && name === void 0) return { error: "A workspace root or name is required." };
+	if (name !== void 0 && (name.length > WORKSPACE_NAME_MAX_LENGTH || !WORKSPACE_NAME_PATTERN.test(name) || name.includes(".."))) return { error: `Workspace names use letters, numbers, spaces, dots, dashes, or underscores (up to ${String(WORKSPACE_NAME_MAX_LENGTH)} characters).` };
+	return {
+		...root === void 0 ? {} : { root },
+		...name === void 0 ? {} : { name }
+	};
+}
+async function directorySuggestions(query, sessions) {
+	const typed = expandHome(query.trim());
+	if (typed === "") return [];
+	const matches = (value) => value.toLowerCase().includes(typed.toLowerCase());
+	const known = [.../* @__PURE__ */ new Set([process.cwd(), ...sessions.map((session) => session.cwd)])].filter(matches);
+	const candidates = path.isAbsolute(typed) ? [typed] : typed.includes(path.sep) ? [path.resolve(process.cwd(), typed)] : [path.join(path.dirname(process.cwd()), typed), path.join(process.cwd(), typed)];
+	const completed = [];
+	for (const candidate of candidates) {
+		const drilling = typed.endsWith(path.sep);
+		const parent = drilling ? candidate : path.dirname(candidate);
+		const partial = drilling ? "" : path.basename(candidate).toLowerCase();
+		try {
+			const entries = await fs.promises.readdir(parent, { withFileTypes: true });
+			completed.push(...entries.filter((entry) => entry.isDirectory() && entry.name.toLowerCase().includes(partial)).map((entry) => path.join(parent, entry.name)));
+		} catch {}
+	}
+	return [.../* @__PURE__ */ new Set([...known, ...completed.sort((left, right) => left.localeCompare(right))])].slice(0, DIRECTORY_SUGGESTION_LIMIT);
+}
+/**
+* Lists the visible child directories of one folder for the workspace folder browser.
+* Resolves undefined for a relative, missing, or unreadable path.
+*/
+async function directoryChildren(requested) {
+	const directory = requested === null || requested.trim() === "" ? os.homedir() : expandHome(requested.trim());
+	if (!path.isAbsolute(directory)) return void 0;
+	const resolved = path.resolve(directory);
+	let entries;
+	try {
+		entries = await fs.promises.readdir(resolved, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	const directories = entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map((entry) => path.join(resolved, entry.name)).sort((left, right) => left.localeCompare(right)).slice(0, DIRECTORY_CHILDREN_LIMIT);
+	const parent = path.dirname(resolved);
+	return {
+		path: resolved,
+		...parent === resolved ? {} : { parent },
+		directories
+	};
+}
+var RequestBodyTooLargeError = class extends Error {
+	constructor() {
+		super("Request body is too large.");
+	}
+};
+async function readBody(request) {
+	const chunks = [];
+	let size = 0;
+	for await (const chunk of request) {
+		const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+		size += buffer.byteLength;
+		if (size > MAX_BODY_BYTES) throw new RequestBodyTooLargeError();
+		chunks.push(buffer);
+	}
+	return Buffer.concat(chunks);
+}
+function parseJson(body) {
+	if (body.byteLength === 0) return {};
+	return JSON.parse(Buffer.from(body).toString("utf8"));
+}
+function webRequest(request, url, signal) {
+	const headers = new Headers();
+	for (const [name, value] of Object.entries(request.headers)) if (value !== void 0) headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+	return new Request(url, {
+		method: request.method,
+		headers,
+		signal,
+		...request.method === "GET" || request.method === "HEAD" ? {} : {
+			body: Readable.toWeb(request),
+			duplex: "half"
+		}
+	});
+}
+async function writeResponse(response, result) {
+	response.writeHead(result.status, Object.fromEntries(result.headers.entries()));
+	if (result.body === null) {
+		response.end();
+		return;
+	}
+	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
+* clients cannot create a second session backend or bypass its lifecycle.
+*/
+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;
+	};
+	const computerUseAuthorized = (sessionId, request) => {
+		if (desktopAuthorized(request)) return true;
+		if (!authorized(request, options.token)) return false;
+		const headers = new Headers();
+		for (const [name, value] of Object.entries(request.headers)) if (value !== void 0) headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+		return options.headlessHub.computerUse?.authorizeSession?.(sessionId, headers) === true;
+	};
+	const activationAuthorized = (request) => {
+		if (!authorized(request, options.token)) return false;
+		const headers = new Headers();
+		for (const [name, value] of Object.entries(request.headers)) if (value !== void 0) headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+		return options.headlessHub.computerUse?.authorizeActivation?.(headers) === true;
+	};
+	const pendingAuthorized = (sessionId, request) => {
+		if (!authorized(request, options.token)) return false;
+		const headers = new Headers();
+		for (const [name, value] of Object.entries(request.headers)) if (value !== void 0) headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+		return options.headlessHub.computerUse?.authorizePending?.(sessionId, headers) === true;
+	};
+	const recordingAuthorized = (sessionId, request) => {
+		if (!authorized(request, options.token)) return false;
+		const headers = new Headers();
+		for (const [name, value] of Object.entries(request.headers)) if (value !== void 0) headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+		return options.headlessHub.computerUse?.authorizeRecording?.(sessionId, headers) === true;
+	};
+	let closed = false;
+	const webSockets = new WebSocketServer({ noServer: true });
+	/**
+	* A recorded session is dormant exactly while the hub has no session for its
+	* 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({
+		hub: options.headlessHub,
+		telemetry: options.telemetry,
+		onNotice: options.onNotice,
+		dormantSessions: dormant
+	});
+	const sessionMcpStateDir = options.sessionMcpStateDir ?? fs.mkdtempSync(path.join(os.tmpdir(), "po-session-mcp-"));
+	const sessionMcp = createSessionMcpRoutes({
+		headlessHub: options.headlessHub,
+		publicOrigin: options.sessionMcpPublicOrigin ?? (() => void 0),
+		publicOriginRevision: options.sessionMcpPublicOriginRevision,
+		onNotice: options.onNotice,
+		isSessionPersisted: options.isSessionPersisted,
+		activityStore: createSessionMcpActivityStore(sessionMcpStateDir),
+		conversationStore: createSessionMcpConversationStore(sessionMcpStateDir),
+		registrationStore: createSessionMcpRegistrationStore({
+			stateDir: sessionMcpStateDir,
+			onNotice: options.onNotice
+		})
+	});
+	/** Sessions being restarted, keyed by id, settled once the reopen succeeds or fails. */
+	const restarting = /* @__PURE__ */ new Map();
+	const server = createServer((request, response) => {
+		handleRequest(request, response).catch((error) => {
+			if (response.headersSent) {
+				response.destroy();
+				return;
+			}
+			options.onNotice?.(`Headless request failed: ${harnessErrorMessage(error)}`);
+			if (isDoomSessionSetupError(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") {
+			json(response, 200, {
+				ok: true,
+				role: HEALTH_ROLE,
+				protocol: PROTOCOL_VERSION,
+				sessions: options.headlessHub.snapshot().length
+			});
+			return;
+		}
+		const scopedSession = /^\/api\/workspaces\/[^/]+\/sessions\/([^/]+)(?:\/|$)/u.exec(url.pathname)?.[1];
+		if (scopedSession && options.headlessHub.computerUse?.ownsSession?.(decodeURIComponent(scopedSession)) && !computerUseAuthorized(decodeURIComponent(scopedSession), request) && !(request.method === "GET" && url.pathname.endsWith("/plugins/computer-use/artifact") && recordingAuthorized(decodeURIComponent(scopedSession), request)) && !(request.method === "POST" && url.pathname.endsWith("/plugins/computer-use/activate") && activationAuthorized(request)) && !(url.pathname.endsWith("/plugins/computer-use/activate") && (request.method === "GET" && (pendingAuthorized(decodeURIComponent(scopedSession), request) || recordingAuthorized(decodeURIComponent(scopedSession), request)) || request.method === "DELETE" && pendingAuthorized(decodeURIComponent(scopedSession), request)))) {
+			json(response, 404, { error: "This session belongs to its Desktop instance." });
+			return;
+		}
+		if (isPublicSessionMcpRoute(request.method ?? "GET", url.pathname)) {
+			const sessionMcpAbort = new AbortController();
+			const abortSessionMcp = () => {
+				if (!response.writableEnded) sessionMcpAbort.abort();
+			};
+			response.once("close", abortSessionMcp);
+			const publicSessionMcp = await sessionMcp.handlePublic(webRequest(request, url, sessionMcpAbort.signal));
+			if (publicSessionMcp !== void 0) {
+				try {
+					await writeResponse(response, publicSessionMcp);
+				} finally {
+					response.off("close", abortSessionMcp);
+				}
+				return;
+			}
+			response.off("close", abortSessionMcp);
+		}
+		if (!authorized(request, options.token)) {
+			json(response, 401, { error: "Unauthorized." });
+			return;
+		}
+		const reopening = scopedSession === void 0 ? void 0 : restarting.get(decodeURIComponent(scopedSession));
+		if (reopening !== void 0 && options.headlessHub.session(decodeURIComponent(scopedSession)) === void 0) await reopening;
+		if (isSessionMcpHostRoute(url.pathname)) {
+			const hostSessionMcp = await sessionMcp.handleHost(webRequest(request, url));
+			if (hostSessionMcp !== void 0) {
+				await writeResponse(response, hostSessionMcp);
+				return;
+			}
+		}
+		if (url.pathname === "/api/remote" || url.pathname.startsWith("/api/remote/")) {
+			const headers = new Headers();
+			for (const [name, value] of Object.entries(request.headers)) if (value !== void 0 && name !== "authorization" && name !== "x-po-token") headers.set(name, Array.isArray(value) ? value.join(", ") : value);
+			await writeResponse(response, await options.headlessHub.requestApi({ scope: "global" }, "remote", new Request(`http://po.local${url.pathname.slice(11)}${url.search}`, {
+				method: request.method,
+				headers,
+				...request.method === "GET" || request.method === "HEAD" ? {} : { body: Buffer.from(await readBody(request)) }
+			})));
+			return;
+		}
+		if (url.pathname === "/api/telemetry/browser" && request.method === "POST") {
+			const body = JSON.parse(new TextDecoder().decode(await readBody(request)));
+			if (body.v !== 1 || !Array.isArray(body.events) || body.events.length > 10) {
+				json(response, 400, { error: "Invalid browser telemetry batch." });
+				return;
+			}
+			for (const event of body.events) {
+				if (!event || typeof event !== "object" || typeof event.name !== "string" || !/^web\.browser\.[a-z_]{1,40}$/u.test(event.name)) continue;
+				if (options.telemetry) observe(options.telemetry.recordEvent(event.name, {
+					...typeof event.duration_ms === "number" && Number.isFinite(event.duration_ms) && event.duration_ms >= 0 ? { duration_ms: event.duration_ms } : {},
+					...typeof event.count === "number" && Number.isFinite(event.count) && event.count >= 0 ? { count: event.count } : {}
+				}));
+			}
+			json(response, 200, { ok: true });
+			return;
+		}
+		if (url.pathname === "/api/compositions" && request.method === "GET") {
+			json(response, 200, options.compositions?.() ?? { workspaces: [] });
+			return;
+		}
+		if ((url.pathname.startsWith("/api/web-plugins/") || url.pathname === "/bundle-manifest.json" || url.pathname.startsWith("/bundle-assets/")) && options.requestAsset) {
+			const result = await options.requestAsset(new Request(url, { method: request.method }));
+			if (result) {
+				await writeResponse(response, result);
+				return;
+			}
+		}
+		if (url.pathname === "/api/directories/children" && request.method === "GET") {
+			const listing = await directoryChildren(url.searchParams.get("path"));
+			if (listing === void 0) json(response, 404, { error: "That folder cannot be read." });
+			else json(response, 200, listing);
+			return;
+		}
+		if (url.pathname === "/api/directories" && request.method === "GET") {
+			json(response, 200, { directories: await directorySuggestions(url.searchParams.get("q") ?? "", options.headlessHub.snapshot()) });
+			return;
+		}
+		if (url.pathname === "/api/sessions" && request.method === "POST") {
+			const body = parseJson(await readBody(request));
+			if (!body || typeof body !== "object" || !("cwd" in body) || typeof body.cwd !== "string" || !body.cwd.trim() || "name" in body && typeof body.name !== "string") {
+				json(response, 400, { error: "A session needs a working directory and an optional name." });
+				return;
+			}
+			json(response, 201, { sessionId: (await options.headlessHub.sessionService.create({
+				cwd: body.cwd,
+				name: "name" in body ? String(body.name) : path.basename(body.cwd)
+			})).sessionId });
+			return;
+		}
+		const workspaceSessions = /^\/api\/workspaces\/([^/]+)\/sessions$/u.exec(url.pathname);
+		if (workspaceSessions) {
+			const workspaceId = decodeURIComponent(workspaceSessions[1]);
+			const workspace = options.headlessHub.workspaces().find((entry) => entry.id === workspaceId);
+			if (!workspace) {
+				json(response, 404, { error: "Workspace not found." });
+				return;
+			}
+			if (request.method === "GET") {
+				json(response, 200, { sessions: [...options.headlessHub.snapshot().filter((session) => session.workspaceId === workspaceId && (!options.headlessHub.computerUse?.ownsSession?.(session.id) || computerUseAuthorized(session.id, request))).map(sessionView), ...dormant().filter((record) => record.workspaceId === workspaceId && (!options.headlessHub.computerUse?.ownsSession?.(record.sessionId) || computerUseAuthorized(record.sessionId, request))).map(dormantView)] });
+				return;
+			}
+			if (request.method === "POST") {
+				if (workspace.available === false) {
+					json(response, 409, { error: "Workspace is unavailable." });
+					return;
+				}
+				const body = parseJson(await readBody(request));
+				if (!body || typeof body !== "object" || "name" in body && typeof body.name !== "string") {
+					json(response, 400, { error: "A session accepts an optional name." });
+					return;
+				}
+				json(response, 201, { sessionId: (await options.headlessHub.sessionService.create({
+					cwd: workspace.root,
+					name: "name" in body ? String(body.name) : path.basename(workspace.root)
+				})).sessionId });
+				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()
+			});
+			return;
+		}
+		if (url.pathname === "/api/workspaces") {
+			if (request.method === "GET") {
+				json(response, 200, { workspaces: options.headlessHub.workspaces() });
+				return;
+			}
+			if (request.method === "POST") {
+				const admission = parseWorkspaceAdmission(parseJson(await readBody(request)));
+				if ("error" in admission) {
+					json(response, 400, admission);
+					return;
+				}
+				let workspace;
+				try {
+					workspace = await options.headlessHub.admitWorkspace(admission);
+				} catch (error) {
+					json(response, 422, { error: error instanceof Error ? error.message : String(error) });
+					return;
+				}
+				json(response, 201, { workspace });
+				return;
+			}
+		}
+		const workspaceHistoryMatch = /^\/api\/workspaces\/([^/]+)\/history$/u.exec(url.pathname);
+		if (workspaceHistoryMatch && request.method === "GET" && options.workspaceHistory) {
+			const workspaceId = decodeURIComponent(workspaceHistoryMatch[1]);
+			const workspace = options.headlessHub.workspaces().find((entry) => entry.id === workspaceId);
+			if (!workspace) {
+				json(response, 404, { error: "Workspace not found." });
+				return;
+			}
+			if (workspace.available === false) {
+				json(response, 409, { error: "Workspace is unavailable." });
+				return;
+			}
+			json(response, 200, { sessions: await options.workspaceHistory(workspaceId) });
+			return;
+		}
+		const workspaceResumeMatch = /^\/api\/workspaces\/([^/]+)\/resume$/u.exec(url.pathname);
+		if (workspaceResumeMatch && request.method === "POST" && options.resumeWorkspaceSession) {
+			const workspaceId = decodeURIComponent(workspaceResumeMatch[1]);
+			const workspace = options.headlessHub.workspaces().find((entry) => entry.id === workspaceId);
+			if (!workspace) {
+				json(response, 404, { error: "Workspace not found." });
+				return;
+			}
+			if (workspace.available === false) {
+				json(response, 409, { error: "Workspace is unavailable." });
+				return;
+			}
+			const body = parseJson(await readBody(request));
+			const targetSessionId = body && typeof body === "object" && "targetSessionId" in body ? body.targetSessionId : void 0;
+			if (typeof targetSessionId !== "string" || !/^[A-Za-z0-9_-]+$/u.test(targetSessionId)) {
+				json(response, 400, { error: "Invalid target session id." });
+				return;
+			}
+			json(response, 200, { sessionId: await options.resumeWorkspaceSession(workspaceId, targetSessionId) });
+			return;
+		}
+		const workspaceMatch = /^\/api\/workspaces\/([^/]+)$/u.exec(url.pathname);
+		if (workspaceMatch && request.method === "GET") {
+			const workspace = options.headlessHub.workspaces().find((entry) => entry.id === decodeURIComponent(workspaceMatch[1]));
+			json(response, workspace ? 200 : 404, workspace ? { workspace } : { error: "Workspace not found." });
+			return;
+		}
+		if (workspaceMatch && request.method === "DELETE") {
+			const id = decodeURIComponent(workspaceMatch[1]);
+			if (!options.headlessHub.workspaces().some((workspace) => workspace.id === id)) {
+				json(response, 404, { error: "Workspace not found." });
+				return;
+			}
+			if (options.headlessHub.snapshot().some((session) => session.workspaceId === id) || dormant().some((session) => session.workspaceId === id)) {
+				json(response, 409, { error: "Workspace still has sessions." });
+				return;
+			}
+			await options.headlessHub.removeWorkspace(id);
+			json(response, 200, { ok: true });
+			return;
+		}
+		const pluginMatch = DOOM_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]);
+			if (workspaceId !== void 0 && !options.headlessHub.workspaces().some((entry) => entry.id === workspaceId)) {
+				json(response, 404, { error: "Workspace not found." });
+				return;
+			}
+			if (sessionId !== void 0 && options.headlessHub.session(sessionId)?.workspaceId !== workspaceId) {
+				if (dormant().some((record) => record.sessionId === sessionId && record.workspaceId === workspaceId) && pluginMatch[3] === "context" && request.method === "GET") {
+					const detail = await createContextApi({
+						sessionId,
+						environment: process.env
+					}).fetch(new Request(`http://po.local/${pluginMatch[4] ?? ""}${url.search}`));
+					const body = await detail.json();
+					if (readContextDetail(sessionId, process.env) === void 0) json(response, 404, { error: "This session is stopped. Wake it to read this item." });
+					else json(response, detail.status, body);
+					return;
+				}
+				json(response, 404, { error: "Session not found." });
+				return;
+			}
+			const mount = sessionId !== void 0 ? {
+				scope: "session",
+				sessionId
+			} : workspaceId !== void 0 ? {
+				scope: "workspace",
+				workspaceId
+			} : { scope: "global" };
+			const basePath = pluginMatch[3] === void 0 ? "settings" : decodeURIComponent(pluginMatch[3]);
+			if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u.test(basePath)) {
+				json(response, 400, { error: "Invalid package API base path." });
+				return;
+			}
+			if (pluginMatch[3] === "settings" || sessionId !== void 0 && basePath === "settings") {
+				json(response, 404, { error: "Not found." });
+				return;
+			}
+			const headers = new Headers();
+			const trustedCaller = options.token !== void 0 && authorized(request, options.token);
+			for (const [name, value] of Object.entries(request.headers)) if (value !== void 0 && ![
+				"host",
+				"authorization",
+				"x-po-token"
+			].includes(name) && (trustedCaller || !DOOM_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");
+			}
+			const abort = new AbortController();
+			const disconnected = () => {
+				if (!response.writableEnded) abort.abort();
+			};
+			response.once("close", disconnected);
+			try {
+				const started = performance.now();
+				const attributes = {
+					scope: mount.scope,
+					"plugin.name": basePath,
+					"http.operation": request.method,
+					...mount.scope === "workspace" ? { "workspace.id": mount.workspaceId } : {},
+					...mount.scope === "session" ? { "session.id": mount.sessionId } : {}
+				};
+				const dispatch = async () => options.headlessHub.requestApi(mount, basePath, new Request(`http://po.local/${pluginMatch[4] ?? ""}${url.search}`, {
+					method: request.method,
+					headers,
+					signal: abort.signal,
+					...request.method === "GET" || request.method === "HEAD" ? {} : { body: Buffer.from(await readBody(request)) }
+				}));
+				const result = options.telemetry ? await options.telemetry.runInSpan("po_server.plugin.request", attributes, dispatch) : await dispatch();
+				if (options.telemetry) observe(options.telemetry.recordEvent("po_server.plugin.response", {
+					...attributes,
+					status: result.status,
+					durationMs: performance.now() - started
+				}), options.onNotice);
+				await writeResponse(response, result);
+			} finally {
+				response.off("close", disconnected);
+			}
+			return;
+		}
+		const sessionMatch = /^\/api\/workspaces\/([^/]+)\/sessions\/([^/]+)(?:\/(.*))?$/u.exec(url.pathname);
+		if (sessionMatch === null) {
+			json(response, 404, { error: "Not found." });
+			return;
+		}
+		const sessionId = decodeURIComponent(sessionMatch[2]);
+		const workspaceId = decodeURIComponent(sessionMatch[1]);
+		const session = options.headlessHub.session(sessionId);
+		const suffix = sessionMatch[3] === void 0 ? "" : `/${sessionMatch[3]}`;
+		if (suffix === "/transcript" && request.method === "GET" && options.readDormantTranscript) {
+			const record = dormant().find((candidate) => candidate.sessionId === sessionId && candidate.workspaceId === workspaceId);
+			if (record === void 0) {
+				json(response, 404, { error: "Dormant session not found." });
+				return;
+			}
+			let transcriptRequest;
+			try {
+				transcriptRequest = parseTranscriptRequest(url);
+			} catch (error) {
+				json(response, 400, { error: error instanceof Error ? error.message : "Invalid transcript request." });
+				return;
+			}
+			try {
+				json(response, 200, await options.readDormantTranscript(record, transcriptRequest, BACKGROUND_CONTEXT));
+			} catch (error) {
+				const status = (error instanceof Error ? error.message : String(error)) === "STALE_TRANSCRIPT_CURSOR" ? 409 : 422;
+				json(response, status, { error: status === 409 ? "STALE_TRANSCRIPT_CURSOR" : "Saved transcript is unavailable." });
+			}
+			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) {
+				json(response, 404, { error: "Dormant session not found." });
+				return;
+			}
+			await options.reviveSession(record);
+			json(response, 200, { ok: true });
+			return;
+		}
+		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) {
+				sessionMcp.closeSessionBinding(record.sessionId);
+				await options.removeDormantSession(record);
+				options.headlessHub.notifySessionRemoved(record.sessionId);
+				json(response, 200, { ok: true });
+				return;
+			}
+			json(response, 404, { error: "Session not found." });
+			return;
+		}
+		if (suffix === "" && request.method === "GET") {
+			json(response, 200, sessionView(session));
+			return;
+		}
+		if (suffix === "" && request.method === "DELETE") {
+			sessionMcp.closeSessionBinding(sessionId);
+			await options.headlessHub.closeSession(sessionId);
+			json(response, 200, { ok: true });
+			return;
+		}
+		if (suffix === "/history" && request.method === "GET" && options.sessionHistory) {
+			json(response, 200, { sessions: await options.sessionHistory(session) });
+			return;
+		}
+		if (suffix === "/avatar" && request.method === "GET") {
+			const avatar = options.headlessHub.sessionAvatar(sessionId);
+			if (avatar === void 0) {
+				json(response, 404, { error: "This session has no avatar." });
+				return;
+			}
+			const current = url.searchParams.get("v") === session.profile?.iconVersion;
+			response.writeHead(200, {
+				"content-type": avatar.mimeType,
+				"content-length": String(avatar.bytes.byteLength),
+				"cache-control": current ? "private, max-age=31536000, immutable" : "no-store",
+				"x-content-type-options": "nosniff"
+			});
+			response.end(avatar.bytes);
+			return;
+		}
+		if (suffix === "/file" && request.method === "GET") {
+			await writeResponse(response, await sessionFile(session, url.searchParams.get("path")));
+			return;
+		}
+		if (suffix === "/attachments" && request.method === "POST") {
+			let bytes;
+			try {
+				bytes = await readBody(request);
+			} catch (error) {
+				if (!(error instanceof RequestBodyTooLargeError)) throw error;
+				json(response, 413, { error: "The attachment exceeds the 8 MB upload limit." });
+				return;
+			}
+			json(response, 201, await writeSessionAttachment(sessionId, url.searchParams.get("name") ?? "file", bytes));
+			return;
+		}
+		if (suffix === "/restart" && request.method === "POST" && options.restartSession) {
+			if ((session.phase ?? "idle") !== "idle") {
+				json(response, 409, { error: RESTART_WHILE_RUNNING_ERROR });
+				return;
+			}
+			const restart = options.restartSession(session);
+			const settled = restart.then(() => void 0, () => void 0);
+			restarting.set(sessionId, settled);
+			try {
+				await restart;
+			} finally {
+				if (restarting.get(sessionId) === settled) restarting.delete(sessionId);
+			}
+			json(response, 200, { ok: true });
+			return;
+		}
+		if (suffix === "/resume" && request.method === "POST" && options.resumeSession) {
+			const body = parseJson(await readBody(request));
+			const targetSessionId = body && typeof body === "object" && "targetSessionId" in body ? body.targetSessionId : void 0;
+			if (typeof targetSessionId !== "string" || !/^[A-Za-z0-9_-]+$/u.test(targetSessionId)) {
+				json(response, 400, { error: "Invalid target session id." });
+				return;
+			}
+			if (options.headlessHub.computerUse?.ownsSession?.(targetSessionId) && !computerUseAuthorized(targetSessionId, request)) {
+				json(response, 404, { error: "This session belongs to its Desktop instance." });
+				return;
+			}
+			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,
+			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();
+		});
+		socket.on("error", (error) => handler.onError(error));
+	});
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(options.port, options.host ?? "127.0.0.1", () => resolve());
+	});
+	const address = server.address();
+	if (address === null || typeof address === "string") {
+		await new Promise((resolve) => server.close(() => resolve()));
+		throw new Error("The headless server did not expose a TCP address.");
+	}
+	return {
+		url: `http://${options.host ?? "127.0.0.1"}:${address.port}`,
+		sessionReservations: sessionMcp.reservations,
+		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();
+			if (options.sessionMcpStateDir === void 0) await fs.promises.rm(sessionMcpStateDir, {
+				recursive: true,
+				force: true
+			});
+			await Promise.all([protocol.close(), ...[...scopedProtocols].map((selected) => selected.close())]);
+			webSockets.close();
+			server.closeAllConnections();
+			await new Promise((resolve, reject) => server.close((error) => error === void 0 ? resolve() : reject(error)));
+		}
+	};
+}
+//#endregion
+export { DOOM_PACKAGE_API_PATH_PATTERN, RESTART_WHILE_RUNNING_ERROR, serveHeadlessServer };
+
+//# sourceMappingURL=headlessServer.mjs.map