@tonyclaw/agent-inspector 4.0.1 → 4.0.3

package/src/lib/ssrfGuard.ts

@@ -1,133 +0,0 @@
-/**
- * SSRF guard for upstream provider URLs.
- *
- * The proxy fetches arbitrary provider-configured base URLs (Anthropic, OpenAI,
- * third-party compatible endpoints). Without protection, a malicious provider
- * config could point the proxy at cloud metadata endpoints
- * (169.254.169.254 / fd00:ec2::254), loopback services, or private RFC1918
- * ranges — and the response body is captured to a log file the attacker can
- * read back. We block those targets by default; an env var opt-in allows
- * intentional localhost development (e.g. Ollama on 127.0.0.1).
- */
-
-export type SsrfDecision = { allow: true } | { allow: false; reason: string };
-
-const LOOPBACK_HOSTNAMES = new Set([
-  "localhost",
-  "ip6-localhost",
-  "ip6-loopback",
-  "[::1]",
-  "[::ffff:127.0.0.1]",
-]);
-
-/**
- * Returns true when the host is a loopback address, link-local address, or
- * private RFC1918 / RFC4193 / unique-local range. Both IPv4 dotted-quad and
- * IPv6 forms are recognized; bracketed forms (`[::1]`) are normalized.
- */
-function isLoopbackHost(hostname: string): boolean {
-  const lower = hostname.toLowerCase().replace(/^\[|]$/g, "");
-  if (LOOPBACK_HOSTNAMES.has(lower)) return true;
-  if (lower === "::1") return true;
-  if (lower.startsWith("::ffff:127.")) return true;
-  if (lower.startsWith("::ffff:7f00:")) return true;
-  return /^127\./.test(lower);
-}
-
-function mappedIpv4Address(hostname: string): string | null {
-  const lower = hostname.toLowerCase();
-  if (!lower.startsWith("::ffff:")) return null;
-  const suffix = lower.slice("::ffff:".length);
-  if (/^\d{1,3}(?:\.\d{1,3}){3}$/.test(suffix)) return suffix;
-  const match = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(suffix);
-  if (match === null) return null;
-  const highText = match[1];
-  const lowText = match[2];
-  if (highText === undefined || lowText === undefined) return null;
-  const high = Number.parseInt(highText, 16);
-  const low = Number.parseInt(lowText, 16);
-  return `${String(high >> 8)}.${String(high & 0xff)}.${String(low >> 8)}.${String(low & 0xff)}`;
-}
-
-export function isInternalHost(hostname: string): boolean {
-  if (LOOPBACK_HOSTNAMES.has(hostname.toLowerCase())) return true;
-
-  const mappedIpv4 = mappedIpv4Address(hostname);
-  if (mappedIpv4 !== null) return isInternalHost(mappedIpv4);
-
-  const ipv4Match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(hostname);
-  if (ipv4Match !== null) {
-    const [, a, b] = ipv4Match;
-    if (a === undefined || b === undefined) return false;
-    const first = Number.parseInt(a, 10);
-    const second = Number.parseInt(b, 10);
-    if (first === 127) return true; // 127.0.0.0/8 loopback
-    if (first === 10) return true; // 10.0.0.0/8 private
-    if (first === 172 && second >= 16 && second <= 31) return true; // 172.16.0.0/12
-    if (first === 192 && second === 168) return true; // 192.168.0.0/16
-    if (first === 169 && second === 254) return true; // 169.254.0.0/16 link-local
-    if (first === 0) return true; // 0.0.0.0/8
-    if (first === 100 && second >= 64 && second <= 127) return true; // 100.64.0.0/10 CGNAT
-    if (first >= 224) return true; // multicast and reserved
-    if (first === 198 && (second === 18 || second === 19)) return true; // benchmark range
-    return false;
-  }
-
-  // IPv6 — bracketless form already stripped by URL parser; check for loopback
-  // and link-local prefixes.
-  const lower = hostname.toLowerCase();
-  if (lower === "::") return true;
-  if (lower === "::1") return true;
-  if (/^fe[89ab]/.test(lower)) return true; // fe80::/10 link-local
-  if (lower.startsWith("fc") || lower.startsWith("fd")) return true; // ULA (fd00::/8)
-  if (lower.startsWith("ff")) return true; // multicast
-
-  return false;
-}
-
-export type SsrfGuardOptions = {
-  /** Bypass the guard entirely (used by trusted test code). */
-  bypass?: boolean;
-  /** When true, allow loopback hosts (127.0.0.1, ::1, localhost). Default false. */
-  allowLoopback?: boolean;
-};
-
-/**
- * Inspects a provider base URL and decides whether the proxy is allowed to
- * forward requests to it. Returns `{ allow: true }` for public hosts and
- * `{ allow: false, reason }` for internal/private addresses.
- */
-export function evaluateUpstreamUrl(rawUrl: string, options: SsrfGuardOptions = {}): SsrfDecision {
-  if (options.bypass === true) return { allow: true };
-
-  let parsed: URL;
-  try {
-    parsed = new URL(rawUrl);
-  } catch {
-    return { allow: false, reason: "Not a valid URL" };
-  }
-
-  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-    return { allow: false, reason: `Unsupported scheme "${parsed.protocol}"` };
-  }
-
-  if (options.allowLoopback === true && parsed.hostname === "localhost") {
-    return { allow: true };
-  }
-
-  // Bun's URL parser keeps brackets on IPv6 hostnames (`[::1]`); strip them so
-  // prefix checks below work against the canonical form.
-  const hostname = parsed.hostname.replace(/^\[|]$/g, "");
-
-  if (isInternalHost(hostname)) {
-    if (options.allowLoopback === true) {
-      if (isLoopbackHost(hostname)) return { allow: true };
-    }
-    return {
-      allow: false,
-      reason: `Refusing to proxy to internal address "${hostname}"`,
-    };
-  }
-
-  return { allow: true };
-}

package/src/lib/stopReason.ts

@@ -1,130 +0,0 @@
-import type { CapturedLog, StopReason } from "../contracts";
-import { isRecord } from "./unknown";
-
-export type { StopReason } from "../contracts";
-
-function normalizeAnthropicStopReason(value: string): StopReason {
-  switch (value) {
-    case "end_turn":
-    case "tool_use":
-      return value;
-    case "max_tokens":
-      return "length";
-    default:
-      return null;
-  }
-}
-
-function extractStopReasonFromJsonValue(value: unknown): StopReason {
-  if (!isRecord(value)) return null;
-
-  // Anthropic shape: { stop_reason: "end_turn" | "tool_use" | ... }
-  if (typeof value.stop_reason === "string") {
-    return normalizeAnthropicStopReason(value.stop_reason);
-  }
-
-  // Anthropic SSE shape: { type: "message_delta", delta: { stop_reason: "..." } }
-  if (isRecord(value.delta) && typeof value.delta.stop_reason === "string") {
-    return normalizeAnthropicStopReason(value.delta.stop_reason);
-  }
-
-  // OpenAI Chat shape: { choices: [{ finish_reason: "stop" | "length" | ... }] }
-  if (Array.isArray(value.choices)) {
-    for (const choice of value.choices) {
-      if (!isRecord(choice) || typeof choice.finish_reason !== "string") continue;
-      const reason = normalizeOpenAIFinishReason(choice.finish_reason);
-      if (reason !== null) return reason;
-    }
-  }
-
-  // OpenAI Responses shape: { status: "completed", output: [...] }
-  if (Array.isArray(value.output)) {
-    for (const item of value.output) {
-      if (isRecord(item) && item.type === "function_call") {
-        return "tool_use";
-      }
-    }
-    if (value.status === "completed") {
-      return "stop";
-    }
-  }
-
-  if (value.status === "incomplete" && isRecord(value.incomplete_details)) {
-    const reason = value.incomplete_details.reason;
-    if (typeof reason === "string" && isResponsesLengthLimitReason(reason)) {
-      return "length";
-    }
-  }
-
-  return null;
-}
-
-function extractStopReasonFromSseText(text: string): StopReason {
-  let stopReason: StopReason = null;
-  for (const rawLine of text.split("\n")) {
-    const line = rawLine.trim();
-    if (!line.startsWith("data: ")) continue;
-    const data = line.slice(6).trim();
-    if (data === "[DONE]") break;
-    try {
-      const reason = extractStopReasonFromJsonValue(JSON.parse(data));
-      if (reason !== null) stopReason = reason;
-    } catch {
-      // Ignore malformed or non-JSON SSE data lines.
-    }
-  }
-  return stopReason;
-}
-
-function normalizeOpenAIFinishReason(value: string): StopReason {
-  switch (value) {
-    case "stop":
-    case "length":
-      return value;
-    case "max_tokens":
-      return "length";
-    default:
-      return null;
-  }
-}
-
-function isResponsesLengthLimitReason(value: string): boolean {
-  switch (value) {
-    case "max_output_tokens":
-    case "max_tokens":
-      return true;
-    default:
-      return false;
-  }
-}
-
-/**
- * Extracts the stop/finish reason from a captured log's response text.
- * Detects the response body shape (Anthropic or OpenAI) independently of
- * `log.apiFormat`, since the body shape may not match the declared format
- * (e.g. an Anthropic-compatible endpoint returning Anthropic-shaped JSON
- * while the request was classified as OpenAI).
- */
-export function extractStopReason(log: CapturedLog): StopReason {
-  if (log.stopReason !== undefined) return log.stopReason;
-  if (log.responseText === null) return null;
-
-  try {
-    let json: unknown = JSON.parse(log.responseText);
-    // Handle double-encoded JSON
-    if (typeof json === "string") {
-      json = JSON.parse(json);
-    }
-    return extractStopReasonFromJsonValue(json);
-  } catch {
-    return extractStopReasonFromSseText(log.responseText);
-  }
-}
-
-/**
- * Returns true when the stop reason indicates the assistant completed its
- * turn, including responses truncated by output length limits.
- */
-export function isTurnBoundary(stopReason: StopReason): boolean {
-  return stopReason === "end_turn" || stopReason === "stop" || stopReason === "length";
-}

package/src/lib/themeMode.ts

@@ -1,41 +0,0 @@
-export type ThemeMode = "light" | "dark" | "eye-care";
-
-export const THEME_MODE_STORAGE_KEY = "agent-inspector.theme";
-
-export function normalizeThemeMode(value: string | null): ThemeMode {
-  switch (value) {
-    case "light":
-      return "light";
-    case "dark":
-      return "dark";
-    case "eye-care":
-      return "eye-care";
-    case null:
-      return "dark";
-    default:
-      return "dark";
-  }
-}
-
-export function applyThemeMode(themeMode: ThemeMode): void {
-  if (typeof document === "undefined") return;
-  document.documentElement.dataset.theme = themeMode;
-}
-
-export function readStoredThemeMode(): ThemeMode {
-  if (typeof window === "undefined") return "dark";
-  try {
-    return normalizeThemeMode(window.localStorage.getItem(THEME_MODE_STORAGE_KEY));
-  } catch {
-    return "dark";
-  }
-}
-
-export function persistThemeMode(themeMode: ThemeMode): void {
-  if (typeof window === "undefined") return;
-  try {
-    window.localStorage.setItem(THEME_MODE_STORAGE_KEY, themeMode);
-  } catch {
-    // Local storage can be unavailable in hardened browser contexts.
-  }
-}

package/src/lib/timeDisplay.ts

@@ -1,22 +0,0 @@
-import type { TimeDisplayFormat } from "./runtimeConfig";
-
-export function formatTimestamp(iso: string, format: TimeDisplayFormat): string {
-  switch (format) {
-    case "full":
-      return iso;
-    case "time":
-      return new Date(iso).toLocaleTimeString([], {
-        hour: "2-digit",
-        minute: "2-digit",
-        second: "2-digit",
-      });
-  }
-}
-
-export function formatTimestampRange(
-  startedAt: string,
-  endedAt: string,
-  format: TimeDisplayFormat,
-): string {
-  return `${formatTimestamp(startedAt, format)} - ${formatTimestamp(endedAt, format)}`;
-}

package/src/lib/toolTrace.ts

@@ -1,290 +0,0 @@
-import type { ApiFormat, CapturedLog, StreamingChunk, ToolTraceEvent } from "../contracts";
-import { apiFormatForPath } from "./apiFormat";
-import { safeGetOwnProperty } from "./objectUtils";
-
-export type { ToolTraceEvent };
-
-const PREVIEW_LIMIT = 180;
-
-type ResolvedLogFormat = ApiFormat;
-
-function resolveLogFormat(log: Pick<CapturedLog, "path" | "apiFormat">): ResolvedLogFormat {
-  const pathFormat = apiFormatForPath(log.path);
-  return pathFormat === "unknown" ? log.apiFormat : pathFormat;
-}
-
-function responseMayContainToolTrace(log: CapturedLog, format: ResolvedLogFormat): boolean {
-  const responseText = log.responseText;
-  if (responseText === null) return false;
-
-  switch (format) {
-    case "anthropic":
-      return responseText.includes("tool_use");
-    case "openai":
-      return responseText.includes("tool_calls") || responseText.includes("function_call");
-    case "unknown":
-      return false;
-  }
-}
-
-function parseJsonResponse(responseText: string | null): unknown {
-  if (responseText === null) return null;
-  try {
-    const parsed: unknown = JSON.parse(responseText);
-    if (typeof parsed === "string") {
-      return JSON.parse(parsed);
-    }
-    return parsed;
-  } catch {
-    return null;
-  }
-}
-
-function previewValue(value: unknown): string | null {
-  if (value === undefined || value === null) return null;
-  const raw = typeof value === "string" ? value : JSON.stringify(value);
-  if (raw === undefined) return null;
-  const normalized = raw.replace(/\s+/g, " ").trim();
-  if (normalized.length === 0) return null;
-  return normalized.length > PREVIEW_LIMIT
-    ? `${normalized.slice(0, PREVIEW_LIMIT - 1)}...`
-    : normalized;
-}
-
-function copyValue(value: unknown): string | null {
-  if (value === undefined || value === null) return null;
-  if (typeof value === "string") return value.length > 0 ? value : null;
-  const raw = JSON.stringify(value, null, 2);
-  return raw === undefined || raw.length === 0 ? null : raw;
-}
-
-function makeEvent({
-  log,
-  provider,
-  index,
-  name,
-  input,
-}: {
-  log: Pick<CapturedLog, "id">;
-  provider: "anthropic" | "openai";
-  index: number;
-  name: string;
-  input: unknown;
-}): ToolTraceEvent {
-  return {
-    id: `${String(log.id)}-${provider}-tool-${String(index)}`,
-    logId: log.id,
-    index,
-    provider,
-    name,
-    argumentsText: copyValue(input),
-    argumentsPreview: previewValue(input),
-  };
-}
-
-function extractAnthropicResponseToolTraceEvents(log: CapturedLog): ToolTraceEvent[] {
-  const parsed = parseJsonResponse(log.responseText);
-  const content = safeGetOwnProperty(parsed, "content");
-  if (!Array.isArray(content)) return [];
-
-  const events: ToolTraceEvent[] = [];
-  for (const block of content) {
-    const type = safeGetOwnProperty(block, "type");
-    if (type !== "tool_use") continue;
-    const name = safeGetOwnProperty(block, "name");
-    if (typeof name !== "string" || name.length === 0) continue;
-    const input = safeGetOwnProperty(block, "input");
-    events.push(makeEvent({ log, provider: "anthropic", index: events.length, name, input }));
-  }
-  return events;
-}
-
-function extractOpenAIResponseToolTraceEvents(log: CapturedLog): ToolTraceEvent[] {
-  const parsed = parseJsonResponse(log.responseText);
-  const choices = safeGetOwnProperty(parsed, "choices");
-  const events: ToolTraceEvent[] = [];
-
-  if (Array.isArray(choices)) {
-    for (const choice of choices) {
-      const message = safeGetOwnProperty(choice, "message");
-      const toolCalls = safeGetOwnProperty(message, "tool_calls");
-      if (Array.isArray(toolCalls)) {
-        for (const call of toolCalls) {
-          const fn = safeGetOwnProperty(call, "function");
-          const name = safeGetOwnProperty(fn, "name");
-          if (typeof name !== "string" || name.length === 0) continue;
-          const args = safeGetOwnProperty(fn, "arguments");
-          events.push(
-            makeEvent({ log, provider: "openai", index: events.length, name, input: args }),
-          );
-        }
-      }
-      const functionCall = safeGetOwnProperty(message, "function_call");
-      const functionCallName = safeGetOwnProperty(functionCall, "name");
-      if (typeof functionCallName === "string" && functionCallName.length > 0) {
-        const args = safeGetOwnProperty(functionCall, "arguments");
-        events.push(
-          makeEvent({
-            log,
-            provider: "openai",
-            index: events.length,
-            name: functionCallName,
-            input: args,
-          }),
-        );
-      }
-    }
-  }
-
-  const output = safeGetOwnProperty(parsed, "output");
-  if (Array.isArray(output)) {
-    for (const item of output) {
-      if (safeGetOwnProperty(item, "type") !== "function_call") continue;
-      const name = safeGetOwnProperty(item, "name");
-      if (typeof name !== "string" || name.length === 0) continue;
-      const args = safeGetOwnProperty(item, "arguments");
-      events.push(makeEvent({ log, provider: "openai", index: events.length, name, input: args }));
-    }
-  }
-  return events;
-}
-
-function chunkData(chunk: StreamingChunk): unknown {
-  if (typeof chunk.data === "string") {
-    try {
-      return JSON.parse(chunk.data);
-    } catch {
-      return chunk.data;
-    }
-  }
-  return chunk.data;
-}
-
-function appendUniqueEvent(
-  events: ToolTraceEvent[],
-  seen: Set<string>,
-  event: ToolTraceEvent,
-): void {
-  const key = `${event.provider}:${event.name}:${event.index}`;
-  if (seen.has(key)) return;
-  seen.add(key);
-  events.push(event);
-}
-
-function extractAnthropicChunkToolTraceEvents(log: CapturedLog): ToolTraceEvent[] {
-  const chunks = log.streamingChunks?.chunks ?? [];
-  const events: ToolTraceEvent[] = [];
-  const seen = new Set<string>();
-
-  for (const chunk of chunks) {
-    const data = chunkData(chunk);
-    const contentBlock = safeGetOwnProperty(data, "content_block");
-    if (safeGetOwnProperty(contentBlock, "type") !== "tool_use") continue;
-    const name = safeGetOwnProperty(contentBlock, "name");
-    if (typeof name !== "string" || name.length === 0) continue;
-    const input = safeGetOwnProperty(contentBlock, "input");
-    appendUniqueEvent(
-      events,
-      seen,
-      makeEvent({ log, provider: "anthropic", index: chunk.index, name, input }),
-    );
-  }
-
-  return events.map((event, index) => ({
-    ...event,
-    id: `${String(log.id)}-anthropic-tool-${String(index)}`,
-    index,
-  }));
-}
-
-function extractOpenAIChunkToolTraceEvents(log: CapturedLog): ToolTraceEvent[] {
-  const chunks = log.streamingChunks?.chunks ?? [];
-  const events: ToolTraceEvent[] = [];
-  const seen = new Set<string>();
-
-  for (const chunk of chunks) {
-    const data = chunkData(chunk);
-    const choices = safeGetOwnProperty(data, "choices");
-    if (Array.isArray(choices)) {
-      for (const choice of choices) {
-        const delta = safeGetOwnProperty(choice, "delta");
-        const toolCalls = safeGetOwnProperty(delta, "tool_calls");
-        if (Array.isArray(toolCalls)) {
-          for (const call of toolCalls) {
-            const fn = safeGetOwnProperty(call, "function");
-            const name = safeGetOwnProperty(fn, "name");
-            if (typeof name !== "string" || name.length === 0) continue;
-            const args = safeGetOwnProperty(fn, "arguments");
-            appendUniqueEvent(
-              events,
-              seen,
-              makeEvent({ log, provider: "openai", index: events.length, name, input: args }),
-            );
-          }
-        }
-        const functionCall = safeGetOwnProperty(delta, "function_call");
-        const functionCallName = safeGetOwnProperty(functionCall, "name");
-        if (typeof functionCallName === "string" && functionCallName.length > 0) {
-          const args = safeGetOwnProperty(functionCall, "arguments");
-          appendUniqueEvent(
-            events,
-            seen,
-            makeEvent({
-              log,
-              provider: "openai",
-              index: events.length,
-              name: functionCallName,
-              input: args,
-            }),
-          );
-        }
-      }
-    }
-
-    const item = safeGetOwnProperty(data, "item");
-    if (safeGetOwnProperty(item, "type") === "function_call") {
-      const name = safeGetOwnProperty(item, "name");
-      if (typeof name === "string" && name.length > 0) {
-        const args = safeGetOwnProperty(item, "arguments");
-        appendUniqueEvent(
-          events,
-          seen,
-          makeEvent({ log, provider: "openai", index: events.length, name, input: args }),
-        );
-      }
-    }
-  }
-
-  return events.map((event, index) => ({
-    ...event,
-    id: `${String(log.id)}-openai-tool-${String(index)}`,
-    index,
-  }));
-}
-
-export function extractToolTraceEvents(log: CapturedLog): ToolTraceEvent[] {
-  if (log.toolTraceEvents !== undefined && log.toolTraceEvents.length > 0) {
-    return log.toolTraceEvents;
-  }
-
-  const format = resolveLogFormat(log);
-  if (responseMayContainToolTrace(log, format)) {
-    switch (format) {
-      case "anthropic":
-        return extractAnthropicResponseToolTraceEvents(log);
-      case "openai":
-        return extractOpenAIResponseToolTraceEvents(log);
-      case "unknown":
-        return [];
-    }
-  }
-
-  switch (format) {
-    case "anthropic":
-      return extractAnthropicChunkToolTraceEvents(log);
-    case "openai":
-      return extractOpenAIChunkToolTraceEvents(log);
-    case "unknown":
-      return [];
-  }
-}