@tonyclaw/agent-inspector 2.0.0

package/src/knowledge/redactor.ts

@@ -0,0 +1,80 @@
+import type { KnowledgeCandidate, RedactionMetadata } from "./types";
+
+type RedactionPattern = {
+  name: string;
+  pattern: RegExp;
+};
+
+const REDACTION_PATTERNS: RedactionPattern[] = [
+  { name: "authorization-header", pattern: /\bAuthorization\s*:\s*[^\s,;]+/gi },
+  { name: "bearer-token", pattern: /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/gi },
+  { name: "api-key", pattern: /\b(?:sk|ak)-[A-Za-z0-9_-]{12,}\b/gi },
+  { name: "cookie", pattern: /\bCookie\s*:\s*[^;\n]+(?:;[^\n]+)?/gi },
+  {
+    name: "secret-assignment",
+    pattern: /\b(?:api[_-]?key|token|secret|password)\s*=\s*["']?[^"'\s,;]{8,}["']?/gi,
+  },
+];
+
+type RedactedText = {
+  text: string;
+  patterns: string[];
+};
+
+function unique(values: string[]): string[] {
+  return [...new Set(values)];
+}
+
+export function redactText(input: string): RedactedText {
+  let text = input;
+  const patterns: string[] = [];
+  for (const item of REDACTION_PATTERNS) {
+    let matched = false;
+    text = text.replace(item.pattern, () => {
+      matched = true;
+      return `[REDACTED:${item.name}]`;
+    });
+    if (matched) {
+      patterns.push(item.name);
+    }
+  }
+  return { text, patterns: unique(patterns) };
+}
+
+function combineRedaction(patterns: string[]): RedactionMetadata {
+  const uniquePatterns = unique(patterns);
+  return {
+    redacted: uniquePatterns.length > 0,
+    patterns: uniquePatterns,
+  };
+}
+
+export function redactCandidate(candidate: KnowledgeCandidate): KnowledgeCandidate {
+  const title = redactText(candidate.title);
+  const content = redactText(candidate.content);
+  const tagResults = candidate.tags.map(redactText);
+  const evidenceProject =
+    candidate.evidence.project === null ? null : redactText(candidate.evidence.project);
+  const evidenceModels = candidate.evidence.models.map(redactText);
+  const patterns = [
+    ...title.patterns,
+    ...content.patterns,
+    ...tagResults.flatMap((result) => result.patterns),
+    ...(evidenceProject === null ? [] : evidenceProject.patterns),
+    ...evidenceModels.flatMap((result) => result.patterns),
+    ...candidate.redaction.patterns,
+  ];
+
+  return {
+    ...candidate,
+    title: title.text,
+    content: content.text,
+    tags: tagResults.map((result) => result.text),
+    evidence: {
+      ...candidate.evidence,
+      project: evidenceProject === null ? null : evidenceProject.text,
+      models: evidenceModels.map((result) => result.text),
+    },
+    redaction: combineRedaction(patterns),
+  };
+}

package/src/knowledge/types.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+
+export const KnowledgeCandidateTypeSchema = z.enum([
+  "episode",
+  "procedure",
+  "preference",
+  "project-fact",
+]);
+
+export type KnowledgeCandidateType = z.infer<typeof KnowledgeCandidateTypeSchema>;
+
+export const KnowledgeCandidateStatusSchema = z.enum(["draft", "promoted", "failed"]);
+
+export type KnowledgeCandidateStatus = z.infer<typeof KnowledgeCandidateStatusSchema>;
+
+export const KnowledgeEvidenceSchema = z.object({
+  source: z.literal("agent-inspector"),
+  sessionId: z.string(),
+  logIds: z.array(z.number().int().positive()),
+  project: z.string().nullable(),
+  models: z.array(z.string()),
+});
+
+export type KnowledgeEvidence = z.infer<typeof KnowledgeEvidenceSchema>;
+
+export const RedactionMetadataSchema = z.object({
+  redacted: z.boolean(),
+  patterns: z.array(z.string()),
+});
+
+export type RedactionMetadata = z.infer<typeof RedactionMetadataSchema>;
+
+export const KnowledgeCandidateSchema = z.object({
+  id: z.string(),
+  type: KnowledgeCandidateTypeSchema,
+  title: z.string(),
+  content: z.string(),
+  tags: z.array(z.string()),
+  source: z.literal("agent-inspector"),
+  sessionId: z.string(),
+  logIds: z.array(z.number().int().positive()),
+  evidence: KnowledgeEvidenceSchema,
+  status: KnowledgeCandidateStatusSchema,
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  openClawMemoryId: z.string().nullable(),
+  error: z.string().nullable(),
+  redaction: RedactionMetadataSchema,
+});
+
+export type KnowledgeCandidate = z.infer<typeof KnowledgeCandidateSchema>;
+
+export const OpenClawMemoryPayloadSchema = z.object({
+  idempotencyKey: z.string(),
+  type: KnowledgeCandidateTypeSchema,
+  title: z.string(),
+  content: z.string(),
+  tags: z.array(z.string()),
+  source: z.literal("agent-inspector"),
+  project: z.string().nullable(),
+  evidence: KnowledgeEvidenceSchema,
+});
+
+export type OpenClawMemoryPayload = z.infer<typeof OpenClawMemoryPayloadSchema>;
+
+export const KnowledgeSearchResultSchema = z.object({
+  id: z.string(),
+  type: KnowledgeCandidateTypeSchema.or(z.string()),
+  title: z.string(),
+  content: z.string(),
+  score: z.number().nullable(),
+  source: z.string().nullable(),
+  project: z.string().nullable(),
+  evidence: z.unknown().optional(),
+});
+
+export type KnowledgeSearchResult = z.infer<typeof KnowledgeSearchResultSchema>;
+
+export const KnowledgeSearchResponseSchema = z.object({
+  results: z.array(KnowledgeSearchResultSchema),
+  warning: z.string().nullable(),
+});
+
+export type KnowledgeSearchResponse = z.infer<typeof KnowledgeSearchResponseSchema>;

package/src/lib/apiClient.ts

@@ -0,0 +1,49 @@
+/* eslint-disable functional/no-throw-statements */
+import { z } from "zod";
+
+const ApiErrorSchema = z.object({
+  error: z.string(),
+});
+
+/**
+ * Parse and validate a JSON response at the browser/server trust boundary.
+ *
+ * Keeping this in one place makes response validation consistent without
+ * coupling callers to a specific API or domain type.
+ */
+export async function parseJsonResponse<T>(response: Response, schema: z.ZodType<T>): Promise<T> {
+  const data: unknown = await response.json();
+  return schema.parse(data);
+}
+
+/**
+ * Read the conventional `{ error: string }` API response when available.
+ * Malformed or non-JSON error bodies deliberately fall back to caller-owned
+ * text so each screen retains its existing user-facing message.
+ */
+export async function readApiError(response: Response, fallback: string): Promise<string> {
+  try {
+    const data: unknown = await response.json();
+    const result = ApiErrorSchema.safeParse(data);
+    return result.success ? result.data.error : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Fetch a JSON resource and validate its successful response.
+ */
+export async function fetchJson<T>(
+  input: RequestInfo | URL,
+  schema: z.ZodType<T>,
+  init?: RequestInit,
+  errorFallback?: (response: Response) => string,
+): Promise<T> {
+  const response = await fetch(input, init);
+  if (!response.ok) {
+    const fallback = errorFallback?.(response) ?? `Request failed with status ${response.status}`;
+    throw new Error(await readApiError(response, fallback));
+  }
+  return parseJsonResponse(response, schema);
+}

package/src/lib/export-logs.ts

@@ -0,0 +1,51 @@
+import JSZip from "jszip";
+import type { CapturedLog } from "../proxy/schemas";
+
+async function fetchStreamingChunks(logId: number): Promise<string | null> {
+  try {
+    const response = await fetch(`/api/logs/${logId}/chunks`);
+    if (!response.ok) return null;
+    const data: unknown = await response.json();
+    return JSON.stringify(data, null, 2);
+  } catch {
+    return null;
+  }
+}
+
+export async function exportLogsAsZip(logs: CapturedLog[]): Promise<void> {
+  const zip = new JSZip();
+
+  // Add regular request/response files
+  for (const log of logs) {
+    if (log.rawRequestBody !== null) {
+      zip.file(`#${log.id}.Request.json`, log.rawRequestBody);
+    }
+    if (log.responseText !== null) {
+      zip.file(`#${log.id}.Response.json`, log.responseText);
+    }
+  }
+
+  // Fetch SSE chunks in parallel for streaming logs
+  const streamingLogs = logs.filter((log) => log.streaming);
+  await Promise.allSettled(
+    streamingLogs.map(async (log) => {
+      const chunks = await fetchStreamingChunks(log.id);
+      if (chunks !== null) {
+        zip.file(`#${log.id}.SSE.Response.json`, chunks);
+      }
+    }),
+  );
+
+  // Generate and download ZIP
+  const blob = await zip.generateAsync({ type: "blob" });
+  const url = URL.createObjectURL(blob);
+
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  anchor.download = `agent-inspector-export-${new Date().toISOString().slice(0, 10)}.zip`;
+  document.body.appendChild(anchor);
+  anchor.click();
+  document.body.removeChild(anchor);
+
+  URL.revokeObjectURL(url);
+}

package/src/lib/mask.ts

@@ -0,0 +1,4 @@
+export function maskApiKey(apiKey: string): string {
+  if (apiKey.length <= 8) return "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022";
+  return apiKey.slice(0, 4) + "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022" + apiKey.slice(-4);
+}

package/src/lib/objectUtils.ts

@@ -0,0 +1,22 @@
+/**
+ * Generic object utilities shared across protocol modules.
+ * Only truly protocol-agnostic helpers belong here — Anthropic/OpenAI-specific
+ * checks stay in their respective format modules.
+ */
+
+/**
+ * Returns true if `val` is a plain object (not null, not an array).
+ */
+export function isPlainRecord(val: unknown): val is Record<string, unknown> {
+  return typeof val === "object" && val !== null && !Array.isArray(val);
+}
+
+/**
+ * Safe property access via Object.getOwnPropertyDescriptor.
+ * Returns `undefined` when obj is not an object or the property does not exist.
+ */
+export function safeGetOwnProperty(obj: unknown, key: string): unknown {
+  if (obj === null || typeof obj !== "object" || Array.isArray(obj)) return undefined;
+  const desc = Object.getOwnPropertyDescriptor(obj, key);
+  return desc?.value;
+}

package/src/lib/providerContract.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+
+/**
+ * Persisted provider shape shared by the server store and browser API clients.
+ *
+ * Keep this module free of filesystem and process-level imports so client code
+ * can validate API responses without pulling the provider store into the bundle.
+ */
+export const ProviderConfigSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  apiKey: z.string(),
+  model: z.string().optional(),
+  models: z.array(z.string()).min(1),
+  format: z.enum(["anthropic", "openai"]).optional(),
+  baseUrl: z.string().optional(),
+  anthropicBaseUrl: z.string().optional(),
+  openaiBaseUrl: z.string().optional(),
+  authHeader: z.enum(["bearer", "x-api-key"]).optional().default("bearer"),
+  apiDocsUrl: z.string().optional(),
+  source: z.enum(["company", "personal"]).optional(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+export type ProviderConfig = z.infer<typeof ProviderConfigSchema>;

package/src/lib/providerTestContract.ts

@@ -0,0 +1,107 @@
+import { z } from "zod";
+import { StreamingChunkSchema } from "../proxy/schemas";
+
+export const ProviderTestErrorTypeSchema = z.enum([
+  "timeout",
+  "network_unreachable",
+  "connection_refused",
+  "auth_failed",
+  "rate_limited",
+  "server_error",
+  "invalid_response",
+  "unknown",
+]);
+
+const ProviderTestErrorSchema = z.object({
+  message: z.string(),
+  type: ProviderTestErrorTypeSchema,
+  details: z.string().optional(),
+  hint: z.string().optional(),
+});
+
+const ProviderTestContentSchema = z.object({
+  type: z.enum(["text", "thinking"]),
+  text: z.string().optional(),
+  thinking: z.string().optional(),
+});
+
+export const ProviderTestResultSchema = z.object({
+  success: z.boolean(),
+  error: ProviderTestErrorSchema.optional(),
+  model: z.string().optional(),
+  inputTokens: z.number().optional(),
+  outputTokens: z.number().optional(),
+  cacheCreationInputTokens: z.number().optional(),
+  cacheReadInputTokens: z.number().optional(),
+  latencyMs: z.number().optional(),
+  content: z.array(ProviderTestContentSchema).optional(),
+  rawResponse: z.string().optional(),
+  streaming: z.boolean().optional(),
+  streamingChunks: z
+    .object({
+      chunks: z.array(StreamingChunkSchema),
+      truncated: z.boolean().default(false),
+    })
+    .optional(),
+  requestHeaders: z.record(z.string(), z.string()).optional(),
+});
+
+export const ProviderTestStateSchema = z.union([
+  ProviderTestResultSchema,
+  z.object({ notConfigured: z.literal(true) }),
+  z.object({ testing: z.literal(true) }),
+]);
+
+const ProviderFormatTestResultsSchema = z.object({
+  nonStreaming: ProviderTestStateSchema,
+  streaming: ProviderTestStateSchema,
+});
+
+const ModelTestResultsSchema = z.object({
+  anthropic: ProviderFormatTestResultsSchema,
+  openai: ProviderFormatTestResultsSchema,
+});
+
+export const ProviderTestResultsSchema = z.object({
+  anthropic: ProviderFormatTestResultsSchema,
+  openai: ProviderFormatTestResultsSchema,
+  models: z.record(z.string(), ModelTestResultsSchema).optional(),
+  testedAt: z.string().optional(),
+});
+
+export type ProviderTestErrorType = z.infer<typeof ProviderTestErrorTypeSchema>;
+export type ProviderTestResult = z.infer<typeof ProviderTestResultSchema>;
+export type ProviderTestState = z.infer<typeof ProviderTestStateSchema>;
+export type ProviderTestResults = z.infer<typeof ProviderTestResultsSchema>;
+export type ModelTestResults = z.infer<typeof ModelTestResultsSchema>;
+
+export function createPendingProviderTestResults(): ProviderTestResults {
+  return {
+    anthropic: {
+      nonStreaming: { testing: true },
+      streaming: { testing: true },
+    },
+    openai: {
+      nonStreaming: { testing: true },
+      streaming: { testing: true },
+    },
+  };
+}
+
+export function createFailedProviderTestResults(
+  message: string,
+  type: ProviderTestErrorType,
+): ProviderTestResults {
+  const createFormatResult = () => ({
+    nonStreaming: {
+      success: false as const,
+      error: { message, type },
+    },
+    streaming: { notConfigured: true as const },
+  });
+
+  return {
+    anthropic: createFormatResult(),
+    openai: createFormatResult(),
+  };
+}

package/src/lib/runtimeConfig.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+
+export const DEFAULT_SLOW_RESPONSE_THRESHOLD_SECONDS = 10;
+export const MAX_SLOW_RESPONSE_THRESHOLD_SECONDS = 600;
+
+/**
+ * Schema for the runtime proxy config. Shared between server
+ * (src/proxy/config.ts) and client (src/lib/useStripConfig.ts) so that
+ * the wire format is validated end-to-end with a single source of truth.
+ *
+ * Keep this file free of side effects and Node-only imports so it is
+ * safe to bundle into the client.
+ */
+export const RuntimeConfigSchema = z.object({
+  stripClaudeCodeBillingHeader: z.boolean(),
+  hasSeenOnboarding: z.boolean().default(false),
+  slowResponseThresholdSeconds: z
+    .number()
+    .int()
+    .min(0)
+    .max(MAX_SLOW_RESPONSE_THRESHOLD_SECONDS)
+    .default(DEFAULT_SLOW_RESPONSE_THRESHOLD_SECONDS),
+});
+
+export type RuntimeConfig = z.infer<typeof RuntimeConfigSchema>;

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/lib/sessionUrl.ts

@@ -0,0 +1,44 @@
+const B64URL_RE = /^[A-Za-z0-9_-]+$/;
+
+function bytesToBinary(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return binary;
+}
+
+function binaryToBytes(binary: string): Uint8Array {
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+export function encodeSessionIdForPath(sessionId: string): string {
+  const bytes = new TextEncoder().encode(sessionId);
+  const base64 = btoa(bytesToBinary(bytes));
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+export function decodeSessionIdFromPath(encoded: string): string {
+  if (encoded.startsWith("%")) {
+    return decodeURIComponent(encoded);
+  }
+  if (!B64URL_RE.test(encoded)) {
+    return encoded;
+  }
+  try {
+    const padded = encoded.padEnd(Math.ceil(encoded.length / 4) * 4, "=");
+    const base64 = padded.replace(/-/g, "+").replace(/_/g, "/");
+    const binary = atob(base64);
+    return new TextDecoder().decode(binaryToBytes(binary));
+  } catch {
+    return encoded;
+  }
+}
+
+export function getSessionPath(sessionId: string): string {
+  return `/session/${encodeSessionIdForPath(sessionId)}`;
+}

package/src/lib/stopReason.ts

@@ -0,0 +1,58 @@
+import type { CapturedLog } from "../proxy/schemas";
+
+export type StopReason = "end_turn" | "tool_use" | "stop" | null;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * 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.responseText === null) return null;
+
+  try {
+    let json: unknown = JSON.parse(log.responseText);
+    // Handle double-encoded JSON
+    if (typeof json === "string") {
+      json = JSON.parse(json);
+    }
+    if (!isRecord(json)) return null;
+
+    // Anthropic shape: { stop_reason: "end_turn" | "tool_use" | ... }
+    if (typeof json.stop_reason === "string") {
+      if (json.stop_reason === "end_turn" || json.stop_reason === "tool_use") {
+        return json.stop_reason;
+      }
+      return null;
+    }
+
+    // OpenAI shape: { choices: [{ finish_reason: "stop" | ... }] }
+    if (
+      Array.isArray(json.choices) &&
+      json.choices.length > 0 &&
+      isRecord(json.choices[0]) &&
+      typeof json.choices[0].finish_reason === "string" &&
+      json.choices[0].finish_reason === "stop"
+    ) {
+      return "stop";
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Returns true when the stop reason indicates the assistant completed its
+ * turn naturally (Anthropic end_turn or OpenAI stop).
+ */
+export function isTurnBoundary(stopReason: StopReason): boolean {
+  return stopReason === "end_turn" || stopReason === "stop";
+}

package/src/lib/useOnboarding.ts

@@ -0,0 +1,80 @@
+import useSWR, { type SWRResponse, useSWRConfig } from "swr";
+import { fetchJson } from "./apiClient";
+import {
+  DEFAULT_SLOW_RESPONSE_THRESHOLD_SECONDS,
+  RuntimeConfigSchema,
+  type RuntimeConfig,
+} from "./runtimeConfig";
+
+export const ONBOARDING_SWR_KEY = "/api/config";
+
+async function fetcher(url: string): Promise<RuntimeConfig> {
+  return fetchJson(
+    url,
+    RuntimeConfigSchema,
+    undefined,
+    (response) => `Failed to fetch ${url}: ${response.status}`,
+  );
+}
+
+async function patchRuntimeConfig(patch: Partial<RuntimeConfig>): Promise<RuntimeConfig> {
+  return fetchJson(
+    ONBOARDING_SWR_KEY,
+    RuntimeConfigSchema,
+    {
+      method: "PATCH",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(patch),
+    },
+    (response) => `PATCH failed with status ${response.status}`,
+  );
+}
+
+export type UseOnboarding = {
+  hasSeenOnboarding: boolean;
+  isLoading: boolean;
+  markSeen: () => Promise<void>;
+};
+
+/**
+ * Hook for the first-launch onboarding banner. The server's
+ * `hasSeenOnboarding` flag is the source of truth — set to `true` on
+ * dismissal and persisted in the server config file so it survives
+ * across browser sessions.
+ *
+ * `hasSeenOnboarding` defaults to `false` until the SWR fetch resolves,
+ * which means the banner shows briefly on first load. That is
+ * acceptable: the fetch is local and resolves within milliseconds.
+ */
+export function useOnboarding(): UseOnboarding {
+  const response: SWRResponse<RuntimeConfig, Error> = useSWR<RuntimeConfig, Error>(
+    ONBOARDING_SWR_KEY,
+    fetcher,
+    {
+      revalidateOnFocus: false,
+      revalidateIfStale: false,
+    },
+  );
+  const { mutate: globalMutate } = useSWRConfig();
+
+  const hasSeenOnboarding = response.data?.hasSeenOnboarding ?? false;
+
+  const markSeen = async (): Promise<void> => {
+    await globalMutate(ONBOARDING_SWR_KEY, patchRuntimeConfig({ hasSeenOnboarding: true }), {
+      optimisticData: {
+        stripClaudeCodeBillingHeader: response.data?.stripClaudeCodeBillingHeader ?? false,
+        hasSeenOnboarding: true,
+        slowResponseThresholdSeconds:
+          response.data?.slowResponseThresholdSeconds ?? DEFAULT_SLOW_RESPONSE_THRESHOLD_SECONDS,
+      },
+      rollbackOnError: true,
+      revalidate: false,
+    });
+  };
+
+  return {
+    hasSeenOnboarding,
+    isLoading: response.isLoading,
+    markSeen,
+  };
+}