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

package/src/services/serveOptions.ts

@@ -0,0 +1,63 @@
+export interface ServeOptions {
+  /** Registry override; the default is resolved by the caller. */
+  registryDir?: string;
+  /** Command launching created sessions; the caller resolves one when this is absent. */
+  spawnCommand?: string;
+  port: number;
+  host: string;
+  assetsDir?: string;
+}
+
+const DEFAULT_PORT = 7433;
+const DEFAULT_HOST = '127.0.0.1';
+
+function requireValue(flag: string, value: string | undefined): string {
+  if (value === undefined || value.startsWith('--')) throw new Error(`${flag} needs a value.`);
+  return value;
+}
+
+/**
+ * Parses the doompi-web command line.
+ *
+ * Every flag is an override. Bare `doompi-web` is a hub over the default
+ * registry directory on the default loopback port, which is the way it is
+ * meant to be run; nothing here is required to get a working cockpit.
+ */
+export function parseServeOptions(argv: readonly string[]): ServeOptions {
+  let registryDir: string | undefined;
+  let spawnCommand: string | undefined;
+  let port = DEFAULT_PORT;
+  let host = DEFAULT_HOST;
+  let assetsDir: string | undefined;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    switch (flag) {
+      case '--registry-dir':
+        registryDir = requireValue(flag, argv[++index]);
+        break;
+      case '--spawn-command':
+        spawnCommand = requireValue(flag, argv[++index]);
+        break;
+      case '--port': {
+        const raw = requireValue(flag, argv[++index]);
+        const parsed = Number.parseInt(raw, 10);
+        if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535) {
+          throw new Error(`--port expects a port number, received "${raw}".`);
+        }
+        port = parsed;
+        break;
+      }
+      case '--host':
+        host = requireValue(flag, argv[++index]);
+        break;
+      case '--assets':
+        assetsDir = requireValue(flag, argv[++index]);
+        break;
+      default:
+        throw new Error(`Unknown option "${flag}".`);
+    }
+  }
+
+  return { registryDir, spawnCommand, port, host, assetsDir };
+}

package/src/services/sessionFraming.ts

@@ -0,0 +1,32 @@
+import type { SessionFrame } from '../types/session.ts';
+
+const NEWLINE = '\n';
+
+/**
+ * Splits a byte stream into newline-delimited JSON frames.
+ *
+ * Stateful across chunks because a socket read can land mid-frame, which is the
+ * normal case for streamed agent output rather than an edge case.
+ */
+export function createFrameDecoder(): (chunk: string) => SessionFrame[] {
+  let buffered = '';
+  return (chunk: string): SessionFrame[] => {
+    buffered += chunk;
+    const parts = buffered.split(NEWLINE);
+    buffered = parts.pop() ?? '';
+    const frames: SessionFrame[] = [];
+    for (const part of parts) {
+      const line = part.trim();
+      if (!line) continue;
+      const parsed: unknown = JSON.parse(line);
+      if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+        frames.push(parsed as SessionFrame);
+      }
+    }
+    return frames;
+  };
+}
+
+export function encodeFrame(frame: SessionFrame): string {
+  return `${JSON.stringify(frame)}${NEWLINE}`;
+}

package/src/services/sessionPresence.ts

