@tonyclaw/agent-inspector 3.0.25 → 3.0.27

package/src/contracts/log.ts

@@ -2,7 +2,6 @@ import { z } from "zod";
 import { JsonValueSchema } from "./json";
 
 export type ApiFormat = "anthropic" | "openai" | "unknown";
-export type RequestFormat = ApiFormat;
 
 /**
  * A single SSE event from a streaming response.

package/src/contracts/openai.ts

@@ -242,10 +242,7 @@ export const OpenAIResponsesSSEventSchema = z
   .passthrough();
 
 export type OpenAIResponse = z.infer<typeof OpenAIResponseSchema>;
-export type OpenAIResponsesRequest = z.infer<typeof OpenAIResponsesRequestSchema>;
 export type OpenAIResponsesResponse = z.infer<typeof OpenAIResponsesResponseSchema>;
-export type OpenAIResponsesSSEvent = z.infer<typeof OpenAIResponsesSSEventSchema>;
-export type OpenAIResponsesOutputItem = z.infer<typeof OpenAIResponsesOutputItemSchema>;
 
 export function parseOpenAIResponse(rawBody: string): OpenAIResponse | null {
   try {

package/src/knowledge/openclawClient.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { safeFetch } from "../lib/safeFetch";
 import type { KnowledgeCandidate, KnowledgeSearchResponse, OpenClawMemoryPayload } from "./types";
 import { KnowledgeSearchResponseSchema, KnowledgeSearchResultSchema } from "./types";
 import { isOpenClawGatewayConfigured, searchOpenClawGateway } from "./openclawGatewayClient";
@@ -81,11 +82,17 @@ export async function promoteToOpenClaw(candidate: KnowledgeCandidate): Promise<
     };
   }
 
-  const response = await fetch(buildMemoryUrl(endpoint), {
-    method: "POST",
-    headers: authHeaders(),
-    body: JSON.stringify(buildOpenClawPayload(candidate)),
-  });
+  const fetchResult = await safeFetch(
+    buildMemoryUrl(endpoint),
+    {
+      method: "POST",
+      headers: authHeaders(),
+      body: JSON.stringify(buildOpenClawPayload(candidate)),
+    },
+    { bypass: true },
+  );
+  if (!fetchResult.ok) return { success: false, error: fetchResult.reason };
+  const response = fetchResult.response;
 
   if (!response.ok) {
     return { success: false, error: `OpenClaw memory write failed with ${response.status}` };
@@ -120,10 +127,16 @@ export async function searchOpenClaw(
     };
   }
 
-  const response = await fetch(buildSearchUrl(endpoint, query, project), {
-    method: "GET",
-    headers: authHeaders(),
-  });
+  const fetchResult = await safeFetch(
+    buildSearchUrl(endpoint, query, project),
+    {
+      method: "GET",
+      headers: authHeaders(),
+    },
+    { bypass: true },
+  );
+  if (!fetchResult.ok) return { results: [], warning: fetchResult.reason };
+  const response = fetchResult.response;
   if (!response.ok) {
     return { results: [], warning: `OpenClaw search failed with ${response.status}` };
   }

package/src/knowledge/openclawGatewayClient.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { safeFetch } from "../lib/safeFetch";
 import type { KnowledgeSearchResponse, KnowledgeSearchResult } from "./types";
 
 const OpenClawGatewayErrorSchema = z
@@ -192,19 +193,25 @@ export async function searchOpenClawGateway(
     };
   }
 
-  const response = await fetch(buildToolInvokeUrl(gatewayUrl), {
-    method: "POST",
-    headers: gatewayHeaders(),
-    body: JSON.stringify({
-      tool: "memory_search",
-      args: {
-        query: buildSearchQuery(query, project),
-        maxResults: 10,
-        corpus: "all",
-      },
-      sessionKey: getOpenClawSessionKey(),
-    }),
-  });
+  const fetchResult = await safeFetch(
+    buildToolInvokeUrl(gatewayUrl),
+    {
+      method: "POST",
+      headers: gatewayHeaders(),
+      body: JSON.stringify({
+        tool: "memory_search",
+        args: {
+          query: buildSearchQuery(query, project),
+          maxResults: 10,
+          corpus: "all",
+        },
+        sessionKey: getOpenClawSessionKey(),
+      }),
+    },
+    { bypass: true },
+  );
+  if (!fetchResult.ok) return { results: [], warning: fetchResult.reason };
+  const response = fetchResult.response;
 
   const raw: unknown = await response.json().catch(() => null);
   if (!response.ok) {

package/src/lib/alertContract.ts

@@ -68,12 +68,9 @@ export const AlertListResponseSchema = z.object({
 });
 
 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/ecosystemContract.ts

@@ -91,9 +91,6 @@ export type EcosystemPackageState = z.infer<typeof EcosystemPackageStateSchema>;
 export type EcosystemPackage = z.infer<typeof EcosystemPackageSchema>;
 export type EcosystemRunnerPreset = z.infer<typeof EcosystemRunnerPresetSchema>;
 export type EcosystemRecipe = z.infer<typeof EcosystemRecipeSchema>;
-export type EcosystemPackagesResponse = z.infer<typeof EcosystemPackagesResponseSchema>;
 export type EcosystemTaskAction = z.infer<typeof EcosystemTaskActionSchema>;
 export type EcosystemTaskStatus = z.infer<typeof EcosystemTaskStatusSchema>;
 export type EcosystemTask = z.infer<typeof EcosystemTaskSchema>;
-export type EcosystemTaskResponse = z.infer<typeof EcosystemTaskResponseSchema>;
-export type EcosystemTasksResponse = z.infer<typeof EcosystemTasksResponseSchema>;

package/src/lib/export-logs.ts

@@ -2,6 +2,7 @@ import JSZip from "jszip";
 import type { CapturedLog } from "../contracts";
 import { fetchWithTimeout } from "./apiClient";
 import packageJson from "../../package.json";
+import { isRecord } from "./unknown";
 
 export type ExportMode = "redacted" | "raw";
 export type ExportLogsResult =
@@ -97,10 +98,6 @@ async function fetchStreamingChunks(
   }
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function redactValue(value: unknown): unknown {
   if (Array.isArray(value)) return value.map((item) => redactValue(item));
   if (!isRecord(value)) return value;

package/src/lib/safeFetch.ts

@@ -0,0 +1,100 @@
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import { evaluateUpstreamUrl, isInternalHost, type SsrfGuardOptions } from "./ssrfGuard";
+
+export type ResolvedAddress = {
+  address: string;
+  family: number;
+};
+
+export type HostResolver = (hostname: string) => Promise<readonly ResolvedAddress[]>;
+
+export type SafeFetchOptions = SsrfGuardOptions & {
+  resolver?: HostResolver;
+};
+
+export type SafeFetchResult =
+  | { ok: true; response: Response }
+  | { ok: false; kind: "network-policy" | "redirect"; reason: string };
+
+async function defaultResolver(hostname: string): Promise<readonly ResolvedAddress[]> {
+  return lookup(hostname, { all: true, verbatim: true });
+}
+
+function isLoopbackAddress(hostname: string): boolean {
+  const lower = hostname.toLowerCase();
+  return (
+    lower === "::1" ||
+    lower.startsWith("::ffff:127.") ||
+    lower.startsWith("::ffff:7f00:") ||
+    /^127\./.test(lower)
+  );
+}
+
+export async function evaluateResolvedUpstreamUrl(
+  rawUrl: string,
+  options: SafeFetchOptions = {},
+): Promise<{ allow: true } | { allow: false; reason: string }> {
+  const initial = evaluateUpstreamUrl(rawUrl, options);
+  if (!initial.allow || options.bypass === true) return initial;
+
+  const parsed = new URL(rawUrl);
+  const hostname = parsed.hostname.replace(/^\[|]$/g, "");
+  if (isIP(hostname) !== 0 || hostname.toLowerCase() === "localhost") return initial;
+
+  let addresses: readonly ResolvedAddress[];
+  try {
+    addresses = await (options.resolver ?? defaultResolver)(hostname);
+  } catch (error) {
+    return {
+      allow: false,
+      reason: `Could not safely resolve upstream host "${hostname}": ${String(error)}`,
+    };
+  }
+
+  if (addresses.length === 0) {
+    return { allow: false, reason: `Upstream host "${hostname}" resolved to no addresses` };
+  }
+
+  for (const resolved of addresses) {
+    if (!isInternalHost(resolved.address)) continue;
+    if (options.allowLoopback === true && isLoopbackAddress(resolved.address)) continue;
+    return {
+      allow: false,
+      reason: `Refusing upstream host "${hostname}" because it resolves to internal address "${resolved.address}"`,
+    };
+  }
+
+  return { allow: true };
+}
+
+function isRedirectStatus(status: number): boolean {
+  return status >= 300 && status < 400;
+}
+
+export async function safeFetch(
+  rawUrl: string,
+  init: RequestInit = {},
+  options: SafeFetchOptions = {},
+): Promise<SafeFetchResult> {
+  const decision = await evaluateResolvedUpstreamUrl(rawUrl, options);
+  if (!decision.allow) {
+    return { ok: false, kind: "network-policy", reason: decision.reason };
+  }
+
+  const response = await fetch(rawUrl, { ...init, redirect: "manual" });
+  if (!isRedirectStatus(response.status)) return { ok: true, response };
+
+  if (response.body !== null) {
+    await response.body.cancel().catch(() => undefined);
+  }
+  const location = response.headers.get("location");
+  return {
+    ok: false,
+    kind: "redirect",
+    reason:
+      location === null
+        ? `Upstream returned blocked redirect HTTP ${String(response.status)}`
+        : `Upstream redirect to "${location}" is blocked; configure the final API URL directly`,
+  };
+}

package/src/lib/ssrfGuard.ts

@@ -0,0 +1,133 @@
+/**
+ * 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,11 +1,8 @@
 import type { CapturedLog } from "../contracts";
+import { isRecord } from "./unknown";
 
 export type StopReason = "end_turn" | "tool_use" | "stop" | "length" | null;
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function normalizeAnthropicStopReason(value: string): StopReason {
   switch (value) {
     case "end_turn":

package/src/lib/unknown.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared helpers for traversing values of type `unknown` without resorting to
+ * type assertions. The project's ESLint rules forbid `as` casts and non-null
+ * assertions, so every safe property read goes through these helpers.
+ */
+
+/** True if `value` is a non-array, non-null object. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Safely read an own property of `value`, returning `undefined` for any
+ * non-object input (including arrays, null, primitives). Uses
+ * `getOwnPropertyDescriptor` so that `__proto__` keys cannot be reached.
+ */
+export function readProperty(value: unknown, name: string): unknown {
+  if (!isRecord(value)) return undefined;
+  const descriptor = Object.getOwnPropertyDescriptor(value, name);
+  return descriptor === undefined ? undefined : descriptor.value;
+}
+
+/** Byte length of a UTF-8 string, or `null` if the string is null. */
+export function textByteLength(value: string | null): number | null {
+  if (value === null) return null;
+  return new TextEncoder().encode(value).byteLength;
+}

