@tonyclaw/agent-inspector 2.0.0

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

@@ -0,0 +1,50 @@
+import type { CapturedLog } from "../../schemas";
+import type { ProviderProtocol } from "../protocol";
+import { registry } from "../providers";
+import { extractOpenAIStream } from "./stream";
+
+const DEFAULT_OPENAI_UPSTREAM = "https://api.openai.com/v1";
+
+/**
+ * OpenAI Provider Implementation
+ */
+export const openaiProvider: ProviderProtocol = {
+  name: "openai",
+
+  matches(model: string): boolean {
+    const modelLower = model.toLowerCase();
+    // Match OpenAI models
+    if (modelLower.startsWith("openai-")) {
+      return true;
+    }
+    // Also match common OpenAI model names
+    if (
+      modelLower.includes("gpt-") ||
+      modelLower.includes("o1") ||
+      modelLower.includes("o2") ||
+      modelLower.includes("o3")
+    ) {
+      return true;
+    }
+    return false;
+  },
+
+  getUpstreamBase(_isChatCompletions: boolean, providerConfig?: { baseUrl?: string }): string {
+    if (providerConfig?.baseUrl !== undefined) {
+      return providerConfig.baseUrl;
+    }
+    return DEFAULT_OPENAI_UPSTREAM;
+  },
+
+  extractStream(
+    raw: string,
+    log: CapturedLog,
+    fallbackModel?: string,
+    collectChunks?: boolean,
+  ): string {
+    return extractOpenAIStream(raw, log, fallbackModel, collectChunks);
+  },
+};
+
+// Register the provider
+registry.register(openaiProvider);

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

@@ -0,0 +1,4 @@
+import { formatRegistry } from "../registry";
+import { OpenAIFormatHandler } from "./handler";
+
+formatRegistry.register(OpenAIFormatHandler);

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

