@pi-in-go/pigpen-ahp 0.1.0

package/proof/oracle/src/core/sequencer.ts

@@ -0,0 +1,75 @@
+/**
+ * Server sequence allocation and the action replay buffer.
+ *
+ * The host is the sole authority for ordering: every accepted action gets a
+ * monotonically increasing `serverSeq` and is retained in a bounded ring
+ * buffer so a reconnecting client can replay the gap instead of refetching
+ * every snapshot.
+ *
+ * @see https://microsoft.github.io/agent-host-protocol/specification/lifecycle
+ */
+
+import type { ActionEnvelope } from "@microsoft/agent-host-protocol";
+
+/**
+ * Local memory bound for replay. A client whose gap predates the buffer gets
+ * fresh snapshots instead, preserving correctness at the cost of more data.
+ */
+const DEFAULT_REPLAY_BUFFER_CAPACITY = 1000;
+
+export class Sequencer {
+	#serverSeq = 0;
+	readonly #buffer: ActionEnvelope[] = [];
+	readonly #capacity: number;
+
+	constructor(capacity: number = DEFAULT_REPLAY_BUFFER_CAPACITY) {
+		this.#capacity = Math.max(1, capacity);
+	}
+
+	/** The seq of the most recently emitted envelope (0 before anything is emitted). */
+	get current(): number {
+		return this.#serverSeq;
+	}
+
+	/** Allocates the next seq. Callers must emit the envelope they build with it. */
+	next(): number {
+		return ++this.#serverSeq;
+	}
+
+	/** Retains an envelope for replay, evicting the oldest when at capacity. */
+	retain(envelope: ActionEnvelope): void {
+		this.#buffer.push(envelope);
+		if (this.#buffer.length > this.#capacity) {
+			this.#buffer.shift();
+		}
+	}
+
+	/** The oldest seq still replayable, or `undefined` when the buffer is empty. */
+	get oldestRetainedSeq(): number | undefined {
+		return this.#buffer[0]?.serverSeq;
+	}
+
+	/**
+	 * Whether the gap after `lastSeenServerSeq` is fully covered by the buffer.
+	 *
+	 * A client that is already current (`lastSeenServerSeq >= current`) trivially
+	 * qualifies. Otherwise the buffer must still hold `lastSeenServerSeq + 1`.
+	 */
+	canReplayFrom(lastSeenServerSeq: number): boolean {
+		if (lastSeenServerSeq >= this.#serverSeq) {
+			return true;
+		}
+		const oldest = this.oldestRetainedSeq;
+		return oldest !== undefined && oldest <= lastSeenServerSeq + 1;
+	}
+
+	/**
+	 * Envelopes after `lastSeenServerSeq` whose channel the client subscribes to.
+	 *
+	 * Returned in seq order. Only call after {@link canReplayFrom} returns true;
+	 * otherwise the result silently omits evicted envelopes.
+	 */
+	replayFrom(lastSeenServerSeq: number, channels: ReadonlySet<string>): ActionEnvelope[] {
+		return this.#buffer.filter((envelope) => envelope.serverSeq > lastSeenServerSeq && channels.has(envelope.channel));
+	}
+}

package/proof/oracle/src/core/state-store.ts

