@tonyclaw/agent-inspector 2.0.0

package/src/proxy/logIndex.ts

@@ -0,0 +1,268 @@
+import { readFile, writeFile, stat, readdir, mkdir } from "node:fs/promises";
+import { createReadStream, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { createInterface } from "node:readline";
+import { Buffer } from "node:buffer";
+import { resolveLogDir, logger } from "./logger";
+
+type LogIndexEntry = {
+  id: number;
+  file: string;
+  byteOffset: number;
+  byteLength: number;
+};
+
+type LogIndex = {
+  version: number;
+  entries: Record<number, LogIndexEntry>;
+  maxId: number;
+};
+
+const INDEX_VERSION = 1;
+const INDEX_FILE = "logs.idx";
+
+export { resolveLogDir as getLogDir };
+
+function getIndexPath(): string {
+  return join(resolveLogDir(), INDEX_FILE);
+}
+
+let cachedIndex: LogIndex | null = null;
+
+function createEmptyIndex(): LogIndex {
+  return {
+    version: INDEX_VERSION,
+    entries: {},
+    maxId: 0,
+  };
+}
+
+function isLogIndex(obj: unknown): obj is LogIndex {
+  if (typeof obj !== "object" || obj === null || Array.isArray(obj)) return false;
+  const versionDesc = Object.getOwnPropertyDescriptor(obj, "version");
+  const entriesDesc = Object.getOwnPropertyDescriptor(obj, "entries");
+  const maxIdDesc = Object.getOwnPropertyDescriptor(obj, "maxId");
+  return (
+    versionDesc !== undefined &&
+    typeof versionDesc.value === "number" &&
+    entriesDesc !== undefined &&
+    typeof entriesDesc.value === "object" &&
+    entriesDesc.value !== null &&
+    maxIdDesc !== undefined &&
+    typeof maxIdDesc.value === "number"
+  );
+}
+
+export async function loadIndex(): Promise<LogIndex> {
+  if (cachedIndex !== null) return cachedIndex;
+
+  const indexPath = getIndexPath();
+  if (!existsSync(indexPath)) {
+    cachedIndex = createEmptyIndex();
+    return cachedIndex;
+  }
+
+  try {
+    const content = await readFile(indexPath, "utf-8");
+    const parsed: unknown = JSON.parse(content);
+    if (isLogIndex(parsed)) {
+      cachedIndex = parsed;
+    } else {
+      cachedIndex = createEmptyIndex();
+    }
+    return cachedIndex;
+  } catch (err) {
+    logger.error("[logIndex] Failed to load index:", String(err));
+    cachedIndex = createEmptyIndex();
+    return cachedIndex;
+  }
+}
+
+export async function saveIndex(index: LogIndex): Promise<void> {
+  const indexPath = getIndexPath();
+  const dir = dirname(indexPath);
+
+  try {
+    await mkdir(dir, { recursive: true });
+  } catch {
+    // Ignore
+  }
+
+  try {
+    await writeFile(indexPath, JSON.stringify(index), "utf-8");
+  } catch (err) {
+    logger.error("[logIndex] Failed to save index:", String(err));
+  }
+}
+
+export async function addToIndex(
+  id: number,
+  file: string,
+  byteOffset: number,
+  byteLength: number,
+): Promise<void> {
+  const index = await loadIndex();
+  index.entries[id] = { id, file, byteOffset, byteLength };
+  if (id > index.maxId) {
+    index.maxId = id;
+  }
+  // Defer disk writes to reduce I/O - flush after a batch of updates
+  scheduleIndexFlush();
+}
+
+// Batch writes: collect pending flushes and write once
+let indexFlushScheduled = false;
+let indexFlushTimeout: ReturnType<typeof setTimeout> | null = null;
+
+async function flushIndexAsync(): Promise<void> {
+  indexFlushScheduled = false;
+  indexFlushTimeout = null;
+  const index = await loadIndex();
+  await saveIndex(index);
+}
+
+function scheduleIndexFlush(): void {
+  if (indexFlushScheduled) return;
+  indexFlushScheduled = true;
+  indexFlushTimeout = setTimeout(() => {
+    void flushIndexAsync();
+  }, 1000); // Flush after 1 second of inactivity
+}
+
+export async function flushIndex(): Promise<void> {
+  if (indexFlushTimeout !== null) {
+    clearTimeout(indexFlushTimeout);
+    indexFlushTimeout = null;
+  }
+  indexFlushScheduled = false;
+  const index = await loadIndex();
+  await saveIndex(index);
+}
+
+export async function findInIndex(id: number): Promise<LogIndexEntry | null> {
+  const index = await loadIndex();
+  return index.entries[id] ?? null;
+}
+
+type FileIndexResult = {
+  entries: Record<number, LogIndexEntry>;
+  maxId: number;
+};
+
+async function indexFile(filePath: string, file: string): Promise<FileIndexResult> {
+  const entries: Record<number, LogIndexEntry> = {};
+  let maxId = 0;
+  let byteOffset = 0;
+
+  const fileStream = createInterface({
+    input: createReadStream(filePath),
+    crlfDelay: Infinity,
+  });
+
+  for await (const line of fileStream) {
+    const lineBytes = Buffer.byteLength(line, "utf-8") + 1;
+    if (line.trim() !== "") {
+      try {
+        const entry: unknown = JSON.parse(line);
+        if (typeof entry === "object" && entry !== null && !Array.isArray(entry)) {
+          const idDesc = Object.getOwnPropertyDescriptor(entry, "id");
+          if (idDesc !== undefined && typeof idDesc.value === "number") {
+            const entryId = idDesc.value;
+            maxId = Math.max(maxId, entryId);
+            entries[entryId] = {
+              id: entryId,
+              file,
+              byteOffset,
+              byteLength: lineBytes,
+            };
+          }
+        }
+      } catch {
+        // Skip malformed lines
+      }
+    }
+    byteOffset += lineBytes;
+  }
+
+  return { entries, maxId };
+}
+
+export async function rebuildIndex(): Promise<LogIndex> {
+  const logDir = resolveLogDir();
+  const newIndex = createEmptyIndex();
+
+  if (!existsSync(logDir)) {
+    cachedIndex = newIndex;
+    await saveIndex(newIndex);
+    return newIndex;
+  }
+
+  const files = (await readdir(logDir)).filter((f) => f.endsWith(".jsonl")).sort();
+  const CONCURRENCY = 4;
+
+  // Process files in bounded-concurrency batches
+  for (let i = 0; i < files.length; i += CONCURRENCY) {
+    const batch = files.slice(i, i + CONCURRENCY);
+    const results = await Promise.all(batch.map((file) => indexFile(join(logDir, file), file)));
+
+    for (const result of results) {
+      Object.assign(newIndex.entries, result.entries);
+      newIndex.maxId = Math.max(newIndex.maxId, result.maxId);
+    }
+  }
+
+  cachedIndex = newIndex;
+  await saveIndex(newIndex);
+  return newIndex;
+}
+
+// Async mutex for atomic ID generation to prevent race conditions
+// Uses a promise queue instead of busy-waiting
+let idGenerationPromise: Promise<void> | null = null;
+let releaseLock: (() => void) | null = null;
+
+async function acquireLock(): Promise<void> {
+  if (releaseLock === null) {
+    idGenerationPromise = new Promise<void>((resolve) => {
+      releaseLock = resolve;
+    });
+  } else {
+    // Wait for the previous lock to be released
+    await idGenerationPromise;
+    // After waiting, we need to create a new promise for the next waiter
+    idGenerationPromise = new Promise<void>((resolve) => {
+      releaseLock = resolve;
+    });
+  }
+}
+
+function releaseLockFn(): void {
+  if (releaseLock) {
+    const resolve = releaseLock;
+    releaseLock = null;
+    idGenerationPromise = null;
+    resolve();
+  }
+}
+
+export async function getNextLogId(): Promise<number> {
+  await acquireLock();
+  try {
+    const index = await loadIndex();
+    const nextId = index.maxId + 1;
+    index.maxId = nextId;
+    // Synchronously update the index in memory (disk write is deferred via batching)
+    cachedIndex = index;
+    return nextId;
+  } finally {
+    releaseLockFn();
+  }
+}
+
+export function getCurrentLogFile(): string {
+  const now = new Date();
+  const yyyy = now.getUTCFullYear();
+  const mm = String(now.getUTCMonth() + 1).padStart(2, "0");
+  const dd = String(now.getUTCDate()).padStart(2, "0");
+  return `${yyyy}-${mm}-${dd}.jsonl`;
+}

package/src/proxy/logger.ts

@@ -0,0 +1,179 @@
+import { readdir, stat, unlink, appendFile, mkdir } from "node:fs/promises";
+import { writeFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { getDataDir } from "./dataDir";
+
+const LOG_DIR_ENV = process.env["LOG_DIR"];
+const RETENTION_DAYS = Number(process.env["LOG_RETENTION_DAYS"] ?? "7");
+const LOG_FILE_ENV = process.env["AGENT_INSPECTOR_LOG_FILE"];
+
+let resolvedLogDir: string | null = null;
+
+export function resolveLogDir(): string {
+  if (resolvedLogDir !== null) return resolvedLogDir;
+
+  if (LOG_DIR_ENV !== undefined) {
+    resolvedLogDir = path.isAbsolute(LOG_DIR_ENV)
+      ? LOG_DIR_ENV
+      : path.join(getDataDir(), LOG_DIR_ENV);
+  } else {
+    resolvedLogDir = path.join(getDataDir(), "logs");
+  }
+  return resolvedLogDir;
+}
+
+export function getLogFilePath(): string {
+  const date = new Date();
+  const yyyy = date.getUTCFullYear();
+  const mm = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const dd = String(date.getUTCDate()).padStart(2, "0");
+  return path.join(resolveLogDir(), `${yyyy}-${mm}-${dd}.jsonl`);
+}
+
+function getInspectorLogPath(): string {
+  if (LOG_FILE_ENV !== undefined) {
+    return LOG_FILE_ENV;
+  }
+  return path.join(getDataDir(), "logs", "inspector.log");
+}
+
+export async function initLogger(): Promise<void> {
+  const dir = resolveLogDir();
+  const retentionMs = RETENTION_DAYS * 24 * 60 * 60 * 1000;
+  const cutoff = Date.now() - retentionMs;
+
+  try {
+    const entries = await readdir(dir);
+    for (const entry of entries) {
+      if (!entry.endsWith(".jsonl")) continue;
+      const fullPath = path.join(dir, entry);
+      try {
+        const s = await stat(fullPath);
+        if (s.mtimeMs < cutoff) {
+          await unlink(fullPath);
+        }
+      } catch {
+        // Skip files that can't be stat - not critical
+      }
+    }
+  } catch (err) {
+    // Log directory initialization errors but don't fail startup
+    // eslint-disable-next-line no-console
+    console.error("[logger] Failed to initialize log directory:", err);
+  }
+}
+
+// File-based logger for application logs (not log entries)
+let loggerInitialized = false;
+
+async function writeAppLog(message: string): Promise<void> {
+  // Auto-initialize on first use if not already initialized
+  if (!loggerInitialized) {
+    loggerInitialized = true;
+    void initLogger();
+  }
+
+  const logPath = getInspectorLogPath();
+  try {
+    const logDirPath = path.dirname(logPath);
+    await mkdir(logDirPath, { recursive: true });
+    const timestamp = new Date().toISOString();
+    await appendFile(logPath, `[${timestamp}] ${message}\n`, "utf-8");
+  } catch (err) {
+    // Log to stderr since file logging failed
+    // eslint-disable-next-line no-console
+    console.error(`[logger] Failed to write to ${logPath}:`, err);
+  }
+}
+
+// Application logger - writes to inspector.log
+export const logger = {
+  debug(message: string, ...args: unknown[]): void {
+    const msg = args.length > 0 ? `${message} ${args.map(String).join(" ")}` : message;
+    void writeAppLog(`[DEBUG] ${msg}`);
+  },
+  info(message: string, ...args: unknown[]): void {
+    const msg = args.length > 0 ? `${message} ${args.map(String).join(" ")}` : message;
+    void writeAppLog(`[INFO] ${msg}`);
+  },
+  warn(message: string, ...args: unknown[]): void {
+    const msg = args.length > 0 ? `${message} ${args.map(String).join(" ")}` : message;
+    void writeAppLog(`[WARN] ${msg}`);
+  },
+  error(message: string, ...args: unknown[]): void {
+    const msg = args.length > 0 ? `${message} ${args.map(String).join(" ")}` : message;
+    void writeAppLog(`[ERROR] ${msg}`);
+  },
+};
+
+// Write buffer for batching async writes
+const MAX_BUFFER_SIZE = 1000;
+let writeBuffer: string[] = [];
+let writeQueue: Promise<void> = Promise.resolve();
+
+function drainBuffer(): string {
+  const toWrite = writeBuffer.join("");
+  writeBuffer = [];
+  return toWrite;
+}
+
+async function flushWriteBuffer(): Promise<void> {
+  let toWrite: string;
+  {
+    toWrite = drainBuffer();
+  }
+  if (toWrite.length === 0) return;
+
+  try {
+    const filePath = getLogFilePath();
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await appendFile(filePath, toWrite, "utf-8");
+  } catch (err) {
+    // On failure, re-queue the data so it is not lost
+    writeBuffer.unshift(toWrite);
+    // eslint-disable-next-line no-console
+    console.error("[logger] Failed to flush write buffer, re-queued:", err);
+  }
+}
+
+export function appendLogEntry(entry: Record<string, unknown>): void {
+  const line = JSON.stringify(entry) + "\n";
+  writeBuffer.push(line);
+  if (writeBuffer.length >= MAX_BUFFER_SIZE) {
+    writeQueue = writeQueue.then(() => flushWriteBuffer());
+  } else if (writeBuffer.length === 1) {
+    writeQueue = writeQueue.then(() => flushWriteBuffer());
+  }
+}
+
+/**
+ * Flush all buffered log entries to disk. Call before process exit
+ * to avoid losing unflushed data.
+ */
+export async function flushLogBuffer(): Promise<void> {
+  await writeQueue;
+  if (writeBuffer.length > 0) {
+    await flushWriteBuffer();
+  }
+}
+
+// Ensure buffered logs are written before the process exits
+process.on("exit", () => {
+  if (writeBuffer.length > 0) {
+    const toWrite = drainBuffer();
+    try {
+      // Synchronous write required in 'exit' handler (async I/O not allowed)
+      const filePath = getLogFilePath();
+      mkdirSync(path.dirname(filePath), { recursive: true });
+      writeFileSync(filePath, toWrite, "utf-8");
+    } catch {
+      // Best-effort: nothing we can do in an exit handler
+    }
+  }
+});
+
+for (const signal of ["SIGINT", "SIGTERM"] as const) {
+  process.on(signal, () => {
+    void flushLogBuffer().then(() => process.exit(0));
+  });
+}

package/src/proxy/openaiOrphanToolStrip.ts

@@ -0,0 +1,142 @@
+/**
+ * OpenAI Chat Completions protocol guard: orphan `tool` messages.
+ *
+ * The OpenAI Chat Completions spec requires every message with
+ * `role: "tool"` to reference a `tool_call_id` that appears in a preceding
+ * `assistant` message's `tool_calls` array. When this invariant is broken
+ * (typically by a buggy client that records a tool result without the
+ * matching assistant tool_call), the upstream rejects the request with a
+ * 400 like:
+ *
+ *   {"type":"error","error":{"type":"bad_request_error",
+ *     "message":"invalid params, tool result's tool id(call_xxx) not found"}}
+ *
+ * This module finds such orphan tool messages and returns a rewritten body
+ * with them removed so the proxy can forward a valid request. The original
+ * body is preserved by the caller for the captured log, so the inspector UI
+ * still shows the broken request the client actually sent.
+ */
+
+const ROLE_ASSISTANT = "assistant";
+const ROLE_TOOL = "tool";
+
+export type OrphanToolStripResult = {
+  /** The new request body. Equal to input (by reference) when no change was made. */
+  body: string;
+  /** Number of orphan tool messages removed. */
+  removed: number;
+  /**
+   * The `tool_call_id` values of the removed messages, in document order.
+   * `null` is used when a tool message had no `tool_call_id` at all.
+   */
+  orphanIds: Array<string | null>;
+};
+
+import { safeGetOwnProperty, isPlainRecord } from "../lib/objectUtils";
+
+function isObjectWithMessages(value: unknown): value is { messages: unknown[] } {
+  if (!isPlainRecord(value)) return false;
+  if (!Object.prototype.hasOwnProperty.call(value, "messages")) return false;
+  const messages = safeGetOwnProperty(value, "messages");
+  return Array.isArray(messages);
+}
+
+/**
+ * Collects the set of tool_call ids from an assistant message's `tool_calls`
+ * array. Tolerant of malformed entries: anything without a string `id` is
+ * skipped silently (those ids cannot be referenced by a tool message anyway).
+ */
+function collectAssistantToolCallIds(message: unknown, into: Set<string>): void {
+  if (!isPlainRecord(message)) return;
+  const toolCalls = safeGetOwnProperty(message, "tool_calls");
+  if (!Array.isArray(toolCalls)) return;
+  for (const tc of toolCalls) {
+    if (!isPlainRecord(tc)) continue;
+    const id = safeGetOwnProperty(tc, "id");
+    if (typeof id === "string" && id.length > 0) {
+      into.add(id);
+    }
+  }
+}
+
+/**
+ * Returns the indices of `tool`-role messages whose `tool_call_id` does not
+ * appear in any *preceding* assistant message's `tool_calls`. A tool message
+ * with no `tool_call_id` at all is also considered orphan.
+ *
+ * Pure, exported for unit tests. Used by `stripOpenAIOrphanToolMessages`.
+ */
+export function findOrphanToolMessageIndices(messages: readonly unknown[]): {
+  indices: number[];
+  orphanIds: Array<string | null>;
+} {
+  const knownToolCallIds = new Set<string>();
+  const indices: number[] = [];
+  const orphanIds: Array<string | null> = [];
+
+  for (let i = 0; i < messages.length; i++) {
+    const msg = messages[i];
+    if (!isPlainRecord(msg)) continue;
+
+    const role = safeGetOwnProperty(msg, "role");
+
+    if (role === ROLE_ASSISTANT) {
+      collectAssistantToolCallIds(msg, knownToolCallIds);
+      continue;
+    }
+
+    if (role === ROLE_TOOL) {
+      const id = safeGetOwnProperty(msg, "tool_call_id");
+      if (typeof id !== "string" || id.length === 0) {
+        indices.push(i);
+        orphanIds.push(null);
+        continue;
+      }
+      if (!knownToolCallIds.has(id)) {
+        indices.push(i);
+        orphanIds.push(id);
+      }
+    }
+  }
+
+  return { indices, orphanIds };
+}
+
+/**
+ * Inspects an OpenAI-format request body and, if its `messages` array
+ * contains one or more orphan `tool` messages (see `findOrphanToolMessageIndices`),
+ * returns a new body with those messages removed. The original string is
+ * returned unchanged (by reference equality) when no edit is needed so the
+ * caller can skip a re-serialization.
+ *
+ * Tolerant of bodies that are not valid JSON, not OpenAI-format, or that
+ * have no `messages` array — all such inputs are returned unchanged.
+ */
+export function stripOpenAIOrphanToolMessages(rawBody: string): OrphanToolStripResult {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(rawBody);
+  } catch {
+    return { body: rawBody, removed: 0, orphanIds: [] };
+  }
+
+  if (!isObjectWithMessages(parsed)) {
+    return { body: rawBody, removed: 0, orphanIds: [] };
+  }
+
+  const messages = parsed.messages;
+  const { indices, orphanIds } = findOrphanToolMessageIndices(messages);
+
+  if (indices.length === 0) {
+    return { body: rawBody, removed: 0, orphanIds: [] };
+  }
+
+  const dropSet = new Set(indices);
+  const kept: unknown[] = [];
+  for (let i = 0; i < messages.length; i++) {
+    if (!dropSet.has(i)) kept.push(messages[i]);
+  }
+  parsed.messages = kept;
+
+  return { body: JSON.stringify(parsed), removed: indices.length, orphanIds };
+}