@@ -0,0 +1,187 @@
+import { z } from "zod";
+import { JsonValueSchema } from "../jsonSchema";
+
+// OpenAI Chat Completions Schemas
+
+export const OpenAIMessageContent = z.union([
+  z.string(),
+  z.array(
+    z.discriminatedUnion("type", [
+      z.object({ type: z.literal("text"), text: z.string() }),
+      z.object({
+        type: z.literal("image_url"),
+        image_url: z.object({ url: z.string(), detail: z.string().optional() }),
+      }),
+    ]),
+  ),
+]);
+
+export const OpenAIMessage = z.object({
+  role: z.enum(["system", "user", "assistant", "tool"]),
+  content: OpenAIMessageContent,
+  name: z.string().optional(),
+  reasoning_content: z.string().optional(),
+  thinking: z.string().optional(), // Some providers use 'thinking' field
+  think: z.string().optional(), // MiniMax uses 'think' field
+});
+
+export const OpenAIFunctionCall = z.object({
+  name: z.string(),
+  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({
+  type: z.literal("function"),
+  function: z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    parameters: z.record(z.string(), JsonValueSchema),
+  }),
+});
+
+export const OpenAIRequestSchema = z.object({
+  model: z.string(),
+  messages: z.array(OpenAIMessage),
+  temperature: z.number().optional(),
+  max_tokens: z.number().optional(),
+  stream: z.boolean().optional(),
+  tools: z.array(OpenAIToolDefinition).optional(),
+  tool_choice: z
+    .union([
+      z.enum(["auto", "none", "required"]),
+      z.object({ type: z.literal("auto") }),
+      z.object({ type: z.literal("none") }),
+      z.object({ type: z.literal("function"), function: z.object({ name: z.string() }) }),
+    ])
+    .optional(),
+  user: z.string().optional(),
+});
+
+export const OpenAIChoiceDelta = z.object({
+  role: z.enum(["assistant"]).optional(),
+  content: z.string().nullable().optional(),
+  reasoning_content: z.string().nullable().optional(),
+  thinking: z.string().nullable().optional(), // Some providers use 'thinking' field
+  think: z.string().nullable().optional(), // MiniMax uses 'think' field
+  function_call: z
+    .object({ name: z.string().optional(), arguments: z.string().optional() })
+    .nullable()
+    .optional(),
+  tool_calls: z
+    .array(
+      z.object({
+        index: z.number(),
+        id: z.string().optional(),
+        type: z.literal("function").optional(),
+        function: z.object({
+          name: z.string().optional(),
+          arguments: z.string().optional(),
+        }),
+      }),
+    )
+    .nullable()
+    .optional(),
+});
+
+export const OpenAIChoice = z.object({
+  index: z.number(),
+  message: z
+    .object({
+      role: z.enum(["assistant"]),
+      content: z.string().nullable(),
+      reasoning_content: z.string().optional(),
+      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(),
+  finish_reason: z.string().nullable(),
+});
+
+export const OpenAIResponseSchema = z
+  .object({
+    id: z.string(),
+    object: z.literal("chat.completion"),
+    created: z.number(),
+    model: z.string(),
+    choices: z.array(OpenAIChoice),
+    usage: z
+      .object({
+        prompt_tokens: z.number().nullable().optional(),
+        completion_tokens: z.number().nullable().optional(),
+        total_tokens: z.number().nullable().optional(),
+      })
+      .passthrough(), // Allow extra fields like prompt_tokens_details, completion_tokens_details
+    service_tier: z.string().nullable().optional(),
+    system_fingerprint: z.string().nullable().optional(),
+  })
+  .passthrough(); // Allow extra fields like refusal, annotations, audio
+
+// Schema for actual OpenAI SSE chunk format (not wrapped in event/data)
+export const OpenAISSERawChunkSchema = z
+  .object({
+    id: z.string(),
+    object: z.literal("chat.completion.chunk"),
+    created: z.number(),
+    model: z.string(),
+    choices: z.array(
+      z.object({
+        index: z.number(),
+        delta: OpenAIChoiceDelta,
+        finish_reason: z.string().nullable().optional(),
+      }),
+    ),
+    usage: z
+      .object({
+        prompt_tokens: z.number().nullable().optional(),
+        completion_tokens: z.number().nullable().optional(),
+        total_tokens: z.number().nullable().optional(),
+      })
+      .passthrough()
+      .nullable()
+      .optional(),
+  })
+  .passthrough(); // Allow extra fields in chunks
+
+export type OpenAIResponse = z.infer<typeof OpenAIResponseSchema>;
+
+/**
+ * Parse an OpenAI response body.
+ */
+export function parseOpenAIResponse(rawBody: string): OpenAIResponse | null {
+  try {
+    const json: unknown = JSON.parse(rawBody);
+    const result = OpenAIResponseSchema.safeParse(json);
+    if (result.success) return result.data;
+    return null;
+  } catch {
+    return null;
+  }
+}

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

@@ -0,0 +1,206 @@
+import type { CapturedLog, JsonValue } from "../../schemas";
+import { trustAsJsonValue } from "../jsonSchema";
+import { OpenAISSERawChunkSchema } from "./schemas";
+
+/**
+ * Extract OpenAI streaming response and return normalized JSON.
+ * Optionally collects SSE chunks into log.streamingChunks for debugging/display.
+ */
+export function extractOpenAIStream(
+  raw: string,
+  log: CapturedLog,
+  fallbackModel?: string,
+  collectChunks: boolean = true,
+): string {
+  let id = "";
+  let model = "";
+  let completionContent = "";
+  let reasoningContent = "";
+  let finishReason: string | null = null;
+  let promptTokens = 0;
+  let completionTokens = 0;
+  let usageCaptured = false;
+  let started = false;
+  type ToolCallEntry = {
+    index: number;
+    id?: string;
+    type: "function";
+    function: { name: string; arguments: string };
+  };
+  // Map keyed by `index` so delta accumulation is O(1) per delta instead of
+  // O(N) (the previous Array#find). Map preserves insertion order, so the
+  // final `[...toolCalls.values()]` keeps tool calls in the order they were
+  // first seen.
+  const toolCalls: Map<number, ToolCallEntry> = new Map();
+
+  // Chunk collection state
+  const MAX_CHUNKS = 1000;
+  let chunkIndex = 0;
+  let streamStartMs = 0;
+  const chunks: Array<{ index: number; timestamp: number; type: string; data: JsonValue }> = [];
+
+  for (const line of raw.split("\n")) {
+    const trimmedLine = line.trim();
+    if (!trimmedLine.startsWith("data: ")) continue;
+    const dataStr = trimmedLine.slice(6);
+    if (dataStr === "[DONE]") break;
+
+    try {
+      const parsed: unknown = JSON.parse(dataStr);
+      // Check for error object in SSE stream before trying to parse as chunk
+      if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+        const errorDesc = Object.getOwnPropertyDescriptor(parsed, "error");
+        if (
+          errorDesc !== undefined &&
+          typeof errorDesc.value === "object" &&
+          errorDesc.value !== null
+        ) {
+          const msgDesc = Object.getOwnPropertyDescriptor(errorDesc.value, "message");
+          if (msgDesc !== undefined && typeof msgDesc.value === "string") {
+            log.error = msgDesc.value;
+          }
+          continue;
+        }
+      }
+      const chunkResult = OpenAISSERawChunkSchema.safeParse(parsed);
+      if (!chunkResult.success) continue;
+      const chunk = chunkResult.data;
+
+      // Track stream start for timestamps
+      if (chunkIndex === 0) streamStartMs = Date.now();
+
+      // Collect chunks if enabled
+      if (collectChunks === true && chunks.length < MAX_CHUNKS) {
+        // `chunk` has already been validated by OpenAISSERawChunkSchema above;
+        // skipping the recursive JsonValue walk avoids a second full-tree zod
+        // parse on every SSE event. See trustAsJsonValue for the rationale.
+        chunks.push({
+          index: chunkIndex,
+          timestamp: Date.now() - streamStartMs,
+          type: "chat.completion.chunk",
+          data: trustAsJsonValue(chunk),
+        });
+      }
+      chunkIndex++;
+
+      if (!started) {
+        id = chunk.id;
+        model = chunk.model;
+        started = true;
+      }
+
+      if (!usageCaptured && chunk.usage !== undefined && chunk.usage !== null) {
+        promptTokens = chunk.usage.prompt_tokens ?? 0;
+        completionTokens = chunk.usage.completion_tokens ?? 0;
+        log.inputTokens = promptTokens;
+        // Extract cached_tokens from raw parsed object (passthrough field in usage)
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+          const usageDesc = Object.getOwnPropertyDescriptor(parsed, "usage");
+          if (
+            usageDesc !== undefined &&
+            typeof usageDesc.value === "object" &&
+            usageDesc.value !== null
+          ) {
+            const detailsDesc = Object.getOwnPropertyDescriptor(
+              usageDesc.value,
+              "prompt_tokens_details",
+            );
+            if (
+              detailsDesc !== undefined &&
+              typeof detailsDesc.value === "object" &&
+              detailsDesc.value !== null
+            ) {
+              const cacheDesc = Object.getOwnPropertyDescriptor(detailsDesc.value, "cached_tokens");
+              if (cacheDesc !== undefined && typeof cacheDesc.value === "number") {
+                log.cacheReadInputTokens = cacheDesc.value;
+              }
+            }
+          }
+        }
+        usageCaptured = true;
+      }
+
+      for (const choice of chunk.choices) {
+        const delta = choice.delta;
+        if (delta.content !== undefined && delta.content !== null) {
+          completionContent += delta.content;
+        }
+        if (delta.reasoning_content !== undefined && delta.reasoning_content !== null) {
+          reasoningContent += delta.reasoning_content;
+        }
+        if (delta.thinking !== undefined && delta.thinking !== null) {
+          reasoningContent += delta.thinking;
+        }
+        // MiniMax uses 'think' field for thinking content - check via bracket notation
+        const thinkValue = delta.think;
+        if (thinkValue !== undefined && thinkValue !== null) {
+          reasoningContent += thinkValue;
+        }
+        if (choice.finish_reason !== undefined && choice.finish_reason !== null) {
+          finishReason = choice.finish_reason;
+        }
+        // Accumulate tool_calls
+        if (delta.tool_calls !== undefined && delta.tool_calls !== null) {
+          for (const tc of delta.tool_calls) {
+            // Find or create tool call entry by index
+            let existing = toolCalls.get(tc.index);
+            if (existing === undefined) {
+              existing = {
+                index: tc.index,
+                type: "function",
+                function: { name: "", arguments: "" },
+              };
+              toolCalls.set(tc.index, existing);
+            }
+            if (tc.id !== undefined) existing.id = tc.id;
+            if (tc.function?.name !== undefined) existing.function.name += tc.function.name;
+            if (tc.function?.arguments !== undefined)
+              existing.function.arguments += tc.function.arguments;
+          }
+        }
+      }
+    } catch {
+      // non-JSON SSE line, skip
+    }
+  }
+
+  // Store collected chunks on the log
+  if (collectChunks === true) {
+    log.streamingChunks = {
+      chunks,
+      truncated: chunkIndex > MAX_CHUNKS,
+    };
+  }
+
+  if (!usageCaptured) {
+    completionTokens = Math.ceil(completionContent.length / 4);
+  }
+
+  log.outputTokens = completionTokens;
+
+  const message: Record<string, unknown> = {
+    role: "assistant",
+    content: completionContent,
+  };
+  if (reasoningContent) message.reasoning_content = reasoningContent;
+  if (toolCalls.size > 0) message.tool_calls = [...toolCalls.values()];
+
+  return JSON.stringify({
+    id,
+    object: "chat.completion",
+    created: Math.floor(Date.now() / 1000),
+    model: model !== "" ? model : (fallbackModel ?? ""),
+    choices: [
+      {
+        index: 0,
+        message,
+        finish_reason: finishReason,
+      },
+    ],
+    usage: {
+      prompt_tokens: promptTokens,
+      completion_tokens: completionTokens,
+      total_tokens: promptTokens + completionTokens,
+    },
+  });
+}

package/src/proxy/formats/protocol.ts

@@ -0,0 +1,50 @@
+import type { CapturedLog, RequestFormat } from "../schemas";
+
+/**
+ * Provider Protocol Interface
+ *
+ * Defines the contract that all providers must implement to support
+ * different LLM APIs (Anthropic, OpenAI, etc.).
+ */
+export type ProviderProtocol = {
+  /** Provider identifier (e.g., "anthropic", "openai") */
+  name: string;
+
+  /**
+   * Check if this provider handles the given model.
+   * @param model - Model name from request
+   * @returns true if this provider should handle the model
+   */
+  matches(model: string): boolean;
+
+  /**
+   * Get the upstream base URL for this provider.
+   * @param isChatCompletions - Whether the request uses OpenAI chat completions format
+   * @param providerConfig - Optional provider configuration for custom base URL
+   * @returns Upstream base URL
+   */
+  getUpstreamBase(isChatCompletions: boolean, providerConfig?: { baseUrl?: string }): string;
+
+  /**
+   * Extract structured response from streaming data.
+   * @param raw - Raw SSE stream data
+   * @param log - Captured log entry to update
+   * @param fallbackModel - Fallback model name if not in stream
+   * @param collectChunks - Whether to collect SSE chunks into log.streamingChunks
+   * @returns JSON string of structured response
+   */
+  extractStream(
+    raw: string,
+    log: CapturedLog,
+    fallbackModel?: string,
+    collectChunks?: boolean,
+  ): string;
+
+  /**
+   * Optional request transformation hook.
+   * @param body - Original request body
+   * @param apiFormat - Request format (anthropic/openai/unknown)
+   * @returns Transformed body or null to use original
+   */
+  transformRequest?(body: string, apiFormat: RequestFormat): string | null;
+};

package/src/proxy/formats/providerRegistry.ts

@@ -0,0 +1,51 @@
+import type { ProviderProtocol } from "./protocol";
+
+/**
+ * Provider Registry
+ *
+ * Singleton registry for provider implementations.
+ * Providers register themselves at module load time.
+ */
+class ProviderRegistryImpl {
+  private providers: ProviderProtocol[] = [];
+
+  /**
+   * Register a provider with the registry.
+   * @param provider - Provider implementation to register
+   */
+  register(provider: ProviderProtocol): void {
+    this.providers.push(provider);
+  }
+
+  /**
+   * Find the first provider that matches the given model.
+   * @param model - Model name to match
+   * @returns Matching provider or null if none found
+   */
+  findProvider(model: string): ProviderProtocol | null {
+    let fallback: ProviderProtocol | null = null;
+
+    for (const provider of this.providers) {
+      if (provider.matches(model)) {
+        // Non-anthropic providers win immediately (explicit match)
+        if (provider.name !== "anthropic") {
+          return provider;
+        }
+        // Anthropic is the fallback — only use if nothing else matches
+        fallback = provider;
+      }
+    }
+    return fallback;
+  }
+
+  /**
+   * Get all registered providers.
+   * @returns Array of all registered providers
+   */
+  getAll(): ProviderProtocol[] {
+    return [...this.providers];
+  }
+}
+
+/** Global registry instance */
+export const registry = new ProviderRegistryImpl();

package/src/proxy/formats/providers/index.ts

@@ -0,0 +1,3 @@
+// Provider types and registry
+export type { ProviderProtocol } from "../protocol";
+export { registry } from "../providerRegistry";

package/src/proxy/formats/registry.ts

@@ -0,0 +1,66 @@
+import type { FormatHandler } from "./handler";
+import type { RequestFormat } from "../schemas";
+import { PATH_V1_CHAT_COMPLETIONS, PATH_CHAT_COMPLETIONS, PATH_V1_MESSAGES } from "../constants";
+
+/**
+ * Format registry — maps request paths and formats to their FormatHandler.
+ *
+ * Registered at module load time by each format's init module.
+ */
+class FormatRegistryImpl {
+  private handlers = new Map<RequestFormat, FormatHandler>();
+  private pathMap = new Map<string, RequestFormat>();
+
+  register(handler: FormatHandler): void {
+    this.handlers.set(handler.format, handler);
+  }
+
+  registerPath(path: string, format: RequestFormat): void {
+    this.pathMap.set(path, format);
+  }
+
+  /** Get handler by format identifier */
+  get(format: RequestFormat): FormatHandler | undefined {
+    return this.handlers.get(format);
+  }
+
+  /** Get handler matching a request path */
+  getByPath(path: string): FormatHandler | undefined {
+    const messagesPath = path.split("?")[0] ?? "";
+    const format = this.pathMap.get(messagesPath);
+    return format === undefined ? undefined : this.handlers.get(format);
+  }
+
+  /** Detect format from request body content */
+  detectFormat(rawBody: string | null): RequestFormat {
+    if (rawBody === null) return "unknown";
+    for (const handler of this.handlers.values()) {
+      if (handler.detectFormat(rawBody)) return handler.format;
+    }
+    return "unknown";
+  }
+}
+
+export const formatRegistry = new FormatRegistryImpl();
+
+/**
+ * Get the FormatHandler for a request path.
+ * Returns null if no format matches the path.
+ */
+export function formatForPath(path: string): FormatHandler | null {
+  return formatRegistry.getByPath(path) ?? null;
+}
+
+/**
+ * Resolve the wire format from the request endpoint. The endpoint is
+ * authoritative because Anthropic and OpenAI request bodies overlap for
+ * simple message-only calls.
+ */
+export function requestFormatForPath(path: string): RequestFormat {
+  return formatForPath(path)?.format ?? "unknown";
+}
+
+// Register known paths
+formatRegistry.registerPath(PATH_V1_MESSAGES, "anthropic");
+formatRegistry.registerPath(PATH_V1_CHAT_COMPLETIONS, "openai");
+formatRegistry.registerPath(PATH_CHAT_COMPLETIONS, "openai");