@tonyclaw/agent-inspector 3.0.45 → 3.0.47

package/src/cli/templates/skill-onboard.ts

@@ -24,8 +24,14 @@ export type SkillOnboardContext = {
   readonly version: string;
   /** The default proxy port (mirrors `DEFAULT_PORT` in `src/cli.ts`). */
   readonly port: number;
-  /** Public UI base URL, including the configured base path. */
+  /** Public backend control/agent Base URL, including the configured Base Path. */
   readonly baseUrl: string;
+  /** Optional composed or standalone UI URL. Undefined preserves the legacy composed default. */
+  readonly uiUrl?: string | null;
+  /** REST/SSE Base URL. Falls back to baseUrl for compatibility. */
+  readonly controlBaseUrl?: string;
+  /** Proxy/MCP Base URL. Falls back to baseUrl for compatibility. */
+  readonly agentBaseUrl?: string;
   /** MCP config key selected by onboarding. */
   readonly mcpName?: string;
   /** Selected onboarding target type. */
@@ -56,24 +62,29 @@ export const REQUIRED_PHASE_HEADINGS = [
 ] as const;
 
 export function renderSkillOnboard(ctx: SkillOnboardContext): string {
-  const { version, port, baseUrl, detectedSummary } = ctx;
+  const { version, port, detectedSummary } = ctx;
+  const controlBaseUrl = ctx.controlBaseUrl ?? ctx.baseUrl;
+  const agentBaseUrl = ctx.agentBaseUrl ?? ctx.baseUrl;
+  const uiUrl = ctx.uiUrl === undefined ? ctx.baseUrl : ctx.uiUrl;
   const mcpName = ctx.mcpName ?? "agent-inspector";
   const targetKind = ctx.targetKind ?? "default";
   const targetArguments = ctx.onboardTargetArguments ?? "";
   const instanceName = ctx.instanceName ?? null;
-  const healthUrl = `${baseUrl}/api/health`;
-  const configUrl = `${baseUrl}/api/config`;
-  const anthropicProxyUrl = `${baseUrl}/proxy`;
-  const openAiProxyUrl = `${baseUrl}/proxy/v1`;
-  const mcpUrl = `${baseUrl}/api/mcp`;
-  const logsUrl = `${baseUrl}/api/logs`;
+  const healthUrl = `${controlBaseUrl}/api/health`;
+  const runtimeUrl = `${controlBaseUrl}/api/runtime`;
+  const configUrl = `${controlBaseUrl}/api/config`;
+  const anthropicProxyUrl = `${agentBaseUrl}/proxy`;
+  const openAiProxyUrl = `${agentBaseUrl}/proxy/v1`;
+  const mcpUrl = `${agentBaseUrl}/api/mcp`;
+  const logsUrl = `${controlBaseUrl}/api/logs`;
+  const providersUrl = `${controlBaseUrl}/api/providers`;
   const statusCommand = `agent-inspector onboard --status${targetArguments}`;
   const refreshCommand = `agent-inspector onboard --force${targetArguments}`;
   const startCommand =
     targetKind === "instance" && instanceName !== null
       ? `agent-inspector instance start ${instanceName}`
       : targetKind === "base-url"
-        ? `# Explicit target ${baseUrl}: do not start a replacement local runtime.`
+        ? `# Explicit control target ${controlBaseUrl}: do not start a replacement local runtime.`
         : "agent-inspector --mode simple --background --no-open";
   const fullModeCommand =
     targetKind === "instance" && instanceName !== null
@@ -95,17 +106,27 @@ if (-not $found) { throw 'agent-inspector is not on PATH' }
 & $found.Source ${windowsStartArguments}`;
   const startExplanation =
     targetKind === "base-url"
-      ? `The selected Inspector target is the explicit Base URL \`${baseUrl}\`. Do not launch a default local runtime as a substitute; verify the selected target and ask its operator for help if it is unavailable.`
-      : `Start or reuse the selected Inspector runtime. It listens on port ${String(port)} and preserves the selected Base Path. Use \`${fullModeCommand}\` only when the user needs raw headers, raw response, or SSE chunks.`;
+      ? `The selected Inspector target uses control Base URL \`${controlBaseUrl}\` and agent Base URL \`${agentBaseUrl}\`. Do not launch a default local runtime as a substitute; verify the selected target and ask its operator for help if it is unavailable.`
+      : `Start or reuse the selected Inspector backend. Its public control and agent endpoints preserve the selected Base Path; a Web UI may be composed at the same URL, hosted separately, or intentionally absent in backend-only mode. Use \`${fullModeCommand}\` only when the user needs raw headers, raw response, or SSE chunks.`;
   const stopSnippet =
     targetKind === "instance" && instanceName !== null
       ? `agent-inspector instance stop ${instanceName}`
       : targetKind === "base-url"
-        ? `# Ask the operator of ${baseUrl} to stop the selected runtime.`
+        ? `# Ask the operator of ${controlBaseUrl} to stop the selected runtime.`
         : `# Unix / macOS\n  lsof -ti:${String(port)} | xargs -r kill -9\n\n  # Windows PowerShell\n  Get-NetTCPConnection -LocalPort ${String(port)} | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }`;
+  const providerScopeGuidance =
+    targetKind === "default"
+      ? "The unmanaged default target owns the local Agent Inspector data directory used by the file checks below."
+      : `The selected target is not the unmanaged default data directory. Do not inspect or edit local ~/.agent-inspector Provider files as a substitute. Query \`${providersUrl}\`, use the selected target's MCP Provider tools with explicit approval, or ask its operator to configure Providers. Skip local-file commands below.`;
+  const selectedUi =
+    uiUrl === null ? "not supplied (do not infer one from a backend URL)" : `\`${uiUrl}\``;
+  const uiTour =
+    uiUrl === null
+      ? "not supplied; continue with MCP/REST, and ask the operator for a standalone UI URL only if the user needs one"
+      : `\`${uiUrl}\` — use this explicit composed or standalone browser URL; do not replace it with the control or agent Base URL`;
   return `---
 name: agent-inspector-onboard
-description: Guided setup for Agent Inspector v${version}: start the proxy, wire your AI coding tool, capture your first request, and learn the Web UI.
+description: Guided setup for Agent Inspector v${version}: start or select the backend, wire your AI coding tool, and capture your first request with or without a Web UI.
 metadata:
   author: agent-inspector
   version: ${version}
@@ -113,12 +134,16 @@ metadata:
 
 # Agent Inspector onboard
 
-Guide the user from "I just installed Agent Inspector" to "I can see my AI tool's traffic in the Web UI". This is a teaching experience: you'll do real work in their environment while explaining each step.
+Guide the user from "I just installed Agent Inspector" to "my coding agent can use the proxy, REST API, and MCP surface". The backend works in composed and headless deployments; treat the Web UI as an optional presentation surface.
 
 Environment detected by the installer:
 ${detectedSummary || "  (no known AI tool detected — the user can still use the generic curl example in Phase 4)"}
 
-Selected Inspector target: \`${baseUrl}\` (MCP key: \`${mcpName}\`).
+Selected Inspector surfaces:
+- UI URL: ${selectedUi}
+- Control Base URL: \`${controlBaseUrl}\`
+- Agent Base URL: \`${agentBaseUrl}\`
+- MCP key: \`${mcpName}\`
 
 > **PAUSE protocol.** Every \`**PAUSE**\` marker in this skill is a real stop.
 > Use the \`AskUserQuestion\` tool to actually wait for the user before
@@ -146,9 +171,11 @@ ${statusCommand}
 
 **DO:** Then probe the three pieces of state this skill touches. Use targeted checks — do **not** read large JSON files into the conversation.
 
+**DO:** ${providerScopeGuidance}
+
 \`\`\`bash
-# 1. Is the proxy already up?
-curl -fsS "${healthUrl}" 2>/dev/null && echo "PROXY: up" || echo "PROXY: down"
+# 1. Is the backend already up?
+curl -fsS "${healthUrl}" 2>/dev/null && echo "BACKEND: up" || echo "BACKEND: down"
 
 # 2. Does the provider config have a real provider key?
 agent_inspector_data_dir() {
@@ -209,12 +236,12 @@ $dataDir = Resolve-AgentInspectorDataDir
 $providers = Join-Path $dataDir 'providers.json'
 $legacyConfig = Join-Path $dataDir 'config.json'
 
-# 1. Is the proxy already up?
+# 1. Is the backend already up?
 try {
   $null = Invoke-RestMethod -Uri "${healthUrl}" -TimeoutSec 2 -ErrorAction Stop
-  Write-Host 'PROXY: up'
+  Write-Host 'BACKEND: up'
 } catch {
-  Write-Host 'PROXY: down'
+  Write-Host 'BACKEND: down'
 }
 
 # 2. Does the config have a real provider key?
@@ -284,7 +311,7 @@ node -e "const fs=require('node:fs'),p=require('node:path');const names=process.
 \`\`\`
 ## Welcome to Agent Inspector!
 
-Agent Inspector is an agent observability and knowledge-capture platform for AI coding tools. The \`agent-inspector\` CLI runs a transparent local proxy + Web UI, so you can see model requests and responses, system prompts, tool definitions, message history, timing, and token counts captured live in a browser tab.
+Agent Inspector is an agent observability and knowledge-capture platform for AI coding tools. Its backend owns the transparent model proxy, REST/SSE APIs, capture storage, and MCP server. The default CLI composes a Web UI at the same public Base URL, while \`--backend-only\` keeps every Coding Agent surface available without serving UI files.
 
 Agent Inspector starts in **Simple mode** by default. Simple mode is the right habit for everyday use: it keeps requests, responses, tools, timing, and token usage while avoiding heavier raw headers, raw response, and detailed SSE chunk artifacts. Use **Full mode** only when the user is debugging provider headers, raw response payloads, or SSE stream details.
 
@@ -304,6 +331,8 @@ Ready? Let's start with the provider.
 
 ## Phase 2: Provider setup
 
+**DO:** ${providerScopeGuidance}
+
 **EXPLAIN:** "A 'provider' is an upstream LLM endpoint — Anthropic, OpenAI, MiniMax, etc. agent-inspector routes each request to the right upstream based on the model name. You need at least one provider configured for the proxy to forward traffic."
 
 **DO:** First, re-check whether \`<dataDir>/providers.json\` already has a real key (Phase 0 may have raced with a manual edit). Use the same data-dir resolution and \`grep -qE '"apiKey":"sk-'\` (bash) or \`Select-String\` (PowerShell) check from Phase 0. If a real key is present, skip the rest of this phase.
@@ -399,7 +428,7 @@ $json | Set-Content -Path $file -Encoding UTF8
 
 **EXPLAIN:** "${startExplanation}"
 
-**DO:** Skip this phase entirely if the Phase 0 health check already reported \`PROXY: up\` and the user opted to skip done phases.
+**DO:** Skip this phase entirely if the Phase 0 health check already reported \`BACKEND: up\` and the user opted to skip done phases.
 
 **DO:** Otherwise, use the selected target command below. An explicit wrapper Base URL is connection-only and must not cause a replacement local runtime to start.
 
@@ -412,7 +441,7 @@ ${bashStartSnippet}
 ${powershellStartSnippet}
 \`\`\`
 
-Then wait for the port to be ready:
+Then wait for the selected backend health URL to be ready:
 
 \`\`\`bash
 for i in $(seq 1 20); do
@@ -421,12 +450,18 @@ for i in $(seq 1 20); do
 done
 \`\`\`
 
-**DO:** Hit the health endpoint to confirm the proxy is alive:
+**DO:** Hit the health endpoint to confirm the backend is alive:
 
 \`\`\`bash
 curl -sS "${healthUrl}"
 \`\`\`
 
+**DO:** Read the token-free runtime discovery document. Report \`deploymentMode\` and capabilities; do not treat \`backend-only\` as a failure or infer that a UI is present.
+
+\`\`\`bash
+curl -sS "${runtimeUrl}"
+\`\`\`
+
 **DO:** Read \`/api/config\` and tell the user which capture mode is active. If deeper capture is required, offer \`${fullModeCommand}\`.
 
 \`\`\`bash
@@ -566,10 +601,11 @@ done
 
 ## Phase 6: Tour & wrap
 
-**EXPLAIN:** "Everything's working. Here's the cheat sheet for the Web UI and the supporting surfaces:"
+**EXPLAIN:** "Everything's working. Here's the cheat sheet for the backend surfaces and the optional Web UI:"
 
-- **Web UI**: \`${baseUrl}\` — collapsible log rows, per-tab Copy/Expand in the log header, Diff with Raw (request body), Diff with Previous (compare adjacent requests), Replay (re-send a request), Export (JSON ZIP).
-- **MCP server**: \`${mcpUrl}\` — connect from your coding agent to query logs, replay, and test providers without leaving the editor. Look for the "MCP Ready" badge in the Web UI header.
+- **Runtime discovery**: \`${runtimeUrl}\` — token-free deployment mode, UI Base Path, control/agent Base URLs, and capabilities.
+- **Web UI**: ${uiTour}.
+- **MCP server**: \`${mcpUrl}\` — connect from the coding agent to query logs, replay, and test providers; it does not require a Web UI process.
 - **REST API**: \`/api/logs\`, \`/api/sessions\`, \`/api/providers\` — for scripting and shell-based inspection.
 - **Stop the proxy**:
 
@@ -580,7 +616,7 @@ ${stopSnippet}
 - **Re-run onboard**: \`${refreshCommand}\` refreshes this skill.
 - **Check onboard files**: \`${statusCommand}\` shows whether generated skills are
   current, outdated, missing, newer, or custom.
-- **Full docs**: see the project README (linked from the Web UI footer).
+- **Full docs**: see the project README; do not depend on a UI footer being available.
 
 > **PAUSE** — use \`AskUserQuestion\` with header \`All set?\` and options \`["All set, I'm done", "Wait, I want to revisit a phase"]\`. Wait for the answer.