@tonyclaw/agent-inspector 2.0.0

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

@@ -0,0 +1,237 @@
+import { z } from "zod";
+import { JsonValueSchema } from "../jsonSchema";
+
+const CacheControl = z.object({
+  type: z.string(),
+  ttl: z.string().optional(),
+  scope: z.string().optional(),
+});
+
+const TextContentBlock = z.object({
+  type: z.literal("text"),
+  text: z.string(),
+  cache_control: CacheControl.optional(),
+});
+
+const ThinkingContentBlock = z.object({
+  type: z.literal("thinking"),
+  thinking: z.string(),
+  signature: z.string().optional(),
+});
+
+const ThinkContentBlock = z.object({
+  type: z.literal("think"),
+  thinking: z.string(),
+  signature: z.string().optional(),
+});
+
+const ImageSourceBlock = z.object({
+  type: z.literal("base64"),
+  media_type: z.string(),
+  data: z.string(),
+});
+
+const ImageContentBlock = z.object({
+  type: z.literal("image"),
+  source: ImageSourceBlock,
+});
+
+const ToolUseContentBlock = z.object({
+  type: z.literal("tool_use"),
+  id: z.string(),
+  name: z.string(),
+  input: z.record(z.string(), JsonValueSchema),
+});
+
+const ToolResultContentItem = z.discriminatedUnion("type", [TextContentBlock, ImageContentBlock]);
+
+const ToolResultContentBlock = z.object({
+  type: z.literal("tool_result"),
+  tool_use_id: z.string().optional(),
+  content: z.union([z.string(), z.array(ToolResultContentItem)]),
+  is_error: z.boolean().optional(),
+});
+
+const ContentBlock = z.discriminatedUnion("type", [
+  TextContentBlock,
+  ThinkingContentBlock,
+  ImageContentBlock,
+  ToolUseContentBlock,
+  ToolResultContentBlock,
+]);
+
+const MessageContent = z.union([z.string(), z.array(ContentBlock)]);
+
+const Message = z.object({
+  role: z.enum(["user", "assistant"]),
+  content: MessageContent,
+});
+
+const SystemBlock = z.object({
+  type: z.literal("text"),
+  text: z.string(),
+  cache_control: CacheControl.optional(),
+});
+
+const InputSchema = z.object({
+  type: z.string(),
+  properties: z.record(z.string(), z.record(z.string(), JsonValueSchema)).optional(),
+  required: z.array(z.string()).optional(),
+  additionalProperties: z.boolean().optional(),
+  $schema: z.string().optional(),
+});
+
+const ToolDefinition = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+  input_schema: InputSchema.optional(),
+  cache_control: CacheControl.optional(),
+});
+
+const ThinkingConfig = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("enabled"), budget_tokens: z.number() }),
+  z.object({ type: z.literal("disabled") }),
+  z.object({ type: z.literal("adaptive") }),
+]);
+
+export const AnthropicRequestSchema = z.object({
+  model: z.string(),
+  messages: z.array(Message),
+  system: z.array(SystemBlock).optional(),
+  tools: z.array(ToolDefinition).optional(),
+  max_tokens: z.number().optional(),
+  temperature: z.number().optional(),
+  stream: z.boolean().optional(),
+  thinking: ThinkingConfig.optional(),
+  metadata: z
+    .object({
+      user_id: z.string().optional(),
+    })
+    .optional(),
+});
+
+const ResponseContentBlock = z.discriminatedUnion("type", [
+  TextContentBlock,
+  ThinkingContentBlock,
+  ThinkContentBlock,
+  ToolUseContentBlock,
+]);
+
+const ResponseUsageSchema = z
+  .object({
+    input_tokens: z.number().nullable().optional(),
+    output_tokens: z.number().nullable().optional(),
+    cache_creation_input_tokens: z.number().nullable().optional(),
+    cache_read_input_tokens: z.number().nullable().optional(),
+  })
+  .passthrough(); // Allow extra fields from different providers
+
+export const AnthropicResponseSchema = z
+  .object({
+    id: z.string(),
+    type: z.literal("message"),
+    model: z.string(),
+    role: z.literal("assistant"),
+    content: z.array(ResponseContentBlock),
+    stop_reason: z.string().nullable(),
+    stop_sequence: z.string().nullable().optional(),
+    usage: ResponseUsageSchema,
+  })
+  .passthrough(); // Allow extra unknown fields
+
+const SseMessageStartEvent = z.object({
+  type: z.literal("message_start"),
+  message: z.object({
+    id: z.string(),
+    type: z.literal("message"),
+    model: z.string(),
+    role: z.literal("assistant"),
+    content: z.array(ResponseContentBlock),
+    stop_reason: z.null(),
+    stop_sequence: z.null(),
+    usage: z
+      .object({
+        input_tokens: z.number(),
+        cache_creation_input_tokens: z.number().optional(),
+        cache_read_input_tokens: z.number().optional(),
+      })
+      .passthrough(),
+  }),
+});
+
+const SseContentBlockStartEvent = z.object({
+  type: z.literal("content_block_start"),
+  index: z.number(),
+  content_block: ResponseContentBlock,
+});
+
+const SseDeltaBlock = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("text_delta"), text: z.string() }),
+  z.object({ type: z.literal("input_json_delta"), partial_json: z.string() }),
+  z.object({ type: z.literal("thinking_delta"), thinking: z.string() }),
+  z.object({ type: z.literal("signature_delta"), signature: z.string() }),
+]);
+
+const SseContentBlockDeltaEvent = z.object({
+  type: z.literal("content_block_delta"),
+  index: z.number(),
+  delta: SseDeltaBlock,
+});
+
+const SseContentBlockStopEvent = z.object({
+  type: z.literal("content_block_stop"),
+  index: z.number(),
+});
+
+const SseMessageDeltaEvent = z.object({
+  type: z.literal("message_delta"),
+  delta: z.object({
+    stop_reason: z.string().nullable(),
+    stop_sequence: z.string().nullable().optional(),
+  }),
+  usage: z
+    .object({
+      output_tokens: z.number(),
+      input_tokens: z.number().optional(),
+      cache_creation_input_tokens: z.number().optional(),
+      cache_read_input_tokens: z.number().optional(),
+    })
+    .passthrough(),
+});
+
+const SseMessageStopEvent = z.object({
+  type: z.literal("message_stop"),
+});
+
+const SsePingEvent = z.object({
+  type: z.literal("ping"),
+});
+
+const SseErrorEvent = z.object({
+  type: z.literal("error"),
+  error: z.object({
+    type: z.string(),
+    message: z.string(),
+  }),
+});
+
+export const SseEventSchema = z.discriminatedUnion("type", [
+  SseMessageStartEvent,
+  SseContentBlockStartEvent,
+  SseContentBlockDeltaEvent,
+  SseContentBlockStopEvent,
+  SseMessageDeltaEvent,
+  SseMessageStopEvent,
+  SsePingEvent,
+  SseErrorEvent,
+]);
+
+export type AnthropicRequest = z.infer<typeof AnthropicRequestSchema>;
+export type AnthropicResponse = z.infer<typeof AnthropicResponseSchema>;
+export type ResponseContentBlockType = z.infer<typeof ResponseContentBlock>;
+
+// Backward-compatible aliases (originally named Inspector*)
+export const InspectorRequestSchema = AnthropicRequestSchema;
+export const InspectorResponseSchema = AnthropicResponseSchema;
+export type InspectorRequest = AnthropicRequest;
+export type InspectorResponse = AnthropicResponse;

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

@@ -0,0 +1,205 @@
+import type { CapturedLog, JsonValue } from "../../schemas";
+import { trustAsJsonValue } from "../jsonSchema";
+import { SseEventSchema } from "./schemas";
+
+type StreamTextBlock = { type: "text"; text: string };
+type StreamThinkingBlock = { type: "thinking"; thinking: string; signature: string };
+type StreamThinkBlock = { type: "think"; thinking: string; signature: string };
+type StreamToolUseBlock = { type: "tool_use"; id: string; name: string; inputJson: string };
+type StreamBlock = StreamTextBlock | StreamThinkingBlock | StreamThinkBlock | StreamToolUseBlock;
+
+function parseInputJson(json: string): Record<string, unknown> {
+  if (json === "") return {};
+  try {
+    const parsed: unknown = JSON.parse(json);
+    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return { ...parsed };
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+
+function finalizeBlock(block: StreamBlock): Record<string, unknown> {
+  switch (block.type) {
+    case "text":
+      return { type: "text", text: block.text };
+    case "thinking": {
+      const out: Record<string, unknown> = { type: "thinking", thinking: block.thinking };
+      if (block.signature !== "") out.signature = block.signature;
+      return out;
+    }
+    case "think": {
+      const out: Record<string, unknown> = { type: "think", thinking: block.thinking };
+      if (block.signature !== "") out.signature = block.signature;
+      return out;
+    }
+    case "tool_use":
+      return {
+        type: "tool_use",
+        id: block.id,
+        name: block.name,
+        input: parseInputJson(block.inputJson),
+      };
+  }
+}
+
+/**
+ * Extract Anthropic streaming response and return normalized JSON.
+ * Optionally collects SSE chunks into log.streamingChunks for debugging/display.
+ */
+export function extractAnthropicStream(
+  raw: string,
+  log: CapturedLog,
+  fallbackModel?: string,
+  collectChunks?: boolean,
+): string {
+  const blocks = new Map<number, StreamBlock>();
+  let id = "";
+  let model = "";
+  let stopReason: string | null = null;
+  let stopSequence: string | null = null;
+  let inputTokens = 0;
+  let outputTokens = 0;
+
+  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;
+    try {
+      const json: unknown = JSON.parse(trimmedLine.slice(6));
+      const parsed = SseEventSchema.safeParse(json);
+      if (!parsed.success) continue;
+      const data = parsed.data;
+
+      if (chunkIndex === 0) streamStartMs = Date.now();
+
+      if (collectChunks === true && chunks.length < MAX_CHUNKS) {
+        chunks.push({
+          index: chunkIndex,
+          timestamp: Date.now() - streamStartMs,
+          type: data.type,
+          // `data` has already been validated by SseEventSchema above; the
+          // recursive JsonValue walk is a redundant full-tree zod parse on
+          // every SSE event. See trustAsJsonValue for the rationale.
+          data: trustAsJsonValue(data),
+        });
+      }
+      chunkIndex++;
+
+      switch (data.type) {
+        case "message_start":
+          id = data.message.id;
+          model = data.message.model;
+          inputTokens = data.message.usage.input_tokens;
+          log.inputTokens = inputTokens;
+          log.cacheCreationInputTokens = data.message.usage.cache_creation_input_tokens ?? null;
+          log.cacheReadInputTokens = data.message.usage.cache_read_input_tokens ?? null;
+          if (log.model === null) log.model = model;
+          break;
+        case "content_block_start": {
+          const cb = data.content_block;
+          switch (cb.type) {
+            case "text":
+              blocks.set(data.index, { type: "text", text: cb.text ?? "" });
+              break;
+            case "thinking":
+              blocks.set(data.index, {
+                type: "thinking",
+                thinking: cb.thinking ?? "",
+                signature: cb.signature ?? "",
+              });
+              break;
+            case "think":
+              blocks.set(data.index, {
+                type: "think",
+                thinking: cb.thinking ?? "",
+                signature: cb.signature ?? "",
+              });
+              break;
+            case "tool_use":
+              blocks.set(data.index, {
+                type: "tool_use",
+                id: cb.id,
+                name: cb.name,
+                inputJson: "",
+              });
+              break;
+          }
+          break;
+        }
+        case "content_block_delta": {
+          const block = blocks.get(data.index);
+          if (block === undefined) break;
+          const delta = data.delta;
+          if (delta.type === "text_delta" && block.type === "text") {
+            block.text += delta.text;
+          } else if (
+            delta.type === "thinking_delta" &&
+            (block.type === "thinking" || block.type === "think")
+          ) {
+            block.thinking += delta.thinking;
+          } else if (
+            delta.type === "signature_delta" &&
+            (block.type === "thinking" || block.type === "think")
+          ) {
+            block.signature += delta.signature;
+          } else if (delta.type === "input_json_delta" && block.type === "tool_use") {
+            block.inputJson += delta.partial_json;
+          }
+          break;
+        }
+        case "message_delta":
+          stopReason = data.delta.stop_reason;
+          stopSequence = data.delta.stop_sequence ?? null;
+          outputTokens = data.usage.output_tokens;
+          log.outputTokens = outputTokens;
+          // Cache tokens may also be present in message_delta usage
+          if (data.usage.cache_creation_input_tokens !== undefined) {
+            log.cacheCreationInputTokens = data.usage.cache_creation_input_tokens;
+          }
+          if (data.usage.cache_read_input_tokens !== undefined) {
+            log.cacheReadInputTokens = data.usage.cache_read_input_tokens;
+          }
+          break;
+        case "error":
+          // Store error info on the log for display
+          log.error = data.error.message;
+          break;
+        case "content_block_stop":
+        case "message_stop":
+        case "ping":
+          break;
+      }
+    } catch {
+      // non-JSON SSE line, skip
+    }
+  }
+
+  if (collectChunks === true) {
+    log.streamingChunks = {
+      chunks,
+      truncated: chunkIndex > MAX_CHUNKS,
+    };
+  }
+
+  const orderedContent = [...blocks.entries()]
+    .sort(([a], [b]) => a - b)
+    .map(([, block]) => finalizeBlock(block));
+
+  return JSON.stringify({
+    id,
+    type: "message",
+    model: model !== "" ? model : (fallbackModel ?? ""),
+    role: "assistant",
+    content: orderedContent,
+    stop_reason: stopReason,
+    stop_sequence: stopSequence,
+    usage: { input_tokens: inputTokens, output_tokens: outputTokens },
+  });
+}

package/src/proxy/formats/handler.ts

@@ -0,0 +1,46 @@
+import type { CapturedLog, RequestFormat, TokenUsage } from "../schemas";
+
+/**
+ * Structured result of parsing a raw request body.
+ */
+export type ParsedRequest = {
+  model: string | null;
+  sessionId: string | null;
+};
+
+/**
+ * FormatHandler defines the contract for all API format implementations.
+ *
+ * Each API format (Anthropic, OpenAI) provides its own handler that encapsulates
+ * request parsing, response parsing, SSE stream extraction, and token extraction.
+ * This replaces the scattered if/else format branching previously in handler.ts.
+ */
+export type FormatHandler = {
+  /** The format identifier */
+  readonly format: RequestFormat;
+
+  /**
+   * Parse a raw request body to extract model name and metadata.
+   */
+  parseRequest(rawBody: string, headers?: Headers): ParsedRequest | null;
+
+  /**
+   * Extract token usage from a non-streaming response body.
+   */
+  extractTokens(responseBody: string): TokenUsage;
+
+  /**
+   * Extract structured content from a streaming SSE response.
+   */
+  extractStream(
+    raw: string,
+    log: CapturedLog,
+    fallbackModel?: string,
+    collectChunks?: boolean,
+  ): string;
+
+  /**
+   * Detect if a raw request body uses this format.
+   */
+  detectFormat(rawBody: string | null): boolean;
+};

package/src/proxy/formats/index.ts

@@ -0,0 +1,12 @@
+// Import submodules to trigger handler registration
+import "./anthropic/index";
+import "./openai/index";
+
+// Import providers to trigger self-registration
+import "./anthropic/anthropicProvider";
+import "./openai/provider";
+import "./openai/alibabaProvider";
+
+export type { FormatHandler, ParsedRequest } from "./handler";
+export { formatRegistry, formatForPath, requestFormatForPath } from "./registry";
+export { registry } from "./providers";

package/src/proxy/formats/jsonSchema.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+
+/**
+ * Shared JSON value type for streaming chunks.
+ * Defined in a separate file to avoid circular dependencies.
+ */
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export const JsonValueSchema: z.ZodType<JsonValue> = z.lazy(() =>
+  z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(JsonValueSchema),
+    z.record(z.string(), JsonValueSchema),
+  ]),
+);
+
+/**
+ * Re-types a value as `JsonValue` without re-walking it. Use this ONLY when
+ * the value has already been validated (e.g., via `SseEventSchema.safeParse`)
+ * AND originated from `JSON.parse`. Skipping the recursive `JsonValueSchema`
+ * walk avoids a second full-tree zod parse on every event of every streaming
+ * response. Centralized here so the eslint-disable is one site, not two.
+ */
+export function trustAsJsonValue<T>(value: T): JsonValue {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  return value as unknown as JsonValue;
+}

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

@@ -0,0 +1,38 @@
+import type { CapturedLog } from "../../schemas";
+import type { ProviderProtocol } from "../protocol";
+import { registry } from "../providers";
+import { extractOpenAIStream } from "./stream";
+
+const DEFAULT_ALIBABA_UPSTREAM = "https://dashscope.aliyuncs.com/compatible-mode/v1";
+
+/**
+ * Alibaba Provider Implementation (DashScope)
+ */
+export const alibabaProvider: ProviderProtocol = {
+  name: "alibaba",
+
+  matches(model: string): boolean {
+    // Normalize: lowercase, replace whitespace with hyphens
+    const m = model.toLowerCase().replace(/\s+/g, "-");
+    // Match glm-5* and glm-5.1* models
+    if (m.startsWith("glm-5")) {
+      return true;
+    }
+    // Match qwen models (qwen3.6-plus, qwen3.7-max, Qwen3.6 Plus, etc.)
+    if (m.startsWith("qwen")) {
+      return true;
+    }
+    return false;
+  },
+
+  getUpstreamBase(_isChatCompletions: boolean, _providerConfig?: { baseUrl?: string }): string {
+    return DEFAULT_ALIBABA_UPSTREAM;
+  },
+
+  extractStream(raw: string, log: CapturedLog, fallbackModel?: string): string {
+    return extractOpenAIStream(raw, log, fallbackModel);
+  },
+};
+
+// Register the provider
+registry.register(alibabaProvider);

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

@@ -0,0 +1,96 @@
+import type { FormatHandler, ParsedRequest } from "../handler";
+import type { CapturedLog, TokenUsage } from "../../schemas";
+import { OpenAIRequestSchema, OpenAIResponseSchema, parseOpenAIResponse } from "./schemas";
+import { extractOpenAIStream } from "./stream";
+
+export const OpenAIFormatHandler: FormatHandler = {
+  format: "openai",
+
+  parseRequest(rawBody: string, headers?: Headers): ParsedRequest | null {
+    try {
+      const json: unknown = JSON.parse(rawBody);
+      const result = OpenAIRequestSchema.safeParse(json);
+      if (result.success) {
+        return {
+          model: result.data.model,
+          sessionId: headers?.get("x-session-affinity") ?? null,
+        };
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  },
+
+  extractTokens(responseBody: string): TokenUsage {
+    const parsed = parseOpenAIResponse(responseBody);
+    if (parsed) {
+      // OpenAI puts cached_tokens in usage.prompt_tokens_details (passthrough field)
+      let cacheReadInputTokens: number | null = null;
+      try {
+        const raw: unknown = JSON.parse(responseBody);
+        if (raw !== null && typeof raw === "object" && !Array.isArray(raw)) {
+          const usageDesc = Object.getOwnPropertyDescriptor(raw, "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") {
+                cacheReadInputTokens = cacheDesc.value;
+              }
+            }
+          }
+        }
+      } catch {
+        // ignore parse errors
+      }
+      return {
+        inputTokens: parsed.usage.prompt_tokens ?? null,
+        outputTokens: parsed.usage.completion_tokens ?? null,
+        cacheCreationInputTokens: null,
+        cacheReadInputTokens,
+      };
+    }
+    return {
+      inputTokens: null,
+      outputTokens: null,
+      cacheCreationInputTokens: null,
+      cacheReadInputTokens: null,
+    };
+  },
+
+  extractStream(
+    raw: string,
+    log: CapturedLog,
+    fallbackModel?: string,
+    collectChunks?: boolean,
+  ): string {
+    return extractOpenAIStream(raw, log, fallbackModel, collectChunks);
+  },
+
+  detectFormat(rawBody: string | null): boolean {
+    if (rawBody === null) return false;
+    try {
+      const json: unknown = JSON.parse(rawBody);
+      if (typeof json === "object" && json !== null && !Array.isArray(json)) {
+        const keys = Object.keys(json);
+        // OpenAI has `model` and `messages` at the top level, but NOT `system`
+        return keys.includes("model") && keys.includes("messages") && !keys.includes("system");
+      }
+      return false;
+    } catch {
+      return false;
+    }
+  },
+};

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

@@ -0,0 +1,25 @@
+// Register format handler
+import "./register";
+
+// Schemas
+export {
+  OpenAIRequestSchema,
+  OpenAIResponseSchema,
+  OpenAISSERawChunkSchema,
+  OpenAIMessage,
+  OpenAIMessageContent,
+  OpenAIToolDefinition,
+  OpenAIChoice,
+  OpenAIChoiceDelta,
+  parseOpenAIResponse,
+} from "./schemas";
+
+// Handler
+export { OpenAIFormatHandler } from "./handler";
+
+// Stream extraction
+export { extractOpenAIStream } from "./stream";
+
+// Providers
+export { openaiProvider } from "./provider";
+export { alibabaProvider } from "./alibabaProvider";