@agimon-ai/doompi-web 0.0.1-alpha.0

package/src/adapters/webPluginScan.ts

@@ -0,0 +1,62 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  type DeclaredWebPlugin,
+  declaredPluginsOf,
+  orderDeclaredPlugins,
+  WebPluginManifestError,
+} from '../services/webPluginManifest.ts';
+
+/**
+ * Reads doompiWeb declarations from explicit package roots.
+ *
+ * No workspace walking and no hardcoded plugin names: the caller says which
+ * packages are in play. At doompi-web's own build time that is just the host
+ * package (its built-in plugins); at `doompi sync` time it is the installed
+ * composition's package roots. A plugin package whose manifest is malformed
+ * or whose entry file is missing is skipped with a notice, so one broken or
+ * half-installed package never costs the rest of the cockpit; only the host's
+ * own manifest still throws, because that is a build error of this package.
+ */
+export function scanWebPlugins(
+  hostDir: string,
+  pluginRoots: readonly string[] = [],
+  onNotice: (message: string) => void = () => undefined,
+): DeclaredWebPlugin[] {
+  const seen = new Set<string>();
+  const plugins: DeclaredWebPlugin[] = [];
+  const hostResolved = path.resolve(hostDir);
+  for (const root of [hostDir, ...pluginRoots]) {
+    const resolved = path.resolve(root);
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    try {
+      plugins.push(...declaredPluginsIn(resolved, resolved === hostResolved));
+    } catch (error) {
+      if (resolved === hostResolved) throw error;
+      const reason = error instanceof WebPluginManifestError ? error.message : String(error);
+      onNotice(`web plugin package ${resolved} skipped: ${reason}`);
+    }
+  }
+  return orderDeclaredPlugins(plugins, onNotice);
+}
+
+function declaredPluginsIn(resolved: string, isHost: boolean): DeclaredWebPlugin[] {
+  let manifest: Record<string, unknown>;
+  try {
+    manifest = JSON.parse(fs.readFileSync(path.join(resolved, 'package.json'), 'utf8')) as Record<string, unknown>;
+  } catch (error) {
+    throw new WebPluginManifestError(resolved, `package.json is unreadable: ${String(error)}`);
+  }
+  const declared = declaredPluginsOf(resolved, manifest, isHost);
+  for (const plugin of declared) {
+    const entryPath = path.join(resolved, plugin.client.entry);
+    if (!fs.existsSync(entryPath)) {
+      throw new WebPluginManifestError(resolved, `client.entry '${plugin.client.entry}' does not exist.`);
+    }
+    if (plugin.hub && !fs.existsSync(path.join(resolved, plugin.hub.entry))) {
+      throw new WebPluginManifestError(resolved, `hub.entry '${plugin.hub.entry}' does not exist.`);
+    }
+  }
+  return declared;
+}

package/src/adapters/webPluginVite.ts

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { Alias, Plugin } from 'vite';
+import { devPluginRoots, PLUGIN_ROOTS_ENV, PLUGIN_ROOTS_FILE } from '../services/webDevRoots.ts';
+import type { SyncGeneratedModules } from './webPluginGenerate.ts';
+
+/** Where `doompi sync` publishes the bundle the server prefers; the roots file sits beside its assets. */
+const SYNCED_BUNDLE_DIRECTORY = ['.doompi', 'web', 'current'];
+
+/**
+ * Swaps the committed builtin registry modules for generated ones. A
+ * resolveId hook rather than resolve.alias because aliases match raw import
+ * specifiers while these two are known by their resolved paths. Both the
+ * sync-time build and the dev server use it, so a plugin edit in dev is the
+ * same module the bundle would carry.
+ */
+export function webPluginOverridePlugin(clientRoot: string, generated: SyncGeneratedModules): Plugin {
+  const overrides = new Map([
+    [path.join(clientRoot, 'app', 'webPlugins.generated.ts'), generated.clientModulePath],
+    [path.join(clientRoot, 'styles', 'webPluginSources.generated.css'), generated.cssModulePath],
+  ]);
+  return {
+    name: 'doompi-web-plugin-overrides',
+    enforce: 'pre',
+    async resolveId(source, importer, options) {
+      const resolved = await this.resolve(source, importer, { ...options, skipSelf: true });
+      if (!resolved) return null;
+      return overrides.get(resolved.id) ?? null;
+    },
+  };
+}
+
+/**
+ * The CSS sources module cannot ride the resolveId hook: Vite and Tailwind
+ * resolve CSS @import through Vite's own id resolver, which consults aliases
+ * but no plugin hooks. Without this the builtin (empty) @source list ships
+ * and every plugin-only utility class is missing.
+ */
+export function webPluginCssAlias(generated: SyncGeneratedModules): Alias {
+  return { find: /^\.\/webPluginSources\.generated\.css$/, replacement: generated.cssModulePath };
+}
+
+/** The plugin package roots the dev server should serve, from the environment or the last sync. */
+export function readDevPluginRoots(environment: NodeJS.ProcessEnv, homeDirectory: string): string[] {
+  const rootsFile = path.join(homeDirectory, ...SYNCED_BUNDLE_DIRECTORY, PLUGIN_ROOTS_FILE);
+  return devPluginRoots({
+    envValue: environment[PLUGIN_ROOTS_ENV],
+    rootsFileText: fs.existsSync(rootsFile) ? fs.readFileSync(rootsFile, 'utf8') : undefined,
+    delimiter: path.delimiter,
+  });
+}

