@tonyclaw/agent-inspector 2.0.0

package/src/components/proxy-viewer/log-formats/openai.ts

@@ -0,0 +1,167 @@
+import { OpenAIRequestSchema, parseOpenAIResponse } from "../../../proxy/formats/openai/schemas";
+import type { AnatomySegment } from "../anatomy/types";
+import { countCharacters, estimateTokens } from "../anatomy/tokenEstimate";
+import type { LogFormatAdapter } from "./types";
+import { emptyRequestAnalysis, EMPTY_RESPONSE_ANALYSIS } from "./types";
+
+type OpenAIMessageContent = string | ReadonlyArray<Record<string, unknown>> | null | undefined;
+
+/** Flatten an OpenAI `content` field to its text representation. */
+function contentToText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts: string[] = [];
+  for (const block of content) {
+    if (block === null || typeof block !== "object") continue;
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const b = block as Record<string, unknown>;
+    const type = b.type;
+    if (type === "text" && typeof b.text === "string") {
+      parts.push(b.text);
+    } else if (type === "image_url") {
+      parts.push("[image]");
+    }
+  }
+  return parts.join("\n");
+}
+
+/** Flatten an OpenAI message to text — content plus optional tool calls plus optional reasoning. */
+function messageToText(message: Record<string, unknown>): string {
+  const parts: string[] = [];
+  const text = contentToText(message.content);
+  if (text.length > 0) parts.push(text);
+  const reasoning =
+    typeof message.reasoning_content === "string"
+      ? message.reasoning_content
+      : typeof message.thinking === "string"
+        ? message.thinking
+        : typeof message.think === "string"
+          ? message.think
+          : "";
+  if (reasoning.length > 0) parts.push(reasoning);
+  const toolCalls = message.tool_calls;
+  if (Array.isArray(toolCalls)) {
+    for (const call of toolCalls) {
+      if (call === null || typeof call !== "object") continue;
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+      const fn = (call as { function?: { name?: unknown; arguments?: unknown } }).function;
+      if (fn === undefined) continue;
+      const name = typeof fn.name === "string" ? fn.name : "";
+      const args = typeof fn.arguments === "string" ? fn.arguments : "";
+      parts.push(`${name} ${args}`.trim());
+    }
+  }
+  return parts.join("\n");
+}
+
+/** Flatten an OpenAI `tools` array to its schema text. */
+function toolsToText(tools: unknown): string {
+  if (!Array.isArray(tools)) return "";
+  const parts: string[] = [];
+  for (const tool of tools) {
+    if (tool === null || typeof tool !== "object") continue;
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const t = tool as {
+      function?: { name?: unknown; description?: unknown; parameters?: unknown };
+    };
+    const fn = t.function;
+    if (fn === undefined) continue;
+    if (typeof fn.name === "string") parts.push(fn.name);
+    if (typeof fn.description === "string") parts.push(fn.description);
+    if (fn.parameters !== undefined) parts.push(JSON.stringify(fn.parameters));
+  }
+  return parts.join("\n");
+}
+
+function segment(
+  role: AnatomySegment["role"],
+  label: string,
+  text: string,
+  path: string,
+): AnatomySegment {
+  return {
+    role,
+    label,
+    text,
+    size: estimateTokens(text),
+    characters: countCharacters(text),
+    path,
+  };
+}
+
+export const openAILogFormatAdapter: LogFormatAdapter = {
+  format: "openai",
+
+  analyzeRequest(rawBody) {
+    if (rawBody === null) return emptyRequestAnalysis(rawBody);
+    try {
+      const result = OpenAIRequestSchema.safeParse(JSON.parse(rawBody));
+      if (!result.success) return emptyRequestAnalysis(rawBody);
+      return {
+        parsed: result.data,
+        comparisonValue: result.data,
+        messageCount: result.data.messages.length,
+        toolCount:
+          result.data.tools !== undefined && result.data.tools.length > 0
+            ? result.data.tools.length
+            : null,
+      };
+    } catch {
+      return emptyRequestAnalysis(rawBody);
+    }
+  },
+
+  analyzeResponse(responseText) {
+    if (responseText === null) return EMPTY_RESPONSE_ANALYSIS;
+    const parsed = parseOpenAIResponse(responseText);
+    if (parsed === null) return EMPTY_RESPONSE_ANALYSIS;
+    const toolNames =
+      parsed.choices[0]?.message?.tool_calls
+        ?.map((toolCall) => toolCall.function?.name ?? "")
+        .filter((name) => name !== "") ?? [];
+    return {
+      parsed,
+      toolNames: toolNames.length > 0 ? toolNames : null,
+    };
+  },
+
+  anatomySegments(parsed) {
+    if (parsed === null || typeof parsed !== "object") return null;
+    // We deliberately skip OpenAIRequestSchema validation here for the
+    // same reason as the Anthropic adapter: the Anatomy view should
+    // render even when the body shape is slightly off-schema. We only
+    // need the top-level `messages` and `tools` arrays.
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+    const body = parsed as { messages?: unknown; tools?: unknown };
+    const segments: AnatomySegment[] = [];
+
+    // Promote a leading role: "system" message into a "system" segment.
+    // Spec: derive system role from a leading role: "system" message, then
+    // a segment per remaining message. We still keep the system message in
+    // the segment list (not skipped) when there is no separate system field
+    // to compare against — the leading role: "system" message IS the system
+    // content for OpenAI Chat Completions. If a separate `system` field
+    // existed and matched the message, we would dedupe, but Chat
+    // Completions has no such field, so we never have to skip.
+    if (Array.isArray(body.messages)) {
+      body.messages.forEach((message, index) => {
+        if (message === null || typeof message !== "object") return;
+        // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+        const m = message as { role?: unknown; content?: unknown };
+        const role =
+          m.role === "user" || m.role === "assistant" || m.role === "system" || m.role === "tool"
+            ? m.role
+            : "user";
+        const text = messageToText(m);
+        segments.push(segment(role, `[${index}] ${role}`, text, `/messages/${index}`));
+      });
+    }
+
+    if (Array.isArray(body.tools) && body.tools.length > 0) {
+      const text = toolsToText(body.tools);
+      segments.push(segment("tools", "tools", text, "/tools"));
+    }
+
+    return segments.length > 0 ? segments : null;
+  },
+};

package/src/components/proxy-viewer/log-formats/types.ts

@@ -0,0 +1,40 @@
+import type { RequestFormat } from "../../../proxy/schemas";
+import type { AnatomySegment } from "../anatomy/types";
+
+export type RequestAnalysis = {
+  parsed: unknown | null;
+  comparisonValue: unknown;
+  messageCount: number | null;
+  toolCount: number | null;
+};
+
+export type ResponseAnalysis = {
+  parsed: unknown | null;
+  toolNames: string[] | null;
+};
+
+export type LogFormatAdapter = {
+  readonly format: RequestFormat;
+  analyzeRequest(rawBody: string | null): RequestAnalysis;
+  analyzeResponse(responseText: string | null): ResponseAnalysis;
+  /**
+   * Derive the ordered list of segments shown in the Anatomy tab for a
+   * parsed request body. Returns `null` when the body is `null` or fails
+   * the format's schema (e.g. unknown format).
+   */
+  anatomySegments(parsed: unknown): AnatomySegment[] | null;
+};
+
+export function emptyRequestAnalysis(rawBody: string | null): RequestAnalysis {
+  return {
+    parsed: null,
+    comparisonValue: rawBody,
+    messageCount: null,
+    toolCount: null,
+  };
+}
+
+export const EMPTY_RESPONSE_ANALYSIS: ResponseAnalysis = {
+  parsed: null,
+  toolNames: null,
+};

package/src/components/proxy-viewer/log-formats/unknown.ts

@@ -0,0 +1,18 @@
+import type { LogFormatAdapter } from "./types";
+import { emptyRequestAnalysis, EMPTY_RESPONSE_ANALYSIS } from "./types";
+
+export const unknownLogFormatAdapter: LogFormatAdapter = {
+  format: "unknown",
+
+  analyzeRequest(rawBody) {
+    return emptyRequestAnalysis(rawBody);
+  },
+
+  analyzeResponse() {
+    return EMPTY_RESPONSE_ANALYSIS;
+  },
+
+  anatomySegments() {
+    return null;
+  },
+};

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

@@ -0,0 +1,39 @@
+/**
+ * Pure visibility rule for the "Raw Request" tab. Extracted so it can be
+ * unit-tested without rendering React. The tab appears only when all three
+ * are true: anthropic format, full view mode, strip toggle enabled.
+ */
+export function shouldShowRawRequestTab(
+  apiFormat: string,
+  viewMode: "simple" | "full",
+  strip: boolean,
+): boolean {
+  return apiFormat === "anthropic" && viewMode === "full" && strip;
+}
+
+/**
+ * Pure visibility rule for the "Diff with Raw" button in the Headers tab.
+ * The button only makes sense when the user is in full mode (where the
+ * `Raw Headers` tab is shown) and we actually captured raw headers.
+ */
+export function shouldShowHeadersDiffButton(
+  viewMode: "simple" | "full",
+  hasRawHeaders: boolean,
+): boolean {
+  return viewMode === "full" && hasRawHeaders;
+}
+
+/**
+ * Pure visibility rule for the "Diff with Raw" button in the Request tab.
+ * Mirrors the conditions for the `Raw Request` tab itself: full mode plus
+ * the strip toggle being on for an anthropic-format request. We also need
+ * an actual raw request body to diff against.
+ */
+export function shouldShowRequestDiffButton(
+  apiFormat: string,
+  viewMode: "simple" | "full",
+  strip: boolean,
+  hasRawRequest: boolean,
+): boolean {
+  return apiFormat === "anthropic" && viewMode === "full" && strip && hasRawRequest;
+}

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/components/proxy-viewer/useCopyFeedback.ts

@@ -0,0 +1,36 @@
+import { useCallback, useEffect, useRef, useState, type MouseEvent } from "react";
+
+/**
+ * Clipboard write with a 2s "Copied!" indicator. Returns null-safe
+ * callbacks so callers can pass `text === null` through unconditionally
+ * (the hook still runs; the click handler short-circuits).
+ */
+export function useCopyFeedback(text: string | null): {
+  copied: boolean;
+  copy: (event: MouseEvent) => void;
+} {
+  const [copied, setCopied] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (timerRef.current !== null) clearTimeout(timerRef.current);
+    },
+    [],
+  );
+
+  const copy = useCallback(
+    (event: MouseEvent) => {
+      event.stopPropagation();
+      if (text === null) return;
+      void window.navigator.clipboard.writeText(text).then(() => {
+        setCopied(true);
+        if (timerRef.current !== null) clearTimeout(timerRef.current);
+        timerRef.current = setTimeout(() => setCopied(false), 2000);
+      });
+    },
+    [text],
+  );
+
+  return { copied, copy };
+}