@tonyclaw/agent-inspector 2.0.26 → 2.0.28

package/.output/server/_tanstack-start-manifest_v-DPf3uJys.mjs

@@ -0,0 +1,4 @@
+const tsrStartManifest = () => ({ "routes": { "__root__": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/__root.tsx", "children": ["/", "/api/config", "/api/health", "/api/logs", "/api/mcp", "/api/models", "/api/providers", "/api/runs", "/api/sessions", "/proxy/$", "/session/$sessionId", "/api/knowledge/candidates", "/api/knowledge/project-context", "/api/knowledge/search", "/api/knowledge/sessions/$sessionId/candidates"], "preloads": ["/assets/main-Brj0Gn91.js"], "assets": [] }, "/": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/index.tsx", "assets": [], "preloads": ["/assets/index-B9_VaAWl.js", "/assets/ProxyViewerContainer-BccuA6p5.js"] }, "/api/config": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/config.ts", "children": ["/api/config/paths"] }, "/api/health": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/health.ts" }, "/api/logs": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/logs.ts", "children": ["/api/logs/$id", "/api/logs/stream"] }, "/api/mcp": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/mcp.ts" }, "/api/models": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/models.ts" }, "/api/providers": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/providers.ts", "children": ["/api/providers/$providerId", "/api/providers/export", "/api/providers/import", "/api/providers/scan"] }, "/api/runs": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/runs.ts", "children": ["/api/runs/$runId"] }, "/api/sessions": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/sessions.ts" }, "/proxy/$": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/proxy/$.ts" }, "/session/$sessionId": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/session/$sessionId.tsx", "assets": [], "preloads": ["/assets/_sessionId-9rEF0uSE.js", "/assets/ProxyViewerContainer-BccuA6p5.js"] }, "/api/config/paths": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/config.paths.ts" }, "/api/knowledge/candidates": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/knowledge.candidates.ts", "children": ["/api/knowledge/candidates/$candidateId"] }, "/api/knowledge/project-context": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/knowledge.project-context.ts" }, "/api/knowledge/search": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/knowledge.search.ts" }, "/api/logs/$id": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/logs.$id.ts", "children": ["/api/logs/$id/chunks", "/api/logs/$id/replay"] }, "/api/logs/stream": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/logs.stream.ts" }, "/api/providers/$providerId": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/providers.$providerId.ts", "children": ["/api/providers/$providerId/model-metadata", "/api/providers/$providerId/test"] }, "/api/providers/export": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/providers.export.ts" }, "/api/providers/import": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/providers.import.ts" }, "/api/providers/scan": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/providers.scan.ts" }, "/api/runs/$runId": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/runs.$runId.ts", "children": ["/api/runs/$runId/evidence"] }, "/api/knowledge/candidates/$candidateId": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/knowledge.candidates.$candidateId.ts", "children": ["/api/knowledge/candidates/$candidateId/promote"] }, "/api/logs/$id/chunks": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/logs.$id.chunks.ts" }, "/api/logs/$id/replay": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/logs.$id.replay.ts" }, "/api/providers/$providerId/model-metadata": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/providers.$providerId.model-metadata.ts" }, "/api/providers/$providerId/test": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/providers.$providerId.test.ts", "children": ["/api/providers/$providerId/test/log"] }, "/api/runs/$runId/evidence": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/runs.$runId.evidence.ts" }, "/api/knowledge/candidates/$candidateId/promote": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/knowledge.candidates.$candidateId.promote.ts" }, "/api/knowledge/sessions/$sessionId/candidates": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/knowledge.sessions.$sessionId.candidates.ts" }, "/api/providers/$providerId/test/log": { "filePath": "C:/Users/claw/workspace/agent-inspector/src/routes/api/providers.$providerId.test.log.ts" } }, "clientEntry": "/assets/main-Brj0Gn91.js" });
+export {
+  tsrStartManifest
+};

package/.output/server/index.mjs

@@ -35,103 +35,103 @@ const headers = ((m) => function headersRouteRule(event) {
   }
 });
 const assets = {
+  "/assets/index-B9_VaAWl.js": {
+    "type": "text/javascript; charset=utf-8",
+    "etag": '"74-wegwMejcMaCe2qDEma7y6qUh/6U"',
+    "mtime": "2026-06-30T03:21:19.568Z",
+    "size": 116,
+    "path": "../public/assets/index-B9_VaAWl.js"
+  },
   "/assets/alibaba-TTwafVwX.svg": {
     "type": "image/svg+xml",
     "etag": '"171b-6dyV5K8QjiaY35sN9qNprh9zDIs"',
-    "mtime": "2026-06-30T00:03:39.766Z",
+    "mtime": "2026-06-30T03:21:19.568Z",
     "size": 5915,
     "path": "../public/assets/alibaba-TTwafVwX.svg"
   },
-  "/assets/CompareDrawer-DBTFzxG5.js": {
+  "/assets/CompareDrawer-CicCP3Hb.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"49fe-0/x6kUv/QAjBzcBGGqiJEK7CrGo"',
-    "mtime": "2026-06-30T00:03:39.766Z",
+    "etag": '"49fe-CmOMF3QSwAcX6NWjQdoZrIdyoIw"',
+    "mtime": "2026-06-30T03:21:19.570Z",
     "size": 18942,
-    "path": "../public/assets/CompareDrawer-DBTFzxG5.js"
-  },
-  "/assets/ReplayDialog-syW2hDNE.js": {
-    "type": "text/javascript; charset=utf-8",
-    "etag": '"318c-NQmbQD7SPA/gh+gt24ulUI098ko"',
-    "mtime": "2026-06-30T00:03:39.766Z",
-    "size": 12684,
-    "path": "../public/assets/ReplayDialog-syW2hDNE.js"
-  },
-  "/assets/index-By11a28-.js": {
-    "type": "text/javascript; charset=utf-8",
-    "etag": '"74-wKECK+LXurWi55O6mYvJFEu73U4"',
-    "mtime": "2026-06-30T00:03:39.766Z",
-    "size": 116,
-    "path": "../public/assets/index-By11a28-.js"
+    "path": "../public/assets/CompareDrawer-CicCP3Hb.js"
   },
   "/assets/index-DsiKfWCp.css": {
     "type": "text/css; charset=utf-8",
     "etag": '"1a3d5-pnLJEAiyUUKlRw5OUnvwf1dCQeI"',
-    "mtime": "2026-06-30T00:03:39.766Z",
+    "mtime": "2026-06-30T03:21:19.568Z",
     "size": 107477,
     "path": "../public/assets/index-DsiKfWCp.css"
   },
-  "/assets/main-DKRDRBdd.js": {
-    "type": "text/javascript; charset=utf-8",
-    "etag": '"51726-1JXlqBObsVCWwZtRttZD0+8rmmo"',
-    "mtime": "2026-06-30T00:03:39.766Z",
-    "size": 333606,
-    "path": "../public/assets/main-DKRDRBdd.js"
-  },
-  "/assets/RequestAnatomy-BkuRtY9o.js": {
-    "type": "text/javascript; charset=utf-8",
-    "etag": '"4485-ei5S3iwPLFX3XUKIwoNDXt6pfeg"',
-    "mtime": "2026-06-30T00:03:39.766Z",
-    "size": 17541,
-    "path": "../public/assets/RequestAnatomy-BkuRtY9o.js"
-  },
-  "/assets/ResponseView-BwyvEvoE.js": {
-    "type": "text/javascript; charset=utf-8",
-    "etag": '"30d0-NcNgH32g8TreiCI4JgpE13I81fo"',
-    "mtime": "2026-06-30T00:03:39.766Z",
-    "size": 12496,
-    "path": "../public/assets/ResponseView-BwyvEvoE.js"
-  },
-  "/assets/StreamingChunkSequence-BY4MbPKg.js": {
-    "type": "text/javascript; charset=utf-8",
-    "etag": '"d57-HwRjNFQZ5p5h2qA6wui4VPdas/g"',
-    "mtime": "2026-06-30T00:03:39.766Z",
-    "size": 3415,
-    "path": "../public/assets/StreamingChunkSequence-BY4MbPKg.js"
-  },
   "/assets/minimax-BPMzvuL-.jpeg": {
     "type": "image/jpeg",
     "etag": '"1b06-IwivU89ko5UTMUM1/t7hn4sQK9A"',
-    "mtime": "2026-06-30T00:03:39.765Z",
+    "mtime": "2026-06-30T03:21:19.568Z",
     "size": 6918,
     "path": "../public/assets/minimax-BPMzvuL-.jpeg"
   },
+  "/assets/qwen-CONDcHqt.png": {
+    "type": "image/png",
+    "etag": '"572c3-cdJAPaHdOvFCGzuaQjagdgOu6XE"',
+    "mtime": "2026-06-30T03:21:19.568Z",
+    "size": 357059,
+    "path": "../public/assets/qwen-CONDcHqt.png"
+  },
+  "/assets/ReplayDialog-Bc8q3ujm.js": {
+    "type": "text/javascript; charset=utf-8",
+    "etag": '"318c-QS16LlsGhExlRZzuuDmYzqWLBN0"',
+    "mtime": "2026-06-30T03:21:19.570Z",
+    "size": 12684,
+    "path": "../public/assets/ReplayDialog-Bc8q3ujm.js"
+  },
   "/assets/zhipuai-BPNAnxo-.svg": {
     "type": "image/svg+xml",
     "etag": '"2bf8-hNaLCTi89nOFCsIIfWpP/jrfo0s"',
-    "mtime": "2026-06-30T00:03:39.766Z",
+    "mtime": "2026-06-30T03:21:19.568Z",
     "size": 11256,
     "path": "../public/assets/zhipuai-BPNAnxo-.svg"
   },
-  "/assets/_sessionId-XlPUgIIb.js": {
+  "/assets/main-Brj0Gn91.js": {
+    "type": "text/javascript; charset=utf-8",
+    "etag": '"51726-mwq2VuKeQG//deWEjQSFZIL9ZWo"',
+    "mtime": "2026-06-30T03:21:19.568Z",
+    "size": 333606,
+    "path": "../public/assets/main-Brj0Gn91.js"
+  },
+  "/assets/RequestAnatomy-Coyy3zcH.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"d2-MoOX/bvv9993P6qEc8POysKqaj0"',
-    "mtime": "2026-06-30T00:03:39.766Z",
+    "etag": '"4485-KFNCPYVKcx+a4jW1uo7q7Az4T5c"',
+    "mtime": "2026-06-30T03:21:19.570Z",
+    "size": 17541,
+    "path": "../public/assets/RequestAnatomy-Coyy3zcH.js"
+  },
+  "/assets/_sessionId-9rEF0uSE.js": {
+    "type": "text/javascript; charset=utf-8",
+    "etag": '"d2-+KgPaqhF/ImO1Zb9tZi0sMB8OPI"',
+    "mtime": "2026-06-30T03:21:19.568Z",
     "size": 210,
-    "path": "../public/assets/_sessionId-XlPUgIIb.js"
+    "path": "../public/assets/_sessionId-9rEF0uSE.js"
   },
-  "/assets/qwen-CONDcHqt.png": {
-    "type": "image/png",
-    "etag": '"572c3-cdJAPaHdOvFCGzuaQjagdgOu6XE"',
-    "mtime": "2026-06-30T00:03:39.766Z",
-    "size": 357059,
-    "path": "../public/assets/qwen-CONDcHqt.png"
+  "/assets/ResponseView-BWJzgh0c.js": {
+    "type": "text/javascript; charset=utf-8",
+    "etag": '"30d0-XQuX3LcRTXyoZYFeRDp9J2gMpd0"',
+    "mtime": "2026-06-30T03:21:19.570Z",
+    "size": 12496,
+    "path": "../public/assets/ResponseView-BWJzgh0c.js"
+  },
+  "/assets/StreamingChunkSequence-BSC3uuE5.js": {
+    "type": "text/javascript; charset=utf-8",
+    "etag": '"d57-1GnBSzcha+n1obLlcv4lwyBhPf4"',
+    "mtime": "2026-06-30T03:21:19.570Z",
+    "size": 3415,
+    "path": "../public/assets/StreamingChunkSequence-BSC3uuE5.js"
   },
-  "/assets/ProxyViewerContainer-ivZk8MgE.js": {
+  "/assets/ProxyViewerContainer-BccuA6p5.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"af111-IykBkxC0TII63qeShJvyrJajFT0"',
-    "mtime": "2026-06-30T00:03:39.766Z",
+    "etag": '"af111-eqyso0QJHFS7+IdUoP/1PcawtQE"',
+    "mtime": "2026-06-30T03:21:19.570Z",
     "size": 717073,
-    "path": "../public/assets/ProxyViewerContainer-ivZk8MgE.js"
+    "path": "../public/assets/ProxyViewerContainer-BccuA6p5.js"
   }
 };
 function readAsset(id) {

package/README.md

@@ -9,6 +9,7 @@ The npm package and CLI remain `agent-inspector`; the platform name is Agent Ins
 - Runs a local transparent proxy for Anthropic and OpenAI-compatible APIs.
 - Captures model requests, responses, tool definitions, token usage, and errors.
 - Provides a web UI for browsing sessions and logs in real time.
+- Exposes sessions, logs, runs, and evidence packs through MCP Tools, Resources, and Prompts.
 - Includes a Chrome companion extension for quick capture status and log navigation.
 - Generates reviewable knowledge candidates from agent sessions.
 - Bridges approved knowledge to OpenClaw while keeping OpenClaw hidden behind the Inspector surface.
@@ -107,7 +108,7 @@ The web UI runs at http://localhost:25947.
 
 - [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 and tool usage for coding agents.
+- [MCP Server](docs/MCP-Server.md): MCP setup plus tools, resources, prompts, and evidence usage for coding agents.
 - [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.
@@ -142,9 +143,62 @@ can also set `AGENT_INSPECTOR_MODE=full` or
 `AGENT_INSPECTOR_CAPTURE_MODE=full`; the CLI flag takes precedence over the
 environment.
 
+## MCP Evidence Workflows
+
+Agent Inspector exposes MCP at:
+
+```text
+http://localhost:25947/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,
+  creating evaluation runs, and exporting evidence packs.
+- Resources: read stable evidence URIs without invoking a tool call.
+- Prompts: start common analysis/reporting tasks from reusable templates.
+
+The evaluation-oriented run flow is:
+
+1. Call `inspector_create_run` before a task starts to declare a stable `runId` and optional
+   `sessionId`.
+2. Call `inspector_update_run` as the task moves through `running`, `failed`, `completed`, or
+   `cancelled`; metadata keys are merged so CI can add build numbers, branch names, or case ids.
+3. Let the coding agent run through the proxy as usual.
+4. If something fails, call `inspector_get_recent_failures` or read
+   `inspector://failures/recent`, then use `inspector_search_logs` to locate suspicious log ids.
+5. Call `inspector_get_run` to inspect the declared run.
+6. Call `inspector_export_evidence` to write JSON, Markdown, and HTML artifacts under:
+
+```text
+<dataDir>/evidence/<runId>/evidence.json
+<dataDir>/evidence/<runId>/evidence.md
+<dataDir>/evidence/<runId>/evidence.html
+```
+
+Useful MCP resource URIs:
+
+| Resource | Purpose |
+| --- | --- |
+| `inspector://sessions` | List known session ids. |
+| `inspector://sessions/{sessionId}` | Read a compact session summary with Inspector links, counts, models, providers, token totals, and recent logs. |
+| `inspector://logs/{id}` | Read bounded log details for one captured request. Large bodies are capped for agent safety. |
+| `inspector://runs` | List declared evaluation runs. |
+| `inspector://failures/recent` | Read recent failed/cancelled runs and non-success evidence classifications. |
+| `inspector://runs/{runId}` | Read one declared run and its evidence paths. |
+| `inspector://evidence/{runId}` | Read the exported Markdown evidence pack for a run. |
+
+Built-in prompt templates help turn captured evidence into user-facing output:
+
+- `inspector_analyze_session_failure`: explain why a session failed and cite log evidence.
+- `inspector_triage_recent_failures`: prioritize recent failed runs and suggest next actions.
+- `inspector_generate_jenkins_report`: produce a Jenkins-ready Markdown report for a run.
+- `inspector_extract_repro_steps`: extract concise reproduction steps from a session.
+
 ## Jenkins And GitCode
 
 Team CI, GitCode WebHook setup, Cloudflare Tunnel notes, local push fallback, and the verified PR workflow live in [Jenkins + GitCode WebHook](docs/JENKINS_GITCODE_WEBHOOK_TUNNEL.md). Keep real Jenkins notify tokens, GitCode access tokens, and tunnel URLs out of the repository.
+
 ## Project Direction
 
 Agent Inspector should stay close to the proven inspector codebase while growing into an agent knowledge layer. The memory flow has four layers:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonyclaw/agent-inspector",
-  "version": "2.0.26",
+  "version": "2.0.28",
   "type": "module",
   "description": "Agent observability and knowledge capture layer for AI coding tools.",
   "license": "MIT",

package/src/cli/networkHints.ts

@@ -0,0 +1,150 @@
+import { networkInterfaces } from "node:os";
+
+export type NetworkInterfaceMap = ReturnType<typeof networkInterfaces>;
+
+export type BindHost = string | undefined;
+
+export function localUrlForPort(port: number): string {
+  return `http://localhost:${String(port)}`;
+}
+
+function trimHost(host: BindHost): string | undefined {
+  const trimmed = host?.trim();
+  return trimmed === undefined || trimmed.length === 0 ? undefined : trimmed;
+}
+
+export function isWildcardHost(host: BindHost): boolean {
+  const trimmed = trimHost(host);
+  return trimmed === undefined || trimmed === "0.0.0.0" || trimmed === "::" || trimmed === "[::]";
+}
+
+export function isLoopbackHost(host: BindHost): boolean {
+  const trimmed = trimHost(host);
+  if (trimmed === undefined) return false;
+  return (
+    trimmed === "localhost" ||
+    trimmed === "::1" ||
+    trimmed === "[::1]" ||
+    trimmed.startsWith("127.")
+  );
+}
+
+function bracketIpv6(host: string): string {
+  if (!host.includes(":")) return host;
+  if (host.startsWith("[") && host.endsWith("]")) return host;
+  return `[${host}]`;
+}
+
+export function urlForHost(port: number, host: BindHost): string {
+  const trimmed = trimHost(host);
+  if (trimmed === undefined || isWildcardHost(trimmed)) return localUrlForPort(port);
+  return `http://${bracketIpv6(trimmed)}:${String(port)}`;
+}
+
+export function probeHostForBindHost(host: BindHost): string {
+  const trimmed = trimHost(host);
+  if (trimmed === undefined || isWildcardHost(trimmed)) return "127.0.0.1";
+  if (trimmed.startsWith("[") && trimmed.endsWith("]")) return trimmed.slice(1, -1);
+  return trimmed;
+}
+
+export function isValidBindHost(host: string): boolean {
+  const trimmed = host.trim();
+  if (trimmed.length === 0) return false;
+  if (/^https?:\/\//i.test(trimmed)) return false;
+  if (/[\s/\\]/.test(trimmed)) return false;
+  return true;
+}
+
+function isUsableAddress(address: string): boolean {
+  return address !== "0.0.0.0" && !address.startsWith("169.254.");
+}
+
+function is172Private(address: string): boolean {
+  const parts = address.split(".");
+  const second = Number(parts[1] ?? "");
+  return parts[0] === "172" && Number.isInteger(second) && second >= 16 && second <= 31;
+}
+
+function addressScore(address: string): number {
+  if (address.startsWith("192.168.")) return 0;
+  if (address.startsWith("10.")) return 1;
+  if (is172Private(address)) return 2;
+  return 3;
+}
+
+export function collectNetworkUrls(
+  port: number,
+  interfaces: NetworkInterfaceMap = networkInterfaces(),
+): string[] {
+  const addresses = new Set<string>();
+
+  for (const entries of Object.values(interfaces)) {
+    if (entries === undefined) continue;
+    for (const entry of entries) {
+      if (entry.family === "IPv4" && !entry.internal && isUsableAddress(entry.address)) {
+        addresses.add(entry.address);
+      }
+    }
+  }
+
+  return [...addresses]
+    .sort((left, right) => {
+      const score = addressScore(left) - addressScore(right);
+      return score !== 0 ? score : left.localeCompare(right);
+    })
+    .slice(0, 4)
+    .map((address) => `http://${address}:${String(port)}`);
+}
+
+export function networkUrlsForBindHost(
+  port: number,
+  host: BindHost,
+  interfaces: NetworkInterfaceMap = networkInterfaces(),
+): string[] {
+  if (isLoopbackHost(host)) return [];
+  if (isWildcardHost(host)) return collectNetworkUrls(port, interfaces);
+  return [urlForHost(port, host)];
+}
+
+export function formatAccessHintLines(
+  port: number,
+  networkUrls: readonly string[],
+  host: BindHost = undefined,
+): string[] {
+  const localUrl = localUrlForPort(port);
+  const hostLabel = isWildcardHost(host) ? "all interfaces (0.0.0.0)" : (trimHost(host) ?? "");
+  const lines = ["Access URLs:", `   Bind host:      ${hostLabel}`];
+
+  if (isLoopbackHost(host) || isWildcardHost(host)) {
+    lines.push(`   Local UI:       ${localUrl}`);
+    lines.push(`   Local proxy:    ${localUrl}/proxy`);
+    lines.push(`   Local MCP:      ${localUrl}/api/mcp`);
+  } else {
+    const boundUrl = urlForHost(port, host);
+    lines.push(`   Bound UI:       ${boundUrl}`);
+    lines.push(`   Bound proxy:    ${boundUrl}/proxy`);
+    lines.push(`   Bound MCP:      ${boundUrl}/api/mcp`);
+    lines.push("   Localhost:      may not work because the server is bound to a specific host");
+  }
+
+  const firstNetworkUrl = networkUrls[0];
+  if (isLoopbackHost(host)) {
+    lines.push("   Network:        disabled by loopback bind host");
+  } else if (firstNetworkUrl === undefined) {
+    lines.push("   Network:        no non-loopback IPv4 address detected");
+  } else {
+    lines.push(`   Network UI:     ${firstNetworkUrl}`);
+    lines.push(`   Network proxy:  ${firstNetworkUrl}/proxy`);
+    const moreUrls = networkUrls.slice(1);
+    if (moreUrls.length > 0) {
+      lines.push(`   Other IPs:      ${moreUrls.join(", ")}`);
+    }
+  }
+
+  lines.push(
+    "   Container note: if the coding agent is in another container or machine, replace localhost with a reachable host/IP and verify the port is reachable.",
+  );
+
+  return lines;
+}

package/src/cli.ts

@@ -4,6 +4,14 @@ import { createConnection } from "node:net";
 import { fileURLToPath } from "node:url";
 import { dirname, join, resolve as resolvePath } from "node:path";
 import { existsSync } from "node:fs";
+import {
+  formatAccessHintLines,
+  isValidBindHost,
+  localUrlForPort,
+  networkUrlsForBindHost,
+  probeHostForBindHost,
+  urlForHost,
+} from "./cli/networkHints.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -43,11 +51,11 @@ await runStart(process.argv.slice(2));
 // Legacy `start` behavior — start the proxy on the configured port. Extracted
 // into a function so the router above can keep the top-level flow readable.
 // -----------------------------------------------------------------------------
-async function isInspectorHealthy(port: number): Promise<boolean> {
+async function isInspectorHealthy(port: number, host?: string): Promise<boolean> {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), LOCAL_PROBE_TIMEOUT_MS);
   try {
-    const response = await fetch(`http://127.0.0.1:${port}/api/health`, {
+    const response = await fetch(`${urlForHost(port, probeHostForBindHost(host))}/api/health`, {
       cache: "no-store",
       signal: controller.signal,
     });
@@ -59,11 +67,11 @@ async function isInspectorHealthy(port: number): Promise<boolean> {
   }
 }
 
-async function getRunningCaptureMode(port: number): Promise<CaptureMode | null> {
+async function getRunningCaptureMode(port: number, host?: string): Promise<CaptureMode | null> {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), LOCAL_PROBE_TIMEOUT_MS);
   try {
-    const response = await fetch(`http://127.0.0.1:${port}/api/config`, {
+    const response = await fetch(`${urlForHost(port, probeHostForBindHost(host))}/api/config`, {
       cache: "no-store",
       signal: controller.signal,
     });
@@ -77,9 +85,9 @@ async function getRunningCaptureMode(port: number): Promise<CaptureMode | null>
   }
 }
 
-function isPortAcceptingConnections(port: number): Promise<boolean> {
+function isPortAcceptingConnections(port: number, host?: string): Promise<boolean> {
   return new Promise((resolve) => {
-    const socket = createConnection({ host: "127.0.0.1", port });
+    const socket = createConnection({ host: probeHostForBindHost(host), port });
     const finish = (value: boolean): void => {
       socket.removeAllListeners();
       socket.destroy();
@@ -99,10 +107,14 @@ function sleep(ms: number): Promise<void> {
   });
 }
 
-async function waitForInspectorHealthy(port: number, timeoutMs: number): Promise<boolean> {
+async function waitForInspectorHealthy(
+  port: number,
+  timeoutMs: number,
+  host?: string,
+): Promise<boolean> {
   const start = Date.now();
   while (Date.now() - start < timeoutMs) {
-    if (await isInspectorHealthy(port)) return true;
+    if (await isInspectorHealthy(port, host)) return true;
     await sleep(250);
   }
   return false;
@@ -179,13 +191,22 @@ function readCaptureMode(raw: unknown): CaptureMode | null {
   return typeof value === "string" ? parseCaptureMode(value) : null;
 }
 
+function printAccessHints(port: number, host?: string): void {
+  const networkUrls = networkUrlsForBindHost(port, host);
+  for (const line of formatAccessHintLines(port, networkUrls, host)) {
+    console.log(line);
+  }
+}
+
 async function runStart(args: string[]): Promise<void> {
   const envPort = process.env["PORT"];
   const portDefault = envPort !== undefined ? Number(envPort) : DEFAULT_PORT;
+  const envHost = process.env["NITRO_HOST"] ?? process.env["HOST"];
   const envMode =
     process.env["AGENT_INSPECTOR_CAPTURE_MODE"] ?? process.env["AGENT_INSPECTOR_MODE"];
 
   let port = portDefault;
+  let host = envHost !== undefined && envHost.trim().length > 0 ? envHost.trim() : undefined;
   let open = true;
   let openWasSpecified = false;
   let background = false;
@@ -206,8 +227,24 @@ async function runStart(args: string[]): Promise<void> {
     captureModeWasSpecified = true;
   }
 
+  if (host !== undefined && !isValidBindHost(host)) {
+    console.error(`Invalid host: ${host}. Use an IP or hostname without protocol/path.`);
+    process.exitCode = 1;
+    return;
+  }
+
   for (let i = 0; i < args.length; i++) {
     const arg = args[i] ?? "";
+    if (arg.startsWith("--host=")) {
+      const value = arg.slice(arg.indexOf("=") + 1).trim();
+      if (!isValidBindHost(value)) {
+        console.error(`Invalid host: ${value}. Use an IP or hostname without protocol/path.`);
+        process.exitCode = 1;
+        return;
+      }
+      host = value;
+      continue;
+    }
     if (arg.startsWith("--mode=") || arg.startsWith("--capture-mode=")) {
       const value = arg.slice(arg.indexOf("=") + 1);
       const parsedMode = parseCaptureMode(value);
@@ -226,6 +263,18 @@ async function runStart(args: string[]): Promise<void> {
         port = Number(args[i + 1]);
         i++;
         break;
+      case "--host":
+      case "-H": {
+        const value = args[i + 1]?.trim() ?? "";
+        if (!isValidBindHost(value)) {
+          console.error(`Invalid host: ${value}. Use an IP or hostname without protocol/path.`);
+          process.exitCode = 1;
+          return;
+        }
+        host = value;
+        i++;
+        break;
+      }
       case "--no-open":
         open = false;
         openWasSpecified = true;
@@ -348,12 +397,13 @@ async function runStart(args: string[]): Promise<void> {
 
   process.env["PORT"] = String(port);
 
-  const url = `http://localhost:${port}`;
+  const url = urlForHost(port, host);
 
-  if (!forceRestart && (await isInspectorHealthy(port))) {
+  if (!forceRestart && (await isInspectorHealthy(port, host))) {
     console.log(`agent-inspector is already running at ${url}`);
+    printAccessHints(port, host);
     if (captureModeWasSpecified) {
-      const runningMode = await getRunningCaptureMode(port);
+      const runningMode = await getRunningCaptureMode(port, host);
       if (runningMode !== null && runningMode !== captureMode) {
         console.log(`Existing instance capture mode is ${runningMode}; requested ${captureMode}.`);
         console.log(`Use --force-restart to restart with ${captureMode} mode.`);
@@ -366,7 +416,7 @@ async function runStart(args: string[]): Promise<void> {
     return;
   }
 
-  if (!forceRestart && (await isPortAcceptingConnections(port))) {
+  if (!forceRestart && (await isPortAcceptingConnections(port, host))) {
     console.error(`Port ${port} is already in use, but it is not a healthy agent-inspector.`);
     console.error(`Stop that process, choose --port <n>, or re-run with --force-restart.`);
     process.exitCode = 1;
@@ -380,6 +430,7 @@ async function runStart(args: string[]): Promise<void> {
   console.log(`Server running at ${url}`);
   console.log(`   Capture mode: ${captureMode}`);
   console.log(`   Proxy: ${url}/proxy`);
+  printAccessHints(port, host);
   console.log(``);
   console.log(`Route AI coding tools through the proxy:`);
   console.log(`   Claude Code:  ANTHROPIC_BASE_URL=${url}/proxy claude`);
@@ -388,6 +439,9 @@ async function runStart(args: string[]): Promise<void> {
   console.log(
     `   Direct HTTP:  curl ${url}/proxy/v1/messages -d '{"model":"...","messages":[...]}'`,
   );
+  console.log(
+    `   Remote/container tools: use the Network proxy URL above when shown; otherwise restart with --host 0.0.0.0 or a reachable IP.`,
+  );
   console.log(``);
   console.log(`Routing environment variables:`);
   console.log(`   ROUTES            JSON map of model prefix -> upstream URL`);
@@ -429,6 +483,10 @@ async function runStart(args: string[]): Promise<void> {
   if (providersJson !== undefined) {
     serverEnv["AGENT_INSPECTOR_PROVIDERS_JSON"] = providersJson;
   }
+  if (host !== undefined) {
+    serverEnv["HOST"] = host;
+    serverEnv["NITRO_HOST"] = host;
+  }
   serverEnv["AGENT_INSPECTOR_CAPTURE_MODE"] = captureMode;
   const serverProcess = spawn(serverCommand.command, serverCommand.args, {
     stdio: background ? ["ignore", "ignore", "ignore"] : "inherit",
@@ -439,8 +497,9 @@ async function runStart(args: string[]): Promise<void> {
 
   if (background) {
     serverProcess.unref();
-    if (await waitForInspectorHealthy(port, 5000)) {
+    if (await waitForInspectorHealthy(port, 5000, host)) {
       console.log(`agent-inspector background server is ready at ${url}`);
+      printAccessHints(port, host);
       return;
     }
     console.error(`agent-inspector background server did not become ready at ${url}.`);