@tonyclaw/agent-inspector 2.0.37 → 2.0.39

package/src/contracts/log.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { JsonValueSchema } from "./json";
+
+export type ApiFormat = "anthropic" | "openai" | "unknown";
+export type RequestFormat = ApiFormat;
+
+/**
+ * A single SSE event from a streaming response.
+ */
+export const StreamingChunkSchema = z.object({
+  index: z.number(),
+  timestamp: z.number(),
+  type: z.string(),
+  data: JsonValueSchema,
+});
+
+export type StreamingChunk = z.infer<typeof StreamingChunkSchema>;
+
+const StreamingChunksArraySchema = z.object({
+  chunks: z.array(StreamingChunkSchema),
+  truncated: z.boolean().optional().default(false),
+});
+
+export const CapturedLogSchema = z.object({
+  id: z.number(),
+  timestamp: z.string(),
+  method: z.string(),
+  path: z.string(),
+  model: z.string().nullable(),
+  sessionId: z.string().nullable(),
+  rawRequestBody: z.string().nullable(),
+  responseStatus: z.number().nullable(),
+  responseText: z.string().nullable(),
+  inputTokens: z.number().nullable(),
+  outputTokens: z.number().nullable(),
+  cacheCreationInputTokens: z.number().nullable(),
+  cacheReadInputTokens: z.number().nullable(),
+  elapsedMs: z.number().nullable(),
+  firstChunkMs: z.number().nullable().optional(),
+  totalStreamMs: z.number().nullable().optional(),
+  tokensPerSecond: z.number().nullable().optional(),
+  streaming: z.boolean(),
+  userAgent: z.string().nullable(),
+  origin: z.string().nullable(),
+  rawHeaders: z.record(z.string(), z.string()).optional(),
+  /** Headers sent to the upstream LLM */
+  headers: z.record(z.string(), z.string()).optional(),
+  apiFormat: z.enum(["anthropic", "openai", "unknown"]).default("unknown"),
+  isTest: z.boolean().optional().default(false),
+  replayOfLogId: z.number().nullable().optional(),
+  providerName: z.string().nullable().optional(),
+  clientPort: z.number().nullable().optional(),
+  clientPid: z.number().nullable().optional(),
+  clientCwd: z.string().nullable().optional(),
+  clientProjectFolder: z.string().nullable().optional(),
+  streamingChunks: StreamingChunksArraySchema.optional(),
+  streamingChunksPath: z.string().nullable().optional(),
+  rawRequestBodyBytes: z.number().int().nonnegative().nullable().optional(),
+  responseTextBytes: z.number().int().nonnegative().nullable().optional(),
+  bodyContentMode: z.enum(["full", "compact", "truncated"]).optional(),
+  /** Error message from streaming response (e.g., SSE error event) */
+  error: z.string().nullable().optional(),
+});
+
+export type CapturedLog = z.infer<typeof CapturedLogSchema>;
+
+export type TokenUsage = {
+  inputTokens: number | null;
+  outputTokens: number | null;
+  cacheCreationInputTokens: number | null;
+  cacheReadInputTokens: number | null;
+};

package/src/contracts/openai.ts

@@ -0,0 +1,176 @@
+import { z } from "zod";
+import { JsonValueSchema } from "./json";
+
+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(),
+  think: z.string().optional(),
+});
+
+export const OpenAIFunctionCall = z.object({
+  name: z.string(),
+  arguments: z.string(),
+});
+
+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(),
+  think: z.string().nullable().optional(),
+  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(),
+      think: z.string().optional(),
+      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(),
+    service_tier: z.string().nullable().optional(),
+    system_fingerprint: z.string().nullable().optional(),
+  })
+  .passthrough();
+
+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();
+
+export type OpenAIResponse = z.infer<typeof OpenAIResponseSchema>;
+
+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/knowledge/distiller.ts

@@ -1,5 +1,5 @@
 import { extractLastUserMessagePreview, extractResponsePreview } from "../mcp/previewExtractor";
-import type { CapturedLog } from "../proxy/schemas";
+import type { CapturedLog } from "../contracts";
 import type { KnowledgeCandidate, KnowledgeCandidateType } from "./types";
 import { redactCandidate } from "./redactor";
 

package/src/lib/export-logs.ts

@@ -1,5 +1,5 @@
 import JSZip from "jszip";
-import type { CapturedLog } from "../proxy/schemas";
+import type { CapturedLog } from "../contracts";
 
 export type ExportMode = "redacted" | "raw";
 export type ExportLogsResult =

package/src/lib/groupContract.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { JsonValueSchema } from "../proxy/schemas";
+import { JsonValueSchema } from "../contracts";
 import { EvidenceReportSchema, InspectorRunSchema, InspectorRunStatusSchema } from "./runContract";
 import { SessionInfoSchema, SessionTokenUsageSchema } from "./sessionInfoContract";
 

package/src/lib/objectUtils.ts

@@ -1,7 +1,7 @@
 /**
- * Generic object utilities shared across protocol modules.
- * Only truly protocol-agnostic helpers belong here — Anthropic/OpenAI-specific
- * checks stay in their respective format modules.
+ * Generic object utilities shared across API format modules.
+ * Only truly format-agnostic helpers belong here; Anthropic/OpenAI-specific
+ * checks stay in their respective API format modules.
  */
 
 /**

package/src/lib/providerTestContract.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { StreamingChunkSchema } from "../proxy/schemas";
+import { StreamingChunkSchema } from "../contracts";
 
 export const ProviderTestErrorTypeSchema = z.enum([
   "timeout",

package/src/lib/runContract.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { JsonValueSchema } from "../proxy/schemas";
+import { JsonValueSchema } from "../contracts";
 import { SessionInfoSchema } from "./sessionInfoContract";
 
 export const InspectorRunStatusSchema = z.enum([

package/src/lib/stopReason.ts

@@ -1,4 +1,4 @@
-import type { CapturedLog } from "../proxy/schemas";
+import type { CapturedLog } from "../contracts";
 
 export type StopReason = "end_turn" | "tool_use" | "stop" | null;
 

package/src/mcp/previewExtractor.ts

@@ -10,7 +10,7 @@
  * agent needs to make a "is this the log I care about?" judgment from
  * `list_logs` alone.
  *
- * Null returns are an expected and frequent outcome — they cover:
+ * Null returns are an expected and frequent outcome; they cover:
  *   - `apiFormat === "unknown"`
  *   - `rawRequestBody` / `responseText` is null
  *   - JSON.parse failure
@@ -19,12 +19,9 @@
  *   - the relevant content is non-text (e.g., image-only multimodal block)
  */
 
-import type { CapturedLog } from "../proxy/schemas";
-import {
-  AnthropicRequestSchema,
-  AnthropicResponseSchema,
-} from "../proxy/formats/anthropic/schemas";
-import { OpenAIRequestSchema, OpenAIResponseSchema } from "../proxy/formats/openai/schemas";
+import type { CapturedLog } from "../contracts";
+import { AnthropicRequestSchema, AnthropicResponseSchema } from "../contracts/anthropic";
+import { OpenAIRequestSchema, OpenAIResponseSchema } from "../contracts/openai";
 
 /** Preview length cap, per design D5. */
 const PREVIEW_MAX_CHARS = 500;

package/src/mcp/server.ts

@@ -34,7 +34,7 @@ import {
 } from "../lib/groupContract";
 import { InspectorRunStatusSchema, UpdateInspectorRunInputSchema } from "../lib/runContract";
 import { setCurrentPort } from "../lib/serverPort";
-import { JsonValueSchema } from "../proxy/schemas";
+import { JsonValueSchema } from "../contracts";
 import {
   getInspectorGroup,
   listInspectorGroups,

package/src/mcp/toolHandlers.ts

@@ -28,7 +28,7 @@ import {
 } from "../lib/groupContract";
 import { type CreateInspectorRunInput, type UpdateInspectorRunInput } from "../lib/runContract";
 import { SessionInfoSchema } from "../lib/sessionInfoContract";
-import { CapturedLogSchema, type CapturedLog } from "../proxy/schemas";
+import { CapturedLogSchema, type CapturedLog } from "../contracts";
 import {
   addInspectorGroupSession,
   createInspectorGroup,

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

@@ -1,5 +1,5 @@
 import type { CapturedLog } from "../../schemas";
-import type { ProviderProtocol } from "../protocol";
+import type { ProviderAdapter } from "../providerAdapter";
 import { registry } from "../providers";
 import { extractAnthropicStream } from "./stream";
 
@@ -27,7 +27,7 @@ function getUpstreamForModel(model: string): string {
 /**
  * Anthropic Provider Implementation
  */
-export const anthropicProvider: ProviderProtocol = {
+export const anthropicProvider: ProviderAdapter = {
   name: "anthropic",
 
   matches(model: string): boolean {

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

@@ -1,235 +1,12 @@
-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 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 InspectorResponse = AnthropicResponse;
+export {
+  AnthropicRequestSchema,
+  AnthropicResponseSchema,
+  InspectorRequestSchema,
+  InspectorResponseSchema,
+  SseEventSchema,
+} from "../../../contracts/anthropic";
+export type {
+  AnthropicResponse,
+  InspectorResponse,
+  ResponseContentBlockType,
+} from "../../../contracts/anthropic";

package/src/proxy/formats/handler.ts

@@ -1,4 +1,4 @@
-import type { CapturedLog, RequestFormat, TokenUsage } from "../schemas";
+import type { ApiFormat, CapturedLog, TokenUsage } from "../schemas";
 
 /**
  * Structured result of parsing a raw request body.
@@ -17,7 +17,7 @@ export type ParsedRequest = {
  */
 export type FormatHandler = {
   /** The format identifier */
-  readonly format: RequestFormat;
+  readonly format: ApiFormat;
 
   /**
    * Parse a raw request body to extract model name and metadata.

package/src/proxy/formats/index.ts

@@ -9,5 +9,5 @@ import "./openai/zhipuProvider";
 import "./openai/alibabaProvider";
 
 export type { FormatHandler, ParsedRequest } from "./handler";
-export { formatRegistry, formatForPath, requestFormatForPath } from "./registry";
+export { apiFormatForPath, formatRegistry, formatForPath, requestFormatForPath } from "./registry";
 export { registry } from "./providers";

package/src/proxy/formats/jsonSchema.ts

@@ -1,36 +1,2 @@
-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;
-}
+export { JsonValueSchema, trustAsJsonValue } from "../../contracts/json";
+export type { JsonValue } from "../../contracts/json";