@tonyclaw/llm-inspector 1.12.0 → 1.14.0

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

@@ -21,6 +21,10 @@ export type ConversationGroupProps = {
    * across the whole viewer. Each `LogEntry` looks up its own entry.
    */
   cacheTrends?: Map<number, CacheTrendEntry>;
+  /** Set of log ids currently marked for comparison. Forwarded to each `LogEntry`. */
+  selectedSet: Set<number>;
+  /** Toggle a log in/out of the comparison selection. */
+  onToggleSelect: (logId: number) => void;
 };
 
 function computeStats(logs: CapturedLog[]): {
@@ -41,6 +45,8 @@ export const ConversationGroup = memo(function ({
   viewMode = "simple",
   strip,
   cacheTrends,
+  selectedSet,
+  onToggleSelect,
 }: ConversationGroupProps): JSX.Element {
   const [expanded, setExpanded] = useState(false);
 
@@ -81,6 +87,8 @@ export const ConversationGroup = memo(function ({
               suppressApiFormatBadge={!mixed}
               strip={strip}
               cacheTrend={cacheTrends?.get(log.id) ?? null}
+              isSelected={selectedSet.has(log.id)}
+              onToggleSelect={onToggleSelect}
             />
           ))}
         </div>

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

@@ -31,6 +31,10 @@ export type LogEntryProps = {
    * `null` (or absent) means the header should render with no arrows.
    */
   cacheTrend?: CacheTrendEntry | null;
+  /** Whether this log is currently marked for comparison. */
+  isSelected?: boolean;
+  /** Toggle this log in/out of the comparison selection. */
+  onToggleSelect?: (logId: number) => void;
 };
 
 /**
@@ -138,6 +142,8 @@ export const LogEntry = memo(function ({
   suppressApiFormatBadge = false,
   strip,
   cacheTrend = null,
+  isSelected = false,
+  onToggleSelect,
 }: LogEntryProps): JSX.Element {
   const [expanded, setExpanded] = useState<boolean>(false);
   const [requestCopied, setRequestCopied] = useState<boolean>(false);
@@ -193,7 +199,12 @@ export const LogEntry = memo(function ({
 
   return (
     <>
-      <div className={cn("border border-border rounded-lg mb-3 overflow-hidden")}>
+      <div
+        className={cn(
+          "border border-border rounded-lg mb-3 overflow-hidden",
+          isSelected && "border-l-2 border-l-amber-400",
+        )}
+      >
         <LogEntryHeader
           log={log}
           parsedRequest={parsedRequest}
@@ -201,6 +212,8 @@ export const LogEntry = memo(function ({
           onToggle={() => setExpanded(!expanded)}
           suppressApiFormatBadge={suppressApiFormatBadge}
           cacheTrend={cacheTrend}
+          isSelected={isSelected}
+          onToggleSelect={onToggleSelect}
         />
 
         {expanded && (

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

@@ -1,6 +1,7 @@
 import {
   ArrowDown,
   ArrowUp,
+  Check,
   ChevronDown,
   ChevronRight,
   Clock,
@@ -66,6 +67,10 @@ export type LogEntryHeaderProps = {
    * the corresponding cache span renders as it did before — no arrow.
    */
   cacheTrend?: { creation: CacheTrend | null; read: CacheTrend | null } | null;
+  /** Whether this log is currently marked for comparison. */
+  isSelected?: boolean;
+  /** Toggle this log in/out of the comparison selection. */
+  onToggleSelect?: (logId: number) => void;
 };
 
 export const LogEntryHeader = memo(function ({
@@ -75,6 +80,8 @@ export const LogEntryHeader = memo(function ({
   onToggle,
   suppressApiFormatBadge = false,
   cacheTrend = null,
+  isSelected = false,
+  onToggleSelect,
 }: LogEntryHeaderProps): JSX.Element {
   const statusCategory = getStatusCategory(log.responseStatus);
 
@@ -104,6 +111,27 @@ export const LogEntryHeader = memo(function ({
         }
       }}
     >
+      {/* Selection checkbox (for log-request comparison) */}
+      {onToggleSelect !== undefined && (
+        <button
+          type="button"
+          onClick={(e) => {
+            e.stopPropagation();
+            onToggleSelect(log.id);
+          }}
+          aria-label={isSelected ? "Deselect for comparison" : "Select for comparison"}
+          aria-pressed={isSelected}
+          className={cn(
+            "shrink-0 size-4 rounded-sm border flex items-center justify-center transition-colors cursor-pointer",
+            isSelected
+              ? "bg-amber-400 border-amber-400 text-amber-950"
+              : "border-muted-foreground/40 hover:border-amber-400 hover:bg-amber-400/10",
+          )}
+        >
+          {isSelected && <Check className="size-3" strokeWidth={3} />}
+        </button>
+      )}
+
       {/* Request ID */}
       <span className="text-blue-400/80 font-mono text-xs font-semibold tabular-nums shrink-0">
         #{log.id}

package/src/components/proxy-viewer/formats/openai/ResponseView.tsx

@@ -1,18 +1,83 @@
-import { StopCircle, Zap } from "lucide-react";
-import type { JSX } from "react";
+import { StopCircle, Terminal, Zap } from "lucide-react";
+import { useState, type JSX } from "react";
 import ReactMarkdown from "react-markdown";
-import type { OpenAIResponse } from "../../../../proxy/schemas";
+import type { OpenAIResponse, OpenAIToolCall } from "../../../../proxy/schemas";
 import { formatTokens } from "../../../../lib/utils";
 import { Badge } from "../../../ui/badge";
+import { JsonViewer, safeJsonValue } from "../../../ui/json-viewer";
+import { ScrollArea } from "../../../ui/scroll-area";
 import { Separator } from "../../../ui/separator";
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "../../../ui/collapsible";
+import { ChevronDown, ChevronRight } from "lucide-react";
 import { extractThinkingFromContent, ThinkingBlock } from "../anthropic/ContentBlocks";
 
 // Re-export for use in other components
 export { extractThinkingFromContent } from "../anthropic/ContentBlocks";
 
+/** Best-effort JSON parse of an OpenAI `function.arguments` string. Returns
+ *  the parsed object, or `null` on parse failure so the renderer can fall
+ *  back to showing the raw string. */
+function parseToolArguments(raw: string | undefined): unknown {
+  if (raw === undefined || raw === "") return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/** One collapsible tool_use row, mirroring the Anthropic ToolUseBlock visual
+ *  treatment (Terminal icon, blue accent, name as a Badge, JSON input in a
+ *  scrollable JsonViewer). */
+function OpenAIToolCallBlock({ call }: { call: OpenAIToolCall }): JSX.Element {
+  const [open, setOpen] = useState(false);
+  const name = call.function.name ?? "(unnamed tool)";
+  const parsed = parseToolArguments(call.function.arguments);
+
+  return (
+    <Collapsible open={open} onOpenChange={setOpen}>
+      <div className="border-l-2 border-blue-500/40 my-1">
+        <CollapsibleTrigger className="flex items-center gap-1.5 px-3 py-1 w-full text-left cursor-pointer hover:bg-blue-500/5 transition-colors rounded-r-sm group">
+          <Terminal className="size-3.5 text-blue-400 shrink-0" />
+          <Badge variant="outline" className="text-[10px] font-mono px-1.5 py-0 h-4">
+            {name}
+          </Badge>
+          {call.id !== undefined && call.id !== "" && (
+            <span className="text-[10px] font-mono text-muted-foreground/60 truncate">
+              {call.id}
+            </span>
+          )}
+          <span className="flex-1" />
+          {open ? (
+            <ChevronDown className="size-3 text-muted-foreground" />
+          ) : (
+            <ChevronRight className="size-3 text-muted-foreground" />
+          )}
+        </CollapsibleTrigger>
+        <CollapsibleContent>
+          <div className="px-3 pb-2">
+            <ScrollArea className="max-h-[60vh]">
+              {parsed === null ? (
+                // JSON.parse failed — show the raw string so the user can
+                // still see what the model tried to call.
+                <pre className="font-mono text-xs whitespace-pre-wrap break-words text-rose-300/90">
+                  {call.function.arguments}
+                </pre>
+              ) : (
+                <JsonViewer data={safeJsonValue(parsed)} defaultExpandDepth={2} />
+              )}
+            </ScrollArea>
+          </div>
+        </CollapsibleContent>
+      </div>
+    </Collapsible>
+  );
+}
+
 export function OpenAIResponseView({ response }: { response: OpenAIResponse }): JSX.Element {
   const choice = response.choices[0];
   const message = choice?.message;
+  const toolCalls = message?.tool_calls ?? [];
 
   return (
     <div className="space-y-3">
@@ -70,6 +135,10 @@ export function OpenAIResponseView({ response }: { response: OpenAIResponse }):
               </div>
             );
           })()}
+        {toolCalls.map((call, i) => (
+          // biome-ignore lint/suspicious/noArrayIndexKey: tool_calls is the positionally stable list from the response
+          <OpenAIToolCallBlock key={call.id ?? `tc-${i}`} call={call} />
+        ))}
         {message?.function_call !== null && message?.function_call !== undefined && (
           <div className="border border-blue-500/30 rounded-md p-3 bg-blue-500/5">
             <div className="text-xs text-blue-400 font-mono mb-1">function_call</div>
@@ -85,7 +154,8 @@ export function OpenAIResponseView({ response }: { response: OpenAIResponse }):
           (message?.reasoning_content === null ||
             message?.reasoning_content === undefined ||
             message.reasoning_content.length === 0) &&
-          (message?.function_call === null || message?.function_call === undefined) && (
+          (message?.function_call === null || message?.function_call === undefined) &&
+          toolCalls.length === 0 && (
             <p className="text-xs text-muted-foreground italic">Empty response content</p>
           )}
       </div>

package/src/components/proxy-viewer/requestDiff.ts

@@ -0,0 +1,277 @@
+/**
+ * Path-aligned JSON-tree diff helpers for the "compare two log requests" feature.
+ *
+ * Given two captured log Request payloads, we:
+ *  1. Normalize each payload (deep-clone, sort object keys, keep array order)
+ *     so that non-semantic differences (key order, string whitespace) do not
+ *     generate false positives.
+ *  2. Walk the two trees in lockstep, emitting a list of path-anchored
+ *     `DiffOp`s. Equal subtrees collapse into a single op at the subtree
+ *     root, so the renderer can choose to expand or hide them.
+ *  3. Emit ops in path-sorted order (depth-first, sibling order = object-key
+ *     ascending then array-index ascending) so the renderer can lay them
+ *     out linearly.
+ *
+ * No runtime dependencies. Mirrors the `cacheTrend.ts` pure-helper pattern.
+ */
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+
+export type JsonNode =
+  | { kind: "object"; value: Record<string, JsonNode> }
+  | { kind: "array"; value: JsonNode[] }
+  | { kind: "primitive"; value: JsonPrimitive };
+
+export type DiffOp =
+  | { kind: "equal"; path: string; value: JsonNode }
+  | { kind: "added"; path: string; value: JsonNode }
+  | { kind: "removed"; path: string; value: JsonNode }
+  | {
+      kind: "changed";
+      path: string;
+      left: JsonNode;
+      right: JsonNode;
+    };
+
+/** A single segment of a JSON path: an object key or an array index. */
+export type PathSegment = string | number;
+
+const ROOT_PATH = "";
+
+/** Render a path segment list as a human-readable string.
+ *
+ *  - Root (empty list) → `""` (no label; the renderer hides the gutter)
+ *  - Object key        → `.foo`
+ *  - Array index       → `[3]`
+ *  - Top-level object key  → `messages` (no leading dot)
+ *
+ *  Examples:
+ *    []                                → ""
+ *    ["messages"]                      → "messages"
+ *    ["messages", 3]                   → "messages[3]"
+ *    ["messages", 3, "content"]        → "messages[3].content"
+ *    ["messages", 3, "content", 0]     → "messages[3].content[0]"
+ */
+export function formatPath(segments: PathSegment[]): string {
+  if (segments.length === 0) return ROOT_PATH;
+  let out = "";
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    if (seg === undefined) continue;
+    if (typeof seg === "number") {
+      out += `[${seg}]`;
+    } else if (i === 0) {
+      out += seg;
+    } else {
+      out += `.${seg}`;
+    }
+  }
+  return out;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Normalize a captured Request body for comparison.
+ *
+ * Captured Request bodies are sometimes already-parsed objects and sometimes
+ * JSON-encoded strings (depending on which capture path produced the log).
+ * We:
+ *   1. Try `JSON.parse` if the input is a string.
+ *   2. Deep-walk the value, building a fresh `JsonNode` tree.
+ *   3. Sort object keys lexicographically (key order is not semantically
+ *      meaningful for most LLM SDKs but varies between SDK versions, so we
+ *      canonicalize it).
+ *   4. Keep array order (semantically meaningful: `messages[]` order is
+ *      conversation order; reordering it would silently destroy the diff).
+ *   5. Leave primitives alone (no whitespace trim — those can be meaningful
+ *      in user-message text).
+ *
+ * Idempotent at the data level: re-normalizing the same shape (in any key
+ * order) yields the same tree.
+ */
+export function normalizeRequest(raw: unknown): JsonNode {
+  if (typeof raw === "string") {
+    try {
+      return toNode(JSON.parse(raw));
+    } catch {
+      // Unparseable string: wrap as a primitive string node so the diff can
+      // still operate on it (changed vs. another string, or added/removed
+      // vs. an object).
+      return { kind: "primitive", value: raw };
+    }
+  }
+  return toNode(raw);
+}
+
+function toNode(value: unknown): JsonNode {
+  if (value === null) return { kind: "primitive", value: null };
+  if (typeof value === "string") return { kind: "primitive", value };
+  if (typeof value === "number") return { kind: "primitive", value };
+  if (typeof value === "boolean") return { kind: "primitive", value };
+  if (Array.isArray(value)) {
+    return { kind: "array", value: value.map((v) => toNode(v)) };
+  }
+  if (isPlainObject(value)) {
+    const out: Record<string, JsonNode> = {};
+    for (const k of Object.keys(value).sort()) {
+      out[k] = toNode(value[k]);
+    }
+    return { kind: "object", value: out };
+  }
+  // Functions, symbols, bigints, undefined — treat as null in the diff model.
+  return { kind: "primitive", value: null };
+}
+
+/**
+ * Compute the path-aligned diff of two normalized trees.
+ *
+ * Emits `DiffOp[]` in path-sorted order. For each path:
+ *   - if both trees have the same value, emit a single `equal` op at the
+ *     deepest common ancestor (so equal subtrees collapse into one op);
+ *   - if only the right has it, emit `added`;
+ *   - if only the left has it, emit `removed`;
+ *   - if both have it but it differs, emit `changed` (and recurse into
+ *     objects/arrays so the user sees *which* field changed).
+ *
+ * Pure: does not mutate `left` or `right`.
+ */
+export function diffTrees(left: JsonNode, right: JsonNode): DiffOp[] {
+  const ops: DiffOp[] = [];
+  walk([], left, right, ops);
+  return ops;
+}
+
+function walk(segments: PathSegment[], left: JsonNode, right: JsonNode, out: DiffOp[]): void {
+  const path = formatPath(segments);
+
+  if (nodeEqual(left, right)) {
+    out.push({ kind: "equal", path, value: left });
+    return;
+  }
+
+  // Type mismatch or primitive change.
+  if (left.kind !== right.kind) {
+    out.push({ kind: "changed", path, left, right });
+    return;
+  }
+
+  if (left.kind === "primitive" && right.kind === "primitive") {
+    out.push({ kind: "changed", path, left, right });
+    return;
+  }
+
+  if (left.kind === "object" && right.kind === "object") {
+    const leftKeys = Object.keys(left.value);
+    const rightKeys = Object.keys(right.value);
+    const rightKeySet = new Set(rightKeys);
+
+    for (const k of leftKeys) {
+      const lChild = left.value[k];
+      if (lChild === undefined) continue;
+      if (!rightKeySet.has(k)) {
+        out.push({
+          kind: "removed",
+          path: formatPath([...segments, k]),
+          value: lChild,
+        });
+      } else {
+        const rChild = right.value[k];
+        if (rChild === undefined) continue;
+        walk([...segments, k], lChild, rChild, out);
+      }
+    }
+    for (const k of rightKeys) {
+      if (leftKeys.includes(k)) continue;
+      const rChild = right.value[k];
+      if (rChild === undefined) continue;
+      out.push({
+        kind: "added",
+        path: formatPath([...segments, k]),
+        value: rChild,
+      });
+    }
+    return;
+  }
+
+  if (left.kind === "array" && right.kind === "array") {
+    const minLen = Math.min(left.value.length, right.value.length);
+    for (let i = 0; i < minLen; i++) {
+      const lChild = left.value[i];
+      const rChild = right.value[i];
+      if (lChild === undefined || rChild === undefined) continue;
+      walk([...segments, i], lChild, rChild, out);
+    }
+    for (let i = minLen; i < right.value.length; i++) {
+      const rChild = right.value[i];
+      if (rChild === undefined) continue;
+      out.push({
+        kind: "added",
+        path: formatPath([...segments, i]),
+        value: rChild,
+      });
+    }
+    for (let i = minLen; i < left.value.length; i++) {
+      const lChild = left.value[i];
+      if (lChild === undefined) continue;
+      out.push({
+        kind: "removed",
+        path: formatPath([...segments, i]),
+        value: lChild,
+      });
+    }
+  }
+}
+
+function nodeEqual(a: JsonNode, b: JsonNode): boolean {
+  if (a.kind !== b.kind) return false;
+  if (a.kind === "primitive" && b.kind === "primitive") {
+    return a.value === b.value;
+  }
+  if (a.kind === "array" && b.kind === "array") {
+    if (a.value.length !== b.value.length) return false;
+    for (let i = 0; i < a.value.length; i++) {
+      const ai = a.value[i];
+      const bi = b.value[i];
+      if (ai === undefined || bi === undefined) return false;
+      if (!nodeEqual(ai, bi)) return false;
+    }
+    return true;
+  }
+  if (a.kind === "object" && b.kind === "object") {
+    const aKeys = Object.keys(a.value);
+    const bKeys = Object.keys(b.value);
+    if (aKeys.length !== bKeys.length) return false;
+    for (const k of aKeys) {
+      const av = a.value[k];
+      const bv = b.value[k];
+      if (av === undefined || bv === undefined) return false;
+      if (!nodeEqual(av, bv)) return false;
+    }
+    return true;
+  }
+  return false;
+}
+
+/** Render a JsonNode to a compact human-readable preview. Used by the
+ *  diff view's gutter or change rows where we want a one-line summary
+ *  without pretty-printing the whole subtree. */
+export function previewNode(node: JsonNode, maxLen = 80): string {
+  let s: string;
+  switch (node.kind) {
+    case "primitive":
+      s = node.value === null ? "null" : JSON.stringify(node.value);
+      break;
+    case "array":
+      s = `[… ${node.value.length} items]`;
+      break;
+    case "object":
+      s = `{… ${Object.keys(node.value).length} keys}`;
+      break;
+  }
+  if (s.length > maxLen) s = `${s.slice(0, maxLen - 1)}…`;
+  return s;
+}

package/src/lib/serverPort.ts

@@ -0,0 +1,41 @@
+/* eslint-disable functional/no-throw-statements */
+/**
+ * Tracks the HTTP port the inspector server is bound to, so internal
+ * components (currently the MCP server's loopback fetch) can build
+ * `http://127.0.0.1:<port>/...` URLs without env-var coupling.
+ *
+ * Initialization order:
+ *   1. `setCurrentPort(port)` — explicit override (used by tests, or any
+ *      code that has direct knowledge of the bound port).
+ *   2. `process.env.PORT` — fallback. The CLI (`src/cli.ts`) sets this
+ *      before spawning the server process, so in normal operation this
+ *      branch is taken and no explicit `setCurrentPort` call is needed.
+ *
+ * `getCurrentPort()` throws if neither source is available.
+ */
+
+let overridePort: number | null = null;
+
+export function setCurrentPort(port: number): void {
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new Error(`setCurrentPort: invalid port ${port}`);
+  }
+  overridePort = port;
+}
+
+export function getCurrentPort(): number {
+  if (overridePort !== null) return overridePort;
+  const envPort = process.env["PORT"];
+  if (envPort !== undefined && envPort !== "") {
+    const n = Number(envPort);
+    if (Number.isInteger(n) && n > 0 && n <= 65535) return n;
+  }
+  throw new Error(
+    "Inspector server port not initialized: PORT env var is unset and setCurrentPort() has not been called",
+  );
+}
+
+/** Reset for tests. */
+export function _resetForTests(): void {
+  overridePort = null;
+}

package/src/mcp/loopback.ts

@@ -0,0 +1,76 @@
+/* eslint-disable functional/no-throw-statements */
+/**
+ * HTTP loopback helper for MCP tool handlers.
+ *
+ * Why HTTP loopback (not direct function calls): see
+ * `openspec/changes/add-mcp-server/design.md` decision D2. All MCP tools
+ * delegate to existing `/api/*` endpoints so any future cross-cutting
+ * middleware (auth, rate-limit, audit, metrics) added to `/api` is
+ * automatically inherited by MCP without duplicate plumbing.
+ *
+ * NOTE: TanStack Start / Nitro may expose an in-process route invocation
+ * API (e.g. Nitro's `$fetch` helper) that would let us skip the real HTTP
+ * round-trip while preserving the routing contract. As of this writing
+ * that investigation is open (tasks.md 2.3). If/when adopted, the public
+ * surface of this module — `callApi(path, init?)` returning a `Response`
+ * — should stay identical so callers don't change.
+ */
+
+import { getCurrentPort } from "../lib/serverPort";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+export type CallApiOptions = RequestInit & {
+  /** Override default 30s timeout. */
+  timeoutMs?: number;
+};
+
+export class LoopbackTimeoutError extends Error {
+  constructor(
+    public readonly path: string,
+    public readonly timeoutMs: number,
+  ) {
+    super(`Loopback call to ${path} timed out after ${timeoutMs}ms`);
+    this.name = "LoopbackTimeoutError";
+  }
+}
+
+/**
+ * Make an HTTP request to one of the inspector's own /api/* endpoints
+ * via 127.0.0.1 loopback. The returned Response is a standard Web
+ * Response; callers decide whether to call .json(), .text(), .arrayBuffer().
+ *
+ * `path` MUST start with `/` (e.g. `/api/logs`).
+ */
+export async function callApi(path: string, options: CallApiOptions = {}): Promise<Response> {
+  if (!path.startsWith("/")) {
+    throw new Error(`callApi: path must start with '/', got: ${path}`);
+  }
+  const port = getCurrentPort();
+  const url = `http://127.0.0.1:${port}${path}`;
+
+  const { timeoutMs = DEFAULT_TIMEOUT_MS, signal: userSignal, ...rest } = options;
+
+  const controller = new AbortController();
+  const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
+
+  // If caller passed their own signal, chain it.
+  if (userSignal !== undefined && userSignal !== null) {
+    if (userSignal.aborted) {
+      controller.abort();
+    } else {
+      userSignal.addEventListener("abort", () => controller.abort(), { once: true });
+    }
+  }
+
+  try {
+    return await fetch(url, { ...rest, signal: controller.signal });
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      throw new LoopbackTimeoutError(path, timeoutMs);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timeoutHandle);
+  }
+}