@tonyclaw/agent-inspector 2.0.0

package/src/proxy/schemas.ts

@@ -0,0 +1,209 @@
+import { z } from "zod";
+
+// Import JsonValueSchema from shared location to avoid circular dependency
+import { JsonValueSchema, type JsonValue } from "./formats/jsonSchema";
+
+export { JsonValueSchema };
+export type { JsonValue };
+
+export type RequestFormat = "anthropic" | "openai" | "unknown";
+
+import { safeGetOwnProperty } from "../lib/objectUtils";
+
+/**
+ * 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(),
+  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),
+  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(),
+  /** 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;
+};
+
+// ============================================================
+// Import types and schemas from formats
+// ============================================================
+
+// Import types and schemas from formats for internal use
+import { InspectorRequestSchema, type InspectorRequest } from "./formats/anthropic/schemas";
+
+// Re-export types and schemas from formats for backward compatibility
+export {
+  InspectorRequestSchema,
+  InspectorResponseSchema,
+  SseEventSchema,
+} from "./formats/anthropic/schemas";
+export type {
+  InspectorRequest,
+  InspectorResponse,
+  ResponseContentBlockType,
+} from "./formats/anthropic/schemas";
+
+export {
+  OpenAIRequestSchema,
+  OpenAIResponseSchema,
+  OpenAISSERawChunkSchema,
+  type OpenAIResponse,
+  type OpenAIToolCall,
+  parseOpenAIResponse,
+} from "./formats/openai/schemas";
+
+// ============================================================
+// Utility functions
+// ============================================================
+
+function detectFormat(rawBody: string | null): RequestFormat {
+  if (rawBody === null) return "unknown";
+  try {
+    const json: unknown = JSON.parse(rawBody);
+    if (typeof json === "object" && json !== null && !Array.isArray(json)) {
+      const hasModel = safeGetOwnProperty(json, "model") !== undefined;
+      const hasMessages = safeGetOwnProperty(json, "messages") !== undefined;
+      if (hasModel && hasMessages) {
+        // Anthropic requests put `system` as a top-level key; OpenAI does not.
+        // Both formats can have `tools`, so we check `system` as the discriminator.
+        if (safeGetOwnProperty(json, "system") !== undefined) {
+          return "anthropic";
+        }
+        const msgVal = safeGetOwnProperty(json, "messages");
+        if (Array.isArray(msgVal)) {
+          return "openai";
+        }
+      }
+    }
+    return "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+// Schema for model name in request body (used for routing)
+const RequestModelSchema = z.object({
+  model: z.string(),
+});
+
+export function extractModelFromBody(body: string): string | null {
+  try {
+    const json: unknown = JSON.parse(body);
+    const parsed = RequestModelSchema.safeParse(json);
+    if (parsed.success) {
+      return parsed.data.model;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Loose request schema used for routing + log metadata. Tolerant of missing
+ * fields so it can extract what it can from a partially-valid or unparseable
+ * body without throwing.
+ */
+export const LooseRequestSchema = z.object({
+  model: z.string().optional(),
+  metadata: z.object({ user_id: z.string().optional() }).passthrough().optional(),
+});
+
+export type RequestMetadata = {
+  model: string | null;
+  sessionId: string | null;
+};
+
+function extractSessionIdFromHeaders(headers: Headers): string | null {
+  return headers.get("x-agent-inspector-session-id") ?? headers.get("x-session-affinity");
+}
+
+/**
+ * Parse a request body exactly once and pull out everything the handler needs
+ * for routing + log creation: the model (used for provider selection) and the
+ * session id (from `metadata.user_id` or the `x-session-affinity` header).
+ *
+ * Returning `null` for either field is a valid outcome — callers must handle
+ * "unknown" gracefully. Callers that already have the body string should use
+ * this instead of re-parsing with `extractModelFromBody` and a second pass
+ * for the session id.
+ */
+export function extractRequestMetadata(body: string | null, headers: Headers): RequestMetadata {
+  const headerSessionId = extractSessionIdFromHeaders(headers);
+  if (body === null) return { model: null, sessionId: headerSessionId };
+  try {
+    const json: unknown = JSON.parse(body);
+    const loose = LooseRequestSchema.safeParse(json);
+    if (loose.success) {
+      return {
+        model: loose.data.model ?? null,
+        sessionId: loose.data.metadata?.user_id ?? headerSessionId,
+      };
+    }
+  } catch {
+    // body not valid JSON
+  }
+  return { model: null, sessionId: headerSessionId };
+}
+
+/**
+ * Parse a raw request body into an InspectorRequest.
+ * @deprecated Use FormatHandler.parseRequest() instead
+ */
+export function parseRequest(rawBody: string | null): InspectorRequest | null {
+  if (rawBody === null) return null;
+  try {
+    const json: unknown = JSON.parse(rawBody);
+    const result = InspectorRequestSchema.safeParse(json);
+    if (result.success) return result.data;
+    return null;
+  } catch {
+    return null;
+  }
+}