@@ -0,0 +1,131 @@
+import type { SessionPhase } from '../types/hub.ts';
+import type { SessionFrame } from '../types/session.ts';
+
+const DIALOG_METHODS = ['select', 'confirm', 'input', 'editor'];
+
+/**
+ * What one session's frame stream says it is doing.
+ *
+ * Reduced by the hub for every session it holds, attached or not focused, so
+ * the rail can describe sessions nobody is looking at. The reducer returns the
+ * SAME object when a frame changes nothing it reports; callers use that
+ * reference equality to skip redundant summary pushes.
+ */
+export interface SessionPresence {
+  phase: SessionPhase;
+  /** ISO 8601 timestamp of the last phase change. */
+  phaseSince: string;
+  /** ISO 8601 timestamp of the last change to any reported fact. */
+  updatedAt: string;
+  pendingMessageCount: number;
+  everPrompted: boolean;
+  awaitingInput: boolean;
+  lastSettledAt?: string;
+  /** Name reported by get_state, fresher than the registry record when set. */
+  sessionName?: string;
+}
+
+export function initialPresence(now: string): SessionPresence {
+  return {
+    phase: 'idle',
+    phaseSince: now,
+    updatedAt: now,
+    pendingMessageCount: 0,
+    everPrompted: false,
+    awaitingInput: false,
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function withPhase(presence: SessionPresence, phase: SessionPhase, now: string): SessionPresence {
+  if (presence.phase === phase) return presence;
+  return { ...presence, phase, phaseSince: now, updatedAt: now };
+}
+
+function applyState(presence: SessionPresence, data: Record<string, unknown>, now: string): SessionPresence {
+  let next = presence;
+  const phase: SessionPhase = data.isCompacting === true ? 'compaction' : data.isStreaming === true ? 'turn' : 'idle';
+  next = withPhase(next, phase, now);
+  const pending = typeof data.pendingMessageCount === 'number' ? data.pendingMessageCount : next.pendingMessageCount;
+  if (pending !== next.pendingMessageCount) next = { ...next, pendingMessageCount: pending, updatedAt: now };
+  const name = typeof data.sessionName === 'string' && data.sessionName !== '' ? data.sessionName : undefined;
+  if (name !== undefined && name !== next.sessionName) next = { ...next, sessionName: name, updatedAt: now };
+  return next;
+}
+
+/**
+ * Folds one agent frame into the presence.
+ *
+ * Pure and total like reduceSession: an unrecognised frame changes nothing.
+ */
+export function reducePresence(presence: SessionPresence, frame: SessionFrame, now: string): SessionPresence {
+  switch (frame.type) {
+    case 'replay':
+      return isRecord(frame.frame) ? reducePresence(presence, frame.frame, now) : presence;
+
+    case 'agent_start': {
+      const started = withPhase(presence, 'turn', now);
+      if (!started.awaitingInput) return started;
+      return { ...started, awaitingInput: false, updatedAt: now };
+    }
+
+    case 'agent_settled': {
+      const settled = withPhase(presence, 'idle', now);
+      return { ...settled, awaitingInput: false, lastSettledAt: now, updatedAt: now };
+    }
+
+    case 'extension_ui_request': {
+      if (typeof frame.method !== 'string' || !DIALOG_METHODS.includes(frame.method)) return presence;
+      if (presence.awaitingInput) return presence;
+      return { ...presence, awaitingInput: true, updatedAt: now };
+    }
+
+    case 'response':
+      return frame.command === 'get_state' && isRecord(frame.data) ? applyState(presence, frame.data, now) : presence;
+
+    default:
+      return presence;
+  }
+}
+
+/**
+ * Folds one entry restored from the session's journal.
+ *
+ * A session outlives every hub that watches it, so "has this ever been
+ * prompted" cannot be answered from what this process happened to see: a hub
+ * that restarts, or meets a session first driven from the TUI, saw nothing. A
+ * journalled user message is the proof, and without it a session carrying an
+ * hour of work introduces itself in the rail as fresh.
+ */
+export function presenceAfterRestoredEntry(
+  presence: SessionPresence,
+  entry: Record<string, unknown>,
+  now: string,
+): SessionPresence {
+  if (presence.everPrompted || entry.type !== 'message') return presence;
+  const message = entry.message;
+  if (typeof message !== 'object' || message === null) return presence;
+  if ((message as { role?: unknown }).role !== 'user') return presence;
+  return { ...presence, everPrompted: true, updatedAt: now };
+}
+
+/**
+ * Folds one page command heading to the agent.
+ *
+ * The prompt direction carries facts the event stream does not repeat: that
+ * the session has ever been prompted, and that a pending dialog was answered.
+ */
+export function presenceAfterCommand(presence: SessionPresence, frame: SessionFrame, now: string): SessionPresence {
+  if (frame.type === 'prompt' || frame.type === 'steer' || frame.type === 'follow_up') {
+    if (presence.everPrompted) return presence;
+    return { ...presence, everPrompted: true, updatedAt: now };
+  }
+  if (frame.type === 'extension_ui_response') {
+    if (!presence.awaitingInput) return presence;
+    return { ...presence, awaitingInput: false, updatedAt: now };
+  }
+  return presence;
+}

package/src/services/staticAssets.ts

@@ -0,0 +1,37 @@
+import path from 'node:path';
+
+const CONTENT_TYPES: Readonly<Record<string, string>> = {
+  '.css': 'text/css; charset=utf-8',
+  '.html': 'text/html; charset=utf-8',
+  '.ico': 'image/x-icon',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.woff2': 'font/woff2',
+};
+
+export function contentTypeFor(filePath: string): string {
+  return CONTENT_TYPES[path.extname(filePath).toLowerCase()] ?? 'application/octet-stream';
+}
+
+/**
+ * Maps a request path to a file inside the asset root.
+ *
+ * Returns undefined when the result would escape the root, so an encoded
+ * traversal cannot read files the bundle was never meant to publish.
+ */
+export function resolveAssetPath(assetsDir: string, requestPath: string): string | undefined {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(requestPath);
+  } catch {
+    return undefined;
+  }
+  if (decoded.includes('\0')) return undefined;
+  const root = path.resolve(assetsDir);
+  const candidate = path.resolve(root, `.${path.posix.normalize(decoded)}`);
+  if (candidate !== root && !candidate.startsWith(`${root}${path.sep}`)) return undefined;
+  return candidate;
+}

package/src/services/webDevRoots.ts

@@ -0,0 +1,36 @@
+/**
+ * Where the cockpit's dev server finds the plugin packages to serve with hot
+ * reload. Pure: the adapter hands in the environment value and the roots file
+ * the last `doompi sync` wrote next to its bundle; this only decides.
+ */
+
+/** A delimiter-separated list of plugin package roots; wins over the synced roots file. */
+export const PLUGIN_ROOTS_ENV = 'DOOMPI_WEB_PLUGIN_ROOTS';
+/** The file `doompi sync` writes beside its bundle, listing the package roots it bundled. */
+export const PLUGIN_ROOTS_FILE = 'pluginRoots.json';
+
+export interface DevPluginRootsInput {
+  /** The raw environment value, undefined when unset. */
+  envValue: string | undefined;
+  /** The roots file's text, undefined when no synced bundle exists. */
+  rootsFileText: string | undefined;
+  /** The platform's path list delimiter (':' on POSIX, ';' on Windows). */
+  delimiter: string;
+}
+
+/** The plugin roots the dev server should serve: the environment list, else the synced list, else none. */
+export function devPluginRoots({ envValue, rootsFileText, delimiter }: DevPluginRootsInput): string[] {
+  if (envValue !== undefined && envValue.trim() !== '') {
+    return envValue
+      .split(delimiter)
+      .map((root) => root.trim())
+      .filter((root) => root !== '');
+  }
+  if (rootsFileText === undefined) return [];
+  try {
+    const parsed: unknown = JSON.parse(rootsFileText);
+    return Array.isArray(parsed) ? parsed.filter((root): root is string => typeof root === 'string') : [];
+  } catch {
+    return [];
+  }
+}

package/src/services/webPluginManifest.ts

@@ -0,0 +1,149 @@
+/**
+ * The doompiWeb manifest vocabulary: how a package declares its web plugin in
+ * package.json, validated and ordered without touching the filesystem. The
+ * scan adapter feeds this from real manifests; the sync bundler feeds it from
+ * the installed composition's package roots.
+ *
+ * Plugins are independent: a manifest names no other plugin, and the order
+ * plugins install in is only a tiebreak (registrationOrder, then pluginId),
+ * because every relation between two plugins resolves by name once all of
+ * them are installed. A collision between two packages is a notice for the
+ * sync log and the first package keeps the name; only a malformed block is an
+ * error, which the scanner turns into a notice for that package alone.
+ */
+
+const PLUGIN_ID_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+/** The order a plugin installs at when its manifest names none. */
+export const DEFAULT_REGISTRATION_ORDER = 1000;
+
+export interface WebPluginEntryDeclaration {
+  /** Package-relative ./path to the source entry. */
+  entry: string;
+  /** Package-relative ./path to the built hub entry; required for non-host hub blocks. */
+  dist?: string;
+}
+
+export interface DeclaredWebPlugin {
+  pluginId: string;
+  registrationOrder: number;
+  channels: string[];
+  packageDir: string;
+  packageName: string;
+  isHost: boolean;
+  client: WebPluginEntryDeclaration;
+  hub?: WebPluginEntryDeclaration;
+}
+
+export class WebPluginManifestError extends Error {
+  constructor(packageDir: string, message: string) {
+    super(`doompiWeb manifest in ${packageDir}: ${message}`);
+    this.name = 'WebPluginManifestError';
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function normalizeEntry(packageDir: string, isHost: boolean, kind: string, value: unknown): WebPluginEntryDeclaration {
+  const raw = typeof value === 'string' ? { entry: value } : value;
+  if (!isRecord(raw)) throw new WebPluginManifestError(packageDir, `${kind} must be a path or {entry, dist}.`);
+  const { entry, dist } = raw;
+  if (typeof entry !== 'string' || !entry.startsWith('./') || entry.includes('..')) {
+    throw new WebPluginManifestError(packageDir, `${kind}.entry must be a package-relative ./path with no '..'.`);
+  }
+  if (dist !== undefined && (typeof dist !== 'string' || !dist.startsWith('./') || dist.includes('..'))) {
+    throw new WebPluginManifestError(packageDir, `${kind}.dist must be a package-relative ./path with no '..'.`);
+  }
+  if (kind === 'hub' && !isHost && typeof dist !== 'string') {
+    throw new WebPluginManifestError(
+      packageDir,
+      'hub.dist is required for a non-host package: the hub imports the built entry the package ships.',
+    );
+  }
+  return { entry, ...(typeof dist === 'string' ? { dist } : {}) };
+}
+
+/** The doompiWeb value normalized to a list: one plugin object or an array of them. */
+export function pluginBlocksOf(manifest: Record<string, unknown>): unknown[] {
+  if (manifest.doompiWeb === undefined) return [];
+  return Array.isArray(manifest.doompiWeb) ? manifest.doompiWeb : [manifest.doompiWeb];
+}
+
+/** Validates one manifest's blocks into declared plugins; throws WebPluginManifestError on bad shape. */
+export function declaredPluginsOf(
+  packageDir: string,
+  manifest: Record<string, unknown>,
+  isHost: boolean,
+): DeclaredWebPlugin[] {
+  const plugins: DeclaredWebPlugin[] = [];
+  for (const block of pluginBlocksOf(manifest)) {
+    if (!isRecord(block)) throw new WebPluginManifestError(packageDir, 'each block must be an object.');
+    const { pluginId, registrationOrder = DEFAULT_REGISTRATION_ORDER, channels = [], client, hub } = block;
+    if (typeof pluginId !== 'string' || !PLUGIN_ID_PATTERN.test(pluginId)) {
+      throw new WebPluginManifestError(packageDir, `pluginId '${String(pluginId)}' must be kebab-case.`);
+    }
+    if (!Number.isInteger(registrationOrder) || (registrationOrder as number) < 0) {
+      throw new WebPluginManifestError(packageDir, `'${pluginId}' needs a non-negative integer registrationOrder.`);
+    }
+    if (!Array.isArray(channels) || channels.some((channel) => typeof channel !== 'string' || channel === '')) {
+      throw new WebPluginManifestError(packageDir, `'${pluginId}' channels must be non-empty strings.`);
+    }
+    plugins.push({
+      pluginId,
+      registrationOrder: registrationOrder as number,
+      channels: channels as string[],
+      packageDir,
+      packageName: typeof manifest.name === 'string' ? manifest.name : packageDir,
+      isHost,
+      client: normalizeEntry(packageDir, isHost, 'client', client),
+      ...(hub === undefined ? {} : { hub: normalizeEntry(packageDir, isHost, 'hub', hub) }),
+    });
+  }
+  return plugins;
+}
+
+const byInstallOrder = (left: DeclaredWebPlugin, right: DeclaredWebPlugin): number =>
+  left.registrationOrder - right.registrationOrder ||
+  left.pluginId.localeCompare(right.pluginId) ||
+  left.packageDir.localeCompare(right.packageDir);
+
+/**
+ * The deterministic install order, (registrationOrder, pluginId), with the
+ * cross-package collisions resolved the way the client registry resolves
+ * them: the first plugin keeps a shared pluginId and the later package is
+ * dropped with a notice; a channel two kept plugins both declare is noticed
+ * here and settled first-wins by the client and the hub loader.
+ */
+export function orderDeclaredPlugins(
+  plugins: readonly DeclaredWebPlugin[],
+  onNotice: (message: string) => void = () => undefined,
+): DeclaredWebPlugin[] {
+  const sorted = [...plugins].sort(byInstallOrder);
+  const byId = new Map<string, DeclaredWebPlugin>();
+  const channelOwners = new Map<string, string>();
+  const kept: DeclaredWebPlugin[] = [];
+  for (const plugin of sorted) {
+    const holder = byId.get(plugin.pluginId);
+    if (holder !== undefined) {
+      onNotice(
+        `web plugin '${plugin.pluginId}' from ${plugin.packageDir} is skipped: ${holder.packageDir} already declares it.`,
+      );
+      continue;
+    }
+    byId.set(plugin.pluginId, plugin);
+    kept.push(plugin);
+    for (const channel of plugin.channels) {
+      const owner = channelOwners.get(channel);
+      if (owner !== undefined) {
+        onNotice(
+          `web plugin '${plugin.pluginId}' channel '${channel}' is already claimed by '${owner}'; the first keeps it.`,
+        );
+        continue;
+      }
+      channelOwners.set(channel, plugin.pluginId);
+    }
+  }
+  return kept;
+}

package/src/types/auth.ts

@@ -0,0 +1,118 @@
+/**
+ * Wire vocabulary for provider authentication, shared by the hub routes and
+ * the settings page.
+ *
+ * The hub keeps one Pi ModelRuntime over the same auth.json the sessions
+ * read, so a login here is a login for every session on this machine. Prompt
+ * and event shapes restate pi-ai's AuthPrompt and AuthEvent so neither the
+ * flow service nor the page needs a pi import; the abort signal never leaves
+ * the hub.
+ */
+
+/** REST endpoint listing providers with their auth state; DELETE /:providerId signs out. */
+export const AUTH_PROVIDERS_API_ROUTE = '/api/auth/providers';
+/** REST endpoint for login flows: POST starts one, GET /:flowId polls it, POST /:flowId/answer answers its prompt, DELETE /:flowId cancels. */
+export const AUTH_LOGINS_API_ROUTE = '/api/auth/logins';
+
+export type AuthMethodType = 'api_key' | 'oauth';
+
+export interface ProviderAuthMethod {
+  type: AuthMethodType;
+  /** What the provider calls this method: "Anthropic API key", "Anthropic (Claude Pro/Max)". */
+  label: string;
+}
+
+export interface ProviderAuthSummary {
+  id: string;
+  name: string;
+  /** Login methods the provider offers; ambient-only providers list none. */
+  methods: ProviderAuthMethod[];
+  /**
+   * Present once the provider has working auth: how, and where the credential
+   * comes from ("stored", or the environment variable that holds the key).
+   */
+  authenticated?: { type: AuthMethodType; source?: string };
+}
+
+export interface LoginSelectOption {
+  id: string;
+  label: string;
+  description?: string;
+}
+
+/** pi-ai's AuthPrompt, restated. `signal` cancels this one question, not the flow. */
+export type LoginPrompt = { signal?: AbortSignal } & (
+  | { type: 'text'; message: string; placeholder?: string }
+  | { type: 'secret'; message: string; placeholder?: string }
+  | { type: 'select'; message: string; options: readonly LoginSelectOption[] }
+  | { type: 'manual_code'; message: string; placeholder?: string }
+);
+
+/** The question the page answers: a prompt with an id and without its signal. */
+export interface LoginPromptView {
+  id: string;
+  type: LoginPrompt['type'];
+  message: string;
+  placeholder?: string;
+  /** Present for select prompts. */
+  options?: LoginSelectOption[];
+}
+
+/** pi-ai's AuthEvent, restated. */
+export type LoginEvent =
+  | { type: 'info'; message: string; links?: readonly { url: string; label?: string }[] }
+  | { type: 'auth_url'; url: string; instructions?: string }
+  | {
+      type: 'device_code';
+      userCode: string;
+      verificationUri: string;
+      intervalSeconds?: number;
+      expiresInSeconds?: number;
+    }
+  | { type: 'progress'; message: string };
+
+export type LoginFlowStatus = 'running' | 'succeeded' | 'failed' | 'cancelled';
+
+export interface LoginFlowSnapshot {
+  id: string;
+  providerId: string;
+  providerName: string;
+  type: AuthMethodType;
+  status: LoginFlowStatus;
+  events: LoginEvent[];
+  /** The question the flow is waiting on, while there is one. */
+  prompt?: LoginPromptView;
+  /** Why the flow failed, once it has. */
+  error?: string;
+}
+
+/** pi-ai's AuthInteraction: what a provider's login needs from its host. */
+export interface LoginInteraction {
+  signal: AbortSignal;
+  prompt(prompt: LoginPrompt): Promise<string>;
+  notify(event: LoginEvent): void;
+}
+
+export interface AuthRuntimeProvider {
+  readonly id: string;
+  readonly name: string;
+  readonly auth: {
+    /** Absent `login` means ambient-only (env vars, AWS profiles): nothing to sign in to. */
+    apiKey?: { name: string; login?: unknown };
+    oauth?: { name: string; loginLabel?: string };
+  };
+}
+
+/**
+ * The slice of Pi's ModelRuntime the hub relies on, so a test can stand in a
+ * fake and the adapter never types against the whole agent.
+ */
+export interface AuthRuntime {
+  getProviders(): readonly AuthRuntimeProvider[];
+  getProviderAuthStatus(providerId: string): { configured: boolean; source?: string; label?: string };
+  isUsingOAuth(providerId: string): boolean;
+  /** Re-reads models.json and every provider's auth state without touching the network. */
+  refresh(options: { allowNetwork: boolean }): Promise<unknown>;
+  login(providerId: string, type: AuthMethodType, interaction: LoginInteraction): Promise<unknown>;
+  logout(providerId: string, options?: { signal?: AbortSignal }): Promise<void>;
+}

package/src/types/bridge.ts

@@ -0,0 +1,41 @@
+import type { AuthRuntime } from './auth.ts';
+import type { BridgeStatusFrame, SessionFrame } from './session.ts';
+
+/** One live attachment to a doompi-server socket. */
+export interface SessionAttachment {
+  /** Forwards a command frame to the agent. Ignored once closed. */
+  send(frame: SessionFrame): void;
+  close(): void;
+}
+
+export interface AttachmentHandlers {
+  onFrame(frame: SessionFrame): void;
+  onStatus(status: BridgeStatusFrame): void;
+}
+
+export interface AttachOptions {
+  socketPath: string;
+  token: string;
+  handlers: AttachmentHandlers;
+}
+
+export interface WebServerOptions {
+  port: number;
+  /** Loopback by default; the socket token is not a browser credential. */
+  host?: string;
+  /** Directory holding the built SPA. Defaults to the bundled dist/web. */
+  assetsDir?: string;
+  onNotice?: (message: string) => void;
+  /** Watch this registry directory for running sessions. */
+  registryDir: string;
+  /** Command launching created sessions; overridable so tests can stand in a fake. */
+  spawnCommand?: string;
+  /** Provider auth runtime; overridable so tests can stand in a fake for Pi's ModelRuntime. */
+  authRuntime?: () => Promise<AuthRuntime>;
+}
+
+export interface WebServer {
+  readonly url: string;
+  readonly port: number;
+  close(): Promise<void>;
+}