@tonyclaw/agent-inspector 2.1.2 → 2.1.4

package/src/lib/alertContract.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+import { JsonValueSchema } from "../contracts";
+
+export const AlertSeveritySchema = z.enum(["critical", "warning", "notice"]);
+export const AlertStatusSchema = z.enum(["open"]);
+export const AlertSourceSchema = z.enum(["proxy", "tool-schema", "run", "group"]);
+export const AlertCategorySchema = z.enum([
+  "request-failure",
+  "request-timeout",
+  "slow-response",
+  "tool-schema",
+  "run-failure",
+  "group-failure",
+  "group-incomplete",
+]);
+export const AlertEvidenceKindSchema = z.enum(["log", "session", "run", "group"]);
+export const AlertApiFormatSchema = z.enum(["anthropic", "openai", "unknown"]);
+
+export const AlertEvidenceLinkSchema = z.object({
+  kind: AlertEvidenceKindSchema,
+  id: z.string(),
+  label: z.string(),
+  href: z.string().nullable(),
+});
+
+export const AlertSchema = z.object({
+  id: z.string(),
+  fingerprint: z.string(),
+  severity: AlertSeveritySchema,
+  category: AlertCategorySchema,
+  source: AlertSourceSchema,
+  status: AlertStatusSchema,
+  title: z.string(),
+  message: z.string(),
+  count: z.number().int().positive(),
+  firstSeenAt: z.string(),
+  lastSeenAt: z.string(),
+  logIds: z.array(z.number().int().positive()),
+  sessionIds: z.array(z.string()),
+  runIds: z.array(z.string()),
+  groupIds: z.array(z.string()),
+  provider: z.string().nullable(),
+  model: z.string().nullable(),
+  apiFormat: AlertApiFormatSchema.nullable(),
+  evidence: z.array(AlertEvidenceLinkSchema),
+  metadata: z.record(z.string(), JsonValueSchema),
+});
+
+export const AlertCategoryCountSchema = z.object({
+  category: AlertCategorySchema,
+  count: z.number().int().nonnegative(),
+});
+
+export const AlertSummarySchema = z.object({
+  total: z.number().int().nonnegative(),
+  open: z.number().int().nonnegative(),
+  critical: z.number().int().nonnegative(),
+  warning: z.number().int().nonnegative(),
+  notice: z.number().int().nonnegative(),
+  byCategory: z.array(AlertCategoryCountSchema),
+});
+
+export const AlertListResponseSchema = z.object({
+  alerts: z.array(AlertSchema),
+  total: z.number().int().nonnegative(),
+  limit: z.number().int().positive(),
+  summary: AlertSummarySchema,
+});
+
+export type AlertSeverity = z.infer<typeof AlertSeveritySchema>;
+export type AlertStatus = z.infer<typeof AlertStatusSchema>;
+export type AlertSource = z.infer<typeof AlertSourceSchema>;
+export type AlertCategory = z.infer<typeof AlertCategorySchema>;
+export type AlertEvidenceKind = z.infer<typeof AlertEvidenceKindSchema>;
+export type AlertEvidenceLink = z.infer<typeof AlertEvidenceLinkSchema>;
+export type Alert = z.infer<typeof AlertSchema>;
+export type AlertCategoryCount = z.infer<typeof AlertCategoryCountSchema>;
+export type AlertSummary = z.infer<typeof AlertSummarySchema>;
+export type AlertListResponse = z.infer<typeof AlertListResponseSchema>;

package/src/lib/apiClient.ts

@@ -47,3 +47,42 @@ export async function fetchJson<T>(
   }
   return parseJsonResponse(response, schema);
 }
+
+function formatTimeout(timeoutMs: number): string {
+  if (timeoutMs < 1000) return `${String(timeoutMs)}ms`;
+  return `${String(Math.round(timeoutMs / 1000))}s`;
+}
+
+export class ApiTimeoutError extends Error {
+  constructor(timeoutMs: number) {
+    super(`Request timed out after ${formatTimeout(timeoutMs)}`);
+    this.name = "ApiTimeoutError";
+  }
+}
+
+/**
+ * Fetch a JSON resource with a browser-side timeout. This prevents UI loading
+ * states from waiting forever when a tab keeps a stale connection across a
+ * local server force-restart.
+ */
+export async function fetchJsonWithTimeout<T>(
+  input: RequestInfo | URL,
+  schema: z.ZodType<T>,
+  timeoutMs: number,
+  init?: RequestInit,
+  errorFallback?: (response: Response) => string,
+): Promise<T> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    return await fetchJson(input, schema, { ...init, signal: controller.signal }, errorFallback);
+  } catch (error) {
+    if (error instanceof DOMException && error.name === "AbortError") {
+      throw new ApiTimeoutError(timeoutMs);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/src/lib/export-logs.ts

@@ -1,5 +1,6 @@
 import JSZip from "jszip";
 import type { CapturedLog } from "../contracts";
+import packageJson from "../../package.json";
 
 export type ExportMode = "redacted" | "raw";
 export type ExportLogsResult =
@@ -23,6 +24,17 @@ const MAX_EXPORT_LOGS = 200;
 const MAX_EXPORT_TEXT_CHARS = 25_000_000;
 const MAX_STREAMING_CHUNK_EXPORTS = 50;
 
+export type ExportManifest = {
+  version: string;
+  exportedAt: string;
+  mode: ExportMode;
+  redacted: boolean;
+  logCount: number;
+  logIds: number[];
+  streamingChunkExportLimit: number;
+  streamingChunkLogIds: number[];
+};
+
 function formatApproxSize(chars: number): string {
   if (chars < 1024) return `${chars} chars`;
   if (chars < 1024 * 1024) return `${Math.ceil(chars / 1024)} KB`;
@@ -100,6 +112,36 @@ function exportText(text: string, mode: ExportMode): string {
   return mode === "redacted" ? redactJsonText(text) : text;
 }
 
+export function buildExportLogMetadata(log: CapturedLog, mode: ExportMode): CapturedLog {
+  return {
+    ...log,
+    rawRequestBody: null,
+    responseText: null,
+    rawHeaders: mode === "raw" ? log.rawHeaders : undefined,
+    headers: mode === "raw" ? log.headers : undefined,
+    streamingChunks: undefined,
+    bodyContentMode: "compact",
+  };
+}
+
+export function buildExportManifest(
+  logs: readonly CapturedLog[],
+  mode: ExportMode,
+  streamingLogs: readonly CapturedLog[],
+  exportedAt: string = new Date().toISOString(),
+): ExportManifest {
+  return {
+    version: packageJson.version,
+    exportedAt,
+    mode,
+    redacted: mode === "redacted",
+    logCount: logs.length,
+    logIds: logs.map((log) => log.id),
+    streamingChunkExportLimit: MAX_STREAMING_CHUNK_EXPORTS,
+    streamingChunkLogIds: streamingLogs.map((log) => log.id),
+  };
+}
+
 export async function exportLogsAsZip(
   logs: CapturedLog[],
   mode: ExportMode = "redacted",
@@ -112,16 +154,12 @@ export async function exportLogsAsZip(
   const streamingLogs = logs.filter((log) => log.streaming).slice(0, MAX_STREAMING_CHUNK_EXPORTS);
   zip.file(
     "manifest.json",
+    JSON.stringify(buildExportManifest(logs, mode, streamingLogs), null, 2),
+  );
+  zip.file(
+    "logs.json",
     JSON.stringify(
-      {
-        exportedAt: new Date().toISOString(),
-        mode,
-        redacted: mode === "redacted",
-        logCount: logs.length,
-        logIds: logs.map((log) => log.id),
-        streamingChunkExportLimit: MAX_STREAMING_CHUNK_EXPORTS,
-        streamingChunkLogIds: streamingLogs.map((log) => log.id),
-      },
+      logs.map((log) => buildExportLogMetadata(log, mode)),
       null,
       2,
     ),

package/src/lib/logImportContract.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { CapturedLogSchema } from "../contracts";
+
+export const ImportLogsResponseSchema = z.object({
+  sessionId: z.string(),
+  imported: z.number().int().nonnegative(),
+  skipped: z.number().int().nonnegative(),
+  warnings: z.array(z.string()),
+  logs: z.array(CapturedLogSchema),
+});
+
+export type ImportLogsResponse = z.infer<typeof ImportLogsResponseSchema>;

package/src/lib/useAlerts.ts

@@ -0,0 +1,82 @@
+import useSWR, { type SWRResponse } from "swr";
+import {
+  AlertListResponseSchema,
+  AlertSummarySchema,
+  type AlertCategory,
+  type AlertListResponse,
+  type AlertSeverity,
+  type AlertSource,
+  type AlertSummary,
+} from "./alertContract";
+import { fetchJsonWithTimeout } from "./apiClient";
+
+const ALERT_SUMMARY_FETCH_TIMEOUT_MS = 8_000;
+const ALERT_LIST_FETCH_TIMEOUT_MS = 10_000;
+
+export type AlertListFilters = {
+  severity?: AlertSeverity;
+  category?: AlertCategory;
+  source?: AlertSource;
+  limit?: number;
+};
+
+type UseAlertsResult = {
+  alerts: AlertListResponse["alerts"];
+  total: number;
+  summary: AlertSummary | null;
+  isLoading: boolean;
+  error: Error | undefined;
+  mutate: SWRResponse<AlertListResponse, Error>["mutate"];
+};
+
+type UseAlertSummaryResult = {
+  summary: AlertSummary | null;
+  isLoading: boolean;
+  error: Error | undefined;
+  mutate: SWRResponse<AlertSummary, Error>["mutate"];
+};
+
+function alertsPath(filters: AlertListFilters): string {
+  const params = new URLSearchParams();
+  if (filters.severity !== undefined) params.set("severity", filters.severity);
+  if (filters.category !== undefined) params.set("category", filters.category);
+  if (filters.source !== undefined) params.set("source", filters.source);
+  if (filters.limit !== undefined) params.set("limit", String(filters.limit));
+  const query = params.toString();
+  return query.length > 0 ? `/api/alerts?${query}` : "/api/alerts";
+}
+
+export function useAlerts(filters: AlertListFilters, enabled: boolean): UseAlertsResult {
+  const response: SWRResponse<AlertListResponse, Error> = useSWR<AlertListResponse, Error>(
+    enabled ? alertsPath(filters) : null,
+    (url: string) =>
+      fetchJsonWithTimeout(url, AlertListResponseSchema, ALERT_LIST_FETCH_TIMEOUT_MS),
+  );
+
+  return {
+    alerts: response.data?.alerts ?? [],
+    total: response.data?.total ?? 0,
+    summary: response.data?.summary ?? null,
+    isLoading: response.isLoading,
+    error: response.error,
+    mutate: response.mutate,
+  };
+}
+
+export function useAlertSummary(): UseAlertSummaryResult {
+  const response: SWRResponse<AlertSummary, Error> = useSWR<AlertSummary, Error>(
+    "/api/alerts/summary",
+    (url: string) => fetchJsonWithTimeout(url, AlertSummarySchema, ALERT_SUMMARY_FETCH_TIMEOUT_MS),
+    {
+      refreshInterval: 5_000,
+      revalidateOnFocus: true,
+    },
+  );
+
+  return {
+    summary: response.data ?? null,
+    isLoading: response.isLoading,
+    error: response.error,
+    mutate: response.mutate,
+  };
+}

package/src/lib/useGroupEvidence.ts

@@ -4,7 +4,9 @@ import {
   type GroupEvidenceReadResponse,
   type InspectorGroup,
 } from "./groupContract";
-import { fetchJson } from "./apiClient";
+import { fetchJsonWithTimeout } from "./apiClient";
+
+const GROUP_EVIDENCE_FETCH_TIMEOUT_MS = 12_000;
 
 type UseGroupEvidenceResult = {
   evidenceResponse: GroupEvidenceReadResponse | null;
@@ -22,7 +24,9 @@ export function useGroupEvidence(group: InspectorGroup | null): UseGroupEvidence
   const response: SWRResponse<GroupEvidenceReadResponse, Error> = useSWR<
     GroupEvidenceReadResponse,
     Error
-  >(evidenceKey(group), (url: string) => fetchJson(url, GroupEvidenceReadResponseSchema));
+  >(evidenceKey(group), (url: string) =>
+    fetchJsonWithTimeout(url, GroupEvidenceReadResponseSchema, GROUP_EVIDENCE_FETCH_TIMEOUT_MS),
+  );
 
   return {
     evidenceResponse: response.data ?? null,

package/src/lib/useGroups.ts

@@ -4,7 +4,9 @@ import {
   type InspectorGroup,
   type InspectorGroupsListResponse,
 } from "./groupContract";
-import { fetchJson } from "./apiClient";
+import { fetchJsonWithTimeout } from "./apiClient";
+
+const GROUPS_FETCH_TIMEOUT_MS = 8_000;
 
 type UseGroupsResult = {
   groups: InspectorGroup[];
@@ -17,7 +19,9 @@ export function useGroups(): UseGroupsResult {
   const response: SWRResponse<InspectorGroupsListResponse, Error> = useSWR<
     InspectorGroupsListResponse,
     Error
-  >("/api/groups", (url: string) => fetchJson(url, InspectorGroupsListResponseSchema));
+  >("/api/groups", (url: string) =>
+    fetchJsonWithTimeout(url, InspectorGroupsListResponseSchema, GROUPS_FETCH_TIMEOUT_MS),
+  );
 
   return {
     groups: response.data?.groups ?? [],