pi-remote-control 1.0.0

package/src/runtime-status.ts

@@ -0,0 +1,116 @@
+import type { RuntimeStatus } from "./types.js";
+
+const THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high", "xhigh"]);
+
+type RuntimeStatusUsage = RuntimeStatus["usage"];
+
+export function collectRuntimeStatus(pi: unknown, ctx: unknown, now: () => Date = () => new Date()): RuntimeStatus {
+  const context = asRecord(ctx);
+  return {
+    model: collectModel(context.model),
+    thinkingLevel: collectThinkingLevel(pi),
+    usage: collectUsage(readSessionEntries(context)),
+    context: collectContextUsage(callMethod(context, "getContextUsage")),
+    updatedAt: now().toISOString(),
+  };
+}
+
+function collectModel(value: unknown): RuntimeStatus["model"] {
+  const model = asRecord(value);
+  const provider = readString(model.provider);
+  const id = readString(model.id) ?? readString(model.model);
+  if (!provider || !id) return null;
+  return withoutUndefined({
+    provider,
+    id,
+    name: readString(model.name),
+    contextWindow: readNumber(model.contextWindow) ?? readNumber(model.context_window),
+    maxTokens: readNumber(model.maxTokens) ?? readNumber(model.max_tokens),
+    reasoning: readBoolean(model.reasoning),
+  });
+}
+
+function collectThinkingLevel(pi: unknown): RuntimeStatus["thinkingLevel"] {
+  const level = callMethod(asRecord(pi), "getThinkingLevel");
+  return typeof level === "string" && THINKING_LEVELS.has(level) ? level as RuntimeStatus["thinkingLevel"] : null;
+}
+
+function collectContextUsage(value: unknown): RuntimeStatus["context"] {
+  const usage = asRecord(value);
+  const contextWindow = readNumber(usage.contextWindow) ?? readNumber(usage.context_window) ?? readNumber(usage.maxTokens) ?? readNumber(usage.max_tokens);
+  if (contextWindow === undefined) return null;
+  const tokens = readNumber(usage.tokens) ?? readNumber(usage.currentTokens) ?? readNumber(usage.current_tokens);
+  const percent = readNumber(usage.percent) ?? readNumber(usage.percentage);
+  return {
+    tokens: tokens ?? null,
+    contextWindow,
+    percent: percent ?? null,
+  };
+}
+
+function collectUsage(entries: unknown[]): RuntimeStatusUsage {
+  const usage: RuntimeStatusUsage = {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  };
+
+  for (const entry of entries) {
+    const record = asRecord(entry);
+    const message = asRecord(record.message);
+    if (message.role !== "assistant" && record.role !== "assistant") continue;
+    const entryUsage = asRecord(record.usage ?? message.usage);
+    usage.input += readNumber(entryUsage.input) ?? 0;
+    usage.output += readNumber(entryUsage.output) ?? 0;
+    usage.cacheRead += readNumber(entryUsage.cacheRead) ?? readNumber(entryUsage.cache_read) ?? 0;
+    usage.cacheWrite += readNumber(entryUsage.cacheWrite) ?? readNumber(entryUsage.cache_write) ?? 0;
+
+    const cost = asRecord(entryUsage.cost);
+    usage.cost.input += readNumber(cost.input) ?? 0;
+    usage.cost.output += readNumber(cost.output) ?? 0;
+    usage.cost.cacheRead += readNumber(cost.cacheRead) ?? readNumber(cost.cache_read) ?? 0;
+    usage.cost.cacheWrite += readNumber(cost.cacheWrite) ?? readNumber(cost.cache_write) ?? 0;
+    usage.cost.total += readNumber(cost.total) ?? 0;
+  }
+
+  usage.cost.total = usage.cost.total || usage.cost.input + usage.cost.output + usage.cost.cacheRead + usage.cost.cacheWrite;
+  return usage;
+}
+
+function readSessionEntries(context: Record<string, unknown>): unknown[] {
+  const sessionManager = asRecord(context.sessionManager);
+  const entries = callMethod(sessionManager, "getEntries");
+  return Array.isArray(entries) ? entries : [];
+}
+
+function callMethod(record: Record<string, unknown>, key: string): unknown {
+  const value = record[key];
+  if (typeof value !== "function") return undefined;
+  try {
+    return (value as () => unknown).call(record);
+  } catch {
+    return undefined;
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" ? value as Record<string, unknown> : {};
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function readNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function readBoolean(value: unknown): boolean | undefined {
+  return typeof value === "boolean" ? value : undefined;
+}
+
+function withoutUndefined<T extends Record<string, unknown>>(value: T): T {
+  return Object.fromEntries(Object.entries(value).filter(([, entryValue]) => entryValue !== undefined)) as T;
+}

package/src/server/http.ts

@@ -0,0 +1,529 @@
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import type { Duplex } from "node:stream";
+import { WebSocket, WebSocketServer } from "ws";
+import type { ActiveSessionRegistry } from "../active-session-registry.js";
+import {
+  DEFAULT_TRANSCRIPT_PAGE_LIMIT,
+  decodeTranscriptCursor,
+  InvalidTranscriptCursorError,
+  MAX_TRANSCRIPT_PAGE_LIMIT,
+  type TranscriptPage,
+} from "../transcript-pagination.js";
+import { INITIAL_WEBSOCKET_SESSION_MESSAGE_LIMIT, previewInitialSessionState } from "../transcript-preview.js";
+import { normalizeTuiEvent } from "../transcript-stream.js";
+import type { DaemonConfig, RemoteCompactResultEvent, RuntimeStatus } from "../types.js";
+
+export type RemoteSessionSummary = {
+  id: string;
+  piSessionId: string;
+  projectId: string;
+  name: string | null;
+  path: string;
+  updatedAt: string;
+  messageCount: number;
+};
+
+export type RemoteSessionState = {
+  session: unknown;
+  messages: unknown[];
+  olderMessagesCursor: string | null;
+  hasOlderMessages: boolean;
+  tools: unknown[];
+  isStreaming: boolean;
+  pendingMessageCount: number;
+  runtimeStatus?: unknown;
+};
+
+export type PromptSessionRequest = {
+  text: string;
+  streamingBehavior?: "steer" | "followUp" | null;
+};
+
+export type SessionService = {
+  listProjectSessions?(projectId: string): Promise<RemoteSessionSummary[]>;
+  createProjectSession?(projectId: string): Promise<RemoteSessionSummary>;
+  getSessionState?(sessionId: string, options?: { messageLimit: number }): Promise<RemoteSessionState>;
+  getSessionMessages?(sessionId: string, request: { before: string; limit: number }): Promise<TranscriptPage>;
+  promptSession?(sessionId: string, request: PromptSessionRequest): Promise<void>;
+  abortSession?(sessionId: string): Promise<void>;
+  compactSession?(sessionId: string): Promise<void>;
+  streamSession?(sessionId: string, send: (event: unknown) => void): Promise<void>;
+};
+
+export type DaemonServer = {
+  address: string;
+  close(): Promise<void>;
+};
+
+export type PairClaimRequest = {
+  pairCode: string;
+  deviceName: string;
+};
+
+export type PairClaimResponse = {
+  deviceId: string;
+  token: string;
+  daemonName: string;
+};
+
+export type PairCodeResponse = {
+  pairCode: string;
+  expiresAt: string;
+};
+
+export type PairService = {
+  createPairingCode?(): Promise<PairCodeResponse>;
+  claimPairingCode(request: PairClaimRequest): Promise<PairClaimResponse>;
+};
+
+export type StartServerOptions = {
+  stateDir: string;
+  config: DaemonConfig;
+  piVersion?: string;
+  daemonVersion?: string;
+  authenticateToken?: (token: string) => boolean | Promise<boolean>;
+  sessionService?: SessionService;
+  activeSessions?: ActiveSessionRegistry;
+  pairService?: PairService;
+  sessionSweepIntervalMs?: number;
+};
+
+const DEFAULT_SESSION_SWEEP_INTERVAL_MS = 1_000;
+
+type StreamHub = Map<string, Set<WebSocket>>;
+
+export function bindAddressesForConfig(bindAddress: string): string[] {
+  const { host, port } = parseBindAddress(bindAddress);
+  if (isLoopbackHost(host) || isWildcardHost(host)) return [bindAddress];
+  return [bindAddress, `127.0.0.1:${port}`];
+}
+
+export async function startDaemonServer(options: StartServerOptions): Promise<DaemonServer> {
+  const streamHub: StreamHub = new Map();
+  const webSockets = new WebSocketServer({ noServer: true });
+  const servers = bindAddressesForConfig(options.config.bindAddress).map(() => createHttpServer(options, streamHub, webSockets));
+  const bindAddresses = bindAddressesForConfig(options.config.bindAddress);
+  const sweepTimer = options.activeSessions
+    ? setInterval(() => closeSessions(options.activeSessions!.pruneInactiveSessions(), streamHub), options.sessionSweepIntervalMs ?? DEFAULT_SESSION_SWEEP_INTERVAL_MS)
+    : undefined;
+  sweepTimer?.unref?.();
+
+  for (let index = 0; index < servers.length; index += 1) {
+    const { host, port } = parseBindAddress(bindAddresses[index] ?? options.config.bindAddress);
+    await listen(servers[index]!, host, port);
+  }
+
+  const address = servers[0]!.address() as AddressInfo;
+  return {
+    address: `${address.address}:${address.port}`,
+    close: async () => {
+      if (sweepTimer) clearInterval(sweepTimer);
+      webSockets.close();
+      await Promise.all(servers.map((server) => closeServer(server)));
+    },
+  };
+}
+
+function createHttpServer(options: StartServerOptions, streamHub: StreamHub, webSockets: WebSocketServer): Server {
+  const server = createServer((request, response) => {
+    void handleHttpRequest(request, response, options, streamHub);
+  });
+  server.on("upgrade", (request, socket, head) => {
+    void handleUpgrade(request, socket, head, webSockets, options, streamHub);
+  });
+  return server;
+}
+
+async function listen(server: Server, host: string, port: number): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+}
+
+async function closeServer(server: Server): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    server.close((error) => (error ? reject(error) : resolve()));
+  });
+}
+
+async function handleHttpRequest(
+  request: IncomingMessage,
+  response: ServerResponse,
+  options: StartServerOptions,
+  streamHub: StreamHub,
+): Promise<void> {
+  const url = new URL(request.url ?? "/", "http://localhost");
+  const pathname = url.pathname;
+
+  if (request.method === "GET" && pathname === "/v1/health") {
+    writeJson(response, 200, {
+      status: "ok",
+      piVersion: options.piVersion ?? "unknown",
+      daemonVersion: options.daemonVersion ?? "1.0.0",
+    });
+    return;
+  }
+
+  if (request.method === "POST" && pathname === "/v1/tui/sessions") {
+    if (!(await isTuiAuthorized(request, options))) {
+      writeJson(response, 401, { error: "unauthorized" });
+      return;
+    }
+    const body = (await readJsonBody(request)) as Parameters<ActiveSessionRegistry["registerSession"]>[0];
+    const session = options.activeSessions?.registerSession(body);
+    writeJson(response, session ? 200 : 503, session ? { session } : { error: "active_sessions_unavailable" });
+    return;
+  }
+
+  const tuiSessionMatch = pathname.match(/^\/v1\/tui\/sessions\/([^/]+)$/);
+  if (request.method === "DELETE" && tuiSessionMatch) {
+    if (!(await isTuiAuthorized(request, options))) {
+      writeJson(response, 401, { error: "unauthorized" });
+      return;
+    }
+    const sessionId = decodeURIComponent(tuiSessionMatch[1] ?? "");
+    const unregistered = options.activeSessions?.unregisterSession(sessionId) ?? false;
+    if (unregistered) closeSessions([sessionId], streamHub);
+    writeJson(response, 200, { unregistered });
+    return;
+  }
+
+  const tuiCommandsMatch = pathname.match(/^\/v1\/tui\/sessions\/([^/]+)\/commands$/);
+  if (request.method === "GET" && tuiCommandsMatch) {
+    if (!(await isTuiAuthorized(request, options))) {
+      writeJson(response, 401, { error: "unauthorized" });
+      return;
+    }
+    const sessionId = decodeURIComponent(tuiCommandsMatch[1] ?? "");
+    if (options.activeSessions && !options.activeSessions.touchSession(sessionId)) {
+      writeJson(response, 404, { error: "session_not_found" });
+      return;
+    }
+    writeJson(response, 200, { commands: options.activeSessions?.takeCommands(sessionId) ?? [] });
+    return;
+  }
+
+  const tuiEventMatch = pathname.match(/^\/v1\/tui\/sessions\/([^/]+)\/events$/);
+  if (request.method === "POST" && tuiEventMatch) {
+    if (!(await isTuiAuthorized(request, options))) {
+      writeJson(response, 401, { error: "unauthorized" });
+      return;
+    }
+    const sessionId = decodeURIComponent(tuiEventMatch[1] ?? "");
+    if (options.activeSessions && !options.activeSessions.touchSession(sessionId)) {
+      writeJson(response, 404, { error: "session_not_found" });
+      return;
+    }
+    const event = await readJsonBody(request);
+    if (isRuntimeStatusEvent(event)) {
+      const changed = options.activeSessions?.updateRuntimeStatus(sessionId, event.status) ?? false;
+      if (changed) streamHub.get(sessionId)?.forEach((webSocket) => sendWebSocketJson(webSocket, { type: "runtime_status", status: event.status }));
+      writeJson(response, 200, { accepted: true });
+      return;
+    }
+    if (isRemoteCompactResultEvent(event)) {
+      streamHub.get(sessionId)?.forEach((webSocket) => sendWebSocketJson(webSocket, event));
+      writeJson(response, 200, { accepted: true });
+      return;
+    }
+    const normalizedEvents = normalizeTuiEvent(event);
+    streamHub.get(sessionId)?.forEach((webSocket) => normalizedEvents.forEach((normalizedEvent) => sendWebSocketJson(webSocket, normalizedEvent)));
+    writeJson(response, 200, { accepted: true });
+    return;
+  }
+
+  if (request.method === "POST" && pathname === "/v1/pair/claim") {
+    try {
+      const body = (await readJsonBody(request)) as PairClaimRequest;
+      const result = await options.pairService?.claimPairingCode(body);
+      writeJson(response, 200, result ?? { error: "pairing_unavailable" });
+    } catch (error) {
+      if (error instanceof Error && error.message === "Invalid or expired pairing code") {
+        writeJson(response, 400, { error: "invalid_pairing_code" });
+      } else {
+        writeJson(response, 500, { error: "internal_error" });
+      }
+    }
+    return;
+  }
+
+  if (request.method === "GET" && pathname === "/v1/projects") {
+    if (!(await isAuthorized(request, options))) {
+      writeJson(response, 401, { error: "unauthorized" });
+      return;
+    }
+
+    writeJson(response, 200, { projects: options.activeSessions?.listProjects() ?? [] });
+    return;
+  }
+
+  const abortMatch = pathname.match(/^\/v1\/sessions\/([^/]+)\/abort$/);
+  if (request.method === "POST" && abortMatch) {
+    if (!(await isAuthorized(request, options))) {
+      writeJson(response, 401, { error: "unauthorized" });
+      return;
+    }
+
+    const sessionId = decodeURIComponent(abortMatch[1] ?? "");
+    if (options.activeSessions) {
+      if (!options.activeSessions.enqueueCommand(sessionId, { type: "remote_abort", requestId: nextRequestId() })) {
+        writeJson(response, 409, { error: "session_not_active" });
+        return;
+      }
+    } else {
+      await options.sessionService?.abortSession?.(sessionId);
+    }
+    writeJson(response, 200, { aborted: true });
+    return;
+  }
+
+  const compactMatch = pathname.match(/^\/v1\/sessions\/([^/]+)\/compact$/);
+  if (request.method === "POST" && compactMatch) {
+    if (!(await isAuthorized(request, options))) {
+      writeJson(response, 401, { error: "unauthorized" });
+      return;
+    }
+
+    const sessionId = decodeURIComponent(compactMatch[1] ?? "");
+    const requestId = nextRequestId();
+    if (options.activeSessions) {
+      if (!options.activeSessions.enqueueCommand(sessionId, { type: "remote_compact", requestId })) {
+        writeJson(response, 409, { error: "session_not_active" });
+        return;
+      }
+    } else {
+      await options.sessionService?.compactSession?.(sessionId);
+    }
+    writeJson(response, 200, { accepted: true, requestId });
+    return;
+  }
+
+  const promptMatch = pathname.match(/^\/v1\/sessions\/([^/]+)\/prompt$/);
+  if (request.method === "POST" && promptMatch) {
+    if (!(await isAuthorized(request, options))) {
+      writeJson(response, 401, { error: "unauthorized" });
+      return;
+    }
+
+    const sessionId = decodeURIComponent(promptMatch[1] ?? "");
+    const body = (await readJsonBody(request)) as PromptSessionRequest;
+    if (options.activeSessions) {
+      if (!options.activeSessions.enqueueCommand(sessionId, {
+        type: "remote_prompt",
+        requestId: nextRequestId(),
+        text: body.text,
+        streamingBehavior: body.streamingBehavior,
+      })) {
+        writeJson(response, 409, { error: "session_not_active" });
+        return;
+      }
+    } else {
+      await options.sessionService?.promptSession?.(sessionId, body);
+    }
+    writeJson(response, 200, { accepted: true });
+    return;
+  }
+
+  const sessionMessagesMatch = pathname.match(/^\/v1\/sessions\/([^/]+)\/messages$/);
+  if (request.method === "GET" && sessionMessagesMatch) {
+    if (!(await isAuthorized(request, options))) {
+      writeJson(response, 401, { error: "unauthorized" });
+      return;
+    }
+
+    const limit = parsePositiveLimit(url.searchParams.get("limit"));
+    if (!limit.valid) {
+      writeJson(response, 400, { error: "invalid_limit" });
+      return;
+    }
+    const before = url.searchParams.get("before");
+    if (!before) {
+      writeJson(response, 400, { error: "invalid_cursor" });
+      return;
+    }
+
+    try {
+      decodeTranscriptCursor(before);
+      const sessionId = decodeURIComponent(sessionMessagesMatch[1] ?? "");
+      const page = options.activeSessions?.getSessionMessages(sessionId, before, { limit: limit.value })
+        ?? (await options.sessionService?.getSessionMessages?.(sessionId, { before, limit: limit.value }));
+      if (!page) {
+        writeJson(response, 404, { error: "session_not_found" });
+        return;
+      }
+      writeJson(response, 200, page);
+    } catch (error) {
+      if (error instanceof InvalidTranscriptCursorError) writeJson(response, 400, { error: "invalid_cursor" });
+      else writeJson(response, 500, { error: "internal_error" });
+    }
+    return;
+  }
+
+  const sessionMatch = pathname.match(/^\/v1\/sessions\/([^/]+)$/);
+  if (request.method === "GET" && sessionMatch) {
+    if (!(await isAuthorized(request, options))) {
+      writeJson(response, 401, { error: "unauthorized" });
+      return;
+    }
+
+    const limit = parsePositiveLimit(url.searchParams.get("messageLimit"));
+    if (!limit.valid) {
+      writeJson(response, 400, { error: "invalid_limit" });
+      return;
+    }
+
+    const sessionId = decodeURIComponent(sessionMatch[1] ?? "");
+    const state = options.activeSessions?.getSessionState(sessionId, { messageLimit: limit.value })
+      ?? (await options.sessionService?.getSessionState?.(sessionId, { messageLimit: limit.value }));
+    if (!state) {
+      writeJson(response, 404, { error: "session_not_found" });
+      return;
+    }
+    writeJson(response, 200, state);
+    return;
+  }
+
+  const projectSessionsMatch = pathname.match(/^\/v1\/projects\/([^/]+)\/sessions$/);
+  if ((request.method === "GET" || request.method === "POST") && projectSessionsMatch) {
+    if (!(await isAuthorized(request, options))) {
+      writeJson(response, 401, { error: "unauthorized" });
+      return;
+    }
+
+    const projectId = decodeURIComponent(projectSessionsMatch[1] ?? "");
+    if (request.method === "POST") {
+      writeJson(response, 405, { error: "method_not_allowed" });
+      return;
+    }
+
+    const sessions = options.activeSessions?.listProjectSessions(projectId) ?? (await options.sessionService?.listProjectSessions?.(projectId));
+    writeJson(response, 200, { sessions: sessions ?? [] });
+    return;
+  }
+
+  writeJson(response, 404, { error: "not_found" });
+}
+
+async function handleUpgrade(
+  request: IncomingMessage,
+  socket: Duplex,
+  head: Buffer,
+  webSockets: WebSocketServer,
+  options: StartServerOptions,
+  streamHub: StreamHub,
+): Promise<void> {
+  const url = new URL(request.url ?? "/", "http://localhost");
+  const streamMatch = url.pathname.match(/^\/v1\/sessions\/([^/]+)\/stream$/);
+  if (!streamMatch) {
+    socket.write("HTTP/1.1 404 Not Found\r\n\r\n");
+    socket.destroy();
+    return;
+  }
+
+  if (!(await isAuthorized(request, options))) {
+    socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
+    socket.destroy();
+    return;
+  }
+
+  const sessionId = decodeURIComponent(streamMatch[1] ?? "");
+  webSockets.handleUpgrade(request, socket, head, (webSocket) => {
+    webSockets.emit("connection", webSocket, request);
+    const subscribers = streamHub.get(sessionId) ?? new Set<WebSocket>();
+    subscribers.add(webSocket);
+    streamHub.set(sessionId, subscribers);
+    webSocket.once("close", () => subscribers.delete(webSocket));
+
+    const activeState = options.activeSessions?.getSessionState(sessionId, { messageLimit: INITIAL_WEBSOCKET_SESSION_MESSAGE_LIMIT });
+    if (activeState) sendWebSocketJson(webSocket, { type: "session_state", state: previewInitialSessionState(activeState) });
+
+    void options.sessionService?.streamSession?.(sessionId, (event) => {
+      sendWebSocketJson(webSocket, event);
+    });
+  });
+}
+
+async function isTuiAuthorized(request: IncomingMessage, options: StartServerOptions): Promise<boolean> {
+  if (isLoopbackRemoteAddress(request.socket.remoteAddress)) return true;
+  return isAuthorized(request, options);
+}
+
+async function isAuthorized(request: IncomingMessage, options: StartServerOptions): Promise<boolean> {
+  const authorization = request.headers.authorization;
+  if (!authorization?.startsWith("Bearer ")) return false;
+  const token = authorization.slice("Bearer ".length);
+  return options.authenticateToken ? Boolean(await options.authenticateToken(token)) : false;
+}
+
+function isLoopbackRemoteAddress(address: string | undefined): boolean {
+  return Boolean(address && (address === "::1" || address === "127.0.0.1" || address.startsWith("127.") || address.startsWith("::ffff:127.")));
+}
+
+function isRuntimeStatusEvent(event: unknown): event is { type: "runtime_status"; status: RuntimeStatus } {
+  return Boolean(event && typeof event === "object" && (event as { type?: unknown }).type === "runtime_status" && (event as { status?: unknown }).status && typeof (event as { status?: unknown }).status === "object");
+}
+
+function isRemoteCompactResultEvent(event: unknown): event is RemoteCompactResultEvent {
+  if (!event || typeof event !== "object") return false;
+  const record = event as Record<string, unknown>;
+  if (record.type !== "remote_compact_result" || typeof record.requestId !== "string") return false;
+  if (record.ok === true) {
+    return typeof record.summary === "string" && typeof record.firstKeptEntryId === "string" && typeof record.tokensBefore === "number";
+  }
+  return record.ok === false && typeof record.message === "string";
+}
+
+function nextRequestId(): string {
+  return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function parsePositiveLimit(rawLimit: string | null): { valid: true; value: number } | { valid: false } {
+  if (rawLimit === null) return { valid: true, value: DEFAULT_TRANSCRIPT_PAGE_LIMIT };
+  const parsed = Number(rawLimit);
+  if (!Number.isInteger(parsed) || parsed <= 0) return { valid: false };
+  return { valid: true, value: Math.min(parsed, MAX_TRANSCRIPT_PAGE_LIMIT) };
+}
+
+function parseBindAddress(bindAddress: string): { host: string; port: number } {
+  const index = bindAddress.lastIndexOf(":");
+  if (index === -1) throw new Error(`Invalid bind address: ${bindAddress}`);
+  return {
+    host: bindAddress.slice(0, index),
+    port: Number.parseInt(bindAddress.slice(index + 1), 10),
+  };
+}
+
+function isLoopbackHost(host: string): boolean {
+  return host === "localhost" || host === "::1" || host === "[::1]" || host === "127.0.0.1" || host.startsWith("127.");
+}
+
+function isWildcardHost(host: string): boolean {
+  return host === "0.0.0.0" || host === "::" || host === "[::]" || host === "";
+}
+
+async function readJsonBody(request: IncomingMessage): Promise<unknown> {
+  let body = "";
+  for await (const chunk of request) body += String(chunk);
+  return body ? JSON.parse(body) : {};
+}
+
+function writeJson(response: ServerResponse, status: number, body: unknown): void {
+  response.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+  response.end(JSON.stringify(body));
+}
+
+function closeSessions(sessionIds: string[], streamHub: StreamHub): void {
+  for (const sessionId of sessionIds) {
+    streamHub.get(sessionId)?.forEach((webSocket) => sendWebSocketJson(webSocket, { type: "session_closed" }));
+    streamHub.delete(sessionId);
+  }
+}
+
+function sendWebSocketJson(webSocket: WebSocket, event: unknown): void {
+  if (webSocket.readyState === WebSocket.OPEN) webSocket.send(JSON.stringify(event));
+}

package/src/session-index.ts

@@ -0,0 +1,9 @@
+import { createHash } from "node:crypto";
+
+export function projectIdForPath(projectPath: string): string {
+  return `proj_${stableHexId(projectPath)}`;
+}
+
+function stableHexId(input: string): string {
+  return createHash("sha256").update(input).digest("hex").slice(0, 16);
+}

package/src/session-transcript.ts

@@ -0,0 +1,34 @@
+import { readFileSync } from "node:fs";
+import { asRecord, readString, transcriptMessageFromPiMessage } from "./transcript-message.js";
+import type { TranscriptMessage } from "./types.js";
+
+export function readSessionTranscriptMessages(sessionFile: string): TranscriptMessage[] {
+  let text: string;
+  try {
+    text = readFileSync(sessionFile, "utf8");
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return [];
+    throw error;
+  }
+
+  return text.split(/\r?\n/u).flatMap((line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return [];
+    try {
+      return messagesFromEntry(JSON.parse(trimmed));
+    } catch {
+      return [];
+    }
+  });
+}
+
+function messagesFromEntry(entry: unknown): TranscriptMessage[] {
+  const record = asRecord(entry);
+  if (record.type !== "message") return [];
+  return transcriptMessageFromPiMessage({
+    id: readString(record.id),
+    timestamp: readString(record.timestamp),
+    message: record.message,
+    isStreaming: false,
+  });
+}