@tonyclaw/llm-inspector 1.12.0 → 1.14.0

package/src/mcp/toolHandlers.ts

@@ -0,0 +1,259 @@
+/**
+ * Pure (dependency-injected) tool handler implementations for the MCP
+ * server. These are split out from `server.ts` so unit tests can pass a
+ * mock `callApi` without spinning up a real HTTP loopback. The
+ * `registerTool` calls in `server.ts` simply wrap each impl in `safeCall`
+ * and bind the real `callApi` from `./loopback`.
+ *
+ * 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 { z } from "zod";
+import { LoopbackTimeoutError, type CallApiOptions } from "./loopback";
+import { extractLastUserMessagePreview, extractResponsePreview } from "./previewExtractor";
+import { CapturedLogSchema, type CapturedLog } from "../proxy/schemas";
+
+/** 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 PAGINATION_DEFAULTS = { offset: 0, limit: 3 };
+export const LIMIT_HARD_CAP = 5;
+
+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 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 };
+}
+
+export function buildLogSummary(log: CapturedLog) {
+  const hasError =
+    (log.error !== null && log.error !== undefined && log.error.length > 0) ||
+    (log.responseStatus !== null && log.responseStatus !== undefined && log.responseStatus >= 400);
+  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,
+    tokens: {
+      input: log.inputTokens,
+      output: log.outputTokens,
+      cacheCreate: log.cacheCreationInputTokens,
+      cacheRead: log.cacheReadInputTokens,
+    },
+    sessionId: log.sessionId,
+    clientPid: log.clientPid ?? null,
+    lastUserMessagePreview: extractLastUserMessagePreview(log),
+    responsePreview: extractResponsePreview(log),
+    hasChunks:
+      (log.streamingChunks !== undefined && log.streamingChunks !== null) ||
+      (log.streamingChunksPath !== null && log.streamingChunksPath !== undefined),
+    hasRawRequestBody: log.rawRequestBody !== null && log.rawRequestBody !== undefined,
+  };
+}
+
+// ===========================================================================
+// Per-tool impls
+// ===========================================================================
+
+export type ListLogsArgs = {
+  offset?: number;
+  limit?: number;
+  sessionId?: string;
+  model?: string;
+};
+
+export async function listLogsImpl(callApi: CallApiFn, args: ListLogsArgs): Promise<ToolResult> {
+  const offset = args.offset ?? PAGINATION_DEFAULTS.offset;
+  const limit = clampLimit(args.limit);
+  const params = new URLSearchParams({ offset: String(offset), limit: String(limit) });
+  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);
+  }
+  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 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`);
+  }
+  // Strip streamingChunks per design D6 — the agent asks for chunks
+  // explicitly via inspector_get_log_chunks.
+  const { streamingChunks: _chunks, ...rest } = parsed.data;
+  return textJson(rest);
+}
+
+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 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 textJson(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 textJson(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;
+  anthropicBaseUrl?: string;
+  openaiBaseUrl?: string;
+  authHeader?: "bearer" | "x-api-key";
+  apiDocsUrl?: string;
+};
+
+export async function addProviderImpl(
+  callApi: CallApiFn,
+  provider: AddProviderInput,
+): Promise<ToolResult> {
+  const res = await callApi("/api/providers", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(provider),
+  });
+  if (!res.ok) return toolError(`POST /api/providers returned ${res.status}`);
+  return textJson(await res.json());
+}
+
+export type UpdateProviderInput = {
+  id: string;
+  name?: string;
+  apiKey?: string;
+  format?: "anthropic" | "openai";
+  model?: string;
+  baseUrl?: string;
+  authHeader?: "bearer" | "x-api-key";
+  anthropicBaseUrl?: string;
+  openaiBaseUrl?: string;
+  apiDocsUrl?: string;
+};
+
+export async function updateProviderImpl(
+  callApi: CallApiFn,
+  input: UpdateProviderInput,
+): Promise<ToolResult> {
+  const { id, ...patch } = input;
+  const res = await callApi(`/api/providers/${encodeURIComponent(id)}`, {
+    method: "PUT",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(patch),
+  });
+  if (!res.ok) return toolError(`PUT /api/providers/${id} returned ${res.status}`);
+  return textJson(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());
+}
+
+/**
+ * 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: () => 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}`);
+  }
+}

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

@@ -30,11 +30,29 @@ export const OpenAIFunctionCall = z.object({
   arguments: z.string(),
 });
 
+/** A single OpenAI tool_call (the modern multi-tool form, returned by most
+ *  providers in `choices[].message.tool_calls`). `function.arguments` is
+ *  a JSON-encoded string per the OpenAI spec — we keep it as a string at
+ *  parse time and let the renderer decide whether to JSON-parse it for
+ *  display. */
+export const OpenAIToolCallSchema = z.object({
+  index: z.number().optional(),
+  id: z.string().optional(),
+  type: z.literal("function").optional(),
+  function: z.object({
+    name: z.string().optional(),
+    arguments: z.string().optional(),
+  }),
+});
+
+export type OpenAIToolCall = z.infer<typeof OpenAIToolCallSchema>;
+
 const OpenAIMessageWithFunctionCall = OpenAIMessage.extend({
   content: z
     .union([z.string(), z.array(z.object({ type: z.literal("text"), text: z.string() }))])
     .optional(),
   function_call: OpenAIFunctionCall.optional(),
+  tool_calls: z.array(OpenAIToolCallSchema).optional(),
 });
 
 export const OpenAIToolDefinition = z.object({
@@ -99,6 +117,7 @@ export const OpenAIChoice = z.object({
       thinking: z.string().optional(), // Some providers use 'thinking' field in message
       think: z.string().optional(), // MiniMax uses 'think' field in message
       function_call: z.object({ name: z.string(), arguments: z.string() }).nullable().optional(),
+      tool_calls: z.array(OpenAIToolCallSchema).optional(),
     })
     .optional(),
   delta: OpenAIChoiceDelta.optional(),

package/src/proxy/handler.ts

@@ -21,6 +21,7 @@ import {
 } from "./constants";
 import { getConfig } from "./config";
 import { stripClaudeCodeBillingHeader } from "./claudeCodeStrip";
+import { stripOpenAIOrphanToolMessages } from "./openaiOrphanToolStrip";
 import {
   buildUpstreamUrl,
   describeApiRoute,
@@ -89,17 +90,20 @@ function buildFileLogEntry(log: CapturedLog, upstreamUrl: string): Record<string
 type ParsedRequestPath = {
   apiPath: string;
   isMessages: boolean;
+  isChatCompletions: boolean;
   normalizedPath: string;
 };
 
 function parseRequestPath(req: Request, url: URL): ParsedRequestPath {
   const route = describeApiRoute(getProxyApiPath(url));
-  const isMessages =
-    req.method === "POST" && (route.endpointPath === PATH_V1_MESSAGES || route.isChatCompletions);
+  const isPost = req.method === "POST";
+  const isChatCompletions = isPost && route.isChatCompletions;
+  const isMessages = isPost && (route.endpointPath === PATH_V1_MESSAGES || route.isChatCompletions);
 
   return {
     apiPath: route.apiPath,
     isMessages,
+    isChatCompletions,
     normalizedPath: route.normalizedPath,
   };
 }
@@ -242,6 +246,23 @@ export async function handleProxy(req: Request): Promise<Response> {
     }
   }
 
+  // Always-on protocol guard: OpenAI Chat Completions requires every
+  // `role: "tool"` message to reference a `tool_call_id` present in a
+  // preceding assistant message's `tool_calls`. Buggy clients sometimes
+  // record a tool result without the matching assistant tool_call, which
+  // makes the upstream reject the request with a 400 ("tool result's tool
+  // id(call_xxx) not found"). Drop the orphan messages so the proxy can
+  // forward a valid request; the original body is still kept in the log.
+  if (bodyToForward !== null && parsed.isChatCompletions) {
+    const stripped = stripOpenAIOrphanToolMessages(bodyToForward);
+    if (stripped.removed > 0) {
+      logger.warn(
+        `[handler] Dropped ${stripped.removed} orphan OpenAI tool message(s) with tool_call_id(s) ${JSON.stringify(stripped.orphanIds)} — the client sent a tool result with no matching assistant.tool_calls`,
+      );
+      bodyToForward = stripped.body;
+    }
+  }
+
   // Parse the request body exactly once. The handler needs the model for
   // provider routing and the session id for the log; `createLog` would
   // otherwise re-parse the same body to extract the same fields.

package/src/proxy/openaiOrphanToolStrip.ts

@@ -0,0 +1,148 @@
+/**
+ * OpenAI Chat Completions protocol guard: orphan `tool` messages.
+ *
+ * The OpenAI Chat Completions spec requires every message with
+ * `role: "tool"` to reference a `tool_call_id` that appears in a preceding
+ * `assistant` message's `tool_calls` array. When this invariant is broken
+ * (typically by a buggy client that records a tool result without the
+ * matching assistant tool_call), the upstream rejects the request with a
+ * 400 like:
+ *
+ *   {"type":"error","error":{"type":"bad_request_error",
+ *     "message":"invalid params, tool result's tool id(call_xxx) not found"}}
+ *
+ * This module finds such orphan tool messages and returns a rewritten body
+ * with them removed so the proxy can forward a valid request. The original
+ * body is preserved by the caller for the captured log, so the inspector UI
+ * still shows the broken request the client actually sent.
+ */
+
+const ROLE_ASSISTANT = "assistant";
+const ROLE_TOOL = "tool";
+
+export type OrphanToolStripResult = {
+  /** The new request body. Equal to input (by reference) when no change was made. */
+  body: string;
+  /** Number of orphan tool messages removed. */
+  removed: number;
+  /**
+   * The `tool_call_id` values of the removed messages, in document order.
+   * `null` is used when a tool message had no `tool_call_id` at all.
+   */
+  orphanIds: Array<string | null>;
+};
+
+function getOwnProperty(obj: object, key: string): unknown {
+  const desc = Object.getOwnPropertyDescriptor(obj, key);
+  return desc?.value;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isObjectWithMessages(value: unknown): value is { messages: unknown[] } {
+  if (!isPlainObject(value)) return false;
+  if (!Object.prototype.hasOwnProperty.call(value, "messages")) return false;
+  const messages = getOwnProperty(value, "messages");
+  return Array.isArray(messages);
+}
+
+/**
+ * Collects the set of tool_call ids from an assistant message's `tool_calls`
+ * array. Tolerant of malformed entries: anything without a string `id` is
+ * skipped silently (those ids cannot be referenced by a tool message anyway).
+ */
+function collectAssistantToolCallIds(message: object, into: Set<string>): void {
+  const toolCalls = getOwnProperty(message, "tool_calls");
+  if (!Array.isArray(toolCalls)) return;
+  for (const tc of toolCalls) {
+    if (!isPlainObject(tc)) continue;
+    const id = getOwnProperty(tc, "id");
+    if (typeof id === "string" && id.length > 0) {
+      into.add(id);
+    }
+  }
+}
+
+/**
+ * Returns the indices of `tool`-role messages whose `tool_call_id` does not
+ * appear in any *preceding* assistant message's `tool_calls`. A tool message
+ * with no `tool_call_id` at all is also considered orphan.
+ *
+ * Pure, exported for unit tests. Used by `stripOpenAIOrphanToolMessages`.
+ */
+export function findOrphanToolMessageIndices(messages: readonly unknown[]): {
+  indices: number[];
+  orphanIds: Array<string | null>;
+} {
+  const knownToolCallIds = new Set<string>();
+  const indices: number[] = [];
+  const orphanIds: Array<string | null> = [];
+
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    if (!isPlainObject(msg)) continue;
+
+    const role = getOwnProperty(msg, "role");
+
+    if (role === ROLE_ASSISTANT) {
+      collectAssistantToolCallIds(msg, knownToolCallIds);
+      continue;
+    }
+
+    if (role === ROLE_TOOL) {
+      const id = getOwnProperty(msg, "tool_call_id");
+      if (typeof id !== "string" || id.length === 0) {
+        indices.push(i);
+        orphanIds.push(null);
+        continue;
+      }
+      if (!knownToolCallIds.has(id)) {
+        indices.push(i);
+        orphanIds.push(id);
+      }
+    }
+  }
+
+  return { indices, orphanIds };
+}
+
+/**
+ * Inspects an OpenAI-format request body and, if its `messages` array
+ * contains one or more orphan `tool` messages (see `findOrphanToolMessageIndices`),
+ * returns a new body with those messages removed. The original string is
+ * returned unchanged (by reference equality) when no edit is needed so the
+ * caller can skip a re-serialization.
+ *
+ * Tolerant of bodies that are not valid JSON, not OpenAI-format, or that
+ * have no `messages` array — all such inputs are returned unchanged.
+ */
+export function stripOpenAIOrphanToolMessages(rawBody: string): OrphanToolStripResult {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawBody);
+  } catch {
+    return { body: rawBody, removed: 0, orphanIds: [] };
+  }
+
+  if (!isObjectWithMessages(parsed)) {
+    return { body: rawBody, removed: 0, orphanIds: [] };
+  }
+
+  const messages = parsed.messages;
+  const { indices, orphanIds } = findOrphanToolMessageIndices(messages);
+
+  if (indices.length === 0) {
+    return { body: rawBody, removed: 0, orphanIds: [] };
+  }
+
+  const dropSet = new Set(indices);
+  const kept: unknown[] = [];
+  for (let i = 0; i < messages.length; i++) {
+    if (!dropSet.has(i)) kept.push(messages[i]);
+  }
+  parsed.messages = kept;
+
+  return { body: JSON.stringify(parsed), removed: indices.length, orphanIds };
+}

