@tonyclaw/agent-inspector 3.0.27 → 3.0.28

package/src/components/proxy-viewer/ConversationHeader.tsx

@@ -24,6 +24,22 @@ import { resolveLogFormat } from "./log-formats";
 const HEADER_ACTION_BUTTON_CLASS =
   "bg-white/[0.045] hover:bg-white/[0.075] inline-flex size-8 shrink-0 cursor-pointer items-center justify-center rounded-md text-muted-foreground transition-colors hover:text-foreground";
 
+export function isSyntheticSessionId(conversationId: string): boolean {
+  return (
+    conversationId.startsWith("PID:") ||
+    conversationId.startsWith("process:") ||
+    conversationId.startsWith("connection:") ||
+    conversationId.includes("|")
+  );
+}
+
+export function compactSessionLabel(conversationId: string): string {
+  if (isSyntheticSessionId(conversationId)) return "Sessionless";
+  return conversationId.length > 24
+    ? `${conversationId.slice(0, 12)}...${conversationId.slice(-12)}`
+    : conversationId;
+}
+
 function HeaderMetric({
   icon,
   children,
@@ -52,7 +68,7 @@ function HeaderMetric({
 function PendingTurnBadge(): JSX.Element {
   return (
     <span
-      className="inline-flex h-6 shrink-0 items-center gap-1.5 rounded-md bg-amber-300/[0.10] px-1.5 font-mono text-[10px] uppercase tracking-[0.14em] text-amber-100/90 ring-1 ring-amber-200/10"
+      className="inline-flex h-6 shrink-0 items-center gap-1.5 rounded-md bg-amber-300/[0.10] px-1.5 font-mono text-[10px] uppercase text-amber-100/90 ring-1 ring-amber-200/10"
       title="This session has a turn that has not finished yet"
     >
       <Loader2 className="size-3 animate-spin" />
@@ -145,11 +161,8 @@ export function ConversationHeader({
   const clientDisplayLabel = detectedClientLabel ?? userAgent ?? null;
   const clientTooltip =
     detectedClientLabel !== null && hasUserAgent ? `${detectedClientLabel} - ${userAgent}` : null;
-  const isFallbackConversation = conversationId.startsWith("PID:") || conversationId.includes("|");
-  const compactSessionLabel =
-    conversationId.length > 24
-      ? conversationId.slice(0, 12) + "..." + conversationId.slice(-12)
-      : conversationId;
+  const isFallbackConversation = isSyntheticSessionId(conversationId);
+  const sessionLabel = compactSessionLabel(conversationId);
 
   const timeLabel = formatTimestampRange(startTime, endTime, timeDisplayFormat);
   const callsLabel = `${totalCalls} call${totalCalls !== 1 ? "s" : ""}`;
@@ -161,8 +174,8 @@ export function ConversationHeader({
       data-nav-id={`conv-${conversationId}`}
       data-nav-action={expanded ? "collapse" : "expand"}
       className={cn(
-        "bg-card/80 shadow-sm relative flex cursor-pointer items-start gap-3 overflow-hidden rounded-[8px] px-3 py-2.5 transition-colors",
-        "hover:bg-card",
+        "bg-black/[0.10] relative flex cursor-pointer items-start gap-2.5 overflow-hidden rounded-[8px] px-3 py-2.5 transition-colors",
+        "hover:bg-black/[0.16]",
         "select-none",
         "sticky top-0 z-10 mb-2",
         "focus-visible:ring-1 focus-visible:ring-cyan-300/35 focus-visible:outline-none",
@@ -185,17 +198,20 @@ export function ConversationHeader({
 
       <span className="min-w-0 flex-1">
         <span className="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1">
+          <span className="shrink-0 rounded bg-white/[0.04] px-1.5 py-0.5 font-mono text-[9px] uppercase text-muted-foreground/70">
+            Session
+          </span>
           {isFallbackConversation && showProcessMetadata ? (
             clientPid !== null && clientPid !== undefined ? (
               <span
-                className="min-w-0 max-w-full truncate font-mono text-xs font-semibold text-violet-200"
+                className="min-w-0 max-w-full truncate font-mono text-xs font-semibold text-slate-100"
                 title={`PID ${clientPid}`}
               >
                 PID {clientPid}
               </span>
             ) : (
               <span
-                className="min-w-0 max-w-full truncate font-mono text-xs font-semibold text-violet-200"
+                className="min-w-0 max-w-full truncate font-mono text-xs font-semibold text-slate-100"
                 title={conversationId}
               >
                 {conversationId}
@@ -203,10 +219,10 @@ export function ConversationHeader({
             )
           ) : (
             <span
-              className="min-w-0 max-w-full truncate font-mono text-xs font-semibold text-violet-200"
+              className="min-w-0 max-w-full truncate font-mono text-xs font-semibold text-slate-100"
               title={conversationId}
             >
-              {isFallbackConversation ? "sessionless" : compactSessionLabel}
+              {sessionLabel}
             </span>
           )}
 
@@ -240,7 +256,7 @@ export function ConversationHeader({
               className="bg-white/[0.045] inline-flex min-h-6 shrink-0 flex-wrap items-center gap-1 rounded-md px-1.5 py-0.5 text-xs text-muted-foreground"
               title={clientTooltip ?? clientDisplayLabel}
             >
-              <ClientLogo client={clientApp} className="size-4 shrink-0" />
+              <ClientLogo client={clientApp} className="size-4 shrink-0" decorative={true} />
               <span className="font-mono leading-snug tabular-nums">{clientDisplayLabel}</span>
             </span>
           )}

package/src/lib/jsonFile.ts

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import { readProperty } from "./unknown";
+
+/**
+ * Reads a UTF-8 JSON file from disk and validates it against a Zod schema in
+ * one call. Used by config/secret/evidence files that store small records
+ * atomically rewritten on update — *not* for streaming log files (those go
+ * through line-by-line parsing in store.ts).
+ *
+ * On any failure returns `{ ok: false, reason }` rather than throwing. The
+ * caller decides between returning a fallback, logging, or surfacing an
+ * error response. To log on failure, wrap the call site with the project's
+ * `logger.warn` (the helper stays a pure parser to avoid a `lib → proxy`
+ * dependency direction).
+ */
+export type ReadJsonFileFailureReason = "missing" | "io-error" | "parse-error" | "schema-mismatch";
+
+export type ReadJsonFileResult<T> =
+  | { ok: true; data: T }
+  | { ok: false; reason: ReadJsonFileFailureReason };
+
+export function readJsonFile<T>(path: string, schema: z.ZodType<T>): ReadJsonFileResult<T> {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (error) {
+    if (isEnoent(error)) return { ok: false, reason: "missing" };
+    return { ok: false, reason: "io-error" };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { ok: false, reason: "parse-error" };
+  }
+
+  const result = schema.safeParse(parsed);
+  if (!result.success) return { ok: false, reason: "schema-mismatch" };
+  return { ok: true, data: result.data };
+}
+
+function isEnoent(error: unknown): boolean {
+  return readProperty(error, "code") === "ENOENT";
+}

package/src/proxy/evidenceAnalysis.ts

@@ -96,86 +96,113 @@ function hasStreamingMismatch(session: SessionInfo): boolean {
   return false;
 }
 
-function categorySummary(category: FailureCategory): string {
-  switch (category) {
-    case "none":
-      return "Session completed without captured errors.";
-    case "active":
-      return "Session still has active requests or running tasks.";
-    case "provider-timeout":
-      return "Provider call appears to have timed out.";
-    case "provider-http-error":
-      return "Provider returned an HTTP error.";
-    case "provider-auth-error":
-      return "Provider authentication or API key configuration appears invalid.";
-    case "provider-rate-limit":
-      return "Provider rejected the request because of rate limit or quota pressure.";
-    case "network-or-container":
-      return "Network connectivity looks suspicious; check container boundaries and localhost use.";
-    case "streaming-mismatch":
-      return "Streaming and non-streaming behavior differ for the same provider/model.";
-    case "context-pressure":
-      return "The failure looks related to context window or token pressure.";
-    case "runtime-task-error":
-      return "Inspector session runtime reported a task error.";
-    case "model-output-error":
-      return "The model output or upstream payload shape appears invalid.";
-    case "unknown-failure":
-      return "Inspector captured errors, but the root cause is not yet classified.";
-    case "no-session-data":
-      return "No Inspector session data was available for this run.";
-  }
-}
-
-function categoryHints(category: FailureCategory): string[] {
-  switch (category) {
-    case "none":
-      return ["Keep the evidence pack as the success proof for CI or release notes."];
-    case "active":
-      return ["Wait for the session to settle, then export evidence again."];
-    case "provider-timeout":
-      return [
-        "Increase the provider test timeout for slow models.",
-        "Compare streaming and non-streaming probes for the same model.",
-      ];
-    case "provider-http-error":
-      return [
-        "Open the cited log ids and inspect upstream status, response body, and provider URL.",
-      ];
-    case "provider-auth-error":
-      return ["Verify the provider API key, auth header mode, and configured base URL."];
-    case "provider-rate-limit":
-      return [
-        "Retry after provider quota recovers or switch to a less constrained provider/model.",
-      ];
-    case "network-or-container":
-      return [
-        "If the coding agent and Inspector are in different containers, replace localhost with a reachable host.",
-        "Check DNS, proxy, firewall, and container network routes.",
-      ];
-    case "streaming-mismatch":
-      return [
-        "Compare the streaming and non-streaming captured logs side by side.",
-        "Check whether the provider's OpenAI-compatible endpoint handles stream=false differently.",
-      ];
-    case "context-pressure":
-      return [
-        "Reduce prompt/tool schema/history size or configure the model context window metadata.",
-      ];
-    case "runtime-task-error":
-      return ["Inspect the session runtime error and retry after clearing stuck session tasks."];
-    case "model-output-error":
-      return ["Inspect the raw response and schema parsing details for the cited log ids."];
-    case "unknown-failure":
-      return [
-        "Open the cited logs and inspect error/status/latency fields to refine the diagnosis.",
-      ];
-    case "no-session-data":
-      return [
-        "Confirm the run's sessionId matches captured traffic and that history scanning is enabled when needed.",
-      ];
+/**
+ * Per-category summary, hints, severity, and outcome. Keyed by every
+ * `FailureCategory` so TypeScript's `Record` enforces exhaustiveness —
+ * adding a new category is a single-place compile error instead of four
+ * parallel switch statements missing a case.
+ */
+const FAILURE_CATEGORY_INFO: Record<
+  FailureCategory,
+  {
+    summary: string;
+    hints: string[];
+    severity: FailureClassification["severity"];
+    outcome: FailureClassification["outcome"];
   }
-}
+> = {
+  none: {
+    summary: "Session completed without captured errors.",
+    hints: ["Keep the evidence pack as the success proof for CI or release notes."],
+    severity: "none",
+    outcome: "success",
+  },
+  active: {
+    summary: "Session still has active requests or running tasks.",
+    hints: ["Wait for the session to settle, then export evidence again."],
+    severity: "low",
+    outcome: "active",
+  },
+  "provider-timeout": {
+    summary: "Provider call appears to have timed out.",
+    hints: [
+      "Increase the provider test timeout for slow models.",
+      "Compare streaming and non-streaming probes for the same model.",
+    ],
+    severity: "high",
+    outcome: "failure",
+  },
+  "provider-http-error": {
+    summary: "Provider returned an HTTP error.",
+    hints: ["Open the cited log ids and inspect upstream status, response body, and provider URL."],
+    severity: "high",
+    outcome: "failure",
+  },
+  "provider-auth-error": {
+    summary: "Provider authentication or API key configuration appears invalid.",
+    hints: ["Verify the provider API key, auth header mode, and configured base URL."],
+    severity: "high",
+    outcome: "failure",
+  },
+  "provider-rate-limit": {
+    summary: "Provider rejected the request because of rate limit or quota pressure.",
+    hints: ["Retry after provider quota recovers or switch to a less constrained provider/model."],
+    severity: "high",
+    outcome: "failure",
+  },
+  "network-or-container": {
+    summary: "Network connectivity looks suspicious; check container boundaries and localhost use.",
+    hints: [
+      "If the coding agent and Inspector are in different containers, replace localhost with a reachable host.",
+      "Check DNS, proxy, firewall, and container network routes.",
+    ],
+    severity: "high",
+    outcome: "failure",
+  },
+  "streaming-mismatch": {
+    summary: "Streaming and non-streaming behavior differ for the same provider/model.",
+    hints: [
+      "Compare the streaming and non-streaming captured logs side by side.",
+      "Check whether the provider's OpenAI-compatible endpoint handles stream=false differently.",
+    ],
+    severity: "high",
+    outcome: "failure",
+  },
+  "context-pressure": {
+    summary: "The failure looks related to context window or token pressure.",
+    hints: [
+      "Reduce prompt/tool schema/history size or configure the model context window metadata.",
+    ],
+    severity: "medium",
+    outcome: "failure",
+  },
+  "runtime-task-error": {
+    summary: "Inspector session runtime reported a task error.",
+    hints: ["Inspect the session runtime error and retry after clearing stuck session tasks."],
+    severity: "high",
+    outcome: "failure",
+  },
+  "model-output-error": {
+    summary: "The model output or upstream payload shape appears invalid.",
+    hints: ["Inspect the raw response and schema parsing details for the cited log ids."],
+    severity: "medium",
+    outcome: "failure",
+  },
+  "unknown-failure": {
+    summary: "Inspector captured errors, but the root cause is not yet classified.",
+    hints: ["Open the cited logs and inspect error/status/latency fields to refine the diagnosis."],
+    severity: "medium",
+    outcome: "failure",
+  },
+  "no-session-data": {
+    summary: "No Inspector session data was available for this run.",
+    hints: [
+      "Confirm the run's sessionId matches captured traffic and that history scanning is enabled when needed.",
+    ],
+    severity: "medium",
+    outcome: "unknown",
+  },
+};
 
 function classifyCategory(
   session: SessionInfo,
@@ -221,47 +248,19 @@ function classifyCategory(
 }
 
 function severityFor(category: FailureCategory): FailureClassification["severity"] {
-  switch (category) {
-    case "none":
-      return "none";
-    case "active":
-      return "low";
-    case "provider-timeout":
-    case "provider-http-error":
-    case "provider-auth-error":
-    case "provider-rate-limit":
-    case "network-or-container":
-    case "streaming-mismatch":
-    case "runtime-task-error":
-      return "high";
-    case "context-pressure":
-    case "model-output-error":
-    case "unknown-failure":
-    case "no-session-data":
-      return "medium";
-  }
+  return FAILURE_CATEGORY_INFO[category].severity;
 }
 
 function outcomeFor(category: FailureCategory): FailureClassification["outcome"] {
-  switch (category) {
-    case "none":
-      return "success";
-    case "active":
-      return "active";
-    case "no-session-data":
-      return "unknown";
-    case "provider-timeout":
-    case "provider-http-error":
-    case "provider-auth-error":
-    case "provider-rate-limit":
-    case "network-or-container":
-    case "streaming-mismatch":
-    case "context-pressure":
-    case "runtime-task-error":
-    case "model-output-error":
-    case "unknown-failure":
-      return "failure";
-  }
+  return FAILURE_CATEGORY_INFO[category].outcome;
+}
+
+function categorySummary(category: FailureCategory): string {
+  return FAILURE_CATEGORY_INFO[category].summary;
+}
+
+function categoryHints(category: FailureCategory): string[] {
+  return FAILURE_CATEGORY_INFO[category].hints;
 }
 
 export function classifyRunFailure(

package/src/proxy/groupEvidenceExporter.ts

@@ -15,6 +15,7 @@ import { getDataDir } from "./dataDir";
 import { getRun } from "./runStore";
 import { getSessionInfo } from "./store";
 import { updateGroupEvidence } from "./groupStore";
+import { readJsonFile } from "../lib/jsonFile";
 
 type GroupEvidenceDocument = GroupEvidenceExportResult;
 
@@ -343,12 +344,7 @@ export function readGroupEvidenceMarkdown(group: InspectorGroup): string | null
 
 export function readGroupEvidenceDocument(group: InspectorGroup): GroupEvidenceExportResult | null {
   const path = group.evidence?.jsonPath;
-  if (path === undefined || !existsSync(path)) return null;
-  try {
-    const raw: unknown = JSON.parse(readFileSync(path, "utf8"));
-    const parsed = GroupEvidenceExportResultSchema.safeParse(raw);
-    return parsed.success ? parsed.data : null;
-  } catch {
-    return null;
-  }
+  if (path === undefined) return null;
+  const result = readJsonFile(path, GroupEvidenceExportResultSchema);
+  return result.ok ? result.data : null;
 }

package/src/proxy/groupStore.ts

@@ -19,6 +19,7 @@ import {
   type UpdateInspectorGroupInput,
 } from "../lib/groupContract";
 import { getDataDir } from "./dataDir";
+import { readJsonFile } from "../lib/jsonFile";
 
 const GroupsFileSchema = z.object({
   groups: z.array(InspectorGroupSchema),
@@ -70,16 +71,8 @@ function nullableText(value: string | null | undefined): string | null {
 }
 
 function readGroups(): InspectorGroup[] {
-  const filePath = groupsFilePath();
-  if (!existsSync(filePath)) return [];
-
-  try {
-    const parsed: unknown = JSON.parse(readFileSync(filePath, "utf8"));
-    const result = GroupsFileSchema.safeParse(parsed);
-    return result.success ? result.data.groups : [];
-  } catch {
-    return [];
-  }
+  const result = readJsonFile(groupsFilePath(), GroupsFileSchema);
+  return result.ok ? result.data.groups : [];
 }
 
 function writeGroups(groups: readonly InspectorGroup[]): void {

package/src/proxy/providerSecretStore.ts

@@ -11,6 +11,7 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
+import { readJsonFile } from "../lib/jsonFile";
 import { logger } from "./logger";
 
 const SECRET_REFERENCE_PREFIX = "secret:provider:";
@@ -39,14 +40,9 @@ function emptySecretFile(): SecretFile {
 
 function readSecretFile(path: string): SecretFile {
   if (!existsSync(path)) return emptySecretFile();
-  try {
-    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
-    const result = SecretFileSchema.safeParse(parsed);
-    if (result.success) return result.data;
-    logger.warn(`[provider-secrets] Ignoring invalid secret file ${path}`);
-  } catch (error) {
-    logger.warn(`[provider-secrets] Could not read ${path}: ${String(error)}`);
-  }
+  const result = readJsonFile(path, SecretFileSchema);
+  if (result.ok) return result.data;
+  logger.warn(`[provider-secrets] Ignoring invalid secret file ${path} (${result.reason})`);
   return emptySecretFile();
 }
 

package/src/proxy/runFailures.ts

@@ -1,4 +1,3 @@
-import { existsSync, readFileSync } from "node:fs";
 import {
   EvidenceExportResultSchema,
   type EvidenceExportResult,
@@ -9,6 +8,7 @@ import {
   type RecentFailure,
   type RecentFailuresResponse,
 } from "../lib/runContract";
+import { readJsonFile } from "../lib/jsonFile";
 import { listRuns } from "./runStore";
 
 export const RECENT_FAILURES_DEFAULT_LIMIT = 5;
@@ -21,15 +21,9 @@ export function clampRecentFailuresLimit(value: number): number {
 
 function readEvidenceDocument(run: InspectorRun): EvidenceExportResult | null {
   const path = run.evidence?.jsonPath;
-  if (path === undefined || !existsSync(path)) return null;
-
-  try {
-    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
-    const result = EvidenceExportResultSchema.safeParse(parsed);
-    return result.success ? result.data : null;
-  } catch {
-    return null;
-  }
+  if (path === undefined) return null;
+  const result = readJsonFile(path, EvidenceExportResultSchema);
+  return result.ok ? result.data : null;
 }
 
 function syntheticFailedClassification(run: InspectorRun): FailureClassification {

package/src/proxy/runStore.ts

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { dirname, join } from "node:path";
 import { z } from "zod";
@@ -13,6 +13,7 @@ import {
 } from "../lib/runContract";
 import { getDataDir } from "./dataDir";
 import { addGroupSession, getGroup } from "./groupStore";
+import { readJsonFile } from "../lib/jsonFile";
 
 const RunsFileSchema = z.object({
   runs: z.array(InspectorRunSchema),
@@ -95,16 +96,8 @@ function syncRunGroupMember(run: InspectorRun, createIfMissing: boolean): void {
 }
 
 function readRuns(): InspectorRun[] {
-  const filePath = runsFilePath();
-  if (!existsSync(filePath)) return [];
-
-  try {
-    const parsed: unknown = JSON.parse(readFileSync(filePath, "utf8"));
-    const result = RunsFileSchema.safeParse(parsed);
-    return result.success ? result.data.runs : [];
-  } catch {
-    return [];
-  }
+  const result = readJsonFile(runsFilePath(), RunsFileSchema);
+  return result.ok ? result.data.runs : [];
 }
 
 function writeRuns(runs: readonly InspectorRun[]): void {