@tonyclaw/agent-inspector 3.0.44 → 3.0.45

package/README.md

@@ -28,7 +28,7 @@ Optional MCP-first companion package:
 
 ```bash
 npm install -g @tonyclaw/agent-inspector-mcp
-agent-inspector-mcp doctor
+agent-inspector-mcp doctor --url http://localhost:9527/inspector/api/mcp
 ```
 
 Agent Inspector requires Node.js 22 or newer. Node.js 24 LTS is recommended for production use.
@@ -84,15 +84,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.
+
 - Claude Code: `~/.claude/skills/agent-inspector-onboard/SKILL.md` plus a slash command.
 - Codex: `~/.codex/skills/agent-inspector-onboard/SKILL.md`, focused on connecting
-  `http://localhost:9527/api/mcp` through Codex `mcp_servers.agent-inspector`.
+  `<inspector-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=http://localhost:9527/proxy`.
+  `OPENAI_BASE_URL=<inspector-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.
@@ -116,6 +121,21 @@ edits a real tool config file instead of adding an Agent Inspector generated ski
 `agent-inspector onboard --status --opencode-only --json` or
 `agent-inspector onboard --status --mimo-only --json` to inspect those MCP entries.
 
+For coding agents that must address more than one Inspector, onboarding can target either a
+registered Windows instance or an explicit wrapper URL:
+
+```powershell
+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
+```
+
+`--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.
+
 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
 metadata version matches the currently installed npm package. npm v7+ does not run package uninstall
@@ -154,6 +174,10 @@ The web UI runs at http://localhost:9527/inspector by default. The public proxy
 `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.
+
 ### Base path
 
 Agent Inspector defaults to the `/inspector` public base path:
@@ -183,26 +207,138 @@ To run at the domain root instead, explicitly set the base path to `/`:
 AGENT_INSPECTOR_BASE_PATH=/ agent-inspector
 ```
 
-Reverse proxies should preserve the `/inspector` prefix when forwarding public requests to Agent
-Inspector.
+### Runtime Base Path aliases
 
-The legacy `http://localhost:9527` port is closed by default. If you need a temporary alias for
-older AI tool or MCP configs, start with `agent-inspector --legacy-port`.
+An already-running Inspector can expose an additional path without starting a second runtime or
+sharing its data directory with another process. For example, after starting the canonical UI at
+the domain root, add `/inspector` on the same origin and port:
 
-## v3.0 Port Migration
+```bash
+AGENT_INSPECTOR_BASE_PATH=/ agent-inspector --background --no-open
+agent-inspector alias add /inspector
+```
 
-Agent Inspector v3.0 changes the default public port from `9527` to `9527`. The packaged CLI now
-opens only `9527` by default. Existing AI coding tool and MCP configs that still point at `9527`
-should be moved to `9527`, or you can temporarily start with `agent-inspector --legacy-port`.
+The canonical and alias URLs share the same Providers, logs, sessions, MCP server, workers, and live
+SSE state. Manage the current runtime's aliases with:
 
-Use these default endpoints for new configs:
+```bash
+agent-inspector alias list
+agent-inspector alias remove /inspector
+```
 
-- Web UI: `http://localhost:9527/inspector`
-- Proxy: `http://localhost:9527/inspector/proxy`
-- OpenAI-compatible `/v1` proxy: `http://localhost:9527/inspector/proxy/v1`
-- MCP: `http://localhost:9527/inspector/api/mcp`
+Use `--port <port>` and `--host <host>` when the running local Inspector does not use
+`localhost:9527`. Runtime aliases are intentionally temporary and are cleared when the Inspector
+supervisor restarts; configure `AGENT_INSPECTOR_BASE_PATH` when a path must remain canonical across
+restarts.
+
+### Windows named instances
+
+Use a named instance when the second URL must have its own Providers, runtime configuration, logs,
+sessions, workers, and data directory. Named instances run as hidden background supervisors on
+Windows; the command waits for readiness before returning. The existing `agent-inspector` and
+`agent-inspector start` commands remain the unmanaged default-instance startup path and do not
+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 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]
+```
+
+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:
+
+```powershell
+agent-inspector instance start review --base-path /inspector --json
+$review = agent-inspector instance status review --json | ConvertFrom-Json
+$connection = agent-inspector instance connect review --json | ConvertFrom-Json
+$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;
+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
+token-free state document on stdout while returning `1`. This makes the commands safe for coding
+agents and PowerShell without scraping human text.
+
+On Windows, instance records default below `%LOCALAPPDATA%\agent-inspector\instances`, and isolated
+runtime data defaults to `%LOCALAPPDATA%\agent-inspector\instances\<name>\data`. A per-user fallback
+is used when `LOCALAPPDATA` is unavailable. Set `AGENT_INSPECTOR_INSTANCES_DIR` before every lifecycle
+command, or set it persistently for the user, to move the registry root. `--data-dir` moves one
+instance's runtime data. Agent Inspector rejects a data directory already registered to another
+name rather than allowing Provider or capture state to be shared accidentally.
+
+```powershell
+[Environment]::SetEnvironmentVariable(
+  "AGENT_INSPECTOR_INSTANCES_DIR",
+  "$env:LOCALAPPDATA\agent-inspector-work",
+  "User"
+)
+```
+
+Runtime aliases and named instances solve different problems:
+
+| Feature | Process and storage | Paths | Persistence |
+| --- | --- | --- | --- |
+| `agent-inspector alias add /path` | Same runtime, Providers, and logs | Adds a path on the same port | Cleared on supervisor restart |
+| `agent-inspector instance start <name>` | Separate supervisor, Providers, and logs | Own saved port and Base Path | Saved until explicitly changed |
+
+#### External wrapper: root plus `/inspector`
+
+An external Windows reverse proxy can give two isolated backends one public origin. Start each
+backend on a distinct public ingress port; the lifecycle manager also reserves a different private
+runtime port for each supervisor:
+
+```powershell
+agent-inspector instance start root-site --port 19527 --base-path /
+agent-inspector instance start review-site --port 19537 --base-path /inspector
+```
 
-If you intentionally need the old compatibility port, start with `agent-inspector --legacy-port`.
+Configure the wrapper to send `/inspector` and `/inspector/*` to `127.0.0.1:19537` **without
+stripping the `/inspector` prefix**, and send the remaining root traffic to `127.0.0.1:19527`. Point
+the wrapper only at each instance's public ingress port, never its private helper port. Add the
+wrapper hostname to `AGENT_INSPECTOR_TRUSTED_HOSTS` when it differs from the local host.
+
+The wrapper is a routing layer only: the two instance data directories and Provider configurations
+remain independent. It also becomes the immediate TCP client seen by Inspector, so original coding
+tool PID attribution can be replaced by the wrapper process's PID. Connect a coding tool directly
+to the appropriate instance ingress when exact client-process attribution is required.
+
+A wrapper that forwards to loopback must authenticate and authorize its own remote callers:
+Inspector sees the wrapper as a local peer. Direct non-loopback calls to `/api/instances` always
+require `Authorization: Bearer <AGENT_INSPECTOR_CONTROL_TOKEN>`, even when general remote UI control
+is allowed. Keep that control token separate from `AGENT_INSPECTOR_PROXY_TOKEN`, which protects
+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:
+
+- 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`
+
+For example, keep startup and onboarding aligned when using a custom prefix:
+
+```bash
+AGENT_INSPECTOR_BASE_PATH=/team/inspector agent-inspector
+AGENT_INSPECTOR_BASE_PATH=/team/inspector agent-inspector onboard --force
+AGENT_INSPECTOR_BASE_PATH=/team/inspector agent-inspector onboard --opencode-only --force
+AGENT_INSPECTOR_BASE_PATH=/team/inspector agent-inspector onboard --mimo-only --force
+```
 
 For Codex-style OpenAI Responses clients, configure the proxy as an OpenAI-compatible `/v1` base:
 
@@ -214,11 +350,18 @@ base_url = "http://127.0.0.1:9527/inspector/proxy/v1"
 wire_api = "responses"
 ```
 
+Use `/proxy` as the base for Anthropic clients (which append `/v1/messages`) and generic
+`LLM_BASE_URL` clients. Use `/proxy/v1` as the OpenAI-compatible base for clients that append
+`/chat/completions` or `/responses`; Codex Responses belongs in this second category. The resulting
+full paths are `/proxy/v1/messages`, `/proxy/v1/chat/completions`, and `/proxy/v1/responses`.
+
 ## Documentation Map
 
 - [Installation](docs/Installation.md): install and runtime notes.
 - [Usage](docs/Usage.md): daily capture, browsing, replay, and export workflows.
 - [MCP Server](docs/MCP-Server.md): MCP setup plus tools, resources, prompts, and evidence usage for coding agents.
+- [Instance Control OpenAPI](docs/instance-control.openapi.yaml): versioned named-instance REST
+  contract for coding agents and external controllers.
 - [Troubleshooting](docs/TROUBLESHOOTING.md): port, provider, MCP, Replay, Jenkins, and GitCode fixes.
 - [Jenkins + GitCode WebHook](docs/JENKINS_GITCODE_WEBHOOK_TUNNEL.md): team CI and tunnel setup.
 - [Local Release Helper](docs/LOCAL_RELEASE.md): local maintainer release helper.
@@ -295,20 +438,49 @@ OpenAI Responses each get separate non-streaming and streaming probes. Test evid
 a provider-specific Session so the UI can show which exact path, payload shape, status code, and
 upstream URL failed.
 
+## Named Instance Control For Coding Agents
+
+Every Inspector Base URL exposes a versioned, token-free Windows named-instance control contract.
+The six endpoints are:
+
+| Method | Endpoint | Purpose |
+| --- | --- | --- |
+| `GET` | `/api/instances` | List registered instances and their live state. |
+| `GET` | `/api/instances/{name}` | Read one instance. |
+| `GET` | `/api/instances/{name}/connection` | Read coding-agent URLs, environment, MCP, and Codex settings. |
+| `POST` | `/api/instances/{name}/start` | Create, start, or idempotently reuse an instance. |
+| `POST` | `/api/instances/{name}/stop` | Gracefully stop a sibling instance. |
+| `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
+[OpenAPI 3.1 contract](docs/instance-control.openapi.yaml) for the complete schemas.
+
+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
+external CLI or a different controller/anchor instance. A failed restart reports whether the old
+launch was restored (`restart_failed_rolled_back`) or the instance remained degraded
+(`restart_failed_degraded`).
+
 ## MCP Evidence Workflows
 
-Agent Inspector exposes MCP at:
+Agent Inspector exposes MCP at `<inspector-base-url>/api/mcp`. With the default public Inspector
+Base URL, that is:
 
 ```text
-http://localhost:9527/api/mcp
+http://localhost:9527/inspector/api/mcp
 ```
 
 Coding agents can connect to this MCP surface directly over Streamable HTTP, or through the
 companion stdio bridge:
 
 ```bash
-agent-inspector-mcp stdio
-agent-inspector-mcp config codex
+agent-inspector-mcp stdio --url http://localhost:9527/inspector/api/mcp
+agent-inspector-mcp config codex --url http://localhost:9527/inspector/api/mcp
 ```
 
 The companion package is useful for MCP clients that expect a local command. Direct HTTP remains the
@@ -318,13 +490,10 @@ 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 `http://localhost:9527/api/mcp` directly. If it only supports stdio, configure
+configure `<inspector-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.
 
-Legacy MCP configs that still use `http://localhost:9527/api/mcp` require starting the CLI with
-`agent-inspector --legacy-port`; new configs should use `http://localhost:9527/api/mcp`.
-
 Coding agents can use the MCP surface in three ways:
 
 - Tools: perform actions such as listing logs, reading bounded log details, testing providers,
@@ -333,6 +502,33 @@ Coding agents can use the MCP surface in three ways:
   paths without invoking a tool call.
 - Prompts: start common analysis/reporting tasks from reusable templates.
 
+The current catalog contains 51 tools, 25 resources, and 5 prompts. Named-instance control adds six
+tools—`inspector_list_instances`, `inspector_get_instance`,
+`inspector_get_instance_connection`, `inspector_start_instance`, `inspector_stop_instance`, and
+`inspector_restart_instance`—plus these resources:
+
+| Resource URI | Purpose |
+| --- | --- |
+| `inspector://instances` | Token-free list of named instances. |
+| `inspector://instances/{name}` | One named instance and its live state. |
+| `inspector://instances/{name}/connection` | Protocol-correct connection descriptor for a coding agent. |
+
+The three discovery tools and resources remain available in read-only mode. Instance start/stop/
+restart require both `AGENT_INSPECTOR_MCP_WRITES=1` and
+`AGENT_INSPECTOR_MCP_INSTANCE_WRITES=1`; their tool descriptions require explicit user approval.
+They cannot stop or restart the instance serving the active MCP connection.
+
+For an authenticated remote MCP endpoint, keep the token outside config and pass only its variable
+name to the companion:
+
+```bash
+agent-inspector-mcp doctor --url https://tools.example.test/inspector/api/mcp --token-env INSPECTOR_CONTROL_TOKEN --json
+agent-inspector-mcp stdio --url https://tools.example.test/inspector/api/mcp --token-env INSPECTOR_CONTROL_TOKEN
+```
+
+The companion reads the raw value from `INSPECTOR_CONTROL_TOKEN`, sends it as a Bearer credential,
+and never prints it. `doctor` verifies health, MCP initialization, and `tools/list` before returning.
+
 The evaluation-oriented run flow is:
 
 1. Call `inspector_create_run` before a task starts to declare a stable `runId`, optional

package/docs/instance-control.openapi.yaml

@@ -0,0 +1,306 @@
+openapi: 3.1.0
+info:
+  title: Agent Inspector Named Instance Control API
+  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
+    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.
+servers:
+  - url: http://127.0.0.1:9527
+    description: Root-mounted controller example
+  - url: http://127.0.0.1:9530/inspector
+    description: Prefixed named-instance controller example
+tags:
+  - name: Instances
+paths:
+  /api/instances:
+    get:
+      tags: [Instances]
+      operationId: listNamedInstances
+      summary: List registered named instances and derived live state
+      responses:
+        "200":
+          description: Versioned instance list
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InstanceList"
+        default:
+          $ref: "#/components/responses/InstanceError"
+  /api/instances/{name}:
+    parameters:
+      - $ref: "#/components/parameters/InstanceName"
+    get:
+      tags: [Instances]
+      operationId: getNamedInstance
+      summary: Read one named instance and its live state
+      responses:
+        "200":
+          description: Instance view
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InstanceView"
+        default:
+          $ref: "#/components/responses/InstanceError"
+  /api/instances/{name}/connection:
+    parameters:
+      - $ref: "#/components/parameters/InstanceName"
+    get:
+      tags: [Instances]
+      operationId: getNamedInstanceConnection
+      summary: Read protocol-correct Coding Agent connection settings
+      responses:
+        "200":
+          description: Token-free connection descriptor
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InstanceConnection"
+        default:
+          $ref: "#/components/responses/InstanceError"
+  /api/instances/{name}/start:
+    parameters:
+      - $ref: "#/components/parameters/InstanceName"
+    post:
+      tags: [Instances]
+      operationId: startNamedInstance
+      summary: Idempotently create, start, or reuse a named instance
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/InstanceStartRequest"
+      responses:
+        "200":
+          description: Existing instance started or reused
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InstanceOperation"
+        "201":
+          description: New instance record created and started
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InstanceOperation"
+        default:
+          $ref: "#/components/responses/InstanceError"
+  /api/instances/{name}/stop:
+    parameters:
+      - $ref: "#/components/parameters/InstanceName"
+    post:
+      tags: [Instances]
+      operationId: stopNamedInstance
+      summary: Gracefully stop a matching sibling instance
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+      responses:
+        "200":
+          description: Instance stopped or already stopped
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InstanceOperation"
+        default:
+          $ref: "#/components/responses/InstanceError"
+  /api/instances/{name}/restart:
+    parameters:
+      - $ref: "#/components/parameters/InstanceName"
+    post:
+      tags: [Instances]
+      operationId: restartNamedInstance
+      summary: Validate configuration, gracefully stop, and relaunch a sibling instance
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/InstanceStartRequest"
+      responses:
+        "200":
+          description: Replacement launch reached readiness
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InstanceOperation"
+        default:
+          $ref: "#/components/responses/InstanceError"
+components:
+  securitySchemes:
+    controlBearer:
+      type: http
+      scheme: bearer
+      description: Value of AGENT_INSPECTOR_CONTROL_TOKEN for direct non-loopback access.
+  parameters:
+    InstanceName:
+      name: name
+      in: path
+      required: true
+      schema:
+        type: string
+        pattern: "^[a-z0-9._-]{1,64}$"
+      example: review
+  responses:
+    InstanceError:
+      description: Versioned machine-readable lifecycle error
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/InstanceError"
+  schemas:
+    InstanceUrls:
+      type: object
+      additionalProperties: false
+      required: [ui, api, health, proxy, openai, mcp]
+      properties:
+        ui: { type: string, format: uri, example: "http://127.0.0.1:9530/inspector" }
+        api: { type: string, format: uri, example: "http://127.0.0.1:9530/inspector/api" }
+        health:
+          { type: string, format: uri, example: "http://127.0.0.1:9530/inspector/api/health" }
+        proxy:
+          { type: string, format: uri, example: "http://127.0.0.1:9530/inspector/proxy" }
+        openai:
+          { type: string, format: uri, example: "http://127.0.0.1:9530/inspector/proxy/v1" }
+        mcp:
+          { type: string, format: uri, example: "http://127.0.0.1:9530/inspector/api/mcp" }
+    InstanceView:
+      type: object
+      additionalProperties: false
+      required:
+        - schemaVersion
+        - name
+        - instanceId
+        - state
+        - stateReason
+        - checkedAt
+        - createdAt
+        - updatedAt
+        - launch
+        - host
+        - publicPort
+        - upstreamPort
+        - basePath
+        - captureMode
+        - dataDir
+        - supervisorPid
+        - urls
+      properties:
+        schemaVersion: { const: 1 }
+        name: { type: string, example: review }
+        instanceId: { type: string, example: "d8805ce7-5ec7-41fb-a370-c56b57418839" }
+        state: { type: string, enum: [running, stopped, conflict] }
+        stateReason:
+          oneOf:
+            - { type: string, enum: [identity_mismatch, port_conflict] }
+            - { type: "null" }
+        checkedAt: { type: string, format: date-time }
+        createdAt: { type: string, format: date-time }
+        updatedAt: { type: string, format: date-time }
+        launch:
+          type: object
+          additionalProperties: false
+          required: [launchId, startedAt]
+          properties:
+            launchId: { type: string }
+            startedAt: { type: string, format: date-time }
+        host: { type: string, example: "127.0.0.1" }
+        publicPort: { type: integer, minimum: 1, maximum: 65535, example: 9530 }
+        upstreamPort: { type: integer, minimum: 1, maximum: 65535, example: 9532 }
+        basePath: { type: string, example: /inspector }
+        captureMode: { type: string, enum: [simple, full] }
+        dataDir: { type: string, example: "C:\\Users\\me\\AppData\\Local\\agent-inspector\\instances\\review\\data" }
+        supervisorPid:
+          oneOf:
+            - { type: integer, minimum: 1 }
+            - { type: "null" }
+        urls:
+          $ref: "#/components/schemas/InstanceUrls"
+    InstanceList:
+      type: object
+      additionalProperties: false
+      required: [schemaVersion, instances]
+      properties:
+        schemaVersion: { const: 1 }
+        instances:
+          type: array
+          items:
+            $ref: "#/components/schemas/InstanceView"
+    InstanceStartRequest:
+      type: object
+      additionalProperties: false
+      properties:
+        port: { type: integer, minimum: 1, maximum: 65535 }
+        basePath: { type: string, example: /inspector }
+        host: { type: string, example: "127.0.0.1" }
+        captureMode: { type: string, enum: [simple, full] }
+        dataDir: { type: string }
+    InstanceOperation:
+      type: object
+      additionalProperties: false
+      required: [schemaVersion, operation, outcome, instance]
+      properties:
+        schemaVersion: { const: 1 }
+        operation: { type: string, enum: [start, stop, restart] }
+        outcome:
+          type: string
+          enum: [created, started, already_running, stopped, already_stopped, restarted]
+        instance:
+          $ref: "#/components/schemas/InstanceView"
+    InstanceConnection:
+      type: object
+      additionalProperties: false
+      required: [schemaVersion, instance, baseUrl, endpoints, environment, mcp, codex]
+      properties:
+        schemaVersion: { const: 1 }
+        instance: { $ref: "#/components/schemas/InstanceView" }
+        baseUrl: { type: string, format: uri }
+        endpoints: { $ref: "#/components/schemas/InstanceUrls" }
+        environment:
+          type: object
+          additionalProperties: false
+          required: [ANTHROPIC_BASE_URL, LLM_BASE_URL, OPENAI_BASE_URL, AGENT_INSPECTOR_MCP_URL]
+          properties:
+            ANTHROPIC_BASE_URL: { type: string, format: uri }
+            LLM_BASE_URL: { type: string, format: uri }
+            OPENAI_BASE_URL: { type: string, format: uri }
+            AGENT_INSPECTOR_MCP_URL: { type: string, format: uri }
+        mcp:
+          type: object
+          additionalProperties: false
+          required: [serverName, transport, url]
+          properties:
+            serverName: { type: string, example: agent-inspector-review }
+            transport: { const: streamable-http }
+            url: { type: string, format: uri }
+        codex:
+          type: object
+          additionalProperties: false
+          required: [providerName, baseUrl, wireApi]
+          properties:
+            providerName: { type: string, example: agent-inspector-review }
+            baseUrl: { type: string, format: uri }
+            wireApi: { const: responses }
+    InstanceError:
+      type: object
+      additionalProperties: false
+      required: [schemaVersion, error]
+      properties:
+        schemaVersion: { const: 1 }
+        error:
+          type: object
+          additionalProperties: false
+          required: [code, message, retryable]
+          properties:
+            code: { type: string }
+            message: { type: string }
+            retryable: { type: boolean }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonyclaw/agent-inspector",
-  "version": "3.0.44",
+  "version": "3.0.45",
   "type": "module",
   "description": "Agent observability and knowledge capture layer for AI coding tools.",
   "license": "MIT",
@@ -48,6 +48,7 @@
     "scripts/setup-windows-runtime.mjs",
     "scripts/setup-agent-skills.mjs",
     "scripts/generate-theme-scales.mjs",
+    "docs/instance-control.openapi.yaml",
     "styles",
     ".output",
     "!.output/*.exe"
@@ -65,6 +66,8 @@
     "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",
     "check:bundle": "node scripts/check-client-bundle.mjs",
     "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",