@tonyclaw/agent-inspector 2.0.36 → 2.0.38

package/src/contracts/anthropic.ts

@@ -0,0 +1,235 @@
+import { z } from "zod";
+import { JsonValueSchema } from "./json";
+
+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();
+
+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();
+
+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;

package/src/contracts/index.ts

@@ -0,0 +1,27 @@
+export { JsonValueSchema, trustAsJsonValue } from "./json";
+export type { JsonValue } from "./json";
+
+export { CapturedLogSchema, StreamingChunkSchema } from "./log";
+export type { ApiFormat, CapturedLog, RequestFormat, StreamingChunk, TokenUsage } from "./log";
+
+export {
+  AnthropicRequestSchema,
+  AnthropicResponseSchema,
+  SseEventSchema,
+} from "./anthropic";
+export type { AnthropicResponse, ResponseContentBlockType } from "./anthropic";
+
+export {
+  OpenAIChoice,
+  OpenAIChoiceDelta,
+  OpenAIFunctionCall,
+  OpenAIMessage,
+  OpenAIMessageContent,
+  OpenAIRequestSchema,
+  OpenAIResponseSchema,
+  OpenAISSERawChunkSchema,
+  OpenAIToolCallSchema,
+  OpenAIToolDefinition,
+  parseOpenAIResponse,
+} from "./openai";
+export type { OpenAIResponse, OpenAIToolCall } from "./openai";

package/src/contracts/json.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+
+/**
+ * Shared JSON value type for API payload fragments and streaming chunks.
+ */
+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 and originated from `JSON.parse`.
+ */
+export function trustAsJsonValue<T>(value: T): JsonValue {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+  return value as unknown as JsonValue;
+}

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 {