@tonyclaw/llm-inspector 1.19.1 → 1.19.3

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

@@ -257,15 +257,15 @@ New-Item -ItemType Directory -Force -Path $dir | Out-Null
 
 ## Phase 3: Start proxy
 
-**EXPLAIN:** "Time to start the proxy. It binds to port ${port} by default, kills any process already on that port, and prints the URL."
+**EXPLAIN:** "Time to start the proxy. It binds to port ${port} by default, reuses an already-running healthy llm-inspector, and prints the URL. Use \`--force-restart\` only when you intentionally want to replace the existing process."
 
 **DO:** Skip this phase entirely if the Phase 0 health check already reported \`PROXY: up\` and the user opted to skip done phases.
 
-**DO:** Otherwise, start the proxy in the background. On Windows, the npm shim is a \`.cmd\`/PowerShell file — \`Start-Process -FilePath "llm-inspector"\` returns "Invalid Win32 application" because Windows can't decide which shim to run. Use \`cmd /c start /B\` to background it through the cmd interpreter.
+**DO:** Otherwise, start the proxy with the explicit \`--background --no-open\` flags. On Windows, resolve the npm shim first and launch it through \`Start-Process -WindowStyle Hidden\` so setup does not flash a command window.
 
 \`\`\`bash
 # Unix / macOS / WSL
-nohup llm-inspector --no-open > /tmp/llm-inspector.log 2>&1 &
+llm-inspector --background --no-open > /tmp/llm-inspector.log 2>&1
 \`\`\`
 
 \`\`\`powershell
@@ -278,14 +278,14 @@ $err = Join-Path $env:TEMP 'llm-inspector.err.log'
 $found = Get-Command llm-inspector -ErrorAction SilentlyContinue
 if ($found) {
   $shim = $found.Source
-  $args = '--no-open'
+  $args = '--background','--no-open'
 } elseif (Test-Path (Join-Path $env:APPDATA 'npm/llm-inspector.cmd')) {
   $shim = Join-Path $env:APPDATA 'npm/llm-inspector.cmd'
-  $args = '--no-open'
+  $args = '--background','--no-open'
 } else {
   # bin not on PATH and not at the default npm prefix — let cmd resolve it
   $shim = 'cmd.exe'
-  $args = '/c','start','/B','llm-inspector','--no-open'
+  $args = '/c','llm-inspector','--background','--no-open'
 }
 Start-Process -FilePath $shim -ArgumentList $args -RedirectStandardOutput $log -RedirectStandardError $err -WindowStyle Hidden
 \`\`\`

package/src/cli.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { spawn, execSync } from "node:child_process";
+import { spawn, execSync, type ChildProcess } from "node:child_process";
+import { createConnection } from "node:net";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { existsSync } from "node:fs";
@@ -8,6 +9,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 const DEFAULT_PORT = 25947;
+const LOCAL_PROBE_TIMEOUT_MS = 2000;
 
 /**
  * Subcommand router. The legacy one-liner UX (`llm-inspector` with no args,
@@ -23,18 +25,107 @@ if (subcommand === "onboard") {
   process.exit(code);
 }
 
-runStart(process.argv.slice(2));
+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.
 // -----------------------------------------------------------------------------
-function runStart(args: string[]): void {
+async function isInspectorHealthy(port: number): 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`, {
+      cache: "no-store",
+      signal: controller.signal,
+    });
+    return response.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function isPortAcceptingConnections(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = createConnection({ host: "127.0.0.1", port });
+    const finish = (value: boolean): void => {
+      socket.removeAllListeners();
+      socket.destroy();
+      resolve(value);
+    };
+
+    socket.setTimeout(LOCAL_PROBE_TIMEOUT_MS);
+    socket.once("connect", () => finish(true));
+    socket.once("timeout", () => finish(false));
+    socket.once("error", () => finish(false));
+  });
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+async function waitForInspectorHealthy(port: number, timeoutMs: number): Promise<boolean> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await isInspectorHealthy(port)) return true;
+    await sleep(250);
+  }
+  return false;
+}
+
+function openBrowser(targetUrl: string): void {
+  let command: string[] | undefined;
+  // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
+  switch (process.platform) {
+    case "darwin":
+      command = ["open", targetUrl];
+      break;
+    case "linux":
+      command = ["xdg-open", targetUrl];
+      break;
+    case "win32":
+      command = ["cmd", "/c", "start", "", targetUrl];
+      break;
+    default:
+      // Unsupported platform - do nothing
+      break;
+  }
+  if (command === undefined) return;
+  const [bin, ...cmdArgs] = command;
+  if (bin === undefined) return;
+  const browserProcess = spawn(bin, cmdArgs, {
+    stdio: "ignore",
+    detached: true,
+    windowsHide: true,
+  });
+  browserProcess.unref();
+}
+
+function waitForProcessExit(child: ChildProcess): Promise<number> {
+  return new Promise((resolve) => {
+    child.once("exit", (code) => {
+      resolve(code ?? 1);
+    });
+    child.once("error", () => {
+      resolve(1);
+    });
+  });
+}
+
+async function runStart(args: string[]): Promise<void> {
   const envPort = process.env["PORT"];
   const portDefault = envPort !== undefined ? Number(envPort) : DEFAULT_PORT;
 
   let port = portDefault;
   let open = true;
+  let openWasSpecified = false;
+  let background = false;
+  let forceRestart = false;
   let configDir: string | undefined;
   let providersJson: string | undefined;
 
@@ -48,9 +139,18 @@ function runStart(args: string[]): void {
         break;
       case "--no-open":
         open = false;
+        openWasSpecified = true;
         break;
       case "--open":
         open = true;
+        openWasSpecified = true;
+        break;
+      case "--force-restart":
+      case "--restart":
+        forceRestart = true;
+        break;
+      case "--background":
+        background = true;
         break;
       case "--config-dir":
         configDir = args[i + 1];
@@ -65,6 +165,12 @@ function runStart(args: string[]): void {
     }
   }
 
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    console.error(`Invalid port: ${String(port)}. Use --port <1-65535>.`);
+    process.exitCode = 1;
+    return;
+  }
+
   /**
    * Check if a port is in use and kill the process using it
    */
@@ -79,6 +185,7 @@ function runStart(args: string[]): void {
         const output = execSync(`netstat -ano | findstr :${targetPort}`, {
           encoding: "utf8",
           timeout: 5000,
+          windowsHide: true,
         });
         const lines = output.trim().split("\n");
         for (const line of lines) {
@@ -99,8 +206,12 @@ function runStart(args: string[]): void {
 
         for (const pid of pids) {
           try {
-            console.log(`Killing process ${pid} on port ${port}...`);
-            execSync(`taskkill /PID ${pid} /F`, { encoding: "utf8", timeout: 5000 });
+            console.log(`Killing process ${pid} on port ${targetPort}...`);
+            execSync(`taskkill /PID ${pid} /F`, {
+              encoding: "utf8",
+              timeout: 5000,
+              windowsHide: true,
+            });
           } catch {
             // Process may have already exited
           }
@@ -120,7 +231,7 @@ function runStart(args: string[]): void {
 
         for (const pid of pids) {
           try {
-            console.log(`Killing process ${pid} on port ${port}...`);
+            console.log(`Killing process ${pid} on port ${targetPort}...`);
             execSync(`kill -9 ${pid}`, { encoding: "utf8", timeout: 5000 });
           } catch {
             // Process may have already exited
@@ -134,11 +245,28 @@ function runStart(args: string[]): void {
 
   process.env["PORT"] = String(port);
 
-  // Kill any existing process on the port
-  killProcessOnPort(port);
-
   const url = `http://localhost:${port}`;
 
+  if (!forceRestart && (await isInspectorHealthy(port))) {
+    console.log(`llm-inspector is already running at ${url}`);
+    console.log(`Use --force-restart to restart the existing instance.`);
+    if (open && openWasSpecified) {
+      openBrowser(url);
+    }
+    return;
+  }
+
+  if (!forceRestart && (await isPortAcceptingConnections(port))) {
+    console.error(`Port ${port} is already in use, but it is not a healthy llm-inspector.`);
+    console.error(`Stop that process, choose --port <n>, or re-run with --force-restart.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (forceRestart) {
+    killProcessOnPort(port);
+  }
+
   console.log(`Server running at ${url}`);
   console.log(`   Proxy: ${url}/proxy`);
   console.log(``);
@@ -157,29 +285,6 @@ function runStart(args: string[]): void {
     `   Example: ROUTES='{"claude-":"https://api.anthropic.com","MiniMax":"https://api.minimaxi.com/anthropic"}'`,
   );
 
-  const openBrowser = (targetUrl: string): void => {
-    let command: string[] | undefined;
-    // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
-    switch (process.platform) {
-      case "darwin":
-        command = ["open", targetUrl];
-        break;
-      case "linux":
-        command = ["xdg-open", targetUrl];
-        break;
-      case "win32":
-        command = ["cmd", "/c", "start", targetUrl];
-        break;
-      default:
-        // Unsupported platform - do nothing
-        break;
-    }
-    if (command === undefined) return;
-    const [bin, ...cmdArgs] = command;
-    if (bin === undefined) return;
-    spawn(bin, cmdArgs, { stdio: "ignore", detached: true });
-  };
-
   if (open) {
     openBrowser(url);
   }
@@ -211,10 +316,22 @@ function runStart(args: string[]): void {
     serverEnv["LLM_INSPECTOR_PROVIDERS_JSON"] = providersJson;
   }
   const serverProcess = spawn(process.execPath, [serverPath], {
-    stdio: ["ignore", "inherit", "inherit"],
-    detached: true,
+    stdio: background ? ["ignore", "ignore", "ignore"] : "inherit",
+    detached: background,
     env: serverEnv,
+    windowsHide: background,
   });
 
-  serverProcess.unref();
+  if (background) {
+    serverProcess.unref();
+    if (await waitForInspectorHealthy(port, 5000)) {
+      console.log(`llm-inspector background server is ready at ${url}`);
+      return;
+    }
+    console.error(`llm-inspector background server did not become ready at ${url}.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  process.exitCode = await waitForProcessExit(serverProcess);
 }

package/src/components/ProxyViewerContainer.tsx

@@ -61,6 +61,8 @@ function filterLogs(
 }
 
 const DEBOUNCE_MS = 50;
+const HASH_SCROLL_ATTEMPTS = 12;
+const HASH_HIGHLIGHT_MS = 1800;
 
 function buildLogsStreamUrl(sessionId: string | undefined): string {
   if (sessionId === undefined) return "/api/logs/stream";
@@ -93,6 +95,7 @@ export function ProxyViewerContainer({
   const [error, setError] = useState<string | null>(null);
   const eventSourceRef = useRef<EventSource | null>(null);
   const reconnectTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const handledHashRef = useRef<string | null>(null);
 
   // O(1) log lookup by id
   const logIndexRef = useRef<Map<number, number>>(new Map());
@@ -214,6 +217,55 @@ export function ProxyViewerContainer({
     };
   }, [connectSSE]);
 
+  useEffect(() => {
+    const hash = window.location.hash;
+    if (!hash.startsWith("#log-")) return;
+    if (handledHashRef.current === hash) return;
+    const targetId = hash.slice(1);
+    let cancelled = false;
+    let attempts = 0;
+    let highlightedTarget: HTMLElement | null = null;
+    let highlightTimer: number | null = null;
+
+    const tryScrollToLog = (): void => {
+      if (cancelled) return;
+      const target = document.getElementById(targetId);
+      if (target !== null) {
+        handledHashRef.current = hash;
+        target.scrollIntoView({ block: "center", behavior: "smooth" });
+        if (target instanceof HTMLElement) {
+          highlightedTarget = target;
+          target.setAttribute("data-deep-link-highlight", "true");
+          highlightTimer = window.setTimeout(() => {
+            target.removeAttribute("data-deep-link-highlight");
+          }, HASH_HIGHLIGHT_MS);
+          target.focus({ preventScroll: true });
+          if (target.getAttribute("data-nav-action") === "expand") {
+            target.click();
+          }
+        }
+        return;
+      }
+
+      attempts += 1;
+      if (attempts < HASH_SCROLL_ATTEMPTS) {
+        window.setTimeout(tryScrollToLog, 100);
+      }
+    };
+
+    tryScrollToLog();
+
+    return () => {
+      cancelled = true;
+      if (highlightTimer !== null) {
+        window.clearTimeout(highlightTimer);
+      }
+      if (highlightedTarget !== null) {
+        highlightedTarget.removeAttribute("data-deep-link-highlight");
+      }
+    };
+  }, [logs.length]);
+
   const handleClearAll = useCallback(() => {
     if (initialSessionId !== undefined && allLogs.length === 0) return;
     void (async () => {

package/src/components/proxy-viewer/LogEntryHeader.tsx

@@ -151,6 +151,7 @@ export const LogEntryHeader = memo(function ({
   return (
     <TooltipProvider>
       <div
+        id={`log-${log.id}`}
         role="button"
         tabIndex={0}
         data-nav-id={`log-${log.id}`}

package/src/proxy/logFinalizer.ts

@@ -3,7 +3,7 @@ import { writeChunks } from "./chunkStorage";
 import { formatForPath } from "./formats";
 import { appendLogEntry, logger } from "./logger";
 import type { CapturedLog } from "./schemas";
-import { getSessionProcess } from "./sessionProcess";
+import { getSessionProcess, isSessionProcessAvailable } from "./sessionProcess";
 import { finalizeLogUpdate } from "./store";
 
 type BaseFinalizeLogJob = {
@@ -209,17 +209,21 @@ export function commitFinalizeLogResult(result: FinalizeLogResult): void {
 
 // ── Routing ─────────────────────────────────────────────────────
 // FINALIZER_RUNTIME selects the execution backend:
-//   "process" → per-session child process (default, max isolation)
+//   "process" → per-session child process (max isolation)
 //   "worker"  → shared Worker Thread pool
 //   "inline"  → synchronous in-process (debug / fallback)
+// The default is "process" only when its worker entry exists. Production
+// bundles that do not emit the standalone worker entry fall back to "inline"
+// instead of repeatedly spawning a failing child process.
 // For backward compatibility, FINALIZER_USE_WORKER=0 forces "inline".
 
 const RUNTIME: "process" | "worker" | "inline" = (() => {
   if (process.env["FINALIZER_USE_WORKER"] === "0") return "inline";
   const mode = process.env["FINALIZER_RUNTIME"];
+  if (mode === "process") return "process";
   if (mode === "worker") return "worker";
   if (mode === "inline") return "inline";
-  return "process";
+  return isSessionProcessAvailable() ? "process" : "inline";
 })();
 
 function executeBuildInSessionProcess(job: FinalizeLogJob): Promise<FinalizeLogResult> {

package/src/proxy/sessionProcess.ts

@@ -1,4 +1,6 @@
-import { fork, type ChildProcess } from "node:child_process";
+import { spawn, type ChildProcess } from "node:child_process";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { logger } from "./logger";
 import type { FinalizeLogJob, FinalizeLogResult } from "./logFinalizer";
 
@@ -12,6 +14,14 @@ type PendingJob = {
   reject: (err: Error) => void;
 };
 
+function resolveSessionWorkerPath(): string {
+  return fileURLToPath(new URL("./sessionWorkerEntry.ts", import.meta.url));
+}
+
+export function isSessionProcessAvailable(): boolean {
+  return existsSync(resolveSessionWorkerPath());
+}
+
 export class SessionProcess {
   private child: ChildProcess | null = null;
   private pending = new Map<string, PendingJob>();
@@ -30,14 +40,11 @@ export class SessionProcess {
   private ensureRunning(): ChildProcess {
     if (this.child !== null && this.child.connected) return this.child;
 
-    const entryPath = new URL("./sessionWorkerEntry.ts", import.meta.url).pathname;
-    // On Windows, the path from URL.pathname starts with "/" which needs to
-    // be stripped when it's a drive letter path (e.g. "/C:/..." → "C:/...")
-    const resolvedPath =
-      process.platform === "win32" && entryPath.startsWith("/") ? entryPath.slice(1) : entryPath;
+    const resolvedPath = resolveSessionWorkerPath();
 
-    this.child = fork(resolvedPath, [], {
+    this.child = spawn(process.execPath, [...process.execArgv, resolvedPath], {
       stdio: ["pipe", "pipe", "pipe", "ipc"],
+      windowsHide: true,
     });
 
     this.restartCount += 1;

package/src/proxy/sessionSupervisor.ts

@@ -1,4 +1,5 @@
 import type { CapturedLog } from "./schemas";
+import { isSessionProcessAvailable } from "./sessionProcess";
 
 export const PROVIDER_TEST_SESSION_ID = "provider-test";
 
@@ -21,10 +22,10 @@ export type SessionRuntimeMode = "in-process" | "worker-thread" | "child-process
 function getRuntimeMode(): SessionRuntimeMode {
   if (process.env["FINALIZER_USE_WORKER"] === "0") return "in-process";
   const mode = process.env["FINALIZER_RUNTIME"];
+  if (mode === "process") return "child-process";
   if (mode === "worker") return "worker-thread";
   if (mode === "inline") return "in-process";
-  // Default: per-session child process
-  return "child-process";
+  return isSessionProcessAvailable() ? "child-process" : "in-process";
 }
 
 export type SessionSnapshot = {

package/src/proxy/socketTracker.ts

@@ -1,8 +1,9 @@
-import { exec } from "node:child_process";
+import { exec, execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { logger } from "./logger";
 
 const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
 
 type ClientInfo = {
   port: number | null;
@@ -78,9 +79,15 @@ async function lookupClientInfo(port: number): Promise<ClientInfo> {
         `  Write-Output "$pid|$cmd"`,
         `}`,
       ].join("; ");
-      const { stdout } = await execAsync(`powershell -NoProfile -Command "${psScript}"`, {
-        windowsHide: true,
-      });
+      const { stdout } = await execFileAsync(
+        "powershell.exe",
+        ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", psScript],
+        {
+          windowsHide: true,
+          timeout: 3000,
+          maxBuffer: 64 * 1024,
+        },
+      );
       const trimmed = stdout.trim();
       if (trimmed === "") {
         return { port, pid: null, cwd: null, projectFolder: null };
@@ -164,9 +171,14 @@ async function lookupProcessInfo(
 
   try {
     if (platform === "win32") {
-      const { stdout } = await execAsync(
-        `wmic process where processid=${pid} get commandline /value`,
-        { windowsHide: true },
+      const { stdout } = await execFileAsync(
+        "wmic.exe",
+        ["process", "where", `processid=${pid}`, "get", "commandline", "/value"],
+        {
+          windowsHide: true,
+          timeout: 3000,
+          maxBuffer: 64 * 1024,
+        },
       );
       const lines = stdout.trim().split("\n").filter(Boolean);
       for (const line of lines) {

package/src/routes/__root.tsx

@@ -2,6 +2,7 @@
 import { Outlet, createRootRoute, HeadContent, Scripts } from "@tanstack/react-router";
 import type { ReactNode } from "react";
 import { SWRConfig } from "swr";
+import faviconSvg from "../assets/favicon.svg?url";
 import appCss from "../index.css?url";
 
 export const Route = createRootRoute({
@@ -11,7 +12,10 @@ export const Route = createRootRoute({
       { name: "viewport", content: "width=device-width, initial-scale=1" },
       { title: "llm-inspector" },
     ],
-    links: [{ rel: "stylesheet", href: appCss }],
+    links: [
+      { rel: "stylesheet", href: appCss },
+      { rel: "icon", type: "image/svg+xml", href: faviconSvg },
+    ],
   }),
   component: RootComponent,
 });

package/styles/globals.css

@@ -165,13 +165,20 @@
   }
 }
 
-@media (prefers-reduced-motion: reduce) {
-  .animate-crab-piano-pop {
-    animation: none !important;
-  }
-}
-
-@layer base {
+@media (prefers-reduced-motion: reduce) {
+  .animate-crab-piano-pop {
+    animation: none !important;
+  }
+}
+
+[data-deep-link-highlight="true"] {
+  background: color-mix(in oklch, var(--chart-2) 18%, transparent);
+  box-shadow:
+    inset 0 0 0 1px color-mix(in oklch, var(--chart-2) 65%, transparent),
+    0 0 0 3px color-mix(in oklch, var(--chart-2) 20%, transparent);
+}
+
+@layer base {
   * {
     @apply border-border outline-ring/50;
   }

package/.output/public/assets/_sessionId-C-aKd1Ky.js

@@ -1 +0,0 @@
-import{R as s,j as e}from"./main-CR9IJlz1.js";import{P as i}from"./ProxyViewerContainer-DfxRK7Nt.js";function t(){const{sessionId:o}=s.useParams();return e.jsx(i,{initialSessionId:o},o)}export{t as component};

package/.output/public/assets/index-B8ttyigz.js

@@ -1 +0,0 @@
-import{P as o}from"./ProxyViewerContainer-DfxRK7Nt.js";import"./main-CR9IJlz1.js";const r=o;export{r as component};