package/src/proxy/schemas.ts

@@ -98,6 +98,7 @@ export {
   OpenAIResponseSchema,
   OpenAISSERawChunkSchema,
   type OpenAIResponse,
+  type OpenAIToolCall,
   parseOpenAIResponse,
 } from "./formats/openai/schemas";
 

package/src/routes/api/mcp.ts

@@ -0,0 +1,25 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { handleMcpRequest } from "../../mcp/server";
+
+/**
+ * MCP HTTP Streamable transport endpoint. Mounted at `POST /api/mcp` on the
+ * existing TanStack Start HTTP server — see
+ * `openspec/changes/add-mcp-server/design.md` D1.
+ *
+ * All method/header routing is handled inside the SDK's
+ * `WebStandardStreamableHTTPServerTransport` (it dispatches GET for SSE
+ * stream, POST for client→server requests, DELETE for session close), so
+ * the route simply forwards the request.
+ */
+export const Route = createFileRoute("/api/mcp")({
+  server: {
+    handlers: {
+      // The SDK may issue either POST, GET, or DELETE. TanStack Start only
+      // requires us to declare the methods we accept; routing by method is
+      // handled inside the transport.
+      POST: ({ request }: { request: Request }) => handleMcpRequest(request),
+      GET: ({ request }: { request: Request }) => handleMcpRequest(request),
+      DELETE: ({ request }: { request: Request }) => handleMcpRequest(request),
+    },
+  },
+});