@@ -0,0 +1,162 @@
+/**
+ * The authoritative state store.
+ *
+ * Every state-bearing channel holds an immutable state tree mutated only by
+ * actions run through the protocol's pure reducers. Terminal state additionally
+ * caps retained output so reconnect snapshots cannot grow without bound.
+ *
+ * @see https://microsoft.github.io/agent-host-protocol/guide/state-model
+ */
+
+import {
+	ActionType,
+	type ChangesetState,
+	type ChatState,
+	changesetReducer,
+	chatReducer,
+	type ResourceWatchState,
+	type RootState,
+	resourceWatchReducer,
+	rootReducer,
+	type SessionState,
+	type Snapshot,
+	type StateAction,
+	sessionReducer,
+	type TerminalAction,
+	type TerminalContentPart,
+	type TerminalState,
+	terminalReducer,
+	type URI,
+} from "@microsoft/agent-host-protocol";
+import { type ChannelKind, channelKind } from "./channels.ts";
+
+/** Any state tree this host serves. */
+export type ChannelState = RootState | SessionState | ChatState | TerminalState | ChangesetState | ResourceWatchState;
+
+/** Maximum output characters retained for snapshots; live clients still receive every action. */
+const MAX_RETAINED_TERMINAL_CHARS = 1_000_000;
+
+function terminalOutput(part: TerminalContentPart): string {
+	return part.type === "unclassified" ? part.value : part.output;
+}
+
+function withTerminalOutput(part: TerminalContentPart, output: string): TerminalContentPart {
+	return part.type === "unclassified" ? { ...part, value: output } : { ...part, output };
+}
+
+/** Applies the official reducer, then trims only the oldest retained output. */
+function reduceTerminal(state: TerminalState, action: TerminalAction): TerminalState {
+	const reduced = terminalReducer(state, action);
+	if (action.type !== ActionType.TerminalData) return reduced;
+
+	let remaining = MAX_RETAINED_TERMINAL_CHARS;
+	let trimmed = false;
+	const newestFirst: TerminalContentPart[] = [];
+
+	for (let index = reduced.content.length - 1; index >= 0; index -= 1) {
+		const part = reduced.content[index];
+		if (!part) continue;
+		const output = terminalOutput(part);
+		if (output.length <= remaining) {
+			newestFirst.push(part);
+			remaining -= output.length;
+			continue;
+		}
+		if (remaining > 0) {
+			newestFirst.push(withTerminalOutput(part, output.slice(-remaining)));
+		}
+		trimmed = true;
+		break;
+	}
+
+	return trimmed ? { ...reduced, content: newestFirst.reverse() } : reduced;
+}
+
+interface ChannelEntry {
+	readonly kind: ChannelKind;
+	state: ChannelState;
+}
+
+/**
+ * Applies an action to a channel's state using the reducer for that channel
+ * kind. Reducers are total: an action they do not recognise is a no-op, which
+ * is how forward compatibility works.
+ */
+function reduce(kind: ChannelKind, state: ChannelState, action: StateAction): ChannelState {
+	switch (kind) {
+		case "root":
+			// Channel routing chooses the reducer; generated unions still require
+			// narrowing at this boundary.
+			return rootReducer(state as RootState, action as never);
+		case "session":
+			return sessionReducer(state as SessionState, action as never);
+		case "chat":
+			return chatReducer(state as ChatState, action as never);
+		case "terminal":
+			return reduceTerminal(state as TerminalState, action as never);
+		case "changeset":
+			return changesetReducer(state as ChangesetState, action as never);
+		case "resourceWatch":
+			// Pass-through by design: a watch's state describes what is being
+			// watched, and `resourceWatch/changed` carries pure event traffic.
+			return resourceWatchReducer(state as ResourceWatchState, action as never);
+		default:
+			return state;
+	}
+}
+
+export class StateStore {
+	readonly #channels = new Map<URI, ChannelEntry>();
+
+	/**
+	 * Registers a channel with its initial state. Replaces any existing entry.
+	 *
+	 * `kind` is normally inferred from the scheme. Callers pass it explicitly
+	 * when the command establishes the kind of a client-chosen URI, such as a
+	 * provider-aliased session or VS Code terminal.
+	 */
+	create(uri: URI, state: ChannelState, kind: ChannelKind | undefined = channelKind(uri)): void {
+		if (kind === undefined) {
+			throw new Error(`Cannot create channel with unknown scheme: ${uri}`);
+		}
+		this.#channels.set(uri, { kind, state });
+	}
+
+	delete(uri: URI): boolean {
+		return this.#channels.delete(uri);
+	}
+
+	has(uri: URI): boolean {
+		return this.#channels.has(uri);
+	}
+
+	get(uri: URI): ChannelState | undefined {
+		return this.#channels.get(uri)?.state;
+	}
+
+	kindOf(uri: URI): ChannelKind | undefined {
+		return this.#channels.get(uri)?.kind;
+	}
+
+	/**
+	 * Reduces an action into a channel.
+	 *
+	 * Returns `false` when the channel does not exist — the spec requires the
+	 * host to silently ignore actions targeting an unknown channel rather than
+	 * echoing a rejection.
+	 */
+	apply(uri: URI, action: StateAction): boolean {
+		const entry = this.#channels.get(uri);
+		if (!entry) {
+			return false;
+		}
+		entry.state = reduce(entry.kind, entry.state, action);
+		return true;
+	}
+
+	/** Builds a subscribe/initialize snapshot for a channel at the given seq. */
+	snapshot(uri: URI, fromSeq: number): Snapshot | undefined {
+		const entry = this.#channels.get(uri);
+		return entry === undefined ? undefined : { resource: uri, state: entry.state, fromSeq };
+	}
+}

package/proof/oracle/src/core/uri.ts

