@tonyclaw/agent-inspector 3.0.45 → 3.0.46

package/README.md

@@ -55,10 +55,11 @@ and defaults to a 64 MiB hard limit and a 120 second body deadline; override the
 integer byte/millisecond values in `AGENT_INSPECTOR_MAX_REQUEST_BYTES` and
 `AGENT_INSPECTOR_REQUEST_TIMEOUT_MS` when a trusted workload requires different bounds.
 
-`@tonyclaw/agent-inspector` runs the local UI, proxy, REST API, storage, and built-in
-`/api/mcp` endpoint. `@tonyclaw/agent-inspector-mcp` is the enhancement package for
-stdio-first MCP clients and setup automation; it bridges to the local Inspector endpoint without
-moving your captured evidence out of the machine.
+`@tonyclaw/agent-inspector` runs the proxy, REST/SSE API, storage, and built-in `/api/mcp`
+endpoint. Its default composed mode also serves the independently built UI; `--backend-only`
+leaves every Coding Agent endpoint running without UI files. `@tonyclaw/agent-inspector-mcp` is the
+enhancement package for stdio-first MCP clients and setup automation; it bridges to the local
+Inspector endpoint without moving your captured evidence out of the machine.
 
 On Windows, the npm install step creates a local `agent-inspector.exe` runtime
 from the user's installed Node.js runtime. The long-running server process
@@ -84,20 +85,20 @@ agent-inspector onboard
 
 The onboarding command installs guided setup skills for local agents:
 
-The generated instructions and automatically merged MCP entries derive the Inspector Base URL from
-the default CLI origin (`http://localhost:9527`) and `AGENT_INSPECTOR_BASE_PATH`. The default is
-`http://localhost:9527/inspector`. This Inspector Base URL is separate from each Provider's upstream
-Base URL.
+The generated instructions and automatically merged MCP entries derive the backend Base URL from
+`AGENT_INSPECTOR_PUBLIC_ORIGIN` (or the default local CLI origin) plus
+`AGENT_INSPECTOR_BASE_PATH`. The default is `http://localhost:9527/inspector`. This control/agent
+Base URL is separate from both the optional UI URL and each Provider's upstream Base URL.
 
 - Claude Code: `~/.claude/skills/agent-inspector-onboard/SKILL.md` plus a slash command.
 - Codex: `~/.codex/skills/agent-inspector-onboard/SKILL.md`, focused on connecting
-  `<inspector-base-url>/api/mcp` through Codex `mcp_servers.agent-inspector`.
+  `<agent-base-url>/api/mcp` through Codex `mcp_servers.agent-inspector`.
 - OpenCode: run `agent-inspector onboard --opencode-only` to merge
   `mcp.agent-inspector` into `~/.config/opencode/opencode.json` or `opencode.jsonc`, then verify
   with `opencode mcp list`.
 - MiMo Code: run `agent-inspector onboard --mimo-only` to merge `mcp.agent-inspector` into
   `~/.config/mimocode/mimocode.jsonc` or `mimocode.json`, then route MiMo through the proxy with
-  `OPENAI_BASE_URL=<inspector-base-url>/proxy/v1`.
+  `OPENAI_BASE_URL=<agent-base-url>/proxy/v1`.
 
 During npm global install, Agent Inspector also makes a best-effort onboarding skill install for
 detected local agents. If `~/.claude` exists, it installs the Claude Code skill and slash command.
@@ -128,13 +129,20 @@ registered Windows instance or an explicit wrapper URL:
 agent-inspector onboard --instance review --force
 agent-inspector onboard --instance review --mcp-name agent-inspector-review --opencode-only --force
 agent-inspector onboard --base-url https://tools.example.test/inspector --mcp-name team-inspector --force
