@abstractframework/observer 0.1.13 → 0.2.0

package/README.md

@@ -4,7 +4,7 @@ Gateway-only observability UI (Web/PWA) for AbstractFramework runs.
 
 What it does (implemented in `src/ui/app.tsx` + `src/lib/gateway_client.ts`):
 - **Discover** workflows/bundles exposed by an AbstractGateway
-- **Launch** or **schedule** runs (durable)
+- **Launch** runs, or create **automations** that the gateway runs on a schedule (durable)
 - **Observe** runs and subruns by replaying + streaming the durable **ledger** (replay-first + SSE)
 - **Inspect runtime state** across active runs, generated artifacts, provider calls, and gateway audit logs
 - **Control** runs via durable commands (`pause`, `resume`, `cancel`)
@@ -18,7 +18,7 @@ The **entity app** (memory graph + visits UI) is its own package,
 *watches* entities — the Board's entities strip reads
 `GET /api/gateway/entities` + `/entities/{name}/card` — and its
 "Entities ↗" links point at the entity app deployment
-(`ABSTRACTOBSERVER_ENTITY_APP_URL`, default `http://127.0.0.1:3007`).
+(`--entity-app-url`, default `http://127.0.0.1:3007`).
 
 ## Where it fits (AbstractFramework ecosystem)
 AbstractObserver is one of the browser UIs in the **AbstractFramework** ecosystem:
@@ -31,7 +31,7 @@ flowchart LR
   U[User] --> O[AbstractObserver<br/>browser UI]
   O -->|HTTP fetch + SSE| G[AbstractGateway<br/>/api/gateway/*]
   G --> R[AbstractRuntime<br/>durable runs + append-only ledger]
-  R --> C[AbstractCore<br/>LLM + tools (optional)]
+  R --> C["AbstractCore<br/>LLM + tools (optional)"]
 ```
 
 ## Quickstart (npm)
@@ -72,17 +72,31 @@ abstractobserver
 
 ### Pin a version (recommended for deployments)
 ```bash
-npx --yes --package @abstractframework/observer@0.1.13 -- abstractobserver
+npx --yes --package @abstractframework/observer@0.2.0 -- abstractobserver
 ```
 
 ### CLI configuration
 The CLI (`bin/cli.js`) serves the built UI and mounts the app-origin Gateway
 session proxy from `@abstractframework/app-server` (a runtime dependency of
 this package, installed automatically).
-- `PORT` (default `3001`)
-- `HOST` (default `0.0.0.0`)
-- `ABSTRACTOBSERVER_GATEWAY_URL` (or `ABSTRACTGATEWAY_URL`) — the Gateway this server signs in to and proxies `/api` to (default `http://127.0.0.1:8080`)
-- `--monitor-gpu` or `ABSTRACTOBSERVER_MONITOR_GPU=on` (enables the optional GPU widget)
+- `--gateway-url <url>` (aliases `--gateway`, `--url`) — the Gateway this server
+  signs in to and proxies `/api` to. Default: the gateway installed on this
+  computer (`~/.abstractframework/gateway.json`, followed when it moves port),
+  else `http://127.0.0.1:8080`.
+- `--port <n>` (default `3001`) and `--host <addr>` (default `127.0.0.1`)
+- `--monitor-gpu` — the optional GPU widget
+- `--entity-app-url <url>` — where the entity app lives (the "Entities ↗" links)
+- `--gateway-dir <dir>` — base for relative run workspace paths (local folder reveal)
+
+Environment variables are legacy aliases below the flags: `PORT`, `HOST`,
+`ABSTRACTOBSERVER_GATEWAY_URL`, `ABSTRACTGATEWAY_URL`,
+`ABSTRACTOBSERVER_MONITOR_GPU`, `ABSTRACTOBSERVER_ENTITY_APP_URL`,
+`ABSTRACTOBSERVER_GATEWAY_DIR`.
+
+The gateway can also serve the Observer through itself at `/apps/observer/`
+(one port and one address for the console, the API and the apps, e.g. on a
+remote server): the gateway starts this server on `127.0.0.1` and relays to
+it. `abstractobserver --help` lists the flags.
 
 See `docs/configuration.md` for the full list.
 
@@ -90,10 +104,12 @@ See `docs/configuration.md` for the full list.
 All pages share the same gateway connection settings.
 
 - **Board** (Mission Control, the landing page): kanban columns Pending / Working / Review / Done across every run — cards move themselves by state; the Review column carries inline Approve/Deny/Answer; an entities strip shows each entity's phase and links into the entity app; run lists poll live (5s visible / 30s hidden)
-- **Observe**: workflow/subworkflow navigator, overview, human timeline, raw ledger, provider calls, graph, digest, attachments, chat (optional voice: PTT + TTS)
-- **Runtime**: Activity, Artifacts, Memory, and Logs modes for platform-level monitoring. The Artifact Explorer uses Gateway artifact envelopes and exact stats, separates Voice/Music/Sound/unclassified audio from render kinds such as Markdown/HTML/JSON, previews media inline, and links artifacts back to producing runs, ledgers, and trace/audit actions when metadata is available
-- **Launch**: start runs, schedule runs, bundle upload/reload
-- **Runtime → Memory**: knowledge-graph (active memory) query UI (requires `POST /api/gateway/kg/query`)
+- **Observe**: workflow/subworkflow navigator, overview, human timeline, raw ledger, provider calls, graph, digest, attachments, **Ask** about the run (the whole conversation is sent; a note says when the gateway's 50,000-token window left older messages out; optional voice: PTT + TTS)
+- **Assistant** (top bar): questions about the Observer itself, from its docs; one gateway session per conversation (**New conversation** starts fresh), no tools
+- **System** (the Runtime view): Activity, Artifacts, Memory, and Logs modes for platform-level monitoring. The Artifact Explorer uses Gateway artifact envelopes and exact stats, separates Voice/Music/Sound/unclassified audio from render kinds such as Markdown/HTML/JSON, previews media inline, and links artifacts back to producing runs, ledgers, and trace/audit actions when metadata is available
+- **Launch**: Run once, or Automate (what, when in UTC intervals, independent or growing context, tool approval); bundle upload/reload
+- **Automations**: every automation of the signed-in user, with pause/resume/run now (also while paused)/stop current/edit (task, interval, context, tools — the row's Edit opens the form at once)/archive, its runs read as a conversation, answers to waiting runs by kind (question, tool approval, event), its folder browsable from the browser (open or download through the gateway), and Discuss (a chat, on the same page, with a fork at an occurrence: its full history, its own workspace and the automation's files read-only); legacy schedules keep their controls and can be recreated as automations (`docs/automations.md`)
+- **System → Memory**: knowledge-graph (active memory) query UI (requires `POST /api/gateway/kg/query`)
 - **Settings**: connection status, theme and display preferences, optional remote tool worker
 - **About** (the info button in the top bar): the AbstractObserver version, links to its website, source, documentation and issue tracker, and the versions the connected gateway reports
 
@@ -104,6 +120,8 @@ All pages share the same gateway connection settings.
 - Architecture (with diagrams): `docs/architecture.md`
 - Configuration & deployment: `docs/configuration.md`
 - API (gateway endpoints used): `docs/api.md`
+- Automations (create, manage, answer, discuss): `docs/automations.md`
+- Troubleshooting: `docs/troubleshooting.md`
 - Development: `docs/development.md`
 - Security & trust boundaries: `docs/security.md`
 

package/bin/cli.js

@@ -1,275 +1,65 @@
 #!/usr/bin/env node
 
 /**
- * CLI entry point for AbstractObserver
- * Serves the built web application on a configurable port
+ * AbstractObserver: serves the built app. Standalone at http://<host>:<port>/,
+ * or through the gateway at /apps/observer/ (the gateway relays to this
+ * server on 127.0.0.1; see bin/server.js).
+ *
+ *   abstractobserver [--gateway-url <url>] [--port <n>] [--host <addr>]
+ *                    [--monitor-gpu] [--entity-app-url <url>] [--gateway-dir <dir>]
+ *
+ * Environment variables are legacy aliases below the flags (PORT, HOST,
+ * ABSTRACTOBSERVER_GATEWAY_URL, ABSTRACTGATEWAY_URL, ABSTRACTOBSERVER_MONITOR_GPU,
+ * ABSTRACTOBSERVER_ENTITY_APP_URL, ABSTRACTOBSERVER_GATEWAY_DIR).
  */
 
-import * as http from 'http';
-import { readFileSync, existsSync, statSync } from 'fs';
-import { join, extname, dirname, resolve, isAbsolute } from 'path';
-import { fileURLToPath } from 'url';
-import { spawn } from 'child_process';
-import { createGatewaySessionProxy } from '@abstractframework/app-server';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const DIST_DIR = join(__dirname, '..', 'dist');
-const PORT = process.env.PORT || 3001;
-const HOST = process.env.HOST || '0.0.0.0';
-// ONE app since the 2026-07-12 split: the entity view moved to its own
-// package (abstractentity, :3007). The ABSTRACTOBSERVER_LANDING knob died
-// with it — this server always lands on index.html.
-const DEFAULT_GATEWAY_URL = String(process.env.ABSTRACTOBSERVER_GATEWAY_URL || process.env.ABSTRACTGATEWAY_URL || 'http://127.0.0.1:8080').trim().replace(/\/+$/, '') || 'http://127.0.0.1:8080';
-// Where the ENTITY app lives — drives the "Entities ↗" links in the UI.
-// Normalized to origin+path (query/hash dropped): both consumers append
-// their own query (`/entity.html` redirect here, deep links in the UI),
-// so a configured value carrying `?` would produce malformed URLs.
-const ENTITY_APP_URL = (() => {
-  const raw = String(process.env.ABSTRACTOBSERVER_ENTITY_APP_URL || '').trim();
-  if (!raw) return '';
-  try {
-    const u = new URL(raw);
-    return `${u.origin}${u.pathname}`.replace(/\/+$/, '');
-  } catch {
-    return raw.split(/[?#]/)[0].replace(/\/+$/, '');
-  }
-})();
-const ARGV = process.argv.slice(2);
-const MONITOR_GPU =
-  ARGV.includes("--monitor-gpu") ||
-  ["1", "true", "yes", "on"].includes(String(process.env.ABSTRACTOBSERVER_MONITOR_GPU || "").trim().toLowerCase());
-
-// MIME types for common file extensions
-const MIME_TYPES = {
-  '.html': 'text/html',
-  '.js': 'application/javascript',
-  '.css': 'text/css',
-  '.json': 'application/json',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.svg': 'image/svg+xml',
-  '.ico': 'image/x-icon',
-  '.webmanifest': 'application/manifest+json',
-};
-
-function getMimeType(filePath) {
-  const ext = extname(filePath).toLowerCase();
-  return MIME_TYPES[ext] || 'application/octet-stream';
-}
-
-function inject_config_html(html) {
-  const ui_config = {};
-  if (MONITOR_GPU) ui_config.monitor_gpu = true;
-  // THIS deployment's gateway (maintainer incident 2026-07-09: the sign-in
-  // card showed a retired gateway's URL) — the UI's connect/sign-in surfaces
-  // default to it instead of any hardcoded historical port.
-  if (DEFAULT_GATEWAY_URL) ui_config.gateway_url = DEFAULT_GATEWAY_URL;
-  if (ENTITY_APP_URL) ui_config.entity_app_url = ENTITY_APP_URL;
-  if (!Object.keys(ui_config).length) return html;
-  const marker = "window.__ABSTRACT_UI_CONFIG__";
-  if (html.includes(marker)) return html;
-  const snippet = `<script>${marker}=Object.assign(${marker}||{}, ${JSON.stringify(ui_config)});</script>`;
-  if (html.includes("</head>")) return html.replace("</head>", `${snippet}\n</head>`);
-  if (html.includes("</body>")) return html.replace("</body>", `${snippet}\n</body>`);
-  return `${html}\n${snippet}\n`;
-}
-
-function serveFile(res, filePath) {
-  try {
-    if (!existsSync(filePath) || !statSync(filePath).isFile()) {
-      return false;
-    }
-    const mimeType = getMimeType(filePath);
-
-    if (mimeType === "text/html") {
-      const html = readFileSync(filePath, "utf8");
-      const content = inject_config_html(html);
-      res.writeHead(200, {
-        "Content-Type": `${mimeType}; charset=utf-8`,
-        "Cache-Control": "no-cache",
-      });
-      res.end(content);
-      return true;
-    }
-
-    const content = readFileSync(filePath);
-    res.writeHead(200, {
-      'Content-Type': mimeType,
-      'Cache-Control': 'no-cache',
-    });
-    res.end(content);
-    return true;
-  } catch (err) {
-    return false;
-  }
-}
-
-// APP-ORIGIN GATEWAY SESSION PROXY - the shared @abstractframework/app-server
-// module (extracted from this file's hardened copy; one source across
-// observer/flow/abstractcode per the 2026-07-12 consolidation). Cookie names
-// (abstractobserver_gateway_*), the x-abstractobserver-csrf header, and the
-// ABSTRACTOBSERVER_* / ABSTRACTGATEWAY_* env gates are all derived from appId,
-// so existing sessions and deployment security posture survive the swap.
-const gatewaySessionProxy = createGatewaySessionProxy({
-  appId: 'abstractobserver',
-  defaultGatewayUrl: DEFAULT_GATEWAY_URL,
-});
-
-// ── LOCAL FOLDER REVEAL (operator 2026-07-15: a folder button on the run
-// opens its workspace). Only meaningful when this server runs on the SAME
-// machine as the gateway (the local-first posture). Gateway workspace roots
-// are often RELATIVE to the gateway process cwd — resolve against
-// ABSTRACTOBSERVER_GATEWAY_DIR (default: the workspace parent this repo
-// lives in, matching the launcher layout).
-const GATEWAY_DIR = String(process.env.ABSTRACTOBSERVER_GATEWAY_DIR || join(__dirname, '..', '..')).trim();
-
-function resolveWorkspacePath(raw) {
-  const p = String(raw || '').trim();
-  if (!p || p.includes('\0')) return null;
-  const abs = isAbsolute(p) ? p : resolve(GATEWAY_DIR, p);
-  try {
-    if (existsSync(abs) && statSync(abs).isDirectory()) return abs;
-  } catch {}
-  return null;
-}
-
-function handleRevealRequest(req, res, pathname) {
-  if (pathname !== '/api/local/reveal' || req.method !== 'POST') return false;
-  // Loopback only: revealing Finder windows on a remotely-served observer
-  // is someone else's desktop. The socket peer is the truth (Host spoofable).
-  const peer = String(req.socket?.remoteAddress || '');
-  const loopback = peer === '127.0.0.1' || peer === '::1' || peer === '::ffff:127.0.0.1';
-  if (!loopback) {
-    res.writeHead(403, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({ ok: false, error: 'Folder reveal is only available on the machine running the observer.' }));
-    return true;
-  }
-  let body = '';
-  req.on('data', (c) => { body += c; if (body.length > 8192) req.destroy(); });
-  req.on('end', () => {
-    let path = '';
-    try { path = String(JSON.parse(body || '{}').path || ''); } catch {}
-    const abs = resolveWorkspacePath(path);
-    if (!abs) {
-      res.writeHead(404, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ ok: false, error: `Workspace folder not found on this machine: ${path || '(empty)'}` }));
-      return;
-    }
-    const cmd = process.platform === 'darwin' ? 'open' : 'xdg-open';
-    try {
-      // `open <dir>` reveals a folder; never a shell, never arbitrary exec.
-      spawn(cmd, [abs], { stdio: 'ignore', detached: true }).unref();
-      res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ ok: true, path: abs }));
-    } catch (e) {
-      res.writeHead(500, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ ok: false, error: String(e && e.message || e) }));
-    }
-  });
-  return true;
-}
-
-const server = http.createServer((req, res) => {
-  // Remove query strings and normalize path
-  const url = new URL(req.url, `http://${req.headers.host}`);
-  let pathname = url.pathname;
-
-  // Local-machine folder reveal (before the proxy: /api/local/* is OURS,
-  // never forwarded to the gateway).
-  if (handleRevealRequest(req, res, pathname)) {
-    return;
-  }
-
-  // Connection endpoint + everything under /api/ (proxied to the gateway
-  // with session cookies swapped for gateway headers).
-  if (gatewaySessionProxy.handle(req, res, pathname)) {
-    return;
-  }
-  
-  // Security: prevent directory traversal
-  if (pathname.includes('..')) {
-    res.writeHead(400);
-    res.end('Bad Request');
-    return;
-  }
-
-  if (pathname === '/' || pathname === '') {
-    pathname = '/index.html';
-  }
-
-  // Try to serve the requested file
-  let filePath = join(DIST_DIR, pathname);
-  
-  if (serveFile(res, filePath)) {
-    return;
-  }
-
-  // An EXPLICIT .html request that misses must fail loudly, never fall
-  // through to the SPA fallback (maintainer incident 2026-07-09: the wrong
-  // app wearing the right URL is worse than a 404). /entity.html was real
-  // here before the 2026-07-12 split — send old bookmarks to the entity
-  // app's own deployment when we know it, otherwise say where it went.
-  if (pathname.endsWith('.html')) {
-    if (pathname === '/entity.html' && ENTITY_APP_URL) {
-      res.writeHead(302, { Location: `${ENTITY_APP_URL}/${url.search || ''}` });
-      res.end();
-      return;
-    }
-    res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
-    res.end(
-      pathname === '/entity.html'
-        ? 'The entity app moved to its own package (abstractentity, default http://127.0.0.1:3007). '
-          + 'Set ABSTRACTOBSERVER_ENTITY_APP_URL to make this a redirect.'
-        : `${pathname} is not in this build (dist/). This server hosts the AbstractObserver app only.`
-    );
-    return;
-  }
-
-  // Try with .html extension
-  if (serveFile(res, filePath + '.html')) {
-    return;
-  }
-
-  // Try index.html in directory
-  if (serveFile(res, join(filePath, 'index.html'))) {
-    return;
-  }
-
-  // SPA fallback
-  const indexPath = join(DIST_DIR, 'index.html');
-  if (serveFile(res, indexPath)) {
-    return;
-  }
-
-  // If nothing works, return 404
-  res.writeHead(404);
-  res.end('Not Found');
+import * as http from "node:http";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { createGatewayUrlResolver, parseAppFlagsOrExit } from "@abstractframework/app-server";
+
+import { createObserverHandler } from "./server.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TRUE = ["1", "true", "yes", "on"];
+
+const flags = parseAppFlagsOrExit(process.argv.slice(2), {
+  appName: "AbstractObserver",
+  command: "abstractobserver",
+  envPrefix: "ABSTRACTOBSERVER",
+  defaultPort: 3001,
+  extra: {
+    "monitor-gpu": { type: "boolean", help: "Show the gateway host's GPU monitor in the header." },
+    "entity-app-url": { type: "string", metavar: "url", help: "Where the entity app lives (the Entities ↗ links)." },
+    "gateway-dir": {
+      type: "string",
+      metavar: "dir",
+      help: "Folder that relative workspace roots are resolved against for the local folder reveal (default: this package's parent folder).",
+    },
+  },
 });
 
-server.listen(PORT, HOST, () => {
-  console.log(`
-╔════════════════════════════════════════════════════╗
-║         AbstractObserver is running!               ║
-╚════════════════════════════════════════════════════╝
-
-  🌐 Local:   http://localhost:${PORT}
-  🌐 Network: http://${HOST}:${PORT}
-
-  📡 Connect to your AbstractGateway instance
-  🚀 Start observing your workflows
-
-  Press Ctrl+C to stop
-`);
+// The gateway URL follows the local gateway pointer (a gateway that moves
+// port is followed) unless a flag or a legacy variable chose it.
+const gatewayUrl =
+  flags.gatewayUrlSource === "flag" || flags.gatewayUrlSource.startsWith("env:")
+    ? flags.gatewayUrl
+    : createGatewayUrlResolver({});
+
+const handler = createObserverHandler({
+  distDir: join(HERE, "..", "dist"),
+  gatewayUrl,
+  monitorGpu: Boolean(flags.extra["monitor-gpu"]) || TRUE.includes(String(process.env.ABSTRACTOBSERVER_MONITOR_GPU || "").trim().toLowerCase()),
+  entityAppUrl: String(flags.extra["entity-app-url"] || process.env.ABSTRACTOBSERVER_ENTITY_APP_URL || ""),
+  gatewayDir: String(flags.extra["gateway-dir"] || process.env.ABSTRACTOBSERVER_GATEWAY_DIR || join(HERE, "..", "..")),
 });
 
-process.on('SIGINT', () => {
-  console.log('\n\n👋 Shutting down AbstractObserver...\n');
-  process.exit(0);
+const server = http.createServer(handler);
+server.listen(flags.port, flags.host, () => {
+  const gw = typeof gatewayUrl === "string" ? gatewayUrl : gatewayUrl.current();
+  console.log(`AbstractObserver on http://${flags.host}:${flags.port}/ (gateway ${gw}, ${flags.gatewayUrlSource})`);
+  console.log("Through the gateway: <gateway>/apps/observer/");
 });
 
-process.on('SIGTERM', () => {
-  console.log('\n\n👋 Shutting down AbstractObserver...\n');
-  process.exit(0);
-});
+for (const signal of ["SIGINT", "SIGTERM"]) process.on(signal, () => process.exit(0));

package/bin/server.js

@@ -0,0 +1,222 @@
+/**
+ * The AbstractObserver app server: serves the built app (dist/), the local
+ * folder reveal and the app-origin gateway session proxy, standalone at `/`
+ * or through the gateway at `/apps/observer/` (the app-server mount
+ * contract: @abstractframework/app-server README, "Serving under the gateway").
+ *
+ * - Every response announces `X-AbstractFramework-App: observer; mount=1`
+ *   (`createMountedHandler`), so the gateway may serve it.
+ * - "Who is asking" is `ctx.clientAddress` / `ctx.clientIsLoopback`, never the
+ *   socket peer (behind the gateway the socket peer is always loopback).
+ * - The page gets `<base href="<basePath>/">` and `base_path` in
+ *   `window.__ABSTRACT_UI_CONFIG__` (`injectShell`); the app's URLs are
+ *   relative, so they resolve under the base.
+ * - The session proxy sets its cookies at `Path=<basePath>/`.
+ */
+
+import { timingSafeEqual } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { extname, isAbsolute, normalize, resolve, sep } from "node:path";
+import { spawn as nodeSpawn } from "node:child_process";
+
+import { createGatewaySessionProxy, createMountedHandler, injectShell } from "@abstractframework/app-server";
+
+/** The gateway catalog id this app announces. */
+export const APP_ID = "observer";
+/** Cookie / CSRF prefix of the session proxy (kept: existing sessions survive). */
+export const COOKIE_APP_ID = "abstractobserver";
+
+const MIME_TYPES = {
+  ".html": "text/html",
+  ".js": "application/javascript",
+  ".css": "text/css",
+  ".json": "application/json",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".webmanifest": "application/manifest+json",
+};
+
+function mimeType(filePath) {
+  return MIME_TYPES[extname(filePath).toLowerCase()] || "application/octet-stream";
+}
+
+function json(res, status, body) {
+  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify(body));
+}
+
+/** Origin + path of a configured app URL (query and hash dropped). */
+export function normalizeAppUrl(raw) {
+  const value = String(raw || "").trim();
+  if (!value) return "";
+  try {
+    const u = new URL(value);
+    return `${u.origin}${u.pathname}`.replace(/\/+$/, "");
+  } catch {
+    return value.split(/[?#]/)[0].replace(/\/+$/, "");
+  }
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.distDir          the built app
+ * @param {string | {current(): string, refresh(): boolean}} options.gatewayUrl  the server-pinned gateway
+ * @param {boolean} [options.monitorGpu]
+ * @param {string} [options.entityAppUrl]   where the entity app lives (Entities ↗ links)
+ * @param {string} options.gatewayDir       base for RELATIVE workspace roots (folder reveal)
+ * @param {Function} [options.spawn]        child_process.spawn (tests inject a recorder)
+ * @returns {(req, res) => void} the request handler
+ */
+export function createObserverHandler(options) {
+  const distDir = resolve(options.distDir);
+  const entityAppUrl = normalizeAppUrl(options.entityAppUrl);
+  const spawn = options.spawn || nodeSpawn;
+  const proxy = createGatewaySessionProxy({ appId: COOKIE_APP_ID, defaultGatewayUrl: options.gatewayUrl });
+
+  function uiConfig() {
+    const config = { gateway_url: proxy.defaultGatewayUrl };
+    if (options.monitorGpu) config.monitor_gpu = true;
+    if (entityAppUrl) config.entity_app_url = entityAppUrl;
+    return config;
+  }
+
+  /** A file under dist/, or null (never outside it). */
+  function distFile(pathname) {
+    const rel = normalize(decodeURIComponent(pathname)).replace(/^([/\\])+/, "");
+    const abs = resolve(distDir, rel);
+    if (abs !== distDir && !abs.startsWith(distDir + sep)) return null;
+    try {
+      return existsSync(abs) && statSync(abs).isFile() ? abs : null;
+    } catch {
+      return null;
+    }
+  }
+
+  function serve(res, filePath, ctx) {
+    const type = mimeType(filePath);
+    if (type === "text/html") {
+      const page = injectShell(readFileSync(filePath, "utf8"), { basePath: ctx.basePath, config: uiConfig() });
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-cache" });
+      res.end(page);
+      return;
+    }
+    res.writeHead(200, { "Content-Type": type, "Cache-Control": "no-cache" });
+    res.end(readFileSync(filePath));
+  }
+
+  function servePage(res, ctx) {
+    const index = distFile("index.html");
+    if (!index) return json(res, 500, { detail: "dist/index.html is missing: build the app (npm run build)." });
+    return serve(res, index, ctx);
+  }
+
+  function resolveWorkspacePath(raw) {
+    const p = String(raw || "").trim();
+    if (!p || p.includes("\0")) return null;
+    const abs = isAbsolute(p) ? p : resolve(options.gatewayDir, p);
+    try {
+      return existsSync(abs) && statSync(abs).isDirectory() ? abs : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * The rule of every mutating route of this origin (the session proxy's):
+   * the request presents the browser session's CSRF token in the app CSRF
+   * header (`X-AbstractObserver-CSRF`, or the canonical `X-Abstract-CSRF`),
+   * which a cross-site page can neither read nor send; and a request that
+   * names its `Origin` names this one. Returns the refusal, or null.
+   */
+  function crossSiteRefusal(req, ctx) {
+    const origin = String(req.headers.origin || "").trim();
+    if (origin && origin !== `${ctx.proto}://${ctx.host}`) return "Cross-site request refused.";
+    const expected = proxy.browserSession(req).csrfToken;
+    const presented = String(proxy.csrfHeaderNames.map((h) => req.headers[h]).find((v) => v) || "").trim();
+    const a = Buffer.from(presented, "utf8");
+    const b = Buffer.from(String(expected || ""), "utf8");
+    if (!expected || a.length !== b.length || !timingSafeEqual(a, b)) return "Browser session CSRF token missing or invalid.";
+    return null;
+  }
+
+  /** Open a run's folder on THIS machine: only for a browser on this machine, from this app's own page. */
+  function reveal(req, res, ctx) {
+    if (!ctx.clientIsLoopback) {
+      json(res, 403, { ok: false, error: "Folder reveal is only available on the machine running the observer." });
+      return;
+    }
+    const refused = crossSiteRefusal(req, ctx);
+    if (refused) {
+      json(res, 403, { ok: false, error: refused, reason_code: "csrf_required" });
+      return;
+    }
+    let body = "";
+    req.on("data", (c) => {
+      body += c;
+      if (body.length > 8192) req.destroy();
+    });
+    req.on("end", () => {
+      let path = "";
+      try {
+        path = String(JSON.parse(body || "{}").path || "");
+      } catch {
+        path = "";
+      }
+      const abs = resolveWorkspacePath(path);
+      if (!abs) {
+        json(res, 404, { ok: false, error: `Workspace folder not found on this machine: ${path || "(empty)"}` });
+        return;
+      }
+      try {
+        // `open <dir>` / `xdg-open <dir>`: never a shell, never arbitrary exec.
+        spawn(process.platform === "darwin" ? "open" : "xdg-open", [abs], { stdio: "ignore", detached: true }).unref();
+        json(res, 200, { ok: true, path: abs });
+      } catch (e) {
+        json(res, 500, { ok: false, error: String((e && e.message) || e) });
+      }
+    });
+  }
+
+  return createMountedHandler({ appId: APP_ID }, (req, res, ctx) => {
+    const url = new URL(req.url || "/", "http://observer.invalid");
+    const pathname = url.pathname;
+
+    // /api/local/* is OURS (never forwarded to the gateway).
+    if (pathname === "/api/local/reveal" && req.method === "POST") return reveal(req, res, ctx);
+    // Connection endpoint + everything under /api/ (session swapped for gateway credentials).
+    if (proxy.handle(req, res, pathname)) return;
+
+    if (pathname === "/" || pathname === "/index.html") return servePage(res, ctx);
+    const file = distFile(pathname);
+    if (file) return serve(res, file, ctx);
+
+    // An explicit .html that misses fails loudly, never the SPA fallback.
+    if (pathname.endsWith(".html")) {
+      if (pathname === "/entity.html" && entityAppUrl) {
+        res.writeHead(302, { Location: `${entityAppUrl}/${url.search || ""}` });
+        res.end();
+        return;
+      }
+      res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end(
+        pathname === "/entity.html"
+          ? "The entity app moved to its own package (abstractentity, default http://127.0.0.1:3007). Start the observer with --entity-app-url to make this a redirect."
+          : `${pathname} is not in this build (dist/). This server hosts the AbstractObserver app only.`
+      );
+      return;
+    }
+    // An asset that is not in the build is a 404, never the page.
+    if (extname(pathname)) {
+      res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end("Not Found");
+      return;
+    }
+    // SPA fallback (deep links such as /<run id>): the page, under the same base.
+    return servePage(res, ctx);
+  });
+}
+