package/src/proxy/sessionProcess.ts

@@ -0,0 +1,140 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { logger } from "./logger";
+import type { FinalizeLogJob, FinalizeLogResult } from "./logFinalizer";
+
+const IDLE_TIMEOUT_MS = Number(process.env["SESSION_PROCESS_IDLE_MS"]) || 5 * 60 * 1000; // 5 min default
+const MAX_RESTARTS = 3;
+
+const _processes = new Map<string, SessionProcess>();
+
+type PendingJob = {
+  resolve: (result: FinalizeLogResult) => void;
+  reject: (err: Error) => void;
+};
+
+function resolveSessionWorkerPath(): string {
+  return fileURLToPath(new URL("./sessionWorkerEntry.ts", import.meta.url));
+}
+
+export function isSessionProcessAvailable(): boolean {
+  return existsSync(resolveSessionWorkerPath());
+}
+
+export class SessionProcess {
+  private child: ChildProcess | null = null;
+  private pending = new Map<string, PendingJob>();
+  private nextId = 0;
+  private idleTimer: ReturnType<typeof setTimeout> | null = null;
+  private restartCount = 0;
+  private destroyed = false;
+
+  constructor(private sessionId: string) {}
+
+  /** Number of outstanding jobs sent to this process. */
+  get pendingCount(): number {
+    return this.pending.size;
+  }
+
+  private ensureRunning(): ChildProcess {
+    if (this.child !== null && this.child.connected) return this.child;
+
+    const resolvedPath = resolveSessionWorkerPath();
+
+    this.child = spawn(process.execPath, [...process.execArgv, resolvedPath], {
+      stdio: ["pipe", "pipe", "pipe", "ipc"],
+      windowsHide: true,
+    });
+
+    this.restartCount += 1;
+
+    this.child.on("message", (msg: { id: string; result: FinalizeLogResult }) => {
+      const pending = this.pending.get(msg.id);
+      if (pending !== undefined) {
+        this.pending.delete(msg.id);
+        pending.resolve(msg.result);
+      }
+      this.resetIdleTimer();
+    });
+
+    this.child.on("error", (err) => {
+      logger.error(`[sessionProcess] Session ${this.sessionId} process error:`, err.message);
+    });
+
+    this.child.on("exit", (code, signal) => {
+      const wasConnected = this.child !== null;
+      this.child = null;
+
+      if (this.destroyed) return;
+
+      // Reject all pending jobs on unexpected exit
+      for (const [, pending] of this.pending) {
+        pending.reject(
+          new Error(
+            `Session process exited with code ${code ?? signal}, session=${this.sessionId}`,
+          ),
+        );
+      }
+      this.pending.clear();
+
+      if (wasConnected && this.restartCount <= MAX_RESTARTS) {
+        logger.warn(
+          `[sessionProcess] Session ${this.sessionId} worker exited (code=${code ?? signal}), ` +
+            `restart ${this.restartCount}/${MAX_RESTARTS}`,
+        );
+      }
+    });
+
+    this.resetIdleTimer();
+    return this.child;
+  }
+
+  enqueue(job: FinalizeLogJob): Promise<FinalizeLogResult> {
+    return new Promise((resolve, reject) => {
+      const child = this.ensureRunning();
+      const id = String(++this.nextId);
+      this.pending.set(id, { resolve, reject });
+      child.send({ id, job });
+    });
+  }
+
+  private resetIdleTimer(): void {
+    if (this.idleTimer !== null) clearTimeout(this.idleTimer);
+    this.idleTimer = setTimeout(() => {
+      if (this.pending.size === 0) {
+        this.destroy();
+      }
+    }, IDLE_TIMEOUT_MS);
+  }
+
+  destroy(): void {
+    this.destroyed = true;
+    if (this.idleTimer !== null) {
+      clearTimeout(this.idleTimer);
+      this.idleTimer = null;
+    }
+    if (this.child !== null) {
+      this.child.kill();
+      this.child = null;
+    }
+    _processes.delete(this.sessionId);
+  }
+}
+
+/** Get or create a dedicated child process for a session. */
+export function getSessionProcess(sessionId: string): SessionProcess {
+  const existing = _processes.get(sessionId);
+  if (existing !== undefined) return existing;
+
+  const sp = new SessionProcess(sessionId);
+  _processes.set(sessionId, sp);
+  return sp;
+}
+
+/** Forcefully tear down all session processes (e.g. on server shutdown). */
+export function destroyAllSessionProcesses(): void {
+  for (const [, sp] of _processes) {
+    sp.destroy();
+  }
+}

package/src/proxy/sessionRuntime.ts

@@ -0,0 +1,85 @@
+import { logger } from "./logger";
+import { executeFinalizeLogJob, type FinalizeLogJob } from "./logFinalizer";
+import type { CapturedLog } from "./schemas";
+import {
+  getLogSessionId,
+  markSessionTaskFinished,
+  markSessionTaskQueued,
+  markSessionTaskStarted,
+} from "./sessionSupervisor";
+
+const UNASSIGNED_SESSION_QUEUE = "__unassigned__";
+
+export type SessionTaskName = "finalize-log";
+
+type SessionTask<T> = () => Promise<T> | T;
+
+const queues = new Map<string, Promise<void>>();
+
+function queueKeyForSession(sessionId: string | null): string {
+  return sessionId ?? UNASSIGNED_SESSION_QUEUE;
+}
+
+function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+async function runSessionTask<T>(
+  sessionId: string | null,
+  taskName: SessionTaskName,
+  task: SessionTask<T>,
+): Promise<T> {
+  markSessionTaskStarted(sessionId);
+  try {
+    const result = await task();
+    markSessionTaskFinished(sessionId, null);
+    return result;
+  } catch (err) {
+    const message = errorMessage(err);
+    logger.error(`[sessionRuntime] ${taskName} failed for session ${sessionId ?? "unassigned"}`);
+    markSessionTaskFinished(sessionId, message);
+    return Promise.reject(err);
+  }
+}
+
+export function enqueueSessionTask<T>(
+  sessionId: string | null,
+  taskName: SessionTaskName,
+  task: SessionTask<T>,
+): Promise<T> {
+  const queueKey = queueKeyForSession(sessionId);
+  const previous = queues.get(queueKey) ?? Promise.resolve();
+
+  markSessionTaskQueued(sessionId);
+
+  const current = previous
+    .catch(() => undefined)
+    .then(() => runSessionTask(sessionId, taskName, task));
+  const settled = current.then(
+    () => undefined,
+    () => undefined,
+  );
+
+  queues.set(queueKey, settled);
+  void settled.then(() => {
+    if (queues.get(queueKey) === settled) {
+      queues.delete(queueKey);
+    }
+  });
+
+  return current;
+}
+
+export function enqueueLogTask<T>(
+  log: CapturedLog,
+  taskName: SessionTaskName,
+  task: SessionTask<T>,
+): Promise<T> {
+  return enqueueSessionTask(getLogSessionId(log), taskName, task);
+}
+
+export function enqueueFinalizeLogJob(job: FinalizeLogJob): Promise<void> {
+  return enqueueSessionTask(getLogSessionId(job.log), "finalize-log", () =>
+    executeFinalizeLogJob(job),
+  );
+}

package/src/proxy/sessionSupervisor.ts

@@ -0,0 +1,283 @@
+import type { CapturedLog } from "./schemas";
+import { isSessionProcessAvailable } from "./sessionProcess";
+
+export const PROVIDER_TEST_SESSION_ID = "provider-test";
+
+export type SessionClientInfo = {
+  port: number | null;
+  pid: number | null;
+  cwd: string | null;
+  projectFolder: string | null;
+};
+
+export type SessionSource = "explicit" | "client-process" | "client-connection" | "provider-test";
+
+export type SessionIdentity = {
+  id: string | null;
+  source: SessionSource | null;
+};
+
+export type SessionRuntimeMode = "in-process" | "worker-thread" | "child-process";
+
+function getRuntimeMode(): SessionRuntimeMode {
+  if (process.env["FINALIZER_USE_WORKER"] === "0") return "in-process";
+  const mode = process.env["FINALIZER_RUNTIME"];
+  if (mode === "process") return "child-process";
+  if (mode === "worker") return "worker-thread";
+  if (mode === "inline") return "in-process";
+  return isSessionProcessAvailable() ? "child-process" : "in-process";
+}
+
+export type SessionSnapshot = {
+  id: string;
+  source: SessionSource;
+  runtimeMode: SessionRuntimeMode;
+  createdAt: string;
+  updatedAt: string;
+  requestCount: number;
+  activeRequests: number;
+  completedRequests: number;
+  failedRequests: number;
+  queuedTasks: number;
+  runningTasks: number;
+  lastTaskError: string | null;
+  lastLogId: number | null;
+  lastModel: string | null;
+  clientPid: number | null;
+  clientProjectFolder: string | null;
+};
+
+type SessionRecord = SessionSnapshot;
+
+const sessions = new Map<string, SessionRecord>();
+const knownLogSessions = new Map<number, string>();
+const completedLogIds = new Set<number>();
+const failedLogIds = new Set<number>();
+
+function normalizeExplicitSessionId(sessionId: string | null | undefined): string | null {
+  if (sessionId === null || sessionId === undefined) return null;
+  const trimmed = sessionId.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function buildClientSessionId(clientInfo: SessionClientInfo): SessionIdentity {
+  const projectFolder = normalizeExplicitSessionId(clientInfo.projectFolder);
+
+  if (clientInfo.pid !== null) {
+    return {
+      id:
+        projectFolder !== null
+          ? `process:${clientInfo.pid}:${projectFolder}`
+          : `process:${clientInfo.pid}`,
+      source: "client-process",
+    };
+  }
+
+  if (clientInfo.port !== null) {
+    return {
+      id: `connection:${clientInfo.port}`,
+      source: "client-connection",
+    };
+  }
+
+  return { id: null, source: null };
+}
+
+export function resolveSessionIdentity(input: {
+  explicitSessionId: string | null;
+  clientInfo?: SessionClientInfo;
+  isTest?: boolean;
+}): SessionIdentity {
+  if (input.isTest === true) {
+    return { id: PROVIDER_TEST_SESSION_ID, source: "provider-test" };
+  }
+
+  const explicit = normalizeExplicitSessionId(input.explicitSessionId);
+  if (explicit !== null) {
+    return { id: explicit, source: "explicit" };
+  }
+
+  if (input.clientInfo !== undefined) {
+    return buildClientSessionId(input.clientInfo);
+  }
+
+  return { id: null, source: null };
+}
+
+export function getLogSessionIdentity(log: CapturedLog): SessionIdentity {
+  return resolveSessionIdentity({
+    explicitSessionId: log.sessionId,
+    clientInfo: {
+      port: log.clientPort ?? null,
+      pid: log.clientPid ?? null,
+      cwd: log.clientCwd ?? null,
+      projectFolder: log.clientProjectFolder ?? null,
+    },
+    isTest: log.isTest,
+  });
+}
+
+export function getLogSessionId(log: CapturedLog): string | null {
+  return getLogSessionIdentity(log).id;
+}
+
+function getTimestamp(log: CapturedLog): string {
+  return log.timestamp.length > 0 ? log.timestamp : new Date().toISOString();
+}
+
+function createSessionRecord(id: string, source: SessionSource, log: CapturedLog): SessionRecord {
+  const timestamp = getTimestamp(log);
+  return {
+    id,
+    source,
+    runtimeMode: getRuntimeMode(),
+    createdAt: timestamp,
+    updatedAt: timestamp,
+    requestCount: 0,
+    activeRequests: 0,
+    completedRequests: 0,
+    failedRequests: 0,
+    queuedTasks: 0,
+    runningTasks: 0,
+    lastTaskError: null,
+    lastLogId: null,
+    lastModel: null,
+    clientPid: log.clientPid ?? null,
+    clientProjectFolder: log.clientProjectFolder ?? null,
+  };
+}
+
+function upsertSession(
+  log: CapturedLog,
+  sourceOverride?: SessionSource | null,
+): SessionRecord | null {
+  const identity = getLogSessionIdentity(log);
+  if (identity.id === null) return null;
+
+  const source = sourceOverride ?? identity.source;
+  if (source === null) return null;
+
+  const existing = sessions.get(identity.id);
+  const session = existing ?? createSessionRecord(identity.id, source, log);
+  session.updatedAt = new Date().toISOString();
+  session.lastLogId = log.id;
+  session.lastModel = log.model ?? session.lastModel;
+  session.clientPid = log.clientPid ?? session.clientPid;
+  session.clientProjectFolder = log.clientProjectFolder ?? session.clientProjectFolder;
+
+  sessions.set(identity.id, session);
+  return session;
+}
+
+function rememberLogSession(log: CapturedLog): boolean {
+  const sessionId = getLogSessionId(log);
+  if (sessionId === null) return false;
+
+  const knownSessionId = knownLogSessions.get(log.id);
+  if (knownSessionId === sessionId) return false;
+
+  knownLogSessions.set(log.id, sessionId);
+  return true;
+}
+
+function isFailedLog(log: CapturedLog): boolean {
+  const hasError = log.error !== null && log.error !== undefined && log.error.length > 0;
+  const hasErrorStatus = log.responseStatus !== null && log.responseStatus >= 400;
+  return hasError || hasErrorStatus;
+}
+
+export function markSessionStarted(log: CapturedLog, sourceOverride?: SessionSource | null): void {
+  const session = upsertSession(log, sourceOverride);
+  if (session === null) return;
+
+  const isNewLog = rememberLogSession(log);
+  if (isNewLog) {
+    session.requestCount += 1;
+  }
+  session.activeRequests += 1;
+}
+
+export function markSessionFinished(log: CapturedLog, sourceOverride?: SessionSource | null): void {
+  const session = upsertSession(log, sourceOverride);
+  if (session === null) return;
+
+  if (session.activeRequests > 0) {
+    session.activeRequests -= 1;
+  }
+
+  if (completedLogIds.has(log.id) === false) {
+    completedLogIds.add(log.id);
+    session.completedRequests += 1;
+  }
+
+  if (isFailedLog(log) && failedLogIds.has(log.id) === false) {
+    failedLogIds.add(log.id);
+    session.failedRequests += 1;
+  }
+}
+
+export function markSessionTaskQueued(sessionId: string | null): void {
+  if (sessionId === null) return;
+  const session = sessions.get(sessionId);
+  if (session === undefined) return;
+  session.queuedTasks += 1;
+  session.updatedAt = new Date().toISOString();
+}
+
+export function markSessionTaskStarted(sessionId: string | null): void {
+  if (sessionId === null) return;
+  const session = sessions.get(sessionId);
+  if (session === undefined) return;
+  if (session.queuedTasks > 0) {
+    session.queuedTasks -= 1;
+  }
+  session.runningTasks += 1;
+  session.updatedAt = new Date().toISOString();
+}
+
+export function markSessionTaskFinished(sessionId: string | null, error: string | null): void {
+  if (sessionId === null) return;
+  const session = sessions.get(sessionId);
+  if (session === undefined) return;
+  if (session.runningTasks > 0) {
+    session.runningTasks -= 1;
+  }
+  session.lastTaskError = error;
+  session.updatedAt = new Date().toISOString();
+}
+
+export function observeSessionLog(log: CapturedLog, sourceOverride?: SessionSource | null): void {
+  const session = upsertSession(log, sourceOverride);
+  if (session === null) return;
+
+  const isNewLog = rememberLogSession(log);
+  if (isNewLog) {
+    session.requestCount += 1;
+  }
+
+  if (log.responseStatus !== null || log.responseText !== null) {
+    markSessionFinished(log, sourceOverride);
+  }
+}
+
+export function clearSessionRegistry(): void {
+  sessions.clear();
+  knownLogSessions.clear();
+  completedLogIds.clear();
+  failedLogIds.clear();
+}
+
+export function rebuildSessionRegistry(logs: Iterable<CapturedLog>): void {
+  clearSessionRegistry();
+  for (const log of logs) {
+    observeSessionLog(log);
+  }
+}
+
+export function getSessionIds(): string[] {
+  return [...sessions.values()].map((session) => session.id);
+}
+
+export function getSessionSnapshots(): SessionSnapshot[] {
+  return [...sessions.values()].map((session) => ({ ...session }));
+}