+agent-inspector onboard --control-base-url https://control.example.test/inspector `
+  --agent-base-url https://agent.example.test/inspector `
+  --ui-url https://ui.example.test/observe --mcp-name team-inspector --force
+agent-inspector onboard --control-base-url https://control.example.test/inspector `
+  --agent-base-url https://agent.example.test/inspector --no-ui --force
 ```
 
 `--instance` resolves the saved instance URL and defaults the MCP config key to
-`agent-inspector-<instance>`. `--base-url` accepts a credential-free HTTP(S) Inspector Base URL and
-is mutually exclusive with `--instance`. `--mcp-name` selects the exact MCP config key, allowing the
-generated config to preserve other Inspector entries. Explicit per-client MCP URL options still
-take precedence over the resolved target.
+`agent-inspector-<instance>`. `--base-url` accepts a credential-free HTTP(S) backend control/agent
+Base URL as a compatibility shortcut; it does not imply that a browser UI exists. Separated
+deployments can set `--control-base-url`, `--agent-base-url`, and either `--ui-url` or `--no-ui`.
+`--instance` is mutually exclusive with every explicit URL option. `--mcp-name` selects the exact MCP
+config key, allowing the generated config to preserve other Inspector entries. Explicit per-client
+MCP URL options still take precedence over the resolved target.
 
 Before uninstalling the npm package, run `agent-inspector onboard --uninstall` to remove matching
 generated onboarding files. The uninstall command only removes Agent Inspector generated files whose
@@ -149,6 +157,111 @@ bun install
 bun run dev
 ```
 
+### Deployment modes and runtime Base URLs
+
+Agent Inspector ships one compatible UI/backend release but can run it in three topologies:
+
+| Mode | Start | UI | Coding Agent surfaces |
+| --- | --- | --- | --- |
+| Composed (default) | `agent-inspector` | Served by the protected public ingress | REST, SSE, proxy, health, and MCP use the same public backend Base URL. |
+| Backend-only | `agent-inspector --backend-only --no-open` | Not served; document requests return a bounded headless response | REST, SSE, proxy, health, MCP, capture, and named-instance control remain available. |
+| Standalone UI | Build/host `.output/ui` with SPA fallback | Served by a separate static host | The UI reads operator runtime configuration and calls an explicitly configured backend. |
+
+Do not use "Inspector Base URL" to mean every surface implicitly. The browser-safe runtime
+contract keeps three locations explicit:
+
+- UI Base Path: router/asset mount for the static UI.
+- Control Base URL: REST, uploads/downloads, mutations, and log SSE.
+- Agent Base URL: model proxy, OpenAI-compatible `/proxy/v1`, and MCP guidance.
+
+Composed and backend-only deployments currently publish the same backend Base URL for control and
+agent traffic, but clients must still use the corresponding runtime field. A separately hosted UI
+has its own origin and mount path. `GET <control-base-url>/api/runtime` returns a versioned,
+token-free, `no-store` discovery document with deployment mode and capabilities.
+
+The static UI loads `runtime-config.js` before the application bundle. For a separately hosted UI,
+replace `.output/ui/runtime-config.js` with an operator-owned value such as:
+
+```js
+window.__AGENT_INSPECTOR_RUNTIME_CONFIG__ = {
+  schemaVersion: 1,
+  deploymentMode: "separated",
+  ui: { basePath: "/" },
+  control: { baseUrl: "http://127.0.0.1:19527/inspector" },
+  agent: { baseUrl: "http://127.0.0.1:19527/inspector" },
+  capabilities: { rest: true, sse: true, proxy: true, mcp: true },
+};
+```
+
+Replace the example URLs with the exact backend URLs printed by the CLI or returned by
+`agent-inspector instance connect <name> --json`. Base URLs must be credential-free HTTP(S) URLs
+without query or fragment. Never put Provider keys, control tokens, or proxy tokens in
+`runtime-config.js`, bootstrap HTML, query strings, or browser storage.
+
+The standalone static host must send a CSP whose `connect-src` contains only `'self'` and the exact
+configured control origin; never use `*`. Composed mode generates a same-origin CSP at the protected
+ingress. If the control Base URL changes, update `runtime-config.js` and CSP together.
+
+For a local UI that directly calls another local origin, set a comma-separated exact loopback
+allowlist on the protected backend, for example:
+
+```bash
+AGENT_INSPECTOR_UI_ORIGINS=http://127.0.0.1:4173,http://localhost:4173 agent-inspector --backend-only
+```
+
+`AGENT_INSPECTOR_UI_ORIGINS` accepts only exact `http`/`https` loopback origins: no wildcard,
+credentials, path, query, fragment, or non-loopback hostname. It enables the control API/SSE CORS
+path only; browser CORS access to `/proxy` and `/api/mcp` stays forbidden. A non-loopback remote UI
+must use an authenticated same-origin gateway that protects the public edge and forwards to the
+loopback Inspector backend. Do not use the loopback CORS allowlist as remote authentication.
+
+When a reverse proxy changes the browser-visible scheme/host/port, set the exact external origin
+separately from the Base Path:
+
+```bash
+AGENT_INSPECTOR_PUBLIC_ORIGIN=https://tools.example.test \
+AGENT_INSPECTOR_BASE_PATH=/inspector \
+agent-inspector
+```
+
+`AGENT_INSPECTOR_PUBLIC_ORIGIN` is an origin only; it allows no credentials, path, query, or
+fragment. It drives request-local runtime discovery, copied endpoint guidance, and MCP outward URLs;
+the proxy must also be included in `AGENT_INSPECTOR_TRUSTED_HOSTS` when its hostname is not otherwise
+trusted.
+
+Independent source workflows:
+
+```bash
+bun run dev             # Windows-safe supervisor: backend dev server + UI dev server
+bun run dev:backend     # backend route tree only (development listener)
+bun run dev:ui          # static UI dev server; same-Base-Path proxy by default
+
+bun run build:backend   # .output/server
+bun run build:ui        # .output/ui
+bun run build           # both artifacts plus CLI/workers/MCP and boundary checks
+
+bun run start:backend   # protected production CLI in backend-only mode
+bun run preview:ui      # preview the independently built static UI
+```
+
+For a true separate-origin development UI, inject its runtime surfaces instead of relying on the
+same-Base-Path dev proxy:
+
+```bash
+AGENT_INSPECTOR_UI_BASE_PATH=/observe \
+AGENT_INSPECTOR_UI_CONTROL_BASE_URL=http://127.0.0.1:19527/inspector \
+AGENT_INSPECTOR_UI_AGENT_BASE_URL=http://127.0.0.1:19527/inspector \
+AGENT_INSPECTOR_UI_PORT=4173 bun run dev:ui
+```
+
+The backend must allow that exact local UI origin with `AGENT_INSPECTOR_UI_ORIGINS`. The explicit
+control/agent variables are used only by UI dev/preview; production static hosting continues to use
+the operator-owned `runtime-config.js` so one `.output/ui` artifact remains relocatable.
+
+The direct backend development listener is loopback-oriented and is not a replacement for the
+protected production ingress. An arbitrary static host must provide SPA fallback for supported deep
+links such as `/session/<id>`.
+
 Run a local health check when you need to verify the proxy and installed
 configuration:
 
@@ -164,19 +277,20 @@ only checked when you ask for them explicitly:
 agent-inspector doctor --chrome-extension
 ```
 
-Then point an AI coding tool at the proxy:
+Then point an AI coding tool at the agent Base URL reported by the CLI or connection descriptor:
 
 ```bash
 ANTHROPIC_BASE_URL=http://localhost:9527/inspector/proxy <tool>
 ```
 
-The web UI runs at http://localhost:9527/inspector by default. The public proxy endpoint is
-`http://localhost:9527/inspector/proxy`; internally Agent Inspector may run the app on a private
-helper port, but AI tools should use the public URL printed by the CLI.
+In default composed mode, the web UI runs at `http://localhost:9527/inspector`. The public proxy
+endpoint is `http://localhost:9527/inspector/proxy`; internally Agent Inspector may run the app on a
+private helper port, but AI tools should use the public URL printed by the CLI.
 
 When the dashboard has no captured requests, its copyable Claude, OpenCode, OpenAI, OpenAI `/v1`,
-and MCP examples are derived from the browser origin plus the configured runtime base path. They
-therefore continue to work when the public origin or base path differs from the default.
+and MCP examples are derived from the resolved browser runtime contract. They therefore use the
+configured agent surface even when the UI origin, backend origin, or Base Path differs from the
+default.
 
 ### Base path
 
@@ -186,13 +300,19 @@ Agent Inspector defaults to the `/inspector` public base path:
 agent-inspector
 ```
 
-This generates prefixed public URLs for the UI, assets, REST API, MCP, sessions, and model proxy:
+In composed mode this additionally generates these browser document/asset URLs:
 
 - Web UI: `http://localhost:9527/inspector`
 - Assets: `http://localhost:9527/inspector/assets/...`
+- Sessions: `http://localhost:9527/inspector/session/...`
+
+Both composed and backend-only modes keep these backend endpoints at the derived control/agent
+Base URL:
+
 - REST API: `http://localhost:9527/inspector/api/...`
+- Runtime discovery: `http://localhost:9527/inspector/api/runtime`
+- Health: `http://localhost:9527/inspector/api/health`
 - MCP: `http://localhost:9527/inspector/api/mcp`
-- Sessions: `http://localhost:9527/inspector/session/...`
 - Proxy: `http://localhost:9527/inspector/proxy`
 
 AI tools should use the prefixed proxy URL:
@@ -240,19 +360,20 @@ Windows; the command waits for readiness before returning. The existing `agent-i
 create an instance record.
 
 ```powershell
-agent-inspector instance start <name> [--port <port>] [--base-path <path>] [--host <host>] [--mode simple|full] [--data-dir <absolute-path>] [--open] [--json]
+agent-inspector instance start <name> [--port <port>] [--base-path <path>] [--host <host>] [--mode simple|full] [--data-dir <absolute-path>] [--backend-only|--with-ui] [--open] [--json]
 agent-inspector instance list [--json]
 agent-inspector instance status <name> [--json]
 agent-inspector instance connect <name> [--json]
 agent-inspector instance stop <name> [--json]
-agent-inspector instance restart <name> [--port <port>] [--base-path <path>] [--host <host>] [--mode simple|full] [--data-dir <absolute-path>] [--open] [--json]
+agent-inspector instance restart <name> [--port <port>] [--base-path <path>] [--host <host>] [--mode simple|full] [--data-dir <absolute-path>] [--backend-only|--with-ui] [--open] [--json]
 ```
 
 Names use lowercase letters, digits, dots, hyphens, and underscores; `default` is reserved for the
 existing unmanaged runtime. A first start without `--port` allocates an available public/private
 port pair. The pair and the other launch options are saved, so later `start` calls reuse the same
-configuration. Use `restart` with overrides to change a saved value. `--open` opens the UI after the
-background instance is ready, while `--json` produces token-free output suitable for PowerShell:
+configuration. Use `restart` with overrides to change a saved value. `--backend-only` persists a
+headless instance; `--with-ui` restores composed UI serving. `--open` is valid only when UI serving
+is enabled. `--json` produces token-free output suitable for PowerShell:
 
 ```powershell
 agent-inspector instance start review --base-path /inspector --json
@@ -262,9 +383,13 @@ $env:OPENAI_BASE_URL = $connection.environment.OPENAI_BASE_URL
 $review
 ```
 
-`connect` (also accepted as `connection`) returns the token-free connection descriptor: UI/API,
-health, Anthropic proxy, OpenAI `/v1` proxy, MCP URL, environment variables, an MCP server name, and
-a Codex Responses provider. In `--json` mode, success writes exactly one JSON document to stdout;
+`connect` (also accepted as `connection`) returns a token-free connection descriptor with explicit
+`surfaces.ui`, `surfaces.control`, and `surfaces.agent` locations. Use
+`surfaces.control.baseUrl` for REST/SSE and `surfaces.agent.baseUrl` for proxy/MCP setup;
+`surfaces.ui.baseUrl` is `null` when `surfaces.ui.enabled` is false. The descriptor also includes
+protocol-ready environment variables, MCP settings, and a Codex Responses provider. The top-level
+`uiEnabled`, `baseUrl`, and `endpoints` fields remain for compatibility, but new integrations should
+use `surfaces`. In `--json` mode, success writes exactly one JSON document to stdout;
 errors write exactly one `{ "schemaVersion": 1, "error": ... }` document to stderr with empty
 stdout. Exit code `0` means success, `1` means an operational/lifecycle failure or a reported
 conflict, and `2` means invalid command syntax or arguments. A `status`/`connect` conflict remains a
@@ -323,13 +448,14 @@ remote model-proxy traffic.
 Reverse proxies should preserve the configured prefix when forwarding public requests to Agent
 Inspector (`/inspector` by default).
 
-Treat the exact public Web UI URL printed by the CLI as `<inspector-base-url>`. Client endpoints are
-always derived from it:
+Treat the exact public backend URL printed by the CLI or connection descriptor as
+`<agent-base-url>` for Coding Agent endpoints. In composed mode it is also the UI URL; in
+backend-only or standalone-UI mode it is not. Client endpoints are derived from the agent surface:
 
-- Proxy: `<inspector-base-url>/proxy`
-- OpenAI-compatible `/v1` proxy: `<inspector-base-url>/proxy/v1`
-- MCP: `<inspector-base-url>/api/mcp`
-- Health: `<inspector-base-url>/api/health`
+- Proxy: `<agent-base-url>/proxy`
+- OpenAI-compatible `/v1` proxy: `<agent-base-url>/proxy/v1`
+- MCP: `<agent-base-url>/api/mcp`
+- Health: `<control-base-url>/api/health`
 
 For example, keep startup and onboarding aligned when using a custom prefix:
 
@@ -440,7 +566,8 @@ upstream URL failed.
 
 ## Named Instance Control For Coding Agents
 
-Every Inspector Base URL exposes a versioned, token-free Windows named-instance control contract.
+Every backend control Base URL exposes a versioned, token-free Windows named-instance control
+contract.
 The six endpoints are:
 
 | Method | Endpoint | Purpose |
@@ -453,12 +580,17 @@ The six endpoints are:
 | `POST` | `/api/instances/{name}/restart` | Restart with saved or validated replacement settings. |
 
 `start` and `restart` accept a strict optional JSON object containing `port`, `basePath`, `host`,
-`captureMode`, and `dataDir`; `stop` accepts only `{}`. Responses use `schemaVersion: 1`, never
-include lifecycle or Provider credentials, and send `Cache-Control: no-store`. Errors use the stable
-shape `{ "schemaVersion": 1, "error": { "code", "message", "retryable" } }` with `400`, `404`,
-`409`, `423`, or `503` according to the failure class. See the checked-in
+`captureMode`, `uiEnabled`, and `dataDir`; `stop` accepts only `{}`. Responses use `schemaVersion: 1`,
+never include lifecycle or Provider credentials, and send `Cache-Control: no-store`. Errors use the
+stable shape `{ "schemaVersion": 1, "error": { "code", "message", "retryable" } }` with `400`,
+`404`, `409`, `423`, or `503` according to the failure class. See the checked-in
 [OpenAPI 3.1 contract](docs/instance-control.openapi.yaml) for the complete schemas.
 
+Connection responses separate the optional browser surface from backend traffic:
+`surfaces.ui` has `{ enabled, baseUrl }`, while `surfaces.control.baseUrl` and
+`surfaces.agent.baseUrl` remain available for backend-only instances. Legacy top-level `baseUrl` and
+`endpoints` are retained for existing clients.
+
 Browser mutations require same-origin proof plus `x-agent-inspector-csrf: 1`. Direct non-loopback
 control calls require `Authorization: Bearer <AGENT_INSPECTOR_CONTROL_TOKEN>`. A managed instance
 cannot stop or restart itself through the REST/MCP transport it is currently serving; use the
@@ -468,8 +600,8 @@ launch was restored (`restart_failed_rolled_back`) or the instance remained degr
 
 ## MCP Evidence Workflows
 
-Agent Inspector exposes MCP at `<inspector-base-url>/api/mcp`. With the default public Inspector
-Base URL, that is:
+Agent Inspector exposes MCP from the backend agent Base URL at `<agent-base-url>/api/mcp`, whether
+or not a Web UI is served. With the default public backend Base URL, that is:
 
 ```text
 http://localhost:9527/inspector/api/mcp
@@ -490,7 +622,7 @@ The MCP HTTP surface is also documented as OpenAPI YAML in
 [`docs/mcp-openapi.yaml`](docs/mcp-openapi.yaml).
 
 Use only one transport for the same Inspector instance. If the MCP client supports Streamable HTTP,
-configure `<inspector-base-url>/api/mcp` directly. If it only supports stdio, configure
+configure `<agent-base-url>/api/mcp` directly. If it only supports stdio, configure
 `agent-inspector-mcp stdio`; that command is only a bridge to `/api/mcp`, not a second Inspector
 server.
 

package/docs/instance-control.openapi.yaml

@@ -4,7 +4,7 @@ info:
   version: 1.0.0
   description: |
     Local control-plane API for discovering and managing Windows named Agent Inspector instances.
-    Paths are relative to the selected Inspector Base URL. Loopback clients are trusted by the
+    Paths are relative to the selected backend control Base URL. Loopback clients are trusted by the
     native ingress; direct non-loopback clients must send the configured control Bearer token.
     Browser mutations also require same-origin CSRF proof. A reverse proxy whose upstream appears
     as loopback must authenticate its own remote clients.
@@ -191,6 +191,7 @@ components:
         - upstreamPort
         - basePath
         - captureMode
+        - uiEnabled
         - dataDir
         - supervisorPid
         - urls
@@ -218,6 +219,9 @@ components:
         upstreamPort: { type: integer, minimum: 1, maximum: 65535, example: 9532 }
         basePath: { type: string, example: /inspector }
         captureMode: { type: string, enum: [simple, full] }
+        uiEnabled:
+          type: boolean
+          description: Whether this instance serves the composed Web UI. Backend endpoints remain available when false.
         dataDir: { type: string, example: "C:\\Users\\me\\AppData\\Local\\agent-inspector\\instances\\review\\data" }
         supervisorPid:
           oneOf:
@@ -243,6 +247,9 @@ components:
         basePath: { type: string, example: /inspector }
         host: { type: string, example: "127.0.0.1" }
         captureMode: { type: string, enum: [simple, full] }
+        uiEnabled:
+          type: boolean
+          description: Persist composed UI serving when true or backend-only mode when false.
         dataDir: { type: string }
     InstanceOperation:
       type: object
@@ -256,15 +263,63 @@ components:
           enum: [created, started, already_running, stopped, already_stopped, restarted]
         instance:
           $ref: "#/components/schemas/InstanceView"
+    InstanceConnectionSurfaces:
+      type: object
+      additionalProperties: false
+      required: [ui, control, agent]
+      properties:
+        ui:
+          type: object
+          additionalProperties: false
+          required: [enabled, baseUrl]
+          properties:
+            enabled:
+              type: boolean
+              description: Whether this instance serves its composed Web UI.
+            baseUrl:
+              description: Composed UI Base URL, or null for a backend-only instance.
+              oneOf:
+                - { type: string, format: uri }
+                - { type: "null" }
+        control:
+          type: object
+          additionalProperties: false
+          required: [baseUrl]
+          properties:
+            baseUrl:
+              type: string
+              format: uri
+              description: Base URL for REST, mutation, upload/download, and SSE traffic.
+        agent:
+          type: object
+          additionalProperties: false
+          required: [baseUrl]
+          properties:
+            baseUrl:
+              type: string
+              format: uri
+              description: Base URL from which proxy and MCP client endpoints are derived.
     InstanceConnection:
       type: object
       additionalProperties: false
-      required: [schemaVersion, instance, baseUrl, endpoints, environment, mcp, codex]
+      required: [schemaVersion, uiEnabled, instance, surfaces, baseUrl, endpoints, environment, mcp, codex]
       properties:
         schemaVersion: { const: 1 }
+        uiEnabled:
+          type: boolean
+          description: Whether the instance currently serves its composed Web UI; proxy, REST, health, and MCP remain valid when false.
         instance: { $ref: "#/components/schemas/InstanceView" }
-        baseUrl: { type: string, format: uri }
-        endpoints: { $ref: "#/components/schemas/InstanceUrls" }
+        surfaces: { $ref: "#/components/schemas/InstanceConnectionSurfaces" }
+        baseUrl:
+          type: string
+          format: uri
+          deprecated: true
+          description: Legacy backend Base URL; use surfaces.control.baseUrl or surfaces.agent.baseUrl.
+        endpoints:
+          allOf:
+            - { $ref: "#/components/schemas/InstanceUrls" }
+          deprecated: true
+          description: Legacy derived endpoint set retained for compatibility; use surfaces for Base URLs.
         environment:
           type: object
           additionalProperties: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonyclaw/agent-inspector",
-  "version": "3.0.45",
+  "version": "3.0.46",
   "type": "module",
   "description": "Agent observability and knowledge capture layer for AI coding tools.",
   "license": "MIT",
@@ -44,7 +44,8 @@
     "!src/**/*.test.ts",
     "!src/**/*.stories.tsx",
     "!src/**/__fixtures__",
-    "!src/routeTree.gen.ts",
+    "!src/ui/routeTree.gen.ts",
+    "!src/backend/routeTree.gen.ts",
     "scripts/setup-windows-runtime.mjs",
     "scripts/setup-agent-skills.mjs",
     "scripts/generate-theme-scales.mjs",
@@ -54,21 +55,37 @@
     "!.output/*.exe"
   ],
   "scripts": {
-    "dev": "vite dev",
+    "dev": "node scripts/dev-decoupled.mjs",
+    "dev:ui": "vite dev --config vite.ui.config.ts",
+    "dev:backend": "node scripts/dev-backend.mjs",
     "test:smoke": "bun scripts/run-test-suite.mjs smoke",
     "test:fast": "bun scripts/run-test-suite.mjs smoke",
     "test:unit": "bun scripts/run-test-suite.mjs unit",
     "test:integration": "bun scripts/run-test-suite.mjs integration",
     "test:changed": "bun scripts/run-test-suite.mjs changed",
     "test:all": "bun scripts/run-test-suite.mjs all",
+    "test:compatibility-tooling": "node --test scripts/compatibility/*.test.mjs",
     "start": "node .output/cli.js",
-    "build": "vite build && bun build:workers && bun build:cli && bun build:mcp && bun check:bundle",
+    "start:backend": "node .output/cli.js --backend-only --no-open",
+    "preview:ui": "vite preview --config vite.ui.config.ts",
+    "clean:output": "node scripts/clean-output.mjs",
+    "build": "bun clean:output && bun build:backend && bun build:ui && bun smoke:ui-preview && bun build:workers && bun build:cli && bun build:mcp && bun check:bundle && bun check:boundaries",
+    "build:backend": "vite build --config vite.backend.config.ts",
+    "build:ui": "vite build --config vite.ui.config.ts",
     "build:workers": "npx esbuild src/proxy/logFinalizer.worker.ts src/proxy/sessionWorkerEntry.ts --bundle --platform=node --target=node22 --format=esm --outdir=.output/workers --external:better-sqlite3",
     "smoke:workers": "node scripts/smoke-production-workers.mjs",
     "smoke:packed-workers": "node scripts/smoke-packed-workers.mjs",
     "smoke:instances": "node scripts/smoke-windows-instances.mjs",
     "smoke:coding-agent-instances": "node scripts/smoke-coding-agent-instances.mjs",
+    "smoke:ui-preview": "node scripts/smoke-decoupled-ui-preview.mjs",
     "check:bundle": "node scripts/check-client-bundle.mjs",
+    "check:boundaries": "node scripts/check-runtime-boundaries.mjs",
+    "compatibility:bdd": "node scripts/lint-bdd-catalog.mjs",
+    "compatibility:compare": "node scripts/compatibility/cli.mjs compare",
+    "compatibility:drift": "node scripts/check-backend-compatibility.mjs",
+    "compatibility:fixtures": "bun scripts/validate-compatibility-fixtures.ts",
+    "compatibility:freeze": "node scripts/freeze-backend-baseline.mjs",
+    "compatibility:run": "node scripts/compatibility/cli.mjs run",
     "build:cli": "npx esbuild src/cli.ts --bundle --platform=node --target=node22 --format=esm --outfile=.output/cli.js",
     "build:mcp": "npx esbuild packages/agent-inspector-mcp/src/cli.ts --bundle --platform=node --target=node22 --format=esm --outfile=packages/agent-inspector-mcp/dist/cli.js",
     "themes:generate": "node scripts/generate-theme-scales.mjs",
@@ -83,7 +100,7 @@
     "extension:release": "node scripts/release-chrome-extension.mjs",
     "release": "node scripts/release.mjs",
     "knip": "knip",
-    "check": "bun scripts/run-static-checks.mjs --format",
+    "check": "bun scripts/run-static-checks.mjs --format && bun check:boundaries && bun compatibility:bdd",
     "prepare": "husky",
     "ladle": "ladle serve",
     "ladle:build": "ladle build"
@@ -122,6 +139,7 @@
     "@ladle/react": "^5.1.1",
     "@radix-ui/colors": "^3.0.0",
     "@tailwindcss/vite": "^4.3.2",
+    "@tanstack/router-plugin": "^1.168.20",
     "@types/bun": "^1.3.14",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
@@ -129,6 +147,8 @@
     "@typescript-eslint/eslint-plugin": "^8.64.0",
     "@typescript-eslint/parser": "^8.64.0",
     "@vitejs/plugin-react": "^5.2.0",
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
     "colorjs.io": "^0.7.0",
     "esbuild": "^0.28.1",
     "eslint": "^9.39.5",

package/scripts/generate-theme-scales.mjs

@@ -3,9 +3,9 @@ import { URL } from "node:url";
 import { olive, sand, slateDark } from "@radix-ui/colors";
 
 const themes = [
-  { selector: ":root,\n:root[data-theme=\"light\"]", scale: sand, source: "sand" },
-  { selector: ":root[data-theme=\"dark\"]", scale: slateDark, source: "slateDark" },
-  { selector: ":root[data-theme=\"eye-care\"]", scale: olive, source: "olive" },
+  { selector: ':root,\n:root[data-theme="light"]', scale: sand, source: "sand" },
+  { selector: ':root[data-theme="dark"]', scale: slateDark, source: "slateDark" },
+  { selector: ':root[data-theme="eye-care"]', scale: olive, source: "olive" },
 ];
 
 function renderTheme({ selector, scale, source }) {

package/src/{router.tsx → backend/router.tsx}

@@ -1,5 +1,5 @@
 import { createRouter } from "@tanstack/react-router";
-import { getRouterBasePath } from "./lib/basePath";
+import { getRouterBasePath } from "../lib/basePath";
 import { routeTree } from "./routeTree.gen";
 
 function defaultRouterBasePath(): string {
@@ -19,14 +19,8 @@ export function getRouter(basepath = defaultRouterBasePath()) {
 function attachServerSsrStoreCompatibility(
   router: Readonly<{ state: Readonly<{ matches: unknown }> }>,
 ): void {
-  // TanStack >= 1.168 refactored `state` from an own data property into a
-  // prototype getter backed by lazily-created `stores` (`this.stores.__store`).
-  // Installing a `stores` value here would shadow that lazy init
-  // (`if (!this.stores && this.latestLocation) { this.stores = … }`) and break
-  // `router.state`. When `state` is already a prototype accessor the new store
-  // architecture handles SSR natively and this shim is obsolete.
-  const stateDesc = Object.getOwnPropertyDescriptor(router, "state");
-  if (stateDesc === undefined) return;
+  const stateDescriptor = Object.getOwnPropertyDescriptor(router, "state");
+  if (stateDescriptor === undefined) return;
 
   const existingStores = Object.getOwnPropertyDescriptor(router, "stores");
   if (existingStores !== undefined) return;
@@ -40,9 +34,3 @@ function attachServerSsrStoreCompatibility(
     },
   });
 }
-
-declare module "@tanstack/react-router" {
-  interface Register {
-    router: ReturnType<typeof getRouter>;
-  }
-}

package/src/backend/routes/$.ts

@@ -0,0 +1,26 @@
+import { createFileRoute } from "@tanstack/react-router";
+
+const BACKEND_NOT_FOUND_BODY = {
+  error: "not_found",
+  message: "Agent Inspector backend does not serve the web UI.",
+};
+
+export function backendNotFoundResponse(): Response {
+  return Response.json(BACKEND_NOT_FOUND_BODY, {
+    status: 404,
+    headers: { "cache-control": "no-store" },
+  });
+}
+
+export const Route = createFileRoute("/$")({
+  server: {
+    handlers: {
+      GET: backendNotFoundResponse,
+      POST: backendNotFoundResponse,
+      PUT: backendNotFoundResponse,
+      PATCH: backendNotFoundResponse,
+      DELETE: backendNotFoundResponse,
+      OPTIONS: backendNotFoundResponse,
+    },
+  },
+});

package/src/backend/routes/__root.ts

@@ -0,0 +1,4 @@
+import { createRootRoute } from "@tanstack/react-router";
+
+/** Backend-only root: all public behavior is provided by server route handlers. */
+export const Route = createRootRoute();

package/src/{routes → backend/routes}/api/-instances.ts

@@ -1,11 +1,11 @@
 import { type z } from "zod";
-import type { InstanceLifecycleError, InstanceLifecycleResult } from "../../cli/instance";
+import type { InstanceLifecycleError, InstanceLifecycleResult } from "../../../cli/instance";
 import {
   type InstancePublicErrorCode,
   INSTANCE_API_SCHEMA_VERSION,
   instanceErrorOutput,
-} from "../../lib/instanceContract";
-import { readManagedInstanceLaunch } from "../../lib/managedInstance";
+} from "../../../lib/instanceContract";
+import { readManagedInstanceLaunch } from "../../../lib/managedInstance";
 
 const NO_STORE_HEADERS = { "cache-control": "no-store" };
 

package/src/{routes → backend/routes}/api/alerts.summary.ts

@@ -1,7 +1,7 @@
 import { createFileRoute } from "@tanstack/react-router";
-import { getInspectorAlertSummary } from "../../services/alerts";
-import { DEFAULT_ALERT_SCAN_LIMIT, MAX_ALERT_SCAN_LIMIT } from "../../proxy/alerts";
-import { parseBoundedIntegerParameter } from "../../lib/resourceLimits";
+import { getInspectorAlertSummary } from "../../../services/alerts";
+import { DEFAULT_ALERT_SCAN_LIMIT, MAX_ALERT_SCAN_LIMIT } from "../../../proxy/alerts";
+import { parseBoundedIntegerParameter } from "../../../lib/resourceLimits";
 
 export const Route = createFileRoute("/api/alerts/summary")({
   server: {