package/src/lib/useProviders.ts

@@ -13,7 +13,7 @@ async function fetcher(url: string): Promise<ProviderConfig[]> {
 
 export function useProviders() {
   const response: SWRResponse<ProviderConfig[], Error> = useSWR<ProviderConfig[], Error>(
-    "/api/providers?includeSecrets=1",
+    "/api/providers",
     fetcher,
     {
       revalidateOnFocus: false,

package/src/mcp/mode.ts

@@ -23,13 +23,7 @@ export function isMcpWriteEnabled(): boolean {
   if (readonlyFlag === true) return false;
 
   const writesFlag = parseFlag(process.env["AGENT_INSPECTOR_MCP_WRITES"]);
-  if (writesFlag === false) return false;
-
-  return true;
-}
-
-export function getMcpWriteMode(): McpWriteMode {
-  return isMcpWriteEnabled() ? "enabled" : "readonly";
+  return writesFlag === true;
 }
 
 export function getMcpModeInfo(): {
@@ -50,7 +44,7 @@ export function getMcpModeInfo(): {
       AGENT_INSPECTOR_MCP_WRITES: process.env["AGENT_INSPECTOR_MCP_WRITES"] ?? null,
     },
     note: writesEnabled
-      ? "MCP write/action tools are enabled. Set AGENT_INSPECTOR_MCP_READONLY=1 to expose the same catalog while blocking mutations."
-      : "MCP is in readonly mode. Read tools/resources still work, while write/action tools return an isError result.",
+      ? "MCP write/action tools are enabled explicitly by AGENT_INSPECTOR_MCP_WRITES=1."
+      : "MCP is readonly by default. Read tools/resources still work; set AGENT_INSPECTOR_MCP_WRITES=1 to enable mutations.",
   };
 }

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;