package/src/bin/serve.ts

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+import os from 'node:os';
+import { hubAnswers } from '../adapters/hubProbe.ts';
+import { serveWeb } from '../adapters/httpServer.ts';
+import { REGISTRY_DIR_ENV, resolveRegistryDir } from '../services/registryStore.ts';
+import { parseServeOptions } from '../services/serveOptions.ts';
+import type { WebServer } from '../types/bridge.ts';
+
+const ADDRESS_IN_USE = 'EADDRINUSE';
+
+function notice(message: string): void {
+  process.stderr.write(`[doompi-web] ${message}\n`);
+}
+
+async function main(): Promise<void> {
+  const options = parseServeOptions(process.argv.slice(2));
+  const url = `http://${options.host}:${String(options.port)}`;
+
+  // One hub serves every session, so a second start is a request to use the
+  // running one, not an error worth a stack trace.
+  if (await hubAnswers(options.host, options.port)) {
+    notice(`cockpit already running at ${url}`);
+    return;
+  }
+
+  let server: WebServer;
+  try {
+    server = await serveWeb({
+      port: options.port,
+      host: options.host,
+      assetsDir: options.assetsDir,
+      registryDir: resolveRegistryDir({
+        flagValue: options.registryDir,
+        envValue: process.env[REGISTRY_DIR_ENV],
+        homeDir: os.homedir(),
+      }),
+      spawnCommand: options.spawnCommand,
+      onNotice: notice,
+    });
+  } catch (error) {
+    // Two cockpits starting together can both find the port free; the loser
+    // settles for the winner rather than reporting a clash nobody caused.
+    if ((error as NodeJS.ErrnoException).code !== ADDRESS_IN_USE) throw error;
+    if (await hubAnswers(options.host, options.port)) {
+      notice(`cockpit already running at ${url}`);
+      return;
+    }
+    throw new Error(`Port ${String(options.port)} is taken by something that is not a DoomPi cockpit; pass --port.`);
+  }
+
+  const stop = (): void => {
+    void server.close().then(() => {
+      process.exit(0);
+    });
+  };
+  process.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+}
+
+main().catch((error: unknown) => {
+  notice(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/src/exports/bundler.ts

@@ -0,0 +1 @@
+export { bundleCockpitWeb, type BundleCockpitWebOptions, type BundleCockpitWebResult } from '../adapters/webBundler.ts';

package/src/exports/index.ts

@@ -0,0 +1,9 @@
+export { serveWeb } from '../adapters/httpServer.ts';
+export { parseServeOptions } from '../services/serveOptions.ts';
+export type { ServeOptions } from '../services/serveOptions.ts';
+export type { SessionAttachment, WebServer, WebServerOptions } from '../types/bridge.ts';
+export { HUB_PROTOCOL_VERSION, HUB_ROLE, SESSIONS_API_ROUTE } from '../types/hub.ts';
+export type { SessionPhase, SessionSummary } from '../types/hub.ts';
+export { SESSION_RECORD_VERSION } from '../types/registry.ts';
+export type { SessionRecord } from '../types/registry.ts';
+export type { BridgeState, BridgeStatusFrame, SessionFrame } from '../types/session.ts';

package/src/services/directoryMatch.ts

@@ -0,0 +1,71 @@
+import path from 'node:path';
+
+/** Scores, highest first: an exact folder name beats a prefix, which beats a substring. */
+const EXACT_NAME = 1000;
+const NAME_PREFIX = 800;
+const NAME_CONTAINS = 600;
+const PATH_CONTAINS = 400;
+/** Each level down costs this much, so a shallow answer wins a deep one of the same kind. */
+const DEPTH_PENALTY = 12;
+
+/**
+ * How well one directory answers a typed query, or undefined when it does not.
+ *
+ * The reader is naming a project, so the folder's own name is what they mean;
+ * a match further up the path still counts, because "workspace/agi" is a
+ * reasonable way to point at a folder, but it ranks below a name that matches
+ * outright. Depth is the tiebreak: given `~/work/api` and
+ * `~/work/api/node_modules/x/api`, the first is what anyone meant.
+ */
+export function scoreDirectory(absolutePath: string, query: string): number | undefined {
+  const needle = query.trim().toLowerCase();
+  if (needle === '') return undefined;
+  const name = path.basename(absolutePath).toLowerCase();
+  const depth = absolutePath.split(path.sep).filter(Boolean).length;
+
+  const base =
+    name === needle
+      ? EXACT_NAME
+      : name.startsWith(needle)
+        ? NAME_PREFIX
+        : name.includes(needle)
+          ? NAME_CONTAINS
+          : absolutePath.toLowerCase().includes(needle)
+            ? PATH_CONTAINS
+            : undefined;
+  if (base === undefined) return undefined;
+  return base - depth * DEPTH_PENALTY;
+}
+
+/**
+ * The best directories for a query, deduplicated and cut to the limit. Ties
+ * break alphabetically so the same query always lists the same way.
+ */
+export function rankDirectories(paths: Iterable<string>, query: string, limit: number): string[] {
+  const scored = new Map<string, number>();
+  for (const candidate of paths) {
+    if (scored.has(candidate)) continue;
+    const score = scoreDirectory(candidate, query);
+    if (score !== undefined) scored.set(candidate, score);
+  }
+  return [...scored.entries()]
+    .sort(
+      ([leftPath, leftScore], [rightPath, rightScore]) => rightScore - leftScore || leftPath.localeCompare(rightPath),
+    )
+    .slice(0, limit)
+    .map(([candidate]) => candidate);
+}
+
+/**
+ * The part of a typed value to search for when it is not a path that exists.
+ *
+ * Someone typing a remembered path from another machine ("/home/me/work/api")
+ * still means "api", so the trailing segment is the query and the rest is
+ * discarded rather than treated as a location that must exist.
+ */
+export function searchTermFor(typed: string): string {
+  const trimmed = typed.trim().replace(/\/+$/u, '');
+  if (trimmed === '') return '';
+  const cut = trimmed.lastIndexOf('/');
+  return cut === -1 ? trimmed : trimmed.slice(cut + 1);
+}

package/src/services/fileMatch.ts

@@ -0,0 +1,37 @@
+/**
+ * Ranking for the composer's @ file completion: pure string policy, no
+ * filesystem, so the ordering rules stay testable on their own.
+ */
+
+interface RankedMatch {
+  file: string;
+  rank: number;
+}
+
+/**
+ * Case-insensitive substring match, ranked so what a person is reaching for
+ * surfaces first: basename prefix beats basename substring beats path
+ * substring, earlier and shorter paths break ties.
+ */
+export function rankFileMatches(files: readonly string[], query: string, limit: number): string[] {
+  const needle = query.toLowerCase();
+  const ranked: RankedMatch[] = [];
+  for (const file of files) {
+    const lower = file.toLowerCase();
+    const base = lower.slice(lower.lastIndexOf('/') + 1);
+    let rank: number;
+    if (needle === '') rank = 3;
+    else if (base.startsWith(needle)) rank = 0;
+    else if (base.includes(needle)) rank = 1;
+    else if (lower.includes(needle)) rank = 2;
+    else continue;
+    ranked.push({ file, rank });
+  }
+  return ranked
+    .sort(
+      (left, right) =>
+        left.rank - right.rank || left.file.length - right.file.length || left.file.localeCompare(right.file),
+    )
+    .slice(0, limit)
+    .map((entry) => entry.file);
+}

package/src/services/fileMedia.ts

@@ -0,0 +1,27 @@
+import path from 'node:path';
+import { MEDIA_TYPES, type MediaType } from '../types/media.ts';
+
+const OCTET_STREAM = 'application/octet-stream';
+
+/** The preview type for a file the hub is asked to serve, or undefined for a plain download. */
+export function mediaTypeFor(filePath: string): MediaType | undefined {
+  return MEDIA_TYPES[path.extname(filePath).slice(1).toLowerCase()];
+}
+
+/**
+ * The response headers for a mentioned file. Previewable kinds render inline;
+ * everything else downloads under its own name. SVG is the one previewable
+ * type that can carry script, so it is served sandboxed: an <img> never runs
+ * script anyway, and a direct navigation gets an inert document.
+ */
+export function sessionFileHeaders(filePath: string): Record<string, string> {
+  const media = mediaTypeFor(filePath);
+  const name = path.basename(filePath).replaceAll('"', '');
+  const headers: Record<string, string> = {
+    'Content-Type': media?.contentType ?? OCTET_STREAM,
+    'Content-Disposition': `${media ? 'inline' : 'attachment'}; filename="${name}"`,
+    'X-Content-Type-Options': 'nosniff',
+  };
+  if (media?.contentType === 'image/svg+xml') headers['Content-Security-Policy'] = "default-src 'none'; sandbox";
+  return headers;
+}

package/src/services/frameRing.ts

@@ -0,0 +1,33 @@
+import type { SessionFrame } from '../types/session.ts';
+
+const DEFAULT_RING_LIMIT = 512;
+
+/**
+ * Bounded history of one session's frame stream.
+ *
+ * The unix-socket backlog only fills while nothing is attached, and the hub is
+ * always attached, so a page that connects later would otherwise start blind.
+ * The ring is what a subscribe replays; it mirrors the server backlog's
+ * semantics, dropping the oldest frames past the limit and counting the loss.
+ */
+export interface FrameRing {
+  record(frame: SessionFrame): void;
+  snapshot(): { frames: SessionFrame[]; dropped: number };
+}
+
+export function createFrameRing(limit = DEFAULT_RING_LIMIT): FrameRing {
+  const frames: SessionFrame[] = [];
+  let dropped = 0;
+  return {
+    record(frame) {
+      frames.push(frame);
+      if (frames.length > limit) {
+        frames.shift();
+        dropped += 1;
+      }
+    },
+    snapshot() {
+      return { frames: [...frames], dropped };
+    },
+  };
+}

package/src/services/journalTail.ts

@@ -0,0 +1,47 @@
+import type { SessionFrame } from '../types/session.ts';
+
+/** The entry type a journal line must carry to render; everything else is Pi's own bookkeeping. */
+const MESSAGE_ENTRY_TYPE = 'message';
+/** The frame the hub already replays journal entries as, so the page folds a thread with its one reducer. */
+const ENTRY_APPENDED_TYPE = 'entry_appended';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** One journal line as a renderable entry, or undefined for the header, bookkeeping, or a torn line. */
+function parseEntry(line: string): Record<string, unknown> | undefined {
+  const trimmed = line.trim();
+  if (trimmed === '') return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    // A line the writer had not finished, or one that was never JSON: nothing to render from it.
+    return undefined;
+  }
+  if (!isRecord(parsed) || parsed.type !== MESSAGE_ENTRY_TYPE) return undefined;
+  // An entry without an id is the runtime's own bookkeeping; the page would skip it too.
+  if (typeof parsed.id !== 'string' || parsed.id === '' || !isRecord(parsed.message)) return undefined;
+  return parsed;
+}
+
+/**
+ * Folds complete lines of a Pi session journal into the frames the cockpit
+ * already renders for a live session: one entry_appended per message entry,
+ * oldest first. The header, other entry types and unparsable lines are
+ * skipped, so the page needs no second reducer for a thread.
+ */
+export function journalFrames(text: string): SessionFrame[] {
+  const frames: SessionFrame[] = [];
+  for (const line of text.split('\n')) {
+    const entry = parseEntry(line);
+    if (entry) frames.push({ type: ENTRY_APPENDED_TYPE, entry });
+  }
+  return frames;
+}
+
+/** The newest `limit` frames; a long journal gives up its oldest, as an attach does. */
+export function retainNewest(frames: readonly SessionFrame[], limit: number): SessionFrame[] {
+  return frames.length <= limit ? [...frames] : frames.slice(frames.length - limit);
+}

package/src/services/loginFlow.ts

@@ -0,0 +1,144 @@
+import type {
+  AuthMethodType,
+  LoginEvent,
+  LoginFlowSnapshot,
+  LoginFlowStatus,
+  LoginInteraction,
+  LoginPrompt,
+  LoginPromptView,
+} from '../types/auth.ts';
+
+/** The message Pi's own login dialog uses; a provider flow may match on it. */
+const CANCELLED_MESSAGE = 'Login cancelled';
+const SUPERSEDED_MESSAGE = 'Superseded by a newer prompt';
+
+interface PendingPrompt {
+  view: LoginPromptView;
+  resolve(value: string): void;
+  reject(error: Error): void;
+  detach(): void;
+}
+
+export interface LoginFlowInput {
+  id: string;
+  providerId: string;
+  providerName: string;
+  type: AuthMethodType;
+}
+
+/**
+ * One login in progress, seen from both sides: the provider's flow talks to
+ * it through `interaction`, the page through snapshots and answers.
+ */
+export interface LoginFlow {
+  readonly id: string;
+  readonly providerId: string;
+  /** Hand this to the runtime's login; prompts and events route through the flow. */
+  readonly interaction: LoginInteraction;
+  snapshot(): LoginFlowSnapshot;
+  /** Answers the pending prompt; false when the flow is not waiting on that prompt. */
+  answer(promptId: string, value: string): boolean;
+  /** Aborts the provider's flow; a settled flow is left as it ended. */
+  cancel(): void;
+  /** Records how the runtime's login ended; a cancelled flow stays cancelled. */
+  settle(outcome: { ok: true } | { ok: false; error: string }): void;
+}
+
+function promptView(id: string, prompt: LoginPrompt): LoginPromptView {
+  const view: LoginPromptView = { id, type: prompt.type, message: prompt.message };
+  if (prompt.type === 'select') view.options = prompt.options.map((option) => ({ ...option }));
+  else if (prompt.placeholder !== undefined) view.placeholder = prompt.placeholder;
+  return view;
+}
+
+/**
+ * The state machine between a provider login and a browser that can only
+ * poll and post.
+ *
+ * A provider asks one question at a time and may withdraw it (a manual-code
+ * prompt raced against a callback server aborts when the callback wins), so
+ * the flow holds at most one pending prompt, rejects it when its signal
+ * fires, and supersedes it if the provider asks again.
+ */
+export function createLoginFlow(input: LoginFlowInput): LoginFlow {
+  const controller = new AbortController();
+  const events: LoginEvent[] = [];
+  let status: LoginFlowStatus = 'running';
+  let error: string | undefined;
+  let pending: PendingPrompt | undefined;
+  let promptSeq = 0;
+
+  const failPending = (reason: Error): void => {
+    const current = pending;
+    if (!current) return;
+    pending = undefined;
+    current.detach();
+    current.reject(reason);
+  };
+
+  const interaction: LoginInteraction = {
+    signal: controller.signal,
+    prompt(prompt) {
+      if (controller.signal.aborted || prompt.signal?.aborted) return Promise.reject(new Error(CANCELLED_MESSAGE));
+      failPending(new Error(SUPERSEDED_MESSAGE));
+      promptSeq += 1;
+      const view = promptView(String(promptSeq), prompt);
+      return new Promise<string>((resolve, reject) => {
+        const onAbort = (): void => failPending(new Error(CANCELLED_MESSAGE));
+        prompt.signal?.addEventListener('abort', onAbort, { once: true });
+        pending = {
+          view,
+          resolve,
+          reject,
+          detach: () => prompt.signal?.removeEventListener('abort', onAbort),
+        };
+      });
+    },
+    notify(event) {
+      events.push(event);
+    },
+  };
+
+  return {
+    id: input.id,
+    providerId: input.providerId,
+    interaction,
+    snapshot() {
+      const snapshot: LoginFlowSnapshot = {
+        id: input.id,
+        providerId: input.providerId,
+        providerName: input.providerName,
+        type: input.type,
+        status,
+        events: [...events],
+      };
+      if (pending) snapshot.prompt = pending.view;
+      if (error !== undefined) snapshot.error = error;
+      return snapshot;
+    },
+    answer(promptId, value) {
+      const current = pending;
+      if (!current || current.view.id !== promptId) return false;
+      pending = undefined;
+      current.detach();
+      current.resolve(value);
+      return true;
+    },
+    cancel() {
+      if (status !== 'running') return;
+      status = 'cancelled';
+      controller.abort();
+      failPending(new Error(CANCELLED_MESSAGE));
+    },
+    settle(outcome) {
+      if (status !== 'running') return;
+      if (outcome.ok) {
+        status = 'succeeded';
+      } else {
+        status = 'failed';
+        error = outcome.error;
+      }
+      failPending(new Error(CANCELLED_MESSAGE));
+    },
+  };
+}

package/src/services/registryStore.ts

@@ -0,0 +1,83 @@
+import { SESSION_RECORD_VERSION, type SessionRecord } from '../types/registry.ts';
+
+const RECORD_EXTENSION = '.json';
+const REQUIRED_STRINGS = ['id', 'cwd', 'socketPath', 'tokenFile', 'createdAt'] as const;
+
+/** Environment variable overriding where session records live. */
+export const REGISTRY_DIR_ENV = 'DOOMPI_RUNTIME_DIR';
+
+const DEFAULT_RUN_DIR_SEGMENT = '.doompi/run';
+const SESSIONS_SEGMENT = 'sessions';
+
+export interface RegistryDirInput {
+  /** Value of --registry-dir, when given; wins over everything else. */
+  readonly flagValue?: string;
+  /** Value of DOOMPI_RUNTIME_DIR, when set. */
+  readonly envValue?: string;
+  /** The user's home directory, supplied by the host. */
+  readonly homeDir: string;
+}
+
+/** Mirrors doompi-server's resolution so both sides land on the same directory. */
+export function resolveRegistryDir(input: RegistryDirInput): string {
+  if (input.flagValue) return input.flagValue;
+  if (input.envValue) return input.envValue;
+  return `${input.homeDir}/${DEFAULT_RUN_DIR_SEGMENT}`;
+}
+
+/** Directory the watcher scans for record files. */
+export function sessionRecordsDir(registryDir: string): string {
+  return `${registryDir}/${SESSIONS_SEGMENT}`;
+}
+
+export function sessionRecordPath(registryDir: string, sessionId: string): string {
+  return `${sessionRecordsDir(registryDir)}/${sessionId}${RECORD_EXTENSION}`;
+}
+
+export function isRecordFileName(name: string): boolean {
+  return name.endsWith(RECORD_EXTENSION);
+}
+
+/**
+ * Validates one record file's content.
+ *
+ * Returns undefined for anything that is not a well-formed current-version
+ * record: a truncated write, a foreign file, or a future format this build
+ * does not understand. The watcher simply skips such files.
+ */
+export function parseSessionRecord(raw: string): SessionRecord | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return undefined;
+  const record = parsed as Record<string, unknown>;
+  if (record.version !== SESSION_RECORD_VERSION) return undefined;
+  for (const key of REQUIRED_STRINGS) {
+    if (typeof record[key] !== 'string' || record[key] === '') return undefined;
+  }
+  if (typeof record.name !== 'string') return undefined;
+  if (typeof record.pid !== 'number' || !Number.isInteger(record.pid) || record.pid <= 0) return undefined;
+  return {
+    version: SESSION_RECORD_VERSION,
+    id: record.id as string,
+    name: record.name,
+    cwd: record.cwd as string,
+    socketPath: record.socketPath as string,
+    tokenFile: record.tokenFile as string,
+    // Optional: a server that mounted no package API omits it, and so does an
+    // older one that predates the field.
+    ...(typeof record.apiSocketPath === 'string' && record.apiSocketPath !== ''
+      ? { apiSocketPath: record.apiSocketPath }
+      : {}),
+    // Also optional: a server predating the protocol socket serves only the
+    // framed one, and a client that needs the protocol says so itself.
+    ...(typeof record.protocolSocketPath === 'string' && record.protocolSocketPath !== ''
+      ? { protocolSocketPath: record.protocolSocketPath }
+      : {}),
+    pid: record.pid,
+    createdAt: record.createdAt as string,
+  };
+}

package/src/services/retryPolicy.ts

@@ -0,0 +1,15 @@
+const BASE_DELAY_MS = 150;
+const MAX_DELAY_MS = 4000;
+
+/**
+ * Exponential backoff for reattaching to the session socket.
+ *
+ * A browser reload closes the old socket and opens a new one, and the server
+ * only allows one client at a time, so the first retries have to be quick
+ * enough to win that handover without hammering a socket that is genuinely
+ * held by someone else.
+ */
+export function reattachDelayMs(attempt: number): number {
+  if (attempt <= 0) return 0;
+  return Math.min(BASE_DELAY_MS * 2 ** (attempt - 1), MAX_DELAY_MS);
+}