@@ -0,0 +1,25 @@
+/**
+ * URI helpers shared across channels and backends. Filesystem conversion uses
+ * `node:url` consistently so platform and remote-authority semantics cannot
+ * diverge between commands.
+ */
+
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/**
+ * Converts a `file:` URI to a filesystem path.
+ *
+ * A value that is not a `file:` URI is returned unchanged: clients occasionally
+ * send a bare path where the protocol asks for a URI, and treating that as a
+ * path is friendlier than failing.
+ *
+ * @throws {TypeError} when the URI is malformed or names a remote host.
+ */
+export function fileUriToPath(uri: string): string {
+	return uri.startsWith("file://") ? fileURLToPath(uri) : uri;
+}
+
+/** Converts a filesystem path to a `file:` URI. */
+export function pathToFileUri(path: string): string {
+	return pathToFileURL(path).toString();
+}

package/proof/oracle/src/host/direct-settings.ts

@@ -0,0 +1,110 @@
+/**
+ * Direct `pi-ahp` listener settings, persisted at `~/.pi/ahp/settings.json`.
+ *
+ * Two file states, deliberately kept apart:
+ *
+ * - **No file.** Nothing can be defaulted usefully — a port has to be free and
+ *   a token has to be secret — so one of each is produced and written out. This
+ *   is the only time the host invents anything.
+ * - **A file exists.** It is taken literally. A missing `token` means no token,
+ *   a missing `port` is an error, and a value of the wrong shape is an error
+ *   rather than a silent substitution: a setting quietly replaced by something
+ *   the user did not write is worse than a refusal to start.
+ */
+
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export interface DirectListenerSettings {
+	port: number;
+	/** `null` disables the check; clients then connect without `?token=`. */
+	token: string | null;
+	/** Bind address. Keep on loopback unless clients connect from another machine. */
+	host: string;
+}
+
+const CONFIG_DIR_NAME = ".pi";
+const DEFAULT_HOST = "127.0.0.1";
+
+function getAhpDir(): string {
+	const configDir = process.env.PI_CONFIG_DIR || join(homedir(), CONFIG_DIR_NAME);
+	return join(configDir, "ahp");
+}
+
+function getSettingsPath(): string {
+	return process.env.PI_AHP_SETTINGS || join(getAhpDir(), "settings.json");
+}
+
+/** Asks the OS for a free port and immediately gives it back. */
+async function freePort(): Promise<number> {
+	const probe = createServer();
+	return new Promise<number>((resolve, reject) => {
+		probe.once("error", reject);
+		probe.listen(0, DEFAULT_HOST, () => {
+			const address = probe.address();
+			const port = typeof address === "object" && address ? address.port : 0;
+			probe.close(() => resolve(port));
+		});
+	});
+}
+
+export class SettingsError extends Error {
+	constructor(path: string, detail: string) {
+		super(`${path}: ${detail}`);
+		this.name = "SettingsError";
+	}
+}
+
+export async function loadDirectListenerSettings(path: string = getSettingsPath()): Promise<DirectListenerSettings> {
+	let raw: string;
+	try {
+		raw = readFileSync(path, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+			throw error;
+		}
+		const settings: DirectListenerSettings = {
+			port: await freePort(),
+			token: randomBytes(32).toString("base64url"),
+			host: DEFAULT_HOST,
+		};
+		writeSettings(settings, path);
+		return settings;
+	}
+
+	let stored: Record<string, unknown>;
+	try {
+		stored = JSON.parse(raw) as Record<string, unknown>;
+	} catch (error) {
+		throw new SettingsError(path, `not valid JSON (${(error as Error).message})`);
+	}
+
+	if (stored.port === undefined) {
+		throw new SettingsError(path, "no `port`. Set one, or delete the file to have it chosen.");
+	}
+	if (!Number.isInteger(stored.port) || (stored.port as number) < 1 || (stored.port as number) > 65535) {
+		throw new SettingsError(path, `\`port\` must be an integer 1-65535, got ${JSON.stringify(stored.port)}`);
+	}
+	if (stored.token !== undefined && stored.token !== null && typeof stored.token !== "string") {
+		throw new SettingsError(path, `\`token\` must be a string or null, got ${JSON.stringify(stored.token)}`);
+	}
+	if (stored.host !== undefined && typeof stored.host !== "string") {
+		throw new SettingsError(path, `\`host\` must be a string, got ${JSON.stringify(stored.host)}`);
+	}
+
+	return {
+		port: stored.port as number,
+		// Absent means absent. Only a missing *file* mints a token.
+		token: (stored.token as string | null | undefined) ?? null,
+		host: (stored.host as string | undefined) ?? DEFAULT_HOST,
+	};
+}
+
+function writeSettings(settings: DirectListenerSettings, path: string = getSettingsPath()): void {
+	mkdirSync(dirname(path), { recursive: true });
+	// Owner-only: the token is a bearer credential for the endpoint.
+	writeFileSync(path, `${JSON.stringify(settings, null, 2)}\n`, { mode: 0o600 });
+}

package/proof/oracle/src/host/pi-host.ts

@@ -0,0 +1,220 @@
+/**
+ * Assembles a fully wired host: root channel, session catalogue, and session
+ * lifecycle, all backed by pi.
+ */
+
+import { clampThinkingLevel } from "@earendil-works/pi-ai";
+import { createAgentSessionServices, type ModelRuntime, SettingsManager } from "@earendil-works/pi-coding-agent";
+import type { CreateSessionParams, ModelSelection, URI } from "@microsoft/agent-host-protocol";
+import { installRootChannel } from "../channels/root.ts";
+import { sessionUri } from "../core/channels.ts";
+import { AhpHost, type HostOptions } from "../core/host.ts";
+import { ChangesetService } from "../pi/changeset-service.ts";
+import { CompletionService, MENTION_TRIGGER } from "../pi/completions.ts";
+import { deleteSessionFile } from "../pi/delete-session.ts";
+import { InProcessPiBackend } from "../pi/in-process-backend.ts";
+import { buildAgentInfo, modelSelectionId, THINKING_CONFIG_KEY } from "../pi/models.ts";
+import { type ProjectTrustPolicy, resolveProjectTrust } from "../pi/project-trust.ts";
+import { ResourcePathPolicy } from "../pi/resource-paths.ts";
+import { ResourceService } from "../pi/resource-service.ts";
+import { ResourceWatchService } from "../pi/resource-watch.ts";
+import type { PiSessionCatalogue } from "../pi/session-catalogue.ts";
+import { SessionConfigService } from "../pi/session-config.ts";
+import { SessionHydrator } from "../pi/session-hydrator.ts";
+import { type BackendFactory, type SessionFileDeletionResult, SessionRegistry } from "../pi/session-registry.ts";
+import type { PiSessionStorage } from "../pi/session-storage.ts";
+import { TerminalService } from "./terminal-service.ts";
+
+export interface PiHostOptions extends HostOptions {
+	/** Working directory for sessions created without one. Defaults to `process.cwd()`. */
+	readonly workingDirectory?: string;
+	/** Injectable for tests; defaults to pi's real model runtime. */
+	readonly modelRuntime?: Pick<ModelRuntime, "getAvailable">;
+	/** Injectable for tests; defaults to checked trash-then-unlink deletion. */
+	readonly deleteFile?: (path: string) => SessionFileDeletionResult | Promise<SessionFileDeletionResult>;
+	/** Injectable for tests; defaults to an in-process `AgentSession`. */
+	readonly createBackend?: BackendFactory;
+	/** Explicit storage boundary; tests cannot accidentally fall back to user data. */
+	readonly sessionStorage: PiSessionStorage;
+	/**
+	 * How to treat trust-gated pi resources in a session's working directory.
+	 *
+	 * Defaults to `trust`, matching the pi SDK default. Switch to `inherit` when
+	 * the host is reachable from outside its own trust domain: the working
+	 * directory then arrives from a client, and `inherit` will only load project
+	 * resources the user already approved through pi's CLI.
+	 */
+	readonly projectTrustPolicy?: ProjectTrustPolicy;
+	/**
+	 * Directories the resource commands and watches may reach. Empty means
+	 * unrestricted. See `src/pi/resource-paths.ts` for why that is the default.
+	 */
+	readonly resourceRoots?: readonly string[];
+}
+
+export interface PiHost {
+	readonly host: AhpHost;
+	readonly sessions: SessionRegistry;
+	readonly catalogue: PiSessionCatalogue;
+	readonly changesets: ChangesetService;
+	readonly watches: ResourceWatchService;
+	readonly terminals: { shutdown(): void };
+}
+
+/**
+ * Builds the host and registers every supported channel. The model list is a
+ * startup snapshot; dynamic refresh would require publishing
+ * `root/agentsChanged` and is not implemented.
+ */
+export async function createPiHost(options: PiHostOptions): Promise<PiHost> {
+	const workingDirectory = options.workingDirectory ?? process.cwd();
+	const host = new AhpHost({
+		...options,
+		// `@` is the only trigger this host can answer: every completion item
+		// must carry an attachment, and pi's `/` commands attach nothing.
+		completionTriggerCharacters: options.completionTriggerCharacters ?? [MENTION_TRIGGER],
+	});
+
+	let modelRuntime: Pick<ModelRuntime, "getAvailable">;
+	let settingsManager: SettingsManager | undefined;
+	if (options.modelRuntime) {
+		modelRuntime = options.modelRuntime;
+	} else {
+		// Package extensions can register providers; the bare ModelRuntime cannot
+		// see them until the standard service loader flushes those registrations.
+		const trust = resolveProjectTrust(workingDirectory, options.projectTrustPolicy);
+		const services = await createAgentSessionServices({
+			cwd: workingDirectory,
+			settingsManager: SettingsManager.create(workingDirectory, undefined, { projectTrusted: trust.trusted }),
+		});
+		modelRuntime = services.modelRuntime;
+		settingsManager = services.settingsManager;
+		for (const diagnostic of services.diagnostics) {
+			options.log?.(`[pi models] ${diagnostic.type}: ${diagnostic.message}`);
+		}
+	}
+	// A user with no configured provider still gets a usable host — they just
+	// see an agent with no models, which is the honest representation.
+	const models = await modelRuntime.getAvailable().catch(() => []);
+	installRootChannel(host, [buildAgentInfo(models as never)]);
+
+	const configuredProvider = settingsManager?.getDefaultProvider();
+	const configuredId = settingsManager?.getDefaultModel();
+	const configured = models.find((model) => model.provider === configuredProvider && model.id === configuredId);
+	const fallback = configured ?? models[0];
+	const fallbackThinking = fallback
+		? clampThinkingLevel(fallback, configured ? (settingsManager?.getDefaultThinkingLevel() ?? "medium") : "medium")
+		: undefined;
+	const fallbackSelection = (): ModelSelection | undefined =>
+		fallback && fallbackThinking
+			? { id: modelSelectionId(fallback), config: { [THINKING_CONFIG_KEY]: fallbackThinking } }
+			: undefined;
+
+	const catalogue = options.sessionStorage.catalogue;
+	const resourcePaths = new ResourcePathPolicy(options.resourceRoots);
+	const watches = new ResourceWatchService(host, {
+		pathPolicy: resourcePaths,
+		...(options.log ? { log: options.log } : {}),
+	});
+	const terminals = new TerminalService(host, {
+		defaultWorkingDirectory: workingDirectory,
+		...(options.log ? { log: options.log } : {}),
+	});
+
+	const createBackend: BackendFactory =
+		options.createBackend ??
+		((session) =>
+			InProcessPiBackend.create({
+				cwd: session.workingDirectory,
+				sessionManager: session.sessionManager,
+				...(options.projectTrustPolicy ? { projectTrustPolicy: options.projectTrustPolicy } : {}),
+			}));
+
+	const sessions = new SessionRegistry({
+		host,
+		defaultWorkingDirectory: workingDirectory,
+		createBackend,
+		createSessionManager: options.sessionStorage.createSessionManager,
+		defaultSelection: fallbackSelection,
+		deleteFile: options.deleteFile ?? deleteSessionFile,
+		findSessionFile: (id) => catalogue.findSessionFile(id),
+		...(options.log ? { log: options.log } : {}),
+	});
+	const sessionHydrator = new SessionHydrator({
+		host,
+		catalogue,
+		isLive: (session) => sessions.has(session),
+		isDisposing: (session) => sessions.isDisposing(session),
+		// Adopted without a backend; one starts on the first turn.
+		adopt: (session) => void sessions.adopt(session),
+		fallbackSelection,
+		...(options.log ? { log: options.log } : {}),
+	});
+	const changesets = new ChangesetService(host, {
+		getSession: (sessionId) => sessions.get(sessionUri(sessionId)),
+		getSessionByChat: (chat) => sessions.getByChat(chat),
+		hydrateSession: async (sessionId) => {
+			await sessionHydrator.hydrate(sessionUri(sessionId));
+			return sessions.get(sessionUri(sessionId));
+		},
+		onSessionAvailable: (listener) => sessions.onSessionAvailable(listener),
+		onSessionDeletionCommitted: (listener) => sessions.onSessionDeletionCommitted(listener),
+		authorizeResource: async (uri) => {
+			await resourcePaths.pathFor(uri);
+		},
+		...(options.log ? { log: options.log } : {}),
+	});
+	const resources = new ResourceService({
+		pathPolicy: resourcePaths,
+		readVirtual: (params) => changesets.readResource(params),
+	});
+
+	host.serve({
+		catalogue: {
+			list: (limit, cursor) => catalogue.list(limit, cursor, () => sessions.catalogueOverrides()),
+		},
+		resources,
+		resourceWatches: watches,
+		terminals,
+		sessionConfig: new SessionConfigService({
+			defaultWorkingDirectory: workingDirectory,
+			...(options.projectTrustPolicy ? { projectTrustPolicy: options.projectTrustPolicy } : {}),
+		}),
+		completions: new CompletionService({
+			// Mentions resolve against the chat's own directory, which is the
+			// session's working directory for the single chat this host serves.
+			workingDirectoryFor: (chat) => sessions.getByChat(chat)?.workingDirectory,
+		}),
+		turnPaging: {
+			async fetchTurns(params) {
+				await sessions.fetchTurns(params.channel, params.cursor);
+				return {};
+			},
+		},
+		sessions: {
+			create(params: CreateSessionParams): void {
+				// The registry's narrower structural type makes the unsupported optional
+				// fields explicit: config, activeClient, and progressToken are ignored.
+				sessions.create(params);
+			},
+			async dispose(channel: URI): Promise<void> {
+				const sessionId = sessions.get(channel)?.sessionId;
+				if (sessionId) await changesets.suspendSession(sessionId);
+				try {
+					await sessions.dispose(channel);
+				} catch (error) {
+					if (sessionId) changesets.resumeSession(sessionId);
+					throw error;
+				}
+			},
+		},
+		// Both session/chat and their advertised changesets survive host restarts.
+		hydrator: {
+			async hydrate(channel) {
+				return (await changesets.hydrate(channel)) || sessionHydrator.hydrate(channel);
+			},
+		},
+	});
+
+	return { host, sessions, catalogue, changesets, watches, terminals };
+}

package/proof/oracle/src/host/serve.ts

@@ -0,0 +1,71 @@
+/** Shared host construction; each entry point owns its endpoint and authentication policy. */
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { pathToFileUri } from "../core/uri.ts";
+import { createDefaultPiSessionStorage } from "../pi/session-storage.ts";
+import { type RunningServer, serveWebSocket } from "../transport/websocket.ts";
+import { createPiHost } from "./pi-host.ts";
+
+/**
+ * Read from the manifest rather than restated here.
+ *
+ * The name and version go out in `serverInfo` during the handshake, so a copy
+ * that drifts from the package tells clients something untrue about what they
+ * are connected to. Resolved relative to this file, which keeps working when
+ * the package is installed somewhere else.
+ */
+const manifest = JSON.parse(
+	readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json"), "utf8"),
+) as { name: string; version: string };
+
+export const NAME = manifest.name;
+export const VERSION = manifest.version;
+
+export interface ServeOptions {
+	readonly host: string;
+	readonly port: number;
+	/** Absent or empty disables the WebSocket upgrade credential. */
+	readonly connectionToken?: string | undefined;
+	readonly workingDirectory: string;
+	readonly log?: ((message: string) => void) | undefined;
+}
+
+export async function startHost(options: ServeOptions): Promise<RunningServer> {
+	const {
+		host: ahpHost,
+		changesets,
+		terminals,
+		watches,
+	} = await createPiHost({
+		serverInfo: { name: NAME, version: VERSION },
+		defaultDirectory: pathToFileUri(options.workingDirectory),
+		workingDirectory: options.workingDirectory,
+		sessionStorage: createDefaultPiSessionStorage(),
+		...(options.log ? { log: options.log } : {}),
+	});
+
+	const server = await serveWebSocket(ahpHost, {
+		host: options.host,
+		port: options.port,
+		...(options.connectionToken ? { connectionToken: options.connectionToken } : {}),
+		...(options.log ? { log: options.log } : {}),
+	});
+	return {
+		...server,
+		async close() {
+			terminals.shutdown();
+			await Promise.all([server.close(), changesets.dispose(), watches.dispose()]);
+		},
+	};
+}
+
+/** Closes `server` on SIGINT/SIGTERM. */
+export function closeOnSignal(server: RunningServer): void {
+	const shutdown = (): void => {
+		void server.close().then(() => process.exit(0));
+	};
+	process.on("SIGINT", shutdown);
+	process.on("SIGTERM", shutdown);
+}