@tonyclaw/agent-inspector 3.0.26 → 3.0.28

package/src/mcp/server.ts

@@ -1262,15 +1262,10 @@ function registerTools(server: McpServer): void {
     {
       title: "List configured LLM providers",
       description:
-        "Returns the configured ProviderConfig array with apiKey redacted by default. Set includeSecrets=true only when the user explicitly needs plaintext local provider keys; this exposes secrets from <dataDir>/providers.json.",
-      inputSchema: z.object({
-        includeSecrets: z
-          .boolean()
-          .optional()
-          .describe("Return plaintext provider API keys. Exposes local secrets when true."),
-      }),
+        "Returns the configured ProviderConfig array with write-only API keys represented as configured.",
+      inputSchema: z.object({}),
     },
-    (args) => safeCall(() => listProvidersImpl(callApi, args)),
+    () => safeCall(() => listProvidersImpl(callApi)),
   );
 
   // ----- Action tools -----
@@ -1280,16 +1275,12 @@ function registerTools(server: McpServer): void {
     {
       title: "Get a single provider by id",
       description:
-        "Returns one ProviderConfig with apiKey redacted by default. Set includeSecrets=true only when the user explicitly needs the plaintext local provider key.",
+        "Returns one ProviderConfig. API keys are write-only and represented as configured.",
       inputSchema: z.object({
         id: z.string().describe("The provider id."),
-        includeSecrets: z
-          .boolean()
-          .optional()
-          .describe("Return the plaintext provider API key. Exposes a local secret when true."),
       }),
     },
-    ({ id, includeSecrets }) => safeCall(() => getProviderImpl(callApi, id, { includeSecrets })),
+    ({ id }) => safeCall(() => getProviderImpl(callApi, id)),
   );
 
   server.registerTool(

package/src/mcp/toolHandlers.ts

@@ -36,6 +36,7 @@ import {
 } from "../lib/groupContract";
 import { type CreateInspectorRunInput, type UpdateInspectorRunInput } from "../lib/runContract";
 import { SessionInfoSchema } from "../lib/sessionInfoContract";
+import { isRecord, textByteLength } from "../lib/unknown";
 import { CapturedLogSchema, type CapturedLog } from "../contracts";
 import {
   addInspectorGroupSession,
@@ -112,11 +113,6 @@ function inspectorBaseUrl(): string {
   return `http://127.0.0.1:${String(getCurrentPort())}`;
 }
 
-function textByteLength(value: string | null): number | null {
-  if (value === null) return null;
-  return Buffer.byteLength(value, "utf8");
-}
-
 function hasBodyText(value: string | null, byteLength: number | null | undefined): boolean {
   if (value !== null && value.length > 0) return true;
   return byteLength !== undefined && byteLength !== null && byteLength > 0;
@@ -272,15 +268,44 @@ async function readCompactLogsPage(
   params: URLSearchParams,
 ): Promise<{ logs: CapturedLog[]; total: number } | ToolResult> {
   const path = `/api/logs?${params.toString()}`;
-  const res = await callApi(path);
-  if (!res.ok) return toolError(`GET ${path} returned ${res.status}`);
-  const rawBody: unknown = await res.json();
-  const parsed = LogsListResponseSchema.safeParse(rawBody);
-  if (!parsed.success) return toolError("GET /api/logs returned an unparseable logs shape");
+  const parsed = await fetchApiJson(callApi, path, LogsListResponseSchema);
+  if (!parsed.ok) return parsed.error;
   const logs = parsed.data.logs ?? [];
   return { logs, total: parsed.data.total ?? logs.length };
 }
 
+/**
+ * Fetches a JSON endpoint and validates it against a Zod schema in one call.
+ * On HTTP error or schema mismatch returns a `ToolResult` error so the caller
+ * can propagate it directly. On success returns the typed parsed value.
+ */
+type FetchApiResult<T> = { ok: true; data: T } | { ok: false; error: ToolResult };
+
+async function fetchApiJson<T>(
+  callApi: CallApiFn,
+  path: string,
+  schema: z.ZodType<T>,
+  init?: RequestInit,
+): Promise<FetchApiResult<T>> {
+  const res = await callApi(path, init);
+  if (!res.ok) {
+    return { ok: false, error: toolError(`${methodFor(init)} ${path} returned ${res.status}`) };
+  }
+  const rawBody: unknown = await res.json();
+  const parsed = schema.safeParse(rawBody);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: toolError(`${methodFor(init)} ${path} returned an unparseable shape`),
+    };
+  }
+  return { ok: true, data: parsed.data };
+}
+
+function methodFor(init: RequestInit | undefined): string {
+  return (init?.method ?? "GET").toUpperCase();
+}
+
 function isToolResult(value: unknown): value is ToolResult {
   return (
     typeof value === "object" &&
@@ -373,13 +398,8 @@ export async function searchLogsImpl(
 }
 
 export async function getLogImpl(callApi: CallApiFn, id: number): Promise<ToolResult> {
-  const res = await callApi(`/api/logs/${id}`);
-  if (!res.ok) return toolError(`GET /api/logs/${id} returned ${res.status}`);
-  const rawBody: unknown = await res.json();
-  const parsed = CapturedLogSchema.safeParse(rawBody);
-  if (!parsed.success) {
-    return toolError(`GET /api/logs/${id} returned an unparseable CapturedLog`);
-  }
+  const parsed = await fetchApiJson(callApi, `/api/logs/${id}`, CapturedLogSchema);
+  if (!parsed.ok) return parsed.error;
   return textJson(buildBoundedLogDetail(parsed.data));
 }
 
@@ -413,11 +433,8 @@ export async function getSessionImpl(
     params.set("includeHistory", "1");
   }
   const path = `/api/sessions?${params.toString()}`;
-  const res = await callApi(path);
-  if (!res.ok) return toolError(`GET ${path} returned ${res.status}`);
-  const rawBody: unknown = await res.json();
-  const parsed = SessionInfoSchema.safeParse(rawBody);
-  if (!parsed.success) return toolError("GET /api/sessions returned an unparseable session info");
+  const parsed = await fetchApiJson(callApi, path, SessionInfoSchema);
+  if (!parsed.ok) return parsed.error;
   return textJson(parsed.data);
 }
 
@@ -724,13 +741,8 @@ export async function getProcessTimelineImpl(
 }
 
 export async function getLogHeadersImpl(callApi: CallApiFn, id: number): Promise<ToolResult> {
-  const res = await callApi(`/api/logs/${id}`);
-  if (!res.ok) return toolError(`GET /api/logs/${id} returned ${res.status}`);
-  const rawBody: unknown = await res.json();
-  const parsed = CapturedLogSchema.safeParse(rawBody);
-  if (!parsed.success) {
-    return toolError(`GET /api/logs/${id} returned an unparseable CapturedLog`);
-  }
+  const parsed = await fetchApiJson(callApi, `/api/logs/${id}`, CapturedLogSchema);
+  if (!parsed.ok) return parsed.error;
   const log = parsed.data;
   return textJson({
     id: log.id,
@@ -1045,31 +1057,14 @@ export async function listModelsImpl(callApi: CallApiFn): Promise<ToolResult> {
   return textJson(await res.json());
 }
 
-export type ProviderReadArgs = {
-  includeSecrets?: boolean;
-};
-
-function includeSecretsQuery(includeSecrets: boolean | undefined): string {
-  return includeSecrets === true ? "?includeSecrets=1" : "";
-}
-
-export async function listProvidersImpl(
-  callApi: CallApiFn,
-  args: ProviderReadArgs = {},
-): Promise<ToolResult> {
-  const res = await callApi(`/api/providers${includeSecretsQuery(args.includeSecrets)}`);
+export async function listProvidersImpl(callApi: CallApiFn): Promise<ToolResult> {
+  const res = await callApi("/api/providers");
   if (!res.ok) return toolError(`GET /api/providers returned ${res.status}`);
   return textJson(await res.json());
 }
 
-export async function getProviderImpl(
-  callApi: CallApiFn,
-  id: string,
-  args: ProviderReadArgs = {},
-): Promise<ToolResult> {
-  const res = await callApi(
-    `/api/providers/${encodeURIComponent(id)}${includeSecretsQuery(args.includeSecrets)}`,
-  );
+export async function getProviderImpl(callApi: CallApiFn, id: string): Promise<ToolResult> {
+  const res = await callApi(`/api/providers/${encodeURIComponent(id)}`);
   if (!res.ok) return toolError(`GET /api/providers/${id} returned ${res.status}`);
   return textJson(await res.json());
 }
@@ -1182,10 +1177,6 @@ type ProviderDiagnosticIssue = {
   endpoint: string | null;
 };
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function stringField(record: Record<string, unknown>, key: string): string | null {
   const value = record[key];
   return typeof value === "string" && value.length > 0 ? value : null;

package/src/proxy/constants.ts

@@ -26,12 +26,29 @@ export const HEADER_HOST = "host";
 // Auth header types
 export const AUTH_HEADER_X_API_KEY = "x-api-key";
 
+// Headers whose values contain secrets (API keys, bearer tokens).
+// These are redacted before being written to logs when captureMode is "full".
+export const SENSITIVE_HEADERS = new Set([
+  HEADER_AUTHORIZATION,
+  HEADER_X_API_KEY,
+  "cookie",
+  "set-cookie",
+  "proxy-authorization",
+]);
+
 // Content types
 export const CONTENT_TYPE_EVENT_STREAM = "text/event-stream";
 
 // Response status
 export const STATUS_FORBIDDEN = 403;
 export const STATUS_BAD_GATEWAY = 502;
+export const STATUS_PAYLOAD_TOO_LARGE = 413;
+
+// Maximum request body size accepted by the proxy (50 MB).
+// Legitimate LLM API requests (system prompts, conversation history, tool
+// definitions) are well under this limit; larger payloads are almost certainly
+// malicious or malformed.
+export const MAX_REQUEST_BODY_BYTES = 50 * 1024 * 1024;
 
 // Standard/safe headers to preserve when forwarding to upstream.
 // NOTE: Authorization is intentionally excluded to prevent client auth tokens from leaking.

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/formats/anthropic/handler.ts

@@ -13,7 +13,11 @@ export const AnthropicFormatHandler: FormatHandler = {
       if (result.success) {
         return {
           model: result.data.model,
-          sessionId: result.data.metadata?.user_id ?? headers?.get("x-session-affinity") ?? null,
+          sessionId:
+            result.data.metadata?.user_id ??
+            headers?.get("x-agent-inspector-session-id") ??
+            headers?.get("x-session-affinity") ??
+            null,
         };
       }
       return null;

package/src/proxy/formats/anthropic/schemas.ts

@@ -1,12 +1,6 @@
 export {
   AnthropicRequestSchema,
   AnthropicResponseSchema,
-  InspectorRequestSchema,
-  InspectorResponseSchema,
   SseEventSchema,
 } from "../../../contracts/anthropic";
-export type {
-  AnthropicResponse,
-  InspectorResponse,
-  ResponseContentBlockType,
-} from "../../../contracts/anthropic";
+export type { AnthropicResponse, ResponseContentBlockType } from "../../../contracts/anthropic";

package/src/proxy/formats/index.ts

@@ -9,5 +9,5 @@ import "./openai/zhipuProvider";
 import "./openai/alibabaProvider";
 
 export type { FormatHandler, ParsedRequest } from "./handler";
-export { apiFormatForPath, formatRegistry, formatForPath, requestFormatForPath } from "./registry";
+export { apiFormatForPath, formatRegistry, formatForPath } from "./registry";
 export { registry } from "./providers";

package/src/proxy/formats/openai/schemas.ts

@@ -20,9 +20,6 @@ export {
 } from "../../../contracts/openai";
 export type {
   OpenAIResponse,
-  OpenAIResponsesRequest,
   OpenAIResponsesResponse,
-  OpenAIResponsesSSEvent,
-  OpenAIResponsesOutputItem,
   OpenAIToolCall,
 } from "../../../contracts/openai";

package/src/proxy/formats/registry.ts

@@ -72,9 +72,6 @@ export function apiFormatForPath(path: string): ApiFormat {
   return formatRegistry.getApiFormatByPath(path) ?? "unknown";
 }
 
-/** Backward-compatible alias for older internal imports. */
-export const requestFormatForPath = apiFormatForPath;
-
 // Register known paths
 formatRegistry.registerPath(PATH_V1_MESSAGES, "anthropic");
 formatRegistry.registerPath(PATH_V1_CHAT_COMPLETIONS, "openai");

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 {