@tonyclaw/agent-inspector 4.0.1 → 4.0.3

package/src/mcp/toolHandlers.ts

@@ -1,1533 +0,0 @@
-/**
- * Tool handler implementations for the MCP server. These are split out from
- * `server.ts` so the wire-level MCP registration stays thin.
- *
- * Log/provider/knowledge handlers still use an injected `callApi` while those
- * domains are being migrated. Run/group/evidence handlers call the shared
- * service layer directly so MCP and REST API are peers instead of MCP looping
- * back through `/api/*`.
- *
- * Each impl returns a `CallToolResult`-shaped object: either
- * `{ content: [{ type: "text", text: string }] }` on success or
- * `{ content: [...], isError: true }` on failure. The wrapping
- * `safeCall` in `server.ts` only catches *thrown* errors (loopback
- * timeouts, etc); semantic errors (404 from /api) are returned as
- * `isError: true` results from inside the impl.
- */
-
-import { Buffer } from "node:buffer";
-import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import JSZip from "jszip";
-import { z } from "zod";
-import { getPublicPort } from "../lib/publicBasePathContext";
-import { LoopbackTimeoutError, type CallApiOptions } from "./loopback";
-import { extractLastUserMessagePreview, extractResponsePreview } from "./previewExtractor";
-import {
-  getCurrentContext,
-  setCurrentContext,
-  type InspectorCurrentContextPatch,
-} from "./currentContext";
-import {
-  type AddInspectorGroupSessionInput,
-  type CreateInspectorGroupInput,
-  type DeleteInspectorGroupOptions,
-  type UpdateInspectorGroupInput,
-} from "../lib/groupContract";
-import { type CreateInspectorRunInput, type UpdateInspectorRunInput } from "../lib/runContract";
-import { SessionInfoSchema } from "../lib/sessionInfoContract";
-import {
-  ProviderConfigSchema,
-  toRedactedProviderDto,
-  toRedactedProviderDtos,
-} from "../lib/providerContract";
-import { isRecord, textByteLength } from "../lib/unknown";
-import { CapturedLogSchema, type CapturedLog } from "../contracts";
-import {
-  createResourceLimitError,
-  MAX_PROVIDER_MODELS,
-  MAX_SEARCH_PROJECT_CHARS,
-  MAX_SEARCH_QUERY_CHARS,
-  type ResourceLimitErrorInput,
-} from "../lib/resourceLimits";
-import {
-  addInspectorGroupSession,
-  createInspectorGroup,
-  deleteInspectorGroup,
-  exportInspectorGroupEvidence,
-  getInspectorGroup,
-  listInspectorGroups,
-  readInspectorGroupEvidence,
-  updateInspectorGroup,
-} from "../services/groups";
-import {
-  createInspectorRun,
-  exportInspectorRunEvidence,
-  getInspectorRun,
-  listInspectorRecentFailures,
-  readInspectorRunEvidence,
-  updateInspectorRun,
-} from "../services/runs";
-
-/** Minimal callApi contract: same shape as the real `callApi` in loopback.ts. */
-export type CallApiFn = (path: string, options?: CallApiOptions) => Promise<Response>;
-
-export type ToolResult = {
-  content: { type: "text"; text: string }[];
-  isError?: true;
-};
-
-// Loose shape returned by `GET /api/logs`: `logs: CapturedLog[]` and a few
-// pagination fields. The CapturedLog items are fully validated downstream.
-const LogsListResponseSchema = z.object({
-  logs: z.array(CapturedLogSchema).optional(),
-  total: z.number().optional(),
-  offset: z.number().optional(),
-  limit: z.number().optional(),
-});
-
-const SearchLogsResponseSchema = z.object({
-  query: z.string(),
-  logs: z.array(CapturedLogSchema),
-  total: z.number(),
-  offset: z.number(),
-  limit: z.number(),
-  scanned: z.number().optional(),
-});
-
-const PAGINATION_DEFAULTS = { offset: 0, limit: 3 };
-export const LIMIT_HARD_CAP = 5;
-const LOG_DETAIL_TEXT_LIMIT = 200_000;
-const PROCESS_LOG_LIMIT_DEFAULT = 50;
-const PROCESS_LOG_LIMIT_MAX = 200;
-
-export function clampLimit(input: number | undefined): number {
-  if (input === undefined) return PAGINATION_DEFAULTS.limit;
-  if (!Number.isFinite(input) || input < 1) return 1;
-  return Math.min(Math.floor(input), LIMIT_HARD_CAP);
-}
-
-function clampProcessLogLimit(input: number | undefined): number {
-  if (input === undefined) return PROCESS_LOG_LIMIT_DEFAULT;
-  if (!Number.isFinite(input) || input < 1) return 1;
-  return Math.min(Math.floor(input), PROCESS_LOG_LIMIT_MAX);
-}
-
-function textJson(data: unknown): ToolResult {
-  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
-}
-
-function toolError(message: string): ToolResult {
-  return { content: [{ type: "text", text: message }], isError: true };
-}
-
-function resourceLimitToolError(input: ResourceLimitErrorInput): ToolResult {
-  return toolError(JSON.stringify(createResourceLimitError(input), null, 2));
-}
-
-function redactedProviderResult(value: unknown): ToolResult {
-  const parsed = ProviderConfigSchema.safeParse(value);
-  if (!parsed.success) return toolError("Provider API returned an invalid provider response");
-  return textJson(toRedactedProviderDto(parsed.data));
-}
-
-function redactedProvidersResult(value: unknown): ToolResult {
-  const parsed = ProviderConfigSchema.array().safeParse(value);
-  if (!parsed.success) return toolError("Provider API returned an invalid providers response");
-  return textJson(toRedactedProviderDtos(parsed.data));
-}
-
-function inspectorBaseUrl(): string {
-  return `http://127.0.0.1:${String(getPublicPort())}`;
-}
-
-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;
-}
-
-function truncateToolText(value: string | null): {
-  value: string | null;
-  byteLength: number | null;
-  truncated: boolean;
-} {
-  if (value === null) return { value: null, byteLength: null, truncated: false };
-  const byteLength = textByteLength(value);
-  if (value.length <= LOG_DETAIL_TEXT_LIMIT) {
-    return { value, byteLength, truncated: false };
-  }
-  const suffix = `\n[truncated by agent-inspector MCP: original ${byteLength ?? 0} bytes]`;
-  return {
-    value: `${value.slice(0, LOG_DETAIL_TEXT_LIMIT)}${suffix}`,
-    byteLength,
-    truncated: true,
-  };
-}
-
-function buildBoundedLogDetail(log: CapturedLog): Record<string, unknown> {
-  const { streamingChunks: _chunks, rawRequestBody, responseText, ...rest } = log;
-  const boundedRequest = truncateToolText(rawRequestBody);
-  const boundedResponse = truncateToolText(responseText);
-  return {
-    ...rest,
-    rawRequestBody: boundedRequest.value,
-    responseText: boundedResponse.value,
-    rawRequestBodyBytes: boundedRequest.byteLength,
-    responseTextBytes: boundedResponse.byteLength,
-    rawRequestBodyTruncated: boundedRequest.truncated,
-    responseTextTruncated: boundedResponse.truncated,
-  };
-}
-
-function logHasError(log: CapturedLog): boolean {
-  return (
-    (log.error !== null && log.error !== undefined && log.error.length > 0) ||
-    (log.responseStatus !== null && log.responseStatus !== undefined && log.responseStatus >= 400)
-  );
-}
-
-export function buildLogSummary(log: CapturedLog) {
-  const hasError = logHasError(log);
-  const rawRequestBodyBytes = log.rawRequestBodyBytes ?? textByteLength(log.rawRequestBody);
-  const responseTextBytes = log.responseTextBytes ?? textByteLength(log.responseText);
-  return {
-    id: log.id,
-    timestamp: log.timestamp,
-    provider: log.providerName ?? null,
-    model: log.model,
-    apiFormat: log.apiFormat,
-    method: log.method,
-    path: log.path,
-    status: log.responseStatus,
-    isStreaming: log.streaming,
-    hasError,
-    latencyMs: log.elapsedMs,
-    firstChunkMs: log.firstChunkMs ?? null,
-    totalStreamMs: log.totalStreamMs ?? null,
-    tokensPerSecond: log.tokensPerSecond ?? null,
-    tokens: {
-      input: log.inputTokens,
-      output: log.outputTokens,
-      cacheCreate: log.cacheCreationInputTokens,
-      cacheRead: log.cacheReadInputTokens,
-    },
-    sessionId: log.sessionId,
-    userAgent: log.userAgent ?? null,
-    clientPid: log.clientPid ?? null,
-    clientCwd: log.clientCwd ?? null,
-    clientProjectFolder: log.clientProjectFolder ?? null,
-    lastUserMessagePreview: extractLastUserMessagePreview(log),
-    responsePreview: extractResponsePreview(log),
-    hasChunks:
-      (log.streamingChunks !== undefined && log.streamingChunks !== null) ||
-      (log.streamingChunksPath !== null && log.streamingChunksPath !== undefined),
-    hasRawRequestBody: hasBodyText(log.rawRequestBody, rawRequestBodyBytes),
-    rawRequestBodyBytes,
-    responseTextBytes,
-  };
-}
-
-function sortedUniqueStrings(values: Array<string | null | undefined>): string[] {
-  return [
-    ...new Set(
-      values.filter(
-        (value): value is string => value !== null && value !== undefined && value !== "",
-      ),
-    ),
-  ].sort((left, right) => left.localeCompare(right));
-}
-
-function sortedUniqueNumbers(values: Array<number | null | undefined>): number[] {
-  return [
-    ...new Set(
-      values.filter(
-        (value): value is number => value !== null && value !== undefined && Number.isFinite(value),
-      ),
-    ),
-  ].sort((left, right) => left - right);
-}
-
-function inferAgentFromUserAgent(userAgent: string | null | undefined): string | null {
-  if (userAgent === null || userAgent === undefined) return null;
-  const lower = userAgent.toLowerCase();
-  if (lower.includes("codex")) return "Codex";
-  if (lower.includes("opencode")) return "OpenCode";
-  if (lower.includes("claude")) return "Claude Code";
-  if (lower.includes("mimocode")) return "MiMoCode";
-  if (lower.includes("ai-sdk")) return "AI SDK";
-  return null;
-}
-
-function processSummary(
-  clientPid: number,
-  logs: readonly CapturedLog[],
-  total: number,
-  limit: number,
-): Record<string, unknown> {
-  const sortedLogs = [...logs].sort((left, right) => left.id - right.id);
-  const first = sortedLogs[0];
-  const last = sortedLogs[sortedLogs.length - 1];
-  const userAgents = sortedUniqueStrings(sortedLogs.map((log) => log.userAgent));
-  const agents = sortedUniqueStrings(userAgents.map(inferAgentFromUserAgent));
-  const sessions = sortedUniqueStrings(sortedLogs.map((log) => log.sessionId));
-  return {
-    clientPid,
-    total,
-    limit,
-    logCount: sortedLogs.length,
-    sessionCount: sessions.length,
-    sessions,
-    agents,
-    userAgents,
-    clientPorts: sortedUniqueNumbers(sortedLogs.map((log) => log.clientPort)),
-    clientCwds: sortedUniqueStrings(sortedLogs.map((log) => log.clientCwd)),
-    clientProjectFolders: sortedUniqueStrings(sortedLogs.map((log) => log.clientProjectFolder)),
-    models: sortedUniqueStrings(sortedLogs.map((log) => log.model)),
-    providers: sortedUniqueStrings(sortedLogs.map((log) => log.providerName)),
-    errorCount: sortedLogs.filter(logHasError).length,
-    startedAt: first?.timestamp ?? null,
-    updatedAt: last?.timestamp ?? null,
-    latestLogs: sortedLogs.slice(-Math.min(10, sortedLogs.length)).reverse().map(buildLogSummary),
-  };
-}
-
-async function readCompactLogsPage(
-  callApi: CallApiFn,
-  params: URLSearchParams,
-): Promise<{ logs: CapturedLog[]; total: number } | ToolResult> {
-  const path = `/api/logs?${params.toString()}`;
-  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" &&
-    value !== null &&
-    Object.getOwnPropertyDescriptor(value, "content") !== undefined
-  );
-}
-
-// ===========================================================================
-// Per-tool impls
-// ===========================================================================
-
-export type ListLogsArgs = {
-  offset?: number;
-  limit?: number;
-  sessionId?: string;
-  model?: string;
-  clientPid?: number;
-};
-
-export async function listLogsImpl(callApi: CallApiFn, args: ListLogsArgs): Promise<ToolResult> {
-  if (
-    args.limit !== undefined &&
-    (!Number.isSafeInteger(args.limit) || args.limit < 1 || args.limit > LIMIT_HARD_CAP)
-  ) {
-    return resourceLimitToolError({
-      error: `MCP log pages may contain at most ${String(LIMIT_HARD_CAP)} entries.`,
-      code: "invalid-page-request",
-      status: 400,
-      resource: "mcp-log-page-size",
-      limit: LIMIT_HARD_CAP,
-      retryable: false,
-    });
-  }
-  const offset = args.offset ?? PAGINATION_DEFAULTS.offset;
-  const limit = clampLimit(args.limit);
-  const params = new URLSearchParams({
-    offset: String(offset),
-    limit: String(limit),
-    compact: "1",
-  });
-  if (args.sessionId !== undefined && args.sessionId.length > 0) {
-    params.set("sessionId", args.sessionId);
-  }
-  if (args.model !== undefined && args.model.length > 0) {
-    params.set("model", args.model);
-  }
-  if (args.clientPid !== undefined) {
-    params.set("clientPid", String(args.clientPid));
-  }
-  const res = await callApi(`/api/logs?${params.toString()}`);
-  if (!res.ok) return toolError(`GET /api/logs 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 shape");
-  const logs = parsed.data.logs ?? [];
-  return textJson(logs.map(buildLogSummary));
-}
-
-export type SearchLogsArgs = {
-  query?: string;
-  offset?: number;
-  limit?: number;
-  scanLimit?: number;
-  sessionId?: string;
-  model?: string;
-  clientPid?: number;
-};
-
-export async function searchLogsImpl(
-  callApi: CallApiFn,
-  args: SearchLogsArgs,
-): Promise<ToolResult> {
-  if ((args.query ?? "").length > MAX_SEARCH_QUERY_CHARS) {
-    return resourceLimitToolError({
-      error: `MCP search queries may contain at most ${String(MAX_SEARCH_QUERY_CHARS)} characters.`,
-      code: "search-limit-exceeded",
-      status: 400,
-      resource: "mcp-log-search-query",
-      limit: MAX_SEARCH_QUERY_CHARS,
-      retryable: false,
-    });
-  }
-  if (
-    args.limit !== undefined &&
-    (!Number.isSafeInteger(args.limit) || args.limit < 1 || args.limit > LIMIT_HARD_CAP)
-  ) {
-    return resourceLimitToolError({
-      error: `MCP search pages may contain at most ${String(LIMIT_HARD_CAP)} entries.`,
-      code: "invalid-page-request",
-      status: 400,
-      resource: "mcp-log-search-page-size",
-      limit: LIMIT_HARD_CAP,
-      retryable: false,
-    });
-  }
-  if (
-    args.scanLimit !== undefined &&
-    (!Number.isSafeInteger(args.scanLimit) || args.scanLimit < 1 || args.scanLimit > 1_000)
-  ) {
-    return resourceLimitToolError({
-      error: "MCP log searches may scan at most 1000 entries.",
-      code: "search-limit-exceeded",
-      status: 400,
-      resource: "mcp-log-search-scan-size",
-      limit: 1_000,
-      retryable: false,
-    });
-  }
-  const offset = args.offset ?? PAGINATION_DEFAULTS.offset;
-  const limit = clampLimit(args.limit);
-  const params = new URLSearchParams({
-    q: args.query ?? "",
-    offset: String(offset),
-    limit: String(limit),
-  });
-  if (args.scanLimit !== undefined) {
-    params.set("scanLimit", String(args.scanLimit));
-  }
-  if (args.sessionId !== undefined && args.sessionId.length > 0) {
-    params.set("sessionId", args.sessionId);
-  }
-  if (args.model !== undefined && args.model.length > 0) {
-    params.set("model", args.model);
-  }
-  if (args.clientPid !== undefined) {
-    params.set("clientPid", String(args.clientPid));
-  }
-
-  const res = await callApi(`/api/logs?${params.toString()}`);
-  if (!res.ok) return toolError(`GET /api/logs search returned ${res.status}`);
-  const rawBody: unknown = await res.json();
-  const parsed = SearchLogsResponseSchema.safeParse(rawBody);
-  if (!parsed.success) return toolError("GET /api/logs search returned an unparseable shape");
-  return textJson({
-    ...parsed.data,
-    logs: parsed.data.logs.map(buildLogSummary),
-  });
-}
-
-export async function getLogImpl(callApi: CallApiFn, id: number): Promise<ToolResult> {
-  const parsed = await fetchApiJson(callApi, `/api/logs/${id}`, CapturedLogSchema);
-  if (!parsed.ok) return parsed.error;
-  return textJson(buildBoundedLogDetail(parsed.data));
-}
-
-export async function getLogChunksImpl(callApi: CallApiFn, id: number): Promise<ToolResult> {
-  const res = await callApi(`/api/logs/${id}/chunks`);
-  if (!res.ok) return toolError(`GET /api/logs/${id}/chunks returned ${res.status}`);
-  return textJson(await res.json());
-}
-
-export async function listSessionsImpl(callApi: CallApiFn): Promise<ToolResult> {
-  const res = await callApi("/api/sessions");
-  if (!res.ok) return toolError(`GET /api/sessions returned ${res.status}`);
-  return textJson(await res.json());
-}
-
-export type GetSessionArgs = {
-  sessionId: string;
-  includeHistory?: boolean;
-  latestLogLimit?: number;
-};
-
-export async function getSessionImpl(
-  callApi: CallApiFn,
-  args: GetSessionArgs,
-): Promise<ToolResult> {
-  const params = new URLSearchParams({ sessionId: args.sessionId });
-  if (args.latestLogLimit !== undefined) {
-    params.set("limit", String(args.latestLogLimit));
-  }
-  if (args.includeHistory === true) {
-    params.set("includeHistory", "1");
-  }
-  const path = `/api/sessions?${params.toString()}`;
-  const parsed = await fetchApiJson(callApi, path, SessionInfoSchema);
-  if (!parsed.ok) return parsed.error;
-  return textJson(parsed.data);
-}
-
-export function createRunImpl(args: CreateInspectorRunInput): ToolResult {
-  return textJson(createInspectorRun(args));
-}
-
-export type GetRunArgs = {
-  runId: string;
-};
-
-export function getRunImpl(args: GetRunArgs): ToolResult {
-  const run = getInspectorRun(args.runId);
-  if (!run.ok) return toolError(run.message);
-  return textJson(run.value);
-}
-
-export type UpdateRunArgs = {
-  runId: string;
-} & UpdateInspectorRunInput;
-
-export function updateRunImpl(args: UpdateRunArgs): ToolResult {
-  const { runId, ...patch } = args;
-  const run = updateInspectorRun(runId, patch);
-  if (!run.ok) return toolError(run.message);
-  return textJson(run.value);
-}
-
-export type GetRecentFailuresArgs = {
-  limit?: number;
-};
-
-export function getRecentFailuresImpl(args: GetRecentFailuresArgs): ToolResult {
-  const limit = args.limit ?? 5;
-  return textJson(listInspectorRecentFailures(limit));
-}
-
-export type ExportEvidenceArgs = {
-  runId: string;
-  includeHistory?: boolean;
-  latestLogLimit?: number;
-};
-
-export async function exportEvidenceImpl(args: ExportEvidenceArgs): Promise<ToolResult> {
-  const exported = await exportInspectorRunEvidence(
-    args.runId,
-    {
-      includeHistory: args.includeHistory,
-      latestLogLimit: args.latestLogLimit,
-    },
-    inspectorBaseUrl(),
-  );
-  if (!exported.ok) return toolError(exported.message);
-  return textJson(exported.value);
-}
-
-export function listGroupsImpl(): ToolResult {
-  return textJson(listInspectorGroups());
-}
-
-export function createGroupImpl(args: CreateInspectorGroupInput): ToolResult {
-  return textJson(createInspectorGroup(args));
-}
-
-export type GetGroupArgs = {
-  groupId: string;
-};
-
-export function getGroupImpl(args: GetGroupArgs): ToolResult {
-  const group = getInspectorGroup(args.groupId);
-  if (!group.ok) return toolError(group.message);
-  return textJson(group.value);
-}
-
-export type UpdateGroupArgs = {
-  groupId: string;
-} & UpdateInspectorGroupInput;
-
-export function updateGroupImpl(args: UpdateGroupArgs): ToolResult {
-  const { groupId, ...patch } = args;
-  const group = updateInspectorGroup(groupId, patch);
-  if (!group.ok) return toolError(group.message);
-  return textJson(group.value);
-}
-
-export type DeleteGroupArgs = {
-  groupId: string;
-} & DeleteInspectorGroupOptions;
-
-export function deleteGroupImpl(args: DeleteGroupArgs): ToolResult {
-  const deleted = deleteInspectorGroup(args.groupId, { deleteEvidence: args.deleteEvidence });
-  if (!deleted.ok) return toolError(deleted.message);
-  return textJson(deleted.value);
-}
-
-export type AddGroupSessionArgs = {
-  groupId: string;
-} & AddInspectorGroupSessionInput;
-
-export function addGroupSessionImpl(args: AddGroupSessionArgs): ToolResult {
-  const { groupId, ...session } = args;
-  const group = addInspectorGroupSession(groupId, session);
-  if (!group.ok) return toolError(group.message);
-  return textJson(group.value);
-}
-
-export type ExportGroupEvidenceArgs = {
-  groupId: string;
-  includeHistory?: boolean;
-  latestLogLimit?: number;
-};
-
-export async function exportGroupEvidenceImpl(args: ExportGroupEvidenceArgs): Promise<ToolResult> {
-  const exported = await exportInspectorGroupEvidence(
-    args.groupId,
-    {
-      includeHistory: args.includeHistory,
-      latestLogLimit: args.latestLogLimit,
-    },
-    inspectorBaseUrl(),
-  );
-  if (!exported.ok) return toolError(exported.message);
-  return textJson(exported.value);
-}
-
-const SESSION_TIMELINE_DEFAULT_LIMIT = 20;
-const SESSION_TIMELINE_LIMIT_MAX = 50;
-
-export type SessionTimelineArgs = {
-  sessionId: string;
-  limit?: number;
-  offset?: number;
-};
-
-function clampTimelineLimit(input: number | undefined): number {
-  if (input === undefined) return SESSION_TIMELINE_DEFAULT_LIMIT;
-  if (!Number.isFinite(input) || input < 1) return 1;
-  return Math.min(Math.floor(input), SESSION_TIMELINE_LIMIT_MAX);
-}
-
-export function buildSessionTimeline(
-  sessionId: string,
-  logs: CapturedLog[],
-  total: number,
-  limit: number,
-): Record<string, unknown> {
-  const sortedLogs = [...logs].sort((left, right) => left.id - right.id);
-  const events = sortedLogs.map((log, index) => ({
-    sequence: index + 1,
-    kind: "request",
-    logId: log.id,
-    ...buildLogSummary(log),
-  }));
-  const first = sortedLogs[0];
-  const last = sortedLogs[sortedLogs.length - 1];
-  const errorCount = events.filter((event) => event.hasError).length;
-  const models = [...new Set(sortedLogs.map((log) => log.model).filter((model) => model !== null))];
-  const providers = [
-    ...new Set(
-      sortedLogs.map((log) => log.providerName ?? null).filter((provider) => provider !== null),
-    ),
-  ];
-
-  return {
-    sessionId,
-    logCoverage: "bounded",
-    total,
-    limit,
-    eventCount: events.length,
-    requestCount: events.length,
-    errorCount,
-    startedAt: first?.timestamp ?? null,
-    updatedAt: last?.timestamp ?? null,
-    models,
-    providers,
-    events,
-  };
-}
-
-export async function getSessionTimelineImpl(
-  callApi: CallApiFn,
-  args: SessionTimelineArgs,
-): Promise<ToolResult> {
-  const limit = clampTimelineLimit(args.limit);
-  const offset = args.offset ?? 0;
-  const params = new URLSearchParams({
-    offset: String(offset),
-    limit: String(limit),
-    compact: "1",
-    sessionId: args.sessionId,
-  });
-  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 timeline shape");
-  const logs = parsed.data.logs ?? [];
-  return textJson(
-    buildSessionTimeline(args.sessionId, logs, parsed.data.total ?? logs.length, limit),
-  );
-}
-
-export type ListProcessesArgs = {
-  limit?: number;
-  scanLimit?: number;
-};
-
-export async function listProcessesImpl(
-  callApi: CallApiFn,
-  args: ListProcessesArgs = {},
-): Promise<ToolResult> {
-  const scanLimit = clampProcessLogLimit(args.scanLimit ?? args.limit);
-  const params = new URLSearchParams({
-    q: "",
-    offset: "0",
-    limit: String(Math.min(scanLimit, 50)),
-    scanLimit: String(scanLimit),
-  });
-  const res = await callApi(`/api/logs?${params.toString()}`);
-  if (!res.ok) return toolError(`GET /api/logs process scan returned ${res.status}`);
-  const rawBody: unknown = await res.json();
-  const parsed = SearchLogsResponseSchema.safeParse(rawBody);
-  if (!parsed.success) return toolError("GET /api/logs returned an unparseable process scan shape");
-
-  const grouped = new Map<number, CapturedLog[]>();
-  for (const log of parsed.data.logs) {
-    if (log.clientPid === null || log.clientPid === undefined) continue;
-    const existing = grouped.get(log.clientPid) ?? [];
-    existing.push(log);
-    grouped.set(log.clientPid, existing);
-  }
-
-  const processes = [...grouped.entries()]
-    .map(([clientPid, logs]) => processSummary(clientPid, logs, logs.length, logs.length))
-    .sort((left, right) => {
-      const leftUpdated = typeof left["updatedAt"] === "string" ? left["updatedAt"] : "";
-      const rightUpdated = typeof right["updatedAt"] === "string" ? right["updatedAt"] : "";
-      return rightUpdated.localeCompare(leftUpdated);
-    });
-
-  return textJson({
-    scanned: parsed.data.scanned ?? parsed.data.logs.length,
-    processCount: processes.length,
-    processes,
-  });
-}
-
-export type ProcessArgs = {
-  clientPid: number;
-  limit?: number;
-  offset?: number;
-};
-
-export async function getProcessImpl(callApi: CallApiFn, args: ProcessArgs): Promise<ToolResult> {
-  const limit = clampProcessLogLimit(args.limit);
-  const offset = args.offset ?? 0;
-  const params = new URLSearchParams({
-    clientPid: String(args.clientPid),
-    offset: String(offset),
-    limit: String(limit),
-    compact: "1",
-  });
-  const result = await readCompactLogsPage(callApi, params);
-  if (isToolResult(result)) return result;
-  return textJson(processSummary(args.clientPid, result.logs, result.total, limit));
-}
-
-export async function getProcessTimelineImpl(
-  callApi: CallApiFn,
-  args: ProcessArgs,
-): Promise<ToolResult> {
-  const limit = clampTimelineLimit(args.limit);
-  const offset = args.offset ?? 0;
-  const params = new URLSearchParams({
-    clientPid: String(args.clientPid),
-    offset: String(offset),
-    limit: String(limit),
-    compact: "1",
-  });
-  const result = await readCompactLogsPage(callApi, params);
-  if (isToolResult(result)) return result;
-  const sortedLogs = [...result.logs].sort((left, right) => left.id - right.id);
-  return textJson({
-    clientPid: args.clientPid,
-    logCoverage: "bounded",
-    total: result.total,
-    limit,
-    eventCount: sortedLogs.length,
-    requestCount: sortedLogs.length,
-    errorCount: sortedLogs.filter(logHasError).length,
-    startedAt: sortedLogs[0]?.timestamp ?? null,
-    updatedAt: sortedLogs.at(-1)?.timestamp ?? null,
-    sessions: sortedUniqueStrings(sortedLogs.map((log) => log.sessionId)),
-    models: sortedUniqueStrings(sortedLogs.map((log) => log.model)),
-    providers: sortedUniqueStrings(sortedLogs.map((log) => log.providerName)),
-    events: sortedLogs.map((log, index) => ({
-      sequence: index + 1,
-      kind: "request",
-      logId: log.id,
-      ...buildLogSummary(log),
-    })),
-  });
-}
-
-export async function getLogHeadersImpl(callApi: CallApiFn, id: number): Promise<ToolResult> {
-  const parsed = await fetchApiJson(callApi, `/api/logs/${id}`, CapturedLogSchema);
-  if (!parsed.ok) return parsed.error;
-  const log = parsed.data;
-  return textJson({
-    id: log.id,
-    sessionId: log.sessionId,
-    userAgent: log.userAgent,
-    origin: log.origin,
-    clientPid: log.clientPid ?? null,
-    clientPort: log.clientPort ?? null,
-    clientCwd: log.clientCwd ?? null,
-    clientProjectFolder: log.clientProjectFolder ?? null,
-    apiFormat: log.apiFormat,
-    method: log.method,
-    path: log.path,
-    model: log.model,
-    rawHeaders: log.rawHeaders ?? null,
-    headers: log.headers ?? null,
-    hasRawHeaders: log.rawHeaders !== undefined && Object.keys(log.rawHeaders).length > 0,
-    hasHeaders: log.headers !== undefined && Object.keys(log.headers).length > 0,
-    bodyContentMode: log.bodyContentMode ?? null,
-  });
-}
-
-export async function getRuntimeConfigImpl(callApi: CallApiFn): Promise<ToolResult> {
-  const configRes = await callApi("/api/config");
-  if (!configRes.ok) return toolError(`GET /api/config returned ${configRes.status}`);
-  const statsRes = await callApi("/api/logs?stats=1");
-  if (!statsRes.ok) return toolError(`GET /api/logs?stats=1 returned ${statsRes.status}`);
-  const config: unknown = await configRes.json();
-  const storage: unknown = await statsRes.json();
-  return textJson({
-    config,
-    storage,
-  });
-}
-
-export type DiagnoseCaptureArgs = {
-  id?: number;
-};
-
-export async function diagnoseCaptureImpl(
-  callApi: CallApiFn,
-  args: DiagnoseCaptureArgs = {},
-): Promise<ToolResult> {
-  const runtime = await getRuntimeConfigImpl(callApi);
-  if (runtime.isError === true) return runtime;
-  const runtimeText = runtime.content[0]?.text ?? "{}";
-  let runtimePayload: unknown = {};
-  try {
-    runtimePayload = JSON.parse(runtimeText);
-  } catch {
-    // Non-JSON runtime config text — treat as empty config and continue diagnostics
-  }
-  const runtimeRecord = isRecord(runtimePayload) ? runtimePayload : {};
-  const configRecord = isRecord(runtimeRecord["config"]) ? runtimeRecord["config"] : {};
-  const captureMode = stringField(configRecord, "captureMode");
-
-  let log: CapturedLog | null = null;
-  if (args.id !== undefined) {
-    const logRes = await callApi(`/api/logs/${args.id}`);
-    if (!logRes.ok) return toolError(`GET /api/logs/${args.id} returned ${logRes.status}`);
-    const rawLog: unknown = await logRes.json();
-    const parsed = CapturedLogSchema.safeParse(rawLog);
-    if (!parsed.success) return toolError(`GET /api/logs/${args.id} returned an unparseable log`);
-    log = parsed.data;
-  }
-
-  const findings: string[] = [];
-  const recommendations: string[] = [];
-  if (captureMode !== "full") {
-    findings.push(
-      "Runtime captureMode is not full, so request/response bodies and headers may be compacted.",
-    );
-    recommendations.push(
-      "Restart or launch Agent Inspector with full capture mode when header/body evidence is required.",
-    );
-  }
-  if (log !== null) {
-    if (log.rawHeaders === undefined || Object.keys(log.rawHeaders).length === 0) {
-      findings.push(`Log ${String(log.id)} has no rawHeaders stored.`);
-    }
-    if (log.headers === undefined || Object.keys(log.headers).length === 0) {
-      findings.push(`Log ${String(log.id)} has no upstream headers stored.`);
-    }
-    if (log.rawRequestBody === null) {
-      findings.push(`Log ${String(log.id)} does not include rawRequestBody in this response.`);
-    }
-    if (log.bodyContentMode === "compact") {
-      findings.push(`Log ${String(log.id)} is in compact body mode.`);
-      recommendations.push(
-        "Use inspector_get_log_headers for header-only checks and enable full capture for future body inspection.",
-      );
-    }
-  }
-
-  return textJson({
-    captureMode,
-    logId: log?.id ?? null,
-    hasLog: log !== null,
-    findings,
-    recommendations,
-    runtime: runtimeRecord,
-  });
-}
-
-export type AddGroupProcessArgs = {
-  groupId: string;
-  clientPid: number;
-  labelPrefix?: string;
-};
-
-export async function addGroupProcessImpl(
-  callApi: CallApiFn,
-  args: AddGroupProcessArgs,
-): Promise<ToolResult> {
-  const params = new URLSearchParams({
-    clientPid: String(args.clientPid),
-    offset: "0",
-    limit: String(PROCESS_LOG_LIMIT_MAX),
-    compact: "1",
-  });
-  const result = await readCompactLogsPage(callApi, params);
-  if (isToolResult(result)) return result;
-
-  const bySession = new Map<string, CapturedLog[]>();
-  for (const log of result.logs) {
-    if (log.sessionId === null || log.sessionId === "") continue;
-    const existing = bySession.get(log.sessionId) ?? [];
-    existing.push(log);
-    bySession.set(log.sessionId, existing);
-  }
-  if (bySession.size === 0) {
-    return toolError(`No sessions found for clientPid ${String(args.clientPid)}`);
-  }
-
-  let groupResult: ReturnType<typeof addInspectorGroupSession> | null = null;
-  const attached: Array<Record<string, unknown>> = [];
-  for (const [sessionId, logs] of bySession.entries()) {
-    const first = logs[0];
-    const last = logs.at(-1);
-    const userAgent = last?.userAgent ?? first?.userAgent ?? null;
-    const agent = inferAgentFromUserAgent(userAgent);
-    groupResult = addInspectorGroupSession(args.groupId, {
-      sessionId,
-      label: `${args.labelPrefix ?? `PID ${String(args.clientPid)}`} - ${sessionId}`,
-      agent,
-      provider: last?.providerName ?? first?.providerName ?? null,
-      model: last?.model ?? first?.model ?? null,
-      metadata: {
-        clientPid: args.clientPid,
-        processLogCount: logs.length,
-        userAgent: userAgent ?? "",
-      },
-    });
-    if (!groupResult.ok) return toolError(groupResult.message);
-    attached.push({ sessionId, logCount: logs.length, agent, userAgent });
-  }
-
-  if (groupResult === null || !groupResult.ok) return toolError("Group process attach failed");
-  return textJson({
-    group: groupResult.value,
-    clientPid: args.clientPid,
-    attached,
-  });
-}
-
-type EvidenceFileKind = "json" | "markdown" | "html" | "zip";
-
-type EvidenceFileSummary = {
-  kind: EvidenceFileKind;
-  path: string;
-  exists: boolean;
-  bytes: number | null;
-  included?: boolean;
-};
-
-type EvidencePaths = {
-  jsonPath: string;
-  markdownPath: string;
-  htmlPath: string;
-  exportedAt: string;
-};
-
-function fileBytes(path: string): number | null {
-  if (!existsSync(path)) return null;
-  try {
-    return statSync(path).size;
-  } catch {
-    return null;
-  }
-}
-
-function evidenceFileSummary(kind: EvidenceFileKind, path: string): EvidenceFileSummary {
-  return {
-    kind,
-    path,
-    exists: existsSync(path),
-    bytes: fileBytes(path),
-  };
-}
-
-function evidenceFiles(evidence: EvidencePaths): EvidenceFileSummary[] {
-  return [
-    evidenceFileSummary("json", evidence.jsonPath),
-    evidenceFileSummary("markdown", evidence.markdownPath),
-    evidenceFileSummary("html", evidence.htmlPath),
-  ];
-}
-
-function readEvidenceFile(path: string): Buffer | null {
-  if (!existsSync(path)) return null;
-  try {
-    return readFileSync(path);
-  } catch {
-    return null;
-  }
-}
-
-async function exportEvidenceZip(
-  ownerKind: "run" | "group",
-  ownerId: string,
-  evidence: EvidencePaths,
-): Promise<Record<string, unknown>> {
-  const zip = new JSZip();
-  const sourceFiles = evidenceFiles(evidence);
-  const includedFiles: EvidenceFileSummary[] = [];
-
-  for (const file of sourceFiles) {
-    const content = readEvidenceFile(file.path);
-    const included = content !== null;
-    includedFiles.push({ ...file, included });
-    if (included) {
-      zip.file(`${file.kind}.${file.kind === "markdown" ? "md" : file.kind}`, content);
-    }
-  }
-
-  zip.file(
-    "manifest.json",
-    `${JSON.stringify(
-      {
-        ownerKind,
-        ownerId,
-        exportedAt: evidence.exportedAt,
-        bundledAt: new Date().toISOString(),
-        files: includedFiles,
-      },
-      null,
-      2,
-    )}\n`,
-  );
-
-  const zipPath = join(
-    dirname(evidence.jsonPath),
-    ownerKind === "run" ? "evidence.zip" : "group-evidence.zip",
-  );
-  const buffer = await zip.generateAsync({ type: "nodebuffer" });
-  writeFileSync(zipPath, buffer);
-  const zipSummary = evidenceFileSummary("zip", zipPath);
-  return {
-    ownerKind,
-    ownerId,
-    bundlePath: zipPath,
-    bytes: zipSummary.bytes,
-    files: [...includedFiles, zipSummary],
-  };
-}
-
-export function getEvidenceFilesImpl(args: { runId: string }): ToolResult {
-  const evidence = readInspectorRunEvidence(args.runId);
-  if (!evidence.ok) return toolError(evidence.message);
-  return textJson({
-    runId: args.runId,
-    exportedAt: evidence.value.evidence.exportedAt,
-    files: evidenceFiles(evidence.value.evidence),
-  });
-}
-
-export async function exportEvidenceBundleImpl(args: { runId: string }): Promise<ToolResult> {
-  const evidence = readInspectorRunEvidence(args.runId);
-  if (!evidence.ok) return toolError(evidence.message);
-  return textJson(await exportEvidenceZip("run", args.runId, evidence.value.evidence));
-}
-
-export function getGroupEvidenceFilesImpl(args: { groupId: string }): ToolResult {
-  const evidence = readInspectorGroupEvidence(args.groupId);
-  if (!evidence.ok) return toolError(evidence.message);
-  return textJson({
-    groupId: args.groupId,
-    exportedAt: evidence.value.evidence.exportedAt,
-    files: evidenceFiles(evidence.value.evidence),
-  });
-}
-
-export async function exportGroupEvidenceBundleImpl(args: {
-  groupId: string;
-}): Promise<ToolResult> {
-  const evidence = readInspectorGroupEvidence(args.groupId);
-  if (!evidence.ok) return toolError(evidence.message);
-  return textJson(await exportEvidenceZip("group", args.groupId, evidence.value.evidence));
-}
-
-export function getCurrentContextImpl(): ToolResult {
-  return textJson(getCurrentContext());
-}
-
-export function setCurrentContextImpl(args: InspectorCurrentContextPatch): ToolResult {
-  return textJson(setCurrentContext(args));
-}
-
-export async function listModelsImpl(callApi: CallApiFn): Promise<ToolResult> {
-  const res = await callApi("/api/models");
-  if (!res.ok) return toolError(`GET /api/models returned ${res.status}`);
-  return textJson(await res.json());
-}
-
-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 redactedProvidersResult(await res.json());
-}
-
-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 redactedProviderResult(await res.json());
-}
-
-export type ReplayLogArgs = { id: number };
-
-export async function replayLogImpl(callApi: CallApiFn, args: ReplayLogArgs): Promise<ToolResult> {
-  const logRes = await callApi(`/api/logs/${args.id}`);
-  if (!logRes.ok) return toolError(`GET /api/logs/${args.id} returned ${logRes.status}`);
-  const logRaw: unknown = await logRes.json();
-  const logParsed = CapturedLogSchema.safeParse(logRaw);
-  if (!logParsed.success) {
-    return toolError(`GET /api/logs/${args.id} returned an unparseable CapturedLog`);
-  }
-  const log = logParsed.data;
-  if (log.rawRequestBody === null) return toolError("Log has no rawRequestBody to replay");
-  const replayRes = await callApi(`/api/logs/${args.id}/replay`, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({ modifiedBody: log.rawRequestBody }),
-  });
-  if (!replayRes.ok) {
-    return toolError(`POST /api/logs/${args.id}/replay returned ${replayRes.status}`);
-  }
-  return textJson(await replayRes.json());
-}
-
-export type AddProviderInput = {
-  name: string;
-  apiKey: string;
-  format?: "anthropic" | "openai";
-  model?: string;
-  models?: string[];
-  anthropicBaseUrl?: string;
-  openaiBaseUrl?: string;
-  openaiResponsesBaseUrl?: string;
-  authHeader?: "bearer" | "x-api-key";
-  apiDocsUrl?: string;
-};
-
-function normalizedProviderModels(input: { model?: string; models?: readonly string[] }): string[] {
-  const modelList = input.models ?? [];
-  const models = modelList.map((model) => model.trim()).filter((model) => model !== "");
-  if (models.length > 0) return models;
-  const model = input.model?.trim();
-  return model !== undefined && model !== "" ? [model] : [];
-}
-
-export async function addProviderImpl(
-  callApi: CallApiFn,
-  provider: AddProviderInput,
-): Promise<ToolResult> {
-  const models = normalizedProviderModels(provider);
-  if (models.length > MAX_PROVIDER_MODELS) {
-    return resourceLimitToolError({
-      error: `Provider model lists may contain at most ${String(MAX_PROVIDER_MODELS)} entries.`,
-      code: "provider-model-limit-exceeded",
-      status: 413,
-      resource: "provider-models",
-      limit: MAX_PROVIDER_MODELS,
-      retryable: false,
-    });
-  }
-  const res = await callApi("/api/providers", {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({ ...provider, models }),
-  });
-  if (!res.ok) return toolError(`POST /api/providers returned ${res.status}`);
-  return redactedProviderResult(await res.json());
-}
-
-export type UpdateProviderInput = {
-  id: string;
-  name?: string;
-  apiKey?: string;
-  format?: "anthropic" | "openai";
-  model?: string;
-  models?: string[];
-  baseUrl?: string;
-  authHeader?: "bearer" | "x-api-key";
-  anthropicBaseUrl?: string;
-  openaiBaseUrl?: string;
-  openaiResponsesBaseUrl?: string;
-  apiDocsUrl?: string;
-};
-
-export async function updateProviderImpl(
-  callApi: CallApiFn,
-  input: UpdateProviderInput,
-): Promise<ToolResult> {
-  const { id, ...patch } = input;
-  const models =
-    patch.models !== undefined || patch.model !== undefined
-      ? normalizedProviderModels(patch)
-      : undefined;
-  if (models !== undefined && models.length > MAX_PROVIDER_MODELS) {
-    return resourceLimitToolError({
-      error: `Provider model lists may contain at most ${String(MAX_PROVIDER_MODELS)} entries.`,
-      code: "provider-model-limit-exceeded",
-      status: 413,
-      resource: "provider-models",
-      limit: MAX_PROVIDER_MODELS,
-      retryable: false,
-    });
-  }
-  const body = models === undefined ? patch : { ...patch, models };
-  const res = await callApi(`/api/providers/${encodeURIComponent(id)}`, {
-    method: "PUT",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify(body),
-  });
-  if (!res.ok) return toolError(`PUT /api/providers/${id} returned ${res.status}`);
-  return redactedProviderResult(await res.json());
-}
-
-export async function testProviderImpl(callApi: CallApiFn, id: string): Promise<ToolResult> {
-  const res = await callApi(`/api/providers/${encodeURIComponent(id)}/test`, {
-    method: "POST",
-  });
-  if (!res.ok) return toolError(`POST /api/providers/${id}/test returned ${res.status}`);
-  return textJson(await res.json());
-}
-
-type ProviderDiagnosticIssue = {
-  path: string;
-  status: number | null;
-  error: string | null;
-  durationMs: number | null;
-  endpoint: string | null;
-};
-
-function stringField(record: Record<string, unknown>, key: string): string | null {
-  const value = record[key];
-  return typeof value === "string" && value.length > 0 ? value : null;
-}
-
-function numberField(record: Record<string, unknown>, key: string): number | null {
-  const value = record[key];
-  return typeof value === "number" && Number.isFinite(value) ? value : null;
-}
-
-function firstStringField(record: Record<string, unknown>, keys: string[]): string | null {
-  for (const key of keys) {
-    const value = stringField(record, key);
-    if (value !== null) return value;
-  }
-  return null;
-}
-
-function firstNumberField(record: Record<string, unknown>, keys: string[]): number | null {
-  for (const key of keys) {
-    const value = numberField(record, key);
-    if (value !== null) return value;
-  }
-  return null;
-}
-
-function collectProviderDiagnosticIssues(
-  value: unknown,
-  path: string,
-  issues: ProviderDiagnosticIssue[],
-): void {
-  if (Array.isArray(value)) {
-    value.forEach((item, index) =>
-      collectProviderDiagnosticIssues(item, `${path}[${String(index)}]`, issues),
-    );
-    return;
-  }
-  if (!isRecord(value)) return;
-
-  const success = value["success"];
-  const status = firstNumberField(value, ["status", "responseStatus", "statusCode"]);
-  const error = firstStringField(value, ["error", "message", "errorMessage"]);
-  if (success === false || error !== null || (status !== null && status >= 400)) {
-    issues.push({
-      path,
-      status,
-      error,
-      durationMs: firstNumberField(value, ["durationMs", "elapsedMs", "latencyMs"]),
-      endpoint: firstStringField(value, ["endpoint", "url", "requestUrl", "baseUrl"]),
-    });
-  }
-
-  for (const [key, child] of Object.entries(value)) {
-    if (typeof child === "object" && child !== null) {
-      collectProviderDiagnosticIssues(child, `${path}.${key}`, issues);
-    }
-  }
-}
-
-function stringifyUnknown(value: unknown): string {
-  try {
-    const text = JSON.stringify(value);
-    return text === undefined ? "" : text.toLowerCase();
-  } catch {
-    return "";
-  }
-}
-
-function providerDiagnosticHints(result: unknown): string[] {
-  const text = stringifyUnknown(result);
-  const hints: string[] = [];
-  if (text.includes("timeout") || text.includes("aborted")) {
-    hints.push(
-      "Provider test timed out or was aborted. Increase Settings > Proxy > Provider test timeout when the provider or model is slow.",
-    );
-  }
-  if (text.includes("localhost") || text.includes("127.0.0.1")) {
-    hints.push(
-      "The upstream URL contains localhost. If the agent or provider runs in another container, replace localhost with a reachable host/IP.",
-    );
-  }
-  if (text.includes("econnrefused") || text.includes("enotfound") || text.includes("network")) {
-    hints.push(
-      "This looks like a network or DNS failure. Verify the Inspector container/host can reach the provider base URL.",
-    );
-  }
-  if (
-    text.includes("401") ||
-    text.includes("403") ||
-    text.includes("unauthorized") ||
-    text.includes("forbidden")
-  ) {
-    hints.push(
-      "This looks like an authentication failure. Check the provider API key and auth header mode.",
-    );
-  }
-  if (text.includes("404") || text.includes("not found")) {
-    hints.push(
-      "This looks like a base URL or path mismatch. Check whether the provider endpoint already includes /v1 or needs a vendor-specific path.",
-    );
-  }
-  if (text.includes("nonstream") || text.includes("non-stream")) {
-    hints.push(
-      "The failure mentions non-streaming. Compare the Anthropic, OpenAI Chat, and OpenAI Responses non-streaming path and payload with the streaming request.",
-    );
-  }
-  return [...new Set(hints)];
-}
-
-export async function diagnoseProviderTestImpl(
-  callApi: CallApiFn,
-  id: string,
-): Promise<ToolResult> {
-  const res = await callApi(`/api/providers/${encodeURIComponent(id)}/test`, {
-    method: "POST",
-  });
-  if (!res.ok) return toolError(`POST /api/providers/${id}/test returned ${res.status}`);
-  const result: unknown = await res.json();
-  const issues: ProviderDiagnosticIssue[] = [];
-  collectProviderDiagnosticIssues(result, "result", issues);
-  return textJson({
-    providerId: id,
-    issueCount: issues.length,
-    issues,
-    hints: providerDiagnosticHints(result),
-    result,
-  });
-}
-
-export type CreateSessionKnowledgeArgs = {
-  sessionId: string;
-};
-
-export async function createSessionKnowledgeImpl(
-  callApi: CallApiFn,
-  args: CreateSessionKnowledgeArgs,
-): Promise<ToolResult> {
-  const res = await callApi(
-    `/api/knowledge/sessions/${encodeURIComponent(args.sessionId)}/candidates`,
-    {
-      method: "POST",
-    },
-  );
-  if (!res.ok) {
-    return toolError(
-      `POST /api/knowledge/sessions/${args.sessionId}/candidates returned ${res.status}`,
-    );
-  }
-  return textJson(await res.json());
-}
-
-export async function listKnowledgeCandidatesImpl(callApi: CallApiFn): Promise<ToolResult> {
-  const res = await callApi("/api/knowledge/candidates");
-  if (!res.ok) return toolError(`GET /api/knowledge/candidates returned ${res.status}`);
-  return textJson(await res.json());
-}
-
-export type PromoteKnowledgeCandidateArgs = {
-  candidateId: string;
-};
-
-export async function promoteKnowledgeCandidateImpl(
-  callApi: CallApiFn,
-  args: PromoteKnowledgeCandidateArgs,
-): Promise<ToolResult> {
-  const res = await callApi(
-    `/api/knowledge/candidates/${encodeURIComponent(args.candidateId)}/promote`,
-    {
-      method: "POST",
-    },
-  );
-  if (!res.ok) {
-    return toolError(
-      `POST /api/knowledge/candidates/${args.candidateId}/promote returned ${res.status}`,
-    );
-  }
-  return textJson(await res.json());
-}
-
-export type SearchKnowledgeArgs = {
-  query: string;
-  project?: string;
-};
-
-export async function searchKnowledgeImpl(
-  callApi: CallApiFn,
-  args: SearchKnowledgeArgs,
-): Promise<ToolResult> {
-  if (args.query.length > MAX_SEARCH_QUERY_CHARS) {
-    return resourceLimitToolError({
-      error: `MCP search queries may contain at most ${String(MAX_SEARCH_QUERY_CHARS)} characters.`,
-      code: "search-limit-exceeded",
-      status: 400,
-      resource: "mcp-knowledge-search-query",
-      limit: MAX_SEARCH_QUERY_CHARS,
-      retryable: false,
-    });
-  }
-  if (args.project !== undefined && args.project.length > MAX_SEARCH_PROJECT_CHARS) {
-    return resourceLimitToolError({
-      error: `MCP search project filters may contain at most ${String(MAX_SEARCH_PROJECT_CHARS)} characters.`,
-      code: "search-limit-exceeded",
-      status: 400,
-      resource: "mcp-knowledge-search-project",
-      limit: MAX_SEARCH_PROJECT_CHARS,
-      retryable: false,
-    });
-  }
-  const params = new URLSearchParams({ q: args.query });
-  if (args.project !== undefined && args.project.length > 0) {
-    params.set("project", args.project);
-  }
-  const res = await callApi(`/api/knowledge/search?${params.toString()}`);
-  if (!res.ok) return toolError(`GET /api/knowledge/search returned ${res.status}`);
-  return textJson(await res.json());
-}
-
-export type GetProjectContextArgs = {
-  project: string;
-};
-
-export async function getProjectContextImpl(
-  callApi: CallApiFn,
-  args: GetProjectContextArgs,
-): Promise<ToolResult> {
-  if (args.project.length > MAX_SEARCH_PROJECT_CHARS) {
-    return resourceLimitToolError({
-      error: `MCP search project filters may contain at most ${String(MAX_SEARCH_PROJECT_CHARS)} characters.`,
-      code: "search-limit-exceeded",
-      status: 400,
-      resource: "mcp-knowledge-search-project",
-      limit: MAX_SEARCH_PROJECT_CHARS,
-      retryable: false,
-    });
-  }
-  const params = new URLSearchParams({ project: args.project });
-  const res = await callApi(`/api/knowledge/project-context?${params.toString()}`);
-  if (!res.ok) return toolError(`GET /api/knowledge/project-context returned ${res.status}`);
-  return textJson(await res.json());
-}
-
-/**
- * Wrap an impl so any thrown error becomes a well-formed `isError: true`
- * CallToolResult (instead of a JSON-RPC protocol error, which would abort
- * the whole session). Loopback timeouts get a clear message.
- */
-export async function safeCall(fn: () => ToolResult | Promise<ToolResult>): Promise<ToolResult> {
-  try {
-    return await fn();
-  } catch (err) {
-    if (err instanceof LoopbackTimeoutError) {
-      return toolError(`Internal loopback call timed out after ${err.timeoutMs}ms: ${err.path}`);
-    }
-    const message = err instanceof Error ? err.message : String(err);
-    return toolError(`Tool execution failed: ${message}`);
-  }
-}