@tonyclaw/agent-inspector 3.1.32 → 4.0.2

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

@@ -1,320 +0,0 @@
-/**
- * Renders `~/.codex/skills/agent-inspector-onboard/SKILL.md` for Codex.
- *
- * This is intentionally separate from the Claude Code onboarding skill because
- * Codex uses `~/.codex/config.toml` and supports streamable HTTP MCP servers via
- * `mcp_servers.<id>.url`.
- */
-
-export type CodexSkillOnboardContext = {
-  /** Package version (from `package.json`), stamped into the frontmatter. */
-  readonly version: string;
-  /** The default proxy port (mirrors `DEFAULT_PORT` in `src/cli.ts`). */
-  readonly port: number;
-  /** 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. */
-  readonly targetKind?: "default" | "instance" | "base-url";
-  /** Normalized registry name for a named target. */
-  readonly instanceName?: string | null;
-  /** CLI arguments that reproduce the selected target. */
-  readonly onboardTargetArguments?: string;
-};
-
-export const REQUIRED_CODEX_PHASE_HEADINGS = [
-  "Phase 0: Preflight",
-  "Phase 1: Start Agent Inspector",
-  "Phase 2: Wire Codex MCP",
-  "Phase 3: Restart and verify Codex",
-  "Phase 4: First Inspector query",
-  "Phase 5: Capture and memory review",
-] as const;
-
-export function renderCodexSkillOnboard(ctx: CodexSkillOnboardContext): string {
-  const { version } = 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 = `${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 mcpTomlKey = /^[A-Za-z0-9_-]+$/u.test(mcpName) ? mcpName : JSON.stringify(mcpName);
-  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 control target ${controlBaseUrl}: do not start a replacement local runtime.`
-        : "agent-inspector --mode simple --background --no-open";
-  const fullModeCommand =
-    targetKind === "instance" && instanceName !== null
-      ? `agent-inspector instance restart ${instanceName} --mode full`
-      : targetKind === "base-url"
-        ? "ask the target operator to enable Full capture mode"
-        : "agent-inspector --mode full --force-restart";
-  const startExplanation =
-    targetKind === "base-url"
-      ? `The selected Inspector target uses control Base URL \`${controlBaseUrl}\` and agent Base URL \`${agentBaseUrl}\`. Do not start the 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 Agent Inspector backend before wiring MCP. The default command composes a UI, while backend-only named instances retain proxy, REST, health, and MCP without UI files. Prefer the installed binary so Windows users get the branded runtime in Task Manager. Use \`${fullModeCommand}\` only when the user needs raw headers, raw response, or SSE chunks.`;
-  const selectedUi =
-    uiUrl === null ? "not supplied (do not infer one from a backend URL)" : `\`${uiUrl}\``;
-  const providerTestUiGuidance =
-    uiUrl === null
-      ? `No UI URL was supplied. Do not open \`${controlBaseUrl}\` or \`${agentBaseUrl}\` as a page; use the MCP Provider Test tools and log/session resources, or ask the operator for a standalone UI URL.`
-      : `The operator supplied the explicit composed or standalone UI URL \`${uiUrl}\`. Use that URL for browser steps; do not substitute the control or agent Base URL.`;
-  return `---
-name: agent-inspector-onboard
-description: Guide Codex users through connecting Agent Inspector v${version} as a local MCP server.
-metadata:
-  author: agent-inspector
-  version: ${version}
----
-
-# Agent Inspector onboard for Codex
-
-Use this skill when the user wants to set up Agent Inspector inside Codex, connect the Agent Inspector MCP server, inspect captured model traffic from Codex, or turn Inspector sessions into reviewable knowledge candidates.
-
-The selected deployment has these explicit surfaces:
-
-- UI URL: ${selectedUi}
-- Control Base URL: \`${controlBaseUrl}\`
-- Agent Base URL: \`${agentBaseUrl}\`
-
-Composed mode may use one URL for all three, but backend-only mode and separately hosted UI deployments do not require UI and backend to share a process, origin, or port. The selected MCP endpoint is:
-
-\`\`\`text
-${mcpUrl}
-\`\`\`
-
-This skill is installed at \`~/.codex/skills/agent-inspector-onboard/SKILL.md\`.
-Codex user-level configuration lives in \`~/.codex/config.toml\`. Codex supports streamable HTTP MCP servers with \`mcp_servers.<id>.url\`, so no extra stdio bridge package is needed.
-
-Use exactly one MCP transport for the same Inspector instance:
-
-- Streamable HTTP MCP: configure \`url = "${mcpUrl}"\`.
-- Stdio-only MCP clients: configure \`agent-inspector-mcp stdio --url ${mcpUrl}\`.
-
-Do not configure both transports in the same MCP client, or the client may show duplicate Inspector tools.
-
-Keep this setup local and explicit. Agent Inspector MCP tools can read captured requests and provider configuration, so only wire it into trusted local Codex environments.
-
-The backend publishes token-free runtime discovery at \`${runtimeUrl}\`. Treat \`backend-only\` as healthy when REST, proxy, and MCP capabilities are present.
-
-Agent Inspector starts in **Simple mode** by default. Keep Simple mode for everyday capture: requests, responses, tools, timing, and token usage stay available without retaining heavier raw headers, raw response, or detailed SSE chunk artifacts. Use **Full mode** only when the user is debugging provider headers, raw response payloads, or SSE stream details.
-
----
-
-## Phase 0: Preflight
-
-Check that the package and Codex home exist without printing secrets.
-
-\`\`\`powershell
-Get-Command agent-inspector -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Source
-${statusCommand}
-Test-Path (Join-Path $env:USERPROFILE ".codex")
-Test-Path (Join-Path $env:USERPROFILE ".codex\\config.toml")
-\`\`\`
-
-\`\`\`bash
-node -e "const fs=require('node:fs'),p=require('node:path');const names=process.platform==='win32'?['agent-inspector.cmd','agent-inspector.exe','agent-inspector']:['agent-inspector'];const found=(process.env.PATH||'').split(p.delimiter).some(d=>names.some(n=>fs.existsSync(p.join(d,n))));console.log(found?'agent-inspector: present':'agent-inspector: missing')"
-${statusCommand}
-test -d "$HOME/.codex" && echo "codex home: present" || echo "codex home: missing"
-test -f "$HOME/.codex/config.toml" && echo "config: present" || echo "config: missing"
-\`\`\`
-
-If \`agent-inspector\` is missing, ask the user to install it first:
-
-\`\`\`bash
-npm install -g @tonyclaw/agent-inspector
-\`\`\`
-
-If \`${statusCommand}\` reports \`outdated\` or \`missing\`, ask the user to run
-\`${refreshCommand}\` and restart this skill before continuing.
-
-Do not read \`~/.codex/auth.json\`, token files, or unrelated Codex state files.
-
----
-
-## Phase 1: Start Agent Inspector
-
-${startExplanation}
-
-\`\`\`powershell
-${startCommand}
-Invoke-RestMethod -Uri "${healthUrl}" -TimeoutSec 3
-Invoke-RestMethod -Uri "${runtimeUrl}" -TimeoutSec 3 | Select-Object deploymentMode, capabilities
-Invoke-RestMethod -Uri "${configUrl}" -TimeoutSec 3 | Select-Object captureMode
-\`\`\`
-
-\`\`\`bash
-${startCommand}
-curl -fsS "${healthUrl}"
-curl -fsS "${runtimeUrl}"
-curl -fsS "${configUrl}" | grep -o '"captureMode":"[^"]*"'
-\`\`\`
-
-If the health check fails, show only the relevant error and ask whether to diagnose the selected target before editing Codex config. If deeper capture is required, offer \`${fullModeCommand}\`.
-
----
-
-## Phase 2: Wire Codex MCP
-
-Add the \`${mcpName}\` MCP server to \`~/.codex/config.toml\`. Preserve the user's existing config and merge the table instead of replacing the file.
-
-Recommended user-level config for Codex builds that support Streamable HTTP MCP:
-
-\`\`\`toml
-[mcp_servers.${mcpTomlKey}]
-url = "${mcpUrl}"
-startup_timeout_sec = 30
-tool_timeout_sec = 60
-\`\`\`
-
-Fallback config for a stdio-only MCP client:
-
-\`\`\`toml
-[mcp_servers.${mcpTomlKey}]
-command = "agent-inspector-mcp"
-args = ["stdio", "--url", "${mcpUrl}"]
-\`\`\`
-
-The stdio command is only a bridge to the same HTTP MCP endpoint. It does not start a second Inspector server.
-
-If the user's Codex environment is managed by an admin allowlist, they may also need a matching identity rule in the managed requirements layer:
-
-\`\`\`toml
-[mcp_servers.${mcpTomlKey}.identity]
-url = "${mcpUrl}"
-\`\`\`
-
-When editing:
-
-- Ask before changing \`~/.codex/config.toml\`.
-- Keep existing \`mcp_servers.*\`, \`projects.*\`, profiles, sandbox, approval, and model settings intact.
-- Remove any duplicate Inspector MCP entry that points to the same \`/api/mcp\` endpoint or runs the same \`agent-inspector-mcp stdio\` bridge under another name.
-- Do not write provider API keys into Codex config.
-- Do not expose a raw Inspector listener to untrusted networks. For remote use, require the operator's authenticated same-origin gateway and keep control credentials in environment variables rather than generated config.
-
----
-
-## Phase 3: Restart and verify Codex
-
-Tell the user that Codex loads MCP servers at session startup. After saving \`config.toml\`, they should start a new Codex session or restart the Codex app.
-
-Before restart, verify the HTTP endpoint itself:
-
-\`\`\`bash
-curl -sS -X POST "${mcpUrl}" \\
-  -H "Content-Type: application/json" \\
-  -H "Accept: application/json, text/event-stream" \\
-  -d '{
-    "jsonrpc": "2.0",
-    "id": 1,
-    "method": "initialize",
-    "params": {
-      "protocolVersion": "2025-03-26",
-      "capabilities": {},
-      "clientInfo": { "name": "codex-onboard-check", "version": "0" }
-    }
-  }'
-\`\`\`
-
-Expected signal: a 200 response containing \`serverInfo\` with \`agent-inspector\`.
-
----
-
-## Phase 4: First Inspector query
-
-After Codex restarts with the MCP server configured, ask Codex to use Agent Inspector:
-
-\`\`\`text
-Use Agent Inspector to list the latest captured logs.
-\`\`\`
-
-The expected tool is \`inspector_list_logs\`. If no logs exist yet, that is still a successful MCP connection.
-
-Useful follow-up tools:
-
-- \`inspector_list_logs\`
-- \`inspector_get_log\`
-- \`inspector_get_log_chunks\`
-- \`inspector_list_sessions\`
-- \`inspector_test_provider\`
-- \`inspector_create_session_knowledge\`
-- \`inspector_list_knowledge_candidates\`
-- \`inspector_search_knowledge\`
-- \`inspector_get_project_context\`
-
-Provider mutation tools expose and modify local provider configuration. Ask for explicit user confirmation before using \`inspector_add_provider\`, \`inspector_update_provider\`, or \`inspector_replay_log\`.
-
----
-
-## Phase 5: Capture and memory review
-
-To capture traffic through Agent Inspector, use the protocol-correct base URL:
-
-\`\`\`text
-Anthropic: ${anthropicProxyUrl}
-OpenAI Responses / Codex: ${openAiProxyUrl}
-\`\`\`
-
-For Anthropic-compatible tools, set \`ANTHROPIC_BASE_URL=${anthropicProxyUrl}\`. For OpenAI-compatible tools and Codex Responses providers, set \`OPENAI_BASE_URL=${openAiProxyUrl}\`.
-
-Example Codex Responses provider snippet:
-
-\`\`\`toml
-[model_providers.agent-inspector]
-name = "Agent Inspector"
-base_url = "${openAiProxyUrl}"
-wire_api = "responses"
-\`\`\`
-
-If Codex or another AI tool runs in a different container, VM, WSL distro, or host than Agent
-Inspector, \`localhost\` points at the tool's own environment. Replace \`localhost\` with an Inspector
-address reachable from that environment, then verify the network/firewall path before debugging
-provider credentials.
-
-For a Provider Test memory probe, first read \`${runtimeUrl}\`. ${providerTestUiGuidance}
-
-When an explicit UI URL is available:
-
-1. Open the supplied UI URL.
-2. Go to Settings -> Providers.
-3. Add or edit a Provider.
-4. Run Test.
-5. Check the \`provider-test\` session.
-
-If discovery reports \`backend-only\`, do not fail onboarding. A separately hosted UI may still exist only when its URL was explicitly supplied; otherwise use the MCP Provider Test tools and log/session resources. Proxy, REST, health, and MCP remain fully usable without UI files.
-
-Then ask Codex:
-
-\`\`\`text
-Use Agent Inspector to create knowledge candidates for the provider-test session, then list the candidates.
-\`\`\`
-
-Expected flow:
-
-- Raw Trace stays in Agent Inspector logs.
-- Session Episode is reconstructed from the session.
-- Memory Candidate is generated for review.
-- Promotion to OpenClaw happens only after review through Agent Inspector.
-
-Stop after showing candidates unless the user explicitly approves promotion.
-`;
-}

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

@@ -1,25 +0,0 @@
-/**
- * Renders `~/.claude/commands/agent-inspector:onboard.md` - a thin slash
- * command that loads the `agent-inspector-onboard` skill. Claude Code
- * auto-discovers both the skill and the command once they're written,
- * so the command body just references the skill by name.
- */
-
-export type CommandOnboardContext = {
-  /** Package version (from `package.json`), stamped into the frontmatter. */
-  readonly version: string;
-};
-
-export function renderCommandOnboard(ctx: CommandOnboardContext): string {
-  return `---
-description: Walk through agent-inspector setup - start the proxy, wire your AI tool, capture your first request.
-metadata:
-  author: agent-inspector
-  version: ${ctx.version}
----
-
-Invoke the \`agent-inspector-onboard\` skill and follow its phases.
-
-The user wants to set up agent-inspector. If they have specific context (e.g. "I'm on Windows", "I already added my API key"), honor it - but otherwise just run the skill end-to-end and let the \`EXPLAIN / DO / PAUSE\` markers drive the conversation.
-`;
-}