@tonyclaw/agent-inspector 2.0.6 → 2.0.8

package/src/components/proxy-viewer/anatomy/contextIntelligence.ts

@@ -0,0 +1,414 @@
+import { safeGetOwnProperty } from "../../../lib/objectUtils";
+import type { AnatomyRole, AnatomySegment } from "./types";
+
+export type ContextRiskLevel = "unknown" | "ok" | "watch" | "danger";
+
+export type ContextWindowSource = "request" | "model-rule" | "unknown";
+
+export type ContextWindow = {
+  tokens: number | null;
+  label: string;
+  source: ContextWindowSource;
+};
+
+export type RoleUsage = {
+  role: AnatomyRole;
+  label: string;
+  tokens: number;
+  percent: number;
+};
+
+export type ContextDiagnostic = {
+  kind: "duplicate" | "history-bloat" | "tool-schema" | "system-heavy";
+  severity: "watch" | "danger";
+  title: string;
+  detail: string;
+};
+
+export type ContextIntelligence = {
+  model: string | null;
+  contextWindow: ContextWindow;
+  estimatedInputTokens: number;
+  outputReserveTokens: number | null;
+  windowUsedTokens: number | null;
+  remainingInputTokens: number | null;
+  remainingAfterReserveTokens: number | null;
+  usagePercent: number | null;
+  riskLevel: ContextRiskLevel;
+  roleUsages: RoleUsage[];
+  largestRole: RoleUsage | null;
+  diagnostics: ContextDiagnostic[];
+};
+
+type MatchMode = "prefix" | "includes";
+
+type ModelContextRule = {
+  family: string;
+  tokens: number;
+  mode: MatchMode;
+  patterns: readonly string[];
+};
+
+const WATCH_USAGE_PERCENT = 0.75;
+const DANGER_USAGE_PERCENT = 0.9;
+const LONG_TOOL_SCHEMA_TOKENS = 8_000;
+const LARGE_ROLE_PERCENT = 0.35;
+const DUPLICATE_MIN_TOKENS = 40;
+const DUPLICATE_MIN_CHARS = 160;
+const HISTORY_BLOAT_SEGMENTS = 18;
+const HISTORY_BLOAT_TOKENS = 60_000;
+const HISTORY_BLOAT_PERCENT = 0.7;
+const SYSTEM_HEAVY_TOKENS = 3_000;
+const SYSTEM_HEAVY_PERCENT = 0.3;
+
+const EXPLICIT_CONTEXT_WINDOW_FIELDS = [
+  "context_window",
+  "contextWindow",
+  "context_length",
+  "contextLength",
+  "max_context_length",
+  "maxContextLength",
+  "max_input_tokens",
+  "maxInputTokens",
+] as const;
+
+const OUTPUT_RESERVE_FIELDS = [
+  "max_tokens",
+  "maxTokens",
+  "max_completion_tokens",
+  "maxCompletionTokens",
+  "max_output_tokens",
+  "maxOutputTokens",
+] as const;
+
+const MODEL_CONTEXT_RULES: readonly ModelContextRule[] = [
+  {
+    family: "OpenAI GPT-4.1",
+    tokens: 1_047_576,
+    mode: "prefix",
+    patterns: ["gpt-4.1"],
+  },
+  {
+    family: "OpenAI GPT-4o",
+    tokens: 128_000,
+    mode: "prefix",
+    patterns: ["gpt-4o"],
+  },
+  {
+    family: "OpenAI o-series",
+    tokens: 128_000,
+    mode: "prefix",
+    patterns: ["o1", "o3", "o4"],
+  },
+  {
+    family: "Anthropic Claude",
+    tokens: 200_000,
+    mode: "prefix",
+    patterns: ["claude-"],
+  },
+  {
+    family: "DeepSeek",
+    tokens: 64_000,
+    mode: "prefix",
+    patterns: ["deepseek-"],
+  },
+  {
+    family: "MiniMax",
+    tokens: 1_000_000,
+    mode: "includes",
+    patterns: ["minimax"],
+  },
+];
+
+const ROLE_LABELS: Record<AnatomyRole, string> = {
+  system: "System",
+  user: "User messages",
+  assistant: "Assistant messages",
+  tool: "Tool results",
+  tools: "Tool definitions",
+};
+
+function readPositiveInteger(value: unknown): number | null {
+  if (typeof value === "number") {
+    if (Number.isFinite(value) && value > 0) return Math.floor(value);
+    return null;
+  }
+
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed) && parsed > 0) return Math.floor(parsed);
+  }
+
+  return null;
+}
+
+function readPositiveIntegerField(parsed: unknown, fields: readonly string[]): number | null {
+  for (const field of fields) {
+    const value = readPositiveInteger(safeGetOwnProperty(parsed, field));
+    if (value !== null) return value;
+  }
+  return null;
+}
+
+export function readRequestModel(parsed: unknown): string | null {
+  const value = safeGetOwnProperty(parsed, "model");
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed === "" ? null : trimmed;
+}
+
+function matchesRule(model: string, rule: ModelContextRule): boolean {
+  switch (rule.mode) {
+    case "prefix":
+      return rule.patterns.some((pattern) => model.startsWith(pattern));
+    case "includes":
+      return rule.patterns.some((pattern) => model.includes(pattern));
+  }
+}
+
+export function resolveContextWindow(model: string | null, parsed: unknown): ContextWindow {
+  const explicitWindow = readPositiveIntegerField(parsed, EXPLICIT_CONTEXT_WINDOW_FIELDS);
+  if (explicitWindow !== null) {
+    return {
+      tokens: explicitWindow,
+      label: "Request metadata",
+      source: "request",
+    };
+  }
+
+  if (model === null) {
+    return {
+      tokens: null,
+      label: "Unknown model",
+      source: "unknown",
+    };
+  }
+
+  const normalized = model.trim().toLowerCase();
+  for (const rule of MODEL_CONTEXT_RULES) {
+    if (matchesRule(normalized, rule)) {
+      return {
+        tokens: rule.tokens,
+        label: rule.family,
+        source: "model-rule",
+      };
+    }
+  }
+
+  return {
+    tokens: null,
+    label: "No local rule",
+    source: "unknown",
+  };
+}
+
+function clampPercent(value: number): number {
+  if (value < 0) return 0;
+  if (value > 1) return 1;
+  return value;
+}
+
+function riskLevel(usagePercent: number | null): ContextRiskLevel {
+  if (usagePercent === null) return "unknown";
+  if (usagePercent >= DANGER_USAGE_PERCENT) return "danger";
+  if (usagePercent >= WATCH_USAGE_PERCENT) return "watch";
+  return "ok";
+}
+
+function sumSegments(segments: readonly AnatomySegment[], role: AnatomyRole): number {
+  return segments
+    .filter((segment) => segment.role === role)
+    .reduce((sum, segment) => sum + segment.size, 0);
+}
+
+function buildRoleUsages(segments: readonly AnatomySegment[], total: number): RoleUsage[] {
+  const roles: AnatomyRole[] = ["system", "user", "assistant", "tool", "tools"];
+  return roles
+    .map((role) => {
+      const tokens = sumSegments(segments, role);
+      return {
+        role,
+        label: ROLE_LABELS[role],
+        tokens,
+        percent: total > 0 ? tokens / total : 0,
+      };
+    })
+    .filter((usage) => usage.tokens > 0)
+    .sort((a, b) => b.tokens - a.tokens);
+}
+
+function normalizeDuplicateText(text: string): string {
+  return text.replace(/\s+/g, " ").trim().toLowerCase();
+}
+
+function duplicateDiagnostic(segments: readonly AnatomySegment[]): ContextDiagnostic | null {
+  type DuplicateBucket = {
+    count: number;
+    tokens: number;
+    firstTokens: number;
+    label: string;
+  };
+
+  const buckets = new Map<string, DuplicateBucket>();
+  for (const segment of segments) {
+    if (segment.size < DUPLICATE_MIN_TOKENS) continue;
+    if (segment.characters < DUPLICATE_MIN_CHARS) continue;
+    const normalized = normalizeDuplicateText(segment.text);
+    if (normalized === "") continue;
+    const existing = buckets.get(normalized);
+    if (existing === undefined) {
+      buckets.set(normalized, {
+        count: 1,
+        tokens: segment.size,
+        firstTokens: segment.size,
+        label: segment.label,
+      });
+      continue;
+    }
+    buckets.set(normalized, {
+      count: existing.count + 1,
+      tokens: existing.tokens + segment.size,
+      firstTokens: existing.firstTokens,
+      label: existing.label,
+    });
+  }
+
+  let repeatedGroups = 0;
+  let repeatedSegments = 0;
+  let repeatedTokens = 0;
+  let largest: DuplicateBucket | null = null;
+  for (const bucket of buckets.values()) {
+    if (bucket.count < 2) continue;
+    repeatedGroups += 1;
+    repeatedSegments += bucket.count;
+    repeatedTokens += bucket.tokens - bucket.firstTokens;
+    if (largest === null || bucket.tokens > largest.tokens) largest = bucket;
+  }
+
+  if (repeatedGroups === 0 || largest === null) return null;
+
+  return {
+    kind: "duplicate",
+    severity: repeatedTokens >= LONG_TOOL_SCHEMA_TOKENS ? "danger" : "watch",
+    title: "Duplicate context",
+    detail: `${String(repeatedSegments)} repeated blocks across ${String(
+      repeatedGroups,
+    )} group${repeatedGroups === 1 ? "" : "s"}, ~${String(repeatedTokens)} repeated tokens.`,
+  };
+}
+
+function diagnosticsForRolePressure(
+  roleUsages: readonly RoleUsage[],
+  total: number,
+  messageSegmentCount: number,
+): ContextDiagnostic[] {
+  const diagnostics: ContextDiagnostic[] = [];
+  const toolUsage = roleUsages.find((usage) => usage.role === "tools") ?? null;
+  if (
+    toolUsage !== null &&
+    (toolUsage.tokens >= LONG_TOOL_SCHEMA_TOKENS ||
+      (toolUsage.percent >= LARGE_ROLE_PERCENT && toolUsage.tokens >= SYSTEM_HEAVY_TOKENS))
+  ) {
+    diagnostics.push({
+      kind: "tool-schema",
+      severity: toolUsage.tokens >= LONG_TOOL_SCHEMA_TOKENS ? "danger" : "watch",
+      title: "Large tool schema",
+      detail: `Tool definitions take ${Math.round(toolUsage.percent * 100)}% of request context.`,
+    });
+  }
+
+  const systemUsage = roleUsages.find((usage) => usage.role === "system") ?? null;
+  if (
+    systemUsage !== null &&
+    systemUsage.tokens >= SYSTEM_HEAVY_TOKENS &&
+    systemUsage.percent >= SYSTEM_HEAVY_PERCENT
+  ) {
+    diagnostics.push({
+      kind: "system-heavy",
+      severity: "watch",
+      title: "Large system prompt",
+      detail: `System instructions take ${Math.round(systemUsage.percent * 100)}% of request context.`,
+    });
+  }
+
+  const historyTokens = roleUsages
+    .filter((usage) => usage.role === "user" || usage.role === "assistant" || usage.role === "tool")
+    .reduce((sum, usage) => sum + usage.tokens, 0);
+  const historyPercent = total > 0 ? historyTokens / total : 0;
+  if (
+    messageSegmentCount >= HISTORY_BLOAT_SEGMENTS &&
+    (historyTokens >= HISTORY_BLOAT_TOKENS || historyPercent >= HISTORY_BLOAT_PERCENT)
+  ) {
+    diagnostics.push({
+      kind: "history-bloat",
+      severity: historyPercent >= 0.85 ? "danger" : "watch",
+      title: "Conversation history growth",
+      detail: `${String(messageSegmentCount)} message blocks take ${Math.round(
+        historyPercent * 100,
+      )}% of request context.`,
+    });
+  }
+
+  return diagnostics;
+}
+
+export function analyzeContextIntelligence({
+  segments,
+  inputTokens,
+  parsed,
+  model,
+}: {
+  segments: readonly AnatomySegment[];
+  inputTokens: number | null;
+  parsed: unknown;
+  model: string | null;
+}): ContextIntelligence {
+  const totalEstimatedTokens = segments.reduce((sum, segment) => sum + segment.size, 0);
+  const requestModel = model ?? readRequestModel(parsed);
+  const estimatedInputTokens = inputTokens ?? totalEstimatedTokens;
+  const outputReserveTokens = readPositiveIntegerField(parsed, OUTPUT_RESERVE_FIELDS);
+  const contextWindow = resolveContextWindow(requestModel, parsed);
+  const reservedTokens = outputReserveTokens ?? 0;
+  const windowUsedTokens =
+    contextWindow.tokens === null ? null : estimatedInputTokens + reservedTokens;
+  const remainingInputTokens =
+    contextWindow.tokens === null ? null : contextWindow.tokens - estimatedInputTokens;
+  const remainingAfterReserveTokens =
+    contextWindow.tokens === null
+      ? null
+      : contextWindow.tokens - estimatedInputTokens - reservedTokens;
+  const usagePercent =
+    contextWindow.tokens === null || windowUsedTokens === null
+      ? null
+      : clampPercent(windowUsedTokens / contextWindow.tokens);
+  const roleUsages = buildRoleUsages(segments, totalEstimatedTokens);
+  const largestRole = roleUsages[0] ?? null;
+  const messageSegmentCount = segments.filter((segment) => segment.role !== "tools").length;
+  const duplicate = duplicateDiagnostic(segments);
+  const diagnostics = diagnosticsForRolePressure(
+    roleUsages,
+    totalEstimatedTokens,
+    messageSegmentCount,
+  );
+  if (duplicate !== null) diagnostics.unshift(duplicate);
+
+  return {
+    model: requestModel,
+    contextWindow,
+    estimatedInputTokens,
+    outputReserveTokens,
+    windowUsedTokens,
+    remainingInputTokens,
+    remainingAfterReserveTokens,
+    usagePercent,
+    riskLevel: riskLevel(usagePercent),
+    roleUsages,
+    largestRole,
+    diagnostics,
+  };
+}
+
+export const CONTEXT_USAGE_THRESHOLDS = {
+  watch: WATCH_USAGE_PERCENT,
+  danger: DANGER_USAGE_PERCENT,
+} as const;

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

@@ -0,0 +1,213 @@
+import { safeGetOwnProperty } from "../../lib/objectUtils";
+
+export type RequestToolCategory = "file" | "shell" | "browser" | "web" | "mcp" | "code" | "other";
+
+export type RequestToolDefinition = {
+  name: string;
+  description: string | null;
+  descriptionPreview: string | null;
+  category: RequestToolCategory;
+  parameterCount: number;
+  requiredParameters: string[];
+  schema: unknown | null;
+};
+
+export type RequestToolCategorySummary = {
+  category: RequestToolCategory;
+  count: number;
+};
+
+export type RequestToolsSummary = {
+  tools: RequestToolDefinition[];
+  toolChoiceLabel: string | null;
+  categories: RequestToolCategorySummary[];
+};
+
+const CATEGORY_ORDER: RequestToolCategory[] = [
+  "file",
+  "shell",
+  "browser",
+  "web",
+  "mcp",
+  "code",
+  "other",
+];
+
+function firstTextSlice(value: string): string {
+  const normalized = value.replace(/\s+/g, " ").trim();
+  if (normalized.length <= 120) return normalized;
+  return `${normalized.slice(0, 119)}...`;
+}
+
+function previewDescription(description: string | null): string | null {
+  if (description === null) return null;
+  const normalized = description.replace(/\s+/g, " ").trim();
+  if (normalized.length === 0) return null;
+  const sentenceEnd = normalized.search(/[.!?。！？]/);
+  if (sentenceEnd >= 24) return firstTextSlice(normalized.slice(0, sentenceEnd + 1));
+  return firstTextSlice(normalized);
+}
+
+function lowerHaystack(name: string, description: string | null): string {
+  return `${name} ${description ?? ""}`.toLowerCase();
+}
+
+function includesAny(value: string, needles: readonly string[]): boolean {
+  return needles.some((needle) => value.includes(needle));
+}
+
+function categorizeTool(name: string, description: string | null): RequestToolCategory {
+  const haystack = lowerHaystack(name, description);
+  if (
+    name.startsWith("mcp__") ||
+    name.startsWith("inspector_") ||
+    includesAny(haystack, [" mcp", "model context protocol"])
+  ) {
+    return "mcp";
+  }
+  if (
+    includesAny(haystack, ["bash", "shell", "terminal", "command", "powershell", "exec", "process"])
+  ) {
+    return "shell";
+  }
+  if (
+    includesAny(haystack, [
+      "browser",
+      "playwright",
+      "screenshot",
+      "click",
+      "navigate",
+      "page",
+      "tab",
+    ])
+  ) {
+    return "browser";
+  }
+  if (
+    includesAny(haystack, [
+      "read",
+      "write",
+      "edit",
+      "file",
+      "glob",
+      "grep",
+      "patch",
+      "filesystem",
+      "directory",
+    ])
+  ) {
+    return "file";
+  }
+  if (includesAny(haystack, ["web", "search", "http", "url", "fetch"])) {
+    return "web";
+  }
+  if (includesAny(haystack, ["code", "typescript", "javascript", "python", "repl"])) {
+    return "code";
+  }
+  return "other";
+}
+
+function parameterNames(schema: unknown): string[] {
+  const properties = safeGetOwnProperty(schema, "properties");
+  if (properties === null || typeof properties !== "object" || Array.isArray(properties)) {
+    return [];
+  }
+  return Object.keys(properties).sort((a, b) => a.localeCompare(b));
+}
+
+function requiredParameterNames(schema: unknown): string[] {
+  const required = safeGetOwnProperty(schema, "required");
+  if (!Array.isArray(required)) return [];
+  const names: string[] = [];
+  for (const item of required) {
+    if (typeof item === "string" && item.length > 0) names.push(item);
+  }
+  return names.sort((a, b) => a.localeCompare(b));
+}
+
+function parseAnthropicTool(tool: unknown): RequestToolDefinition | null {
+  const name = safeGetOwnProperty(tool, "name");
+  if (typeof name !== "string" || name.length === 0) return null;
+  const description = safeGetOwnProperty(tool, "description");
+  const schema = safeGetOwnProperty(tool, "input_schema") ?? null;
+  const normalizedDescription = typeof description === "string" ? description : null;
+  return {
+    name,
+    description: normalizedDescription,
+    descriptionPreview: previewDescription(normalizedDescription),
+    category: categorizeTool(name, normalizedDescription),
+    parameterCount: parameterNames(schema).length,
+    requiredParameters: requiredParameterNames(schema),
+    schema,
+  };
+}
+
+function parseOpenAITool(tool: unknown): RequestToolDefinition | null {
+  const fn = safeGetOwnProperty(tool, "function");
+  const name = safeGetOwnProperty(fn, "name");
+  if (typeof name !== "string" || name.length === 0) return null;
+  const description = safeGetOwnProperty(fn, "description");
+  const schema = safeGetOwnProperty(fn, "parameters") ?? null;
+  const normalizedDescription = typeof description === "string" ? description : null;
+  return {
+    name,
+    description: normalizedDescription,
+    descriptionPreview: previewDescription(normalizedDescription),
+    category: categorizeTool(name, normalizedDescription),
+    parameterCount: parameterNames(schema).length,
+    requiredParameters: requiredParameterNames(schema),
+    schema,
+  };
+}
+
+function parseTool(tool: unknown): RequestToolDefinition | null {
+  const openAITool = parseOpenAITool(tool);
+  if (openAITool !== null) return openAITool;
+  return parseAnthropicTool(tool);
+}
+
+function formatToolChoice(choice: unknown): string | null {
+  if (choice === undefined || choice === null) return null;
+  if (typeof choice === "string") return choice;
+  const type = safeGetOwnProperty(choice, "type");
+  const name = safeGetOwnProperty(choice, "name");
+  const fnName = safeGetOwnProperty(safeGetOwnProperty(choice, "function"), "name");
+  if (typeof type === "string" && typeof fnName === "string" && fnName.length > 0) {
+    return `${type}: ${fnName}`;
+  }
+  if (typeof type === "string" && typeof name === "string" && name.length > 0) {
+    return `${type}: ${name}`;
+  }
+  if (typeof type === "string") return type;
+  const encoded = JSON.stringify(choice);
+  return encoded === undefined ? null : firstTextSlice(encoded);
+}
+
+function summarizeCategories(tools: RequestToolDefinition[]): RequestToolCategorySummary[] {
+  const counts = new Map<RequestToolCategory, number>();
+  for (const tool of tools) {
+    counts.set(tool.category, (counts.get(tool.category) ?? 0) + 1);
+  }
+  return CATEGORY_ORDER.flatMap((category) => {
+    const count = counts.get(category) ?? 0;
+    return count > 0 ? [{ category, count }] : [];
+  });
+}
+
+export function parseRequestTools(parsed: unknown): RequestToolsSummary | null {
+  const rawTools = safeGetOwnProperty(parsed, "tools");
+  if (!Array.isArray(rawTools) || rawTools.length === 0) return null;
+
+  const tools: RequestToolDefinition[] = [];
+  for (const rawTool of rawTools) {
+    const tool = parseTool(rawTool);
+    if (tool !== null) tools.push(tool);
+  }
+  if (tools.length === 0) return null;
+
+  return {
+    tools,
+    toolChoiceLabel: formatToolChoice(safeGetOwnProperty(parsed, "tool_choice")),
+    categories: summarizeCategories(tools),
+  };
+}

package/src/routes/__root.tsx

@@ -18,6 +18,7 @@ export const Route = createRootRoute({
     ],
   }),
   component: RootComponent,
+  notFoundComponent: RootNotFoundComponent,
 });
 
 function RootComponent() {
@@ -28,6 +29,32 @@ function RootComponent() {
   );
 }
 
+function RootNotFoundComponent() {
+  return (
+    <RootDocument>
+      <main className="min-h-screen bg-background text-foreground">
+        <div className="mx-auto flex min-h-screen w-full max-w-3xl flex-col justify-center px-6 py-16">
+          <div className="border-border/70 bg-card/60 rounded-lg border p-8 shadow-sm">
+            <div className="text-muted-foreground font-mono text-xs uppercase tracking-wider">
+              404
+            </div>
+            <h1 className="mt-3 text-2xl font-semibold">Page not found</h1>
+            <p className="text-muted-foreground mt-3 max-w-xl text-sm leading-6">
+              This route is not part of the Agent Inspector UI or API surface.
+            </p>
+            <a
+              href="/"
+              className="bg-primary text-primary-foreground hover:bg-primary/90 mt-6 inline-flex h-9 items-center justify-center rounded-md px-4 text-sm font-medium transition-colors"
+            >
+              Open Agent Inspector
+            </a>
+          </div>
+        </div>
+      </main>
+    </RootDocument>
+  );
+}
+
 function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
   return (
     <html lang="en" className="dark">