@tonyclaw/agent-inspector 3.1.19 → 3.1.21

package/src/proxy/sqliteLogIndex.ts

@@ -1,7 +1,12 @@
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { logger, resolveLogDir } from "./logger";
-import { ToolTraceEventSchema, type ApiFormat, type CaptureIncompleteReason } from "./schemas";
+import {
+  ToolTraceEventSchema,
+  type ApiFormat,
+  type CaptureIncompleteReason,
+  type StopReason,
+} from "./schemas";
 import type { LogIndexEntry, LogIndexSummary } from "./logIndex";
 import { ensurePrivateDirectorySync, securePrivateFileSync } from "./privateDataPath";
 
@@ -52,6 +57,7 @@ CREATE TABLE IF NOT EXISTS log_index (
   dropped_bytes INTEGER NOT NULL DEFAULT 0,
   capture_incomplete_reason TEXT,
   warnings_json TEXT,
+  stop_reason TEXT,
   tool_trace_events_json TEXT,
   error TEXT
 );
@@ -99,10 +105,11 @@ INSERT INTO log_index (
   dropped_bytes,
   capture_incomplete_reason,
   warnings_json,
+  stop_reason,
   tool_trace_events_json,
   error
 ) VALUES (
-  ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
+  ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
 )
 ON CONFLICT(id) DO UPDATE SET
   file = excluded.file,
@@ -141,6 +148,7 @@ ON CONFLICT(id) DO UPDATE SET
   dropped_bytes = excluded.dropped_bytes,
   capture_incomplete_reason = excluded.capture_incomplete_reason,
   warnings_json = excluded.warnings_json,
+  stop_reason = excluded.stop_reason,
   tool_trace_events_json = excluded.tool_trace_events_json,
   error = excluded.error
 `;
@@ -235,6 +243,7 @@ const REQUIRED_SCHEMA_COLUMNS = [
   { name: "dropped_chunks", definition: "INTEGER NOT NULL DEFAULT 0" },
   { name: "dropped_bytes", definition: "INTEGER NOT NULL DEFAULT 0" },
   { name: "capture_incomplete_reason", definition: "TEXT" },
+  { name: "stop_reason", definition: "TEXT" },
   { name: "tool_trace_events_json", definition: "TEXT" },
 ];
 
@@ -446,6 +455,7 @@ function entryParams(entry: LogIndexEntry): readonly unknown[] {
     summary?.droppedBytes ?? 0,
     summary?.captureIncompleteReason ?? null,
     warningJson(summary?.warnings),
+    summary?.stopReason ?? null,
     toolTraceEventsJson(summary),
     summary?.error ?? null,
   ];
@@ -496,6 +506,20 @@ function readCaptureIncompleteReason(row: unknown): CaptureIncompleteReason | nu
   }
 }
 
+function readStopReason(row: unknown): StopReason | null {
+  const value = readString(row, "stop_reason");
+  switch (value) {
+    case "end_turn":
+    case "tool_use":
+    case "stop":
+    case "length":
+      return value;
+    case null:
+    default:
+      return null;
+  }
+}
+
 function readWarnings(row: unknown): string[] | undefined {
   const value = readString(row, "warnings_json");
   if (value === null) return undefined;
@@ -566,6 +590,7 @@ function summaryFromRow(row: unknown, id: number): LogIndexSummary {
     droppedBytes: readNumber(row, "dropped_bytes") ?? 0,
     captureIncompleteReason: readCaptureIncompleteReason(row),
     warnings: readWarnings(row),
+    stopReason: readStopReason(row),
     toolTraceEvents: readToolTraceEvents(row),
     error: readString(row, "error"),
   };
@@ -602,6 +627,57 @@ export async function upsertSqliteLogIndexEntry(entry: LogIndexEntry): Promise<b
   return runPrepared(state.db, UPSERT_SQL, entryParams(entry));
 }
 
+export type SqliteLogCursorEntryFilters = {
+  sessionId?: string;
+  model?: string;
+  clientPid?: number;
+};
+
+function sqliteCursorWhereClause(filters: SqliteLogCursorEntryFilters): {
+  sql: string;
+  params: unknown[];
+} {
+  const clauses: string[] = [];
+  const params: unknown[] = [];
+  if (filters.sessionId !== undefined) {
+    clauses.push("session_id = ?");
+    params.push(filters.sessionId);
+  }
+  if (filters.model !== undefined) {
+    clauses.push("model = ?");
+    params.push(filters.model);
+  }
+  if (filters.clientPid !== undefined) {
+    clauses.push("client_pid = ?");
+    params.push(filters.clientPid);
+  }
+  return {
+    sql: clauses.length === 0 ? "" : ` WHERE ${clauses.join(" AND ")}`,
+    params,
+  };
+}
+
+export async function listSqliteLogCursorEntries(
+  filters: SqliteLogCursorEntryFilters,
+): Promise<LogIndexEntry[] | null> {
+  const state = await getSqliteState();
+  if (state.status !== "ready") return null;
+  const where = sqliteCursorWhereClause(filters);
+  const rows = allPrepared(
+    state.db,
+    `SELECT * FROM log_index${where.sql} ORDER BY id ASC`,
+    where.params,
+  );
+  if (rows === null) return null;
+  const entries: LogIndexEntry[] = [];
+  for (const row of rows) {
+    const entry = entryFromRow(row);
+    if (entry === null || entry.summary === undefined) return null;
+    entries.push(entry);
+  }
+  return entries;
+}
+
 export async function syncSqliteLogIndexEntries(
   entries: readonly LogIndexEntry[],
 ): Promise<boolean> {

package/src/proxy/storageLifecycle.ts

@@ -0,0 +1,432 @@
+import { existsSync, lstatSync, readdirSync, unlinkSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { getChunksDir } from "./chunkStorage";
+import { getDataDir } from "./dataDir";
+import { resolveApplicationLogPath, resolveLogDir } from "./logger";
+import { getRawStreamDir } from "./rawStreamCapture";
+import { getSessionArchiveRoot } from "./sessionArchive";
+
+export type StorageArtifactKind =
+  | "captured-log-jsonl"
+  | "sqlite-log-index"
+  | "session-archive"
+  | "streaming-chunk"
+  | "raw-stream-temp"
+  | "application-log"
+  | "evidence"
+  | "backup";
+
+export type StorageArtifactSensitivity = "captured-data" | "secret-adjacent" | "operational";
+
+export type StorageArtifactCleanupBehavior =
+  | "retention-gc"
+  | "orphan-reclaim"
+  | "rotation"
+  | "manual-owner-delete";
+
+export type StorageArtifactInventoryRule = {
+  kind: StorageArtifactKind;
+  root: string;
+  sensitivity: StorageArtifactSensitivity;
+  cleanupBehavior: StorageArtifactCleanupBehavior;
+  shouldCount: (fileName: string, path: string) => boolean;
+};
+
+export type StorageArtifactSummary = {
+  kind: StorageArtifactKind;
+  root: string;
+  sensitivity: StorageArtifactSensitivity;
+  cleanupBehavior: StorageArtifactCleanupBehavior;
+  fileCount: number;
+  bytes: number;
+  oldestModifiedAt: string | null;
+  newestModifiedAt: string | null;
+};
+
+export type StorageLifecycleInventory = {
+  checkedAt: string;
+  totalFiles: number;
+  totalBytes: number;
+  artifacts: StorageArtifactSummary[];
+};
+
+export type StorageLifecycleQuotaPolicy = {
+  maxAgeMs: number;
+  maxTotalBytes: number;
+};
+
+export type StorageLifecycleGcError = {
+  kind: StorageArtifactKind;
+  path: string;
+  message: string;
+};
+
+export type StorageLifecycleGcResult = {
+  checkedAt: string;
+  policy: StorageLifecycleQuotaPolicy;
+  before: StorageLifecycleInventory;
+  after: StorageLifecycleInventory;
+  filesScanned: number;
+  bytesScanned: number;
+  filesDeleted: number;
+  bytesDeleted: number;
+  reclaimableBytes: number;
+  errors: StorageLifecycleGcError[];
+};
+
+type MutableDirectoryStats = {
+  fileCount: number;
+  bytes: number;
+  oldestModifiedMs: number | null;
+  newestModifiedMs: number | null;
+};
+
+type StorageArtifactFile = {
+  rule: StorageArtifactInventoryRule;
+  path: string;
+  bytes: number;
+  modifiedMs: number;
+};
+
+const MAX_INVENTORY_DEPTH = 8;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_RETENTION_DAYS = 7;
+const DEFAULT_MAX_TOTAL_BYTES = 2 * 1024 * 1024 * 1024;
+const DEFAULT_MAINTENANCE_INTERVAL_MS = 60 * 60 * 1000;
+
+let maintenanceTimer: ReturnType<typeof setInterval> | null = null;
+let lastStorageLifecycleGcResult: StorageLifecycleGcResult | null = null;
+
+function emptyStats(): MutableDirectoryStats {
+  return {
+    fileCount: 0,
+    bytes: 0,
+    oldestModifiedMs: null,
+    newestModifiedMs: null,
+  };
+}
+
+function recordFile(stats: MutableDirectoryStats, bytes: number, modifiedMs: number): void {
+  stats.fileCount += 1;
+  stats.bytes += bytes;
+  stats.oldestModifiedMs =
+    stats.oldestModifiedMs === null ? modifiedMs : Math.min(stats.oldestModifiedMs, modifiedMs);
+  stats.newestModifiedMs =
+    stats.newestModifiedMs === null ? modifiedMs : Math.max(stats.newestModifiedMs, modifiedMs);
+}
+
+function isoFromMs(value: number | null): string | null {
+  return value === null ? null : new Date(value).toISOString();
+}
+
+function isPathInsideRoot(root: string, path: string): boolean {
+  const relativePath = relative(resolve(root), resolve(path));
+  return (
+    relativePath.length === 0 ||
+    (!relativePath.startsWith("..") &&
+      !relativePath.startsWith("/") &&
+      !relativePath.startsWith("\\"))
+  );
+}
+
+function collectRuleFiles(rule: StorageArtifactInventoryRule): StorageArtifactFile[] {
+  const files: StorageArtifactFile[] = [];
+  if (!existsSync(rule.root)) return files;
+
+  const visit = (currentDir: string, depth: number): void => {
+    if (depth > MAX_INVENTORY_DEPTH) return;
+    let entries: string[];
+    try {
+      entries = readdirSync(currentDir);
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const path = join(currentDir, entry);
+      if (!isPathInsideRoot(rule.root, path)) continue;
+      try {
+        const fileStats = lstatSync(path);
+        if (fileStats.isDirectory()) {
+          visit(path, depth + 1);
+          continue;
+        }
+        if (!fileStats.isFile() || !rule.shouldCount(entry, path)) continue;
+        files.push({ rule, path, bytes: fileStats.size, modifiedMs: fileStats.mtimeMs });
+      } catch {
+        // Files may disappear while inventory is collected; keep inventory best-effort and safe.
+      }
+    }
+  };
+
+  visit(rule.root, 0);
+  return files;
+}
+
+function collectRuleStats(rule: StorageArtifactInventoryRule): MutableDirectoryStats {
+  const stats = emptyStats();
+  for (const file of collectRuleFiles(rule)) {
+    recordFile(stats, file.bytes, file.modifiedMs);
+  }
+  return stats;
+}
+
+function isAutoDeletableCleanupBehavior(behavior: StorageArtifactCleanupBehavior): boolean {
+  switch (behavior) {
+    case "retention-gc":
+    case "orphan-reclaim":
+      return true;
+    case "rotation":
+    case "manual-owner-delete":
+      return false;
+  }
+}
+
+function summarizeRule(rule: StorageArtifactInventoryRule): StorageArtifactSummary {
+  const stats = collectRuleStats(rule);
+  return {
+    kind: rule.kind,
+    root: rule.root,
+    sensitivity: rule.sensitivity,
+    cleanupBehavior: rule.cleanupBehavior,
+    fileCount: stats.fileCount,
+    bytes: stats.bytes,
+    oldestModifiedAt: isoFromMs(stats.oldestModifiedMs),
+    newestModifiedAt: isoFromMs(stats.newestModifiedMs),
+  };
+}
+
+function isSessionArchiveFile(fileName: string): boolean {
+  return fileName === "session.sqlite" || fileName.startsWith("session.sqlite-");
+}
+
+function isSqliteLogIndexFile(fileName: string): boolean {
+  return fileName === "inspector.sqlite" || fileName.startsWith("inspector.sqlite-");
+}
+
+function isBackupFile(fileName: string): boolean {
+  return fileName.endsWith(".bak") || fileName.endsWith(".backup");
+}
+
+function applicationLogMatcher(logPath: string): (fileName: string, path: string) => boolean {
+  const directory = dirname(logPath);
+  const baseName = basename(logPath);
+  return (fileName, path) => {
+    if (dirname(path) !== directory) return false;
+    if (fileName === baseName) return true;
+    return fileName.startsWith(`${baseName}.`) && /^\d+$/.test(fileName.slice(baseName.length + 1));
+  };
+}
+
+function parsePositiveIntegerEnv(name: string, fallback: number): number {
+  const value = process.env[name];
+  if (value === undefined) return fallback;
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return parsed;
+}
+
+export function resolveStorageLifecycleQuotaPolicy(): StorageLifecycleQuotaPolicy {
+  const retentionDays = parsePositiveIntegerEnv(
+    "AGENT_INSPECTOR_STORAGE_RETENTION_DAYS",
+    parsePositiveIntegerEnv("LOG_RETENTION_DAYS", DEFAULT_RETENTION_DAYS),
+  );
+  return {
+    maxAgeMs: retentionDays * DAY_MS,
+    maxTotalBytes: parsePositiveIntegerEnv(
+      "AGENT_INSPECTOR_STORAGE_MAX_BYTES",
+      DEFAULT_MAX_TOTAL_BYTES,
+    ),
+  };
+}
+
+export function getStorageLifecycleInventoryRules(): StorageArtifactInventoryRule[] {
+  const applicationLogPath = resolveApplicationLogPath();
+  return [
+    {
+      kind: "captured-log-jsonl",
+      root: resolveLogDir(),
+      sensitivity: "captured-data",
+      cleanupBehavior: "retention-gc",
+      shouldCount: (fileName) => fileName.endsWith(".jsonl"),
+    },
+    {
+      kind: "sqlite-log-index",
+      root: resolveLogDir(),
+      sensitivity: "captured-data",
+      cleanupBehavior: "orphan-reclaim",
+      shouldCount: isSqliteLogIndexFile,
+    },
+    {
+      kind: "session-archive",
+      root: getSessionArchiveRoot(),
+      sensitivity: "captured-data",
+      cleanupBehavior: "retention-gc",
+      shouldCount: isSessionArchiveFile,
+    },
+    {
+      kind: "streaming-chunk",
+      root: getChunksDir(),
+      sensitivity: "captured-data",
+      cleanupBehavior: "retention-gc",
+      shouldCount: (fileName) => fileName.endsWith(".json"),
+    },
+    {
+      kind: "raw-stream-temp",
+      root: getRawStreamDir(),
+      sensitivity: "captured-data",
+      cleanupBehavior: "orphan-reclaim",
+      shouldCount: () => true,
+    },
+    {
+      kind: "application-log",
+      root: dirname(applicationLogPath),
+      sensitivity: "operational",
+      cleanupBehavior: "rotation",
+      shouldCount: applicationLogMatcher(applicationLogPath),
+    },
+    {
+      kind: "evidence",
+      root: join(getDataDir(), "evidence"),
+      sensitivity: "captured-data",
+      cleanupBehavior: "manual-owner-delete",
+      shouldCount: () => true,
+    },
+    {
+      kind: "backup",
+      root: getDataDir(),
+      sensitivity: "secret-adjacent",
+      cleanupBehavior: "orphan-reclaim",
+      shouldCount: isBackupFile,
+    },
+  ];
+}
+
+export function getStorageLifecycleInventory(
+  rules: readonly StorageArtifactInventoryRule[] = getStorageLifecycleInventoryRules(),
+): StorageLifecycleInventory {
+  const artifacts = rules.map(summarizeRule);
+  return {
+    checkedAt: new Date().toISOString(),
+    totalFiles: artifacts.reduce((sum, artifact) => sum + artifact.fileCount, 0),
+    totalBytes: artifacts.reduce((sum, artifact) => sum + artifact.bytes, 0),
+    artifacts,
+  };
+}
+
+function collectLifecycleFiles(
+  rules: readonly StorageArtifactInventoryRule[] = getStorageLifecycleInventoryRules(),
+): StorageArtifactFile[] {
+  return rules.flatMap((rule) => collectRuleFiles(rule));
+}
+
+function selectGcCandidates(
+  files: readonly StorageArtifactFile[],
+  policy: StorageLifecycleQuotaPolicy,
+  nowMs: number,
+): StorageArtifactFile[] {
+  const autoDeletableFiles = files.filter((file) =>
+    isAutoDeletableCleanupBehavior(file.rule.cleanupBehavior),
+  );
+  const expiredFiles = autoDeletableFiles.filter(
+    (file) => nowMs - file.modifiedMs > policy.maxAgeMs,
+  );
+  const expiredPaths = new Set(expiredFiles.map((file) => file.path));
+  const candidates = [...expiredFiles];
+  let totalBytes =
+    files.reduce((sum, file) => sum + file.bytes, 0) -
+    expiredFiles.reduce((sum, file) => sum + file.bytes, 0);
+
+  if (totalBytes <= policy.maxTotalBytes) return candidates;
+
+  const quotaCandidates = autoDeletableFiles
+    .filter((file) => !expiredPaths.has(file.path))
+    .sort((a, b) => a.modifiedMs - b.modifiedMs);
+
+  for (const file of quotaCandidates) {
+    if (totalBytes <= policy.maxTotalBytes) break;
+    candidates.push(file);
+    totalBytes -= file.bytes;
+  }
+
+  return candidates;
+}
+
+function deleteLifecycleFile(file: StorageArtifactFile): StorageLifecycleGcError | null {
+  if (!isPathInsideRoot(file.rule.root, file.path)) {
+    return { kind: file.rule.kind, path: file.path, message: "path outside lifecycle root" };
+  }
+  try {
+    unlinkSync(file.path);
+    return null;
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("ENOENT")) return null;
+    return { kind: file.rule.kind, path: file.path, message: String(err) };
+  }
+}
+
+export function runStorageLifecycleGc(
+  policy: StorageLifecycleQuotaPolicy = resolveStorageLifecycleQuotaPolicy(),
+  rules: readonly StorageArtifactInventoryRule[] = getStorageLifecycleInventoryRules(),
+  nowMs: number = Date.now(),
+): StorageLifecycleGcResult {
+  const before = getStorageLifecycleInventory(rules);
+  const files = collectLifecycleFiles(rules);
+  const candidates = selectGcCandidates(files, policy, nowMs);
+  const errors: StorageLifecycleGcError[] = [];
+  let filesDeleted = 0;
+  let bytesDeleted = 0;
+
+  for (const file of candidates) {
+    const error = deleteLifecycleFile(file);
+    if (error !== null) {
+      errors.push(error);
+      continue;
+    }
+    filesDeleted += 1;
+    bytesDeleted += file.bytes;
+  }
+
+  const after = getStorageLifecycleInventory(rules);
+  const autoDeletableBytes = after.artifacts
+    .filter((artifact) => isAutoDeletableCleanupBehavior(artifact.cleanupBehavior))
+    .reduce((sum, artifact) => sum + artifact.bytes, 0);
+
+  const result = {
+    checkedAt: new Date(nowMs).toISOString(),
+    policy,
+    before,
+    after,
+    filesScanned: files.length,
+    bytesScanned: files.reduce((sum, file) => sum + file.bytes, 0),
+    filesDeleted,
+    bytesDeleted,
+    reclaimableBytes: autoDeletableBytes,
+    errors,
+  };
+  lastStorageLifecycleGcResult = result;
+  return result;
+}
+
+export function getLastStorageLifecycleGcResult(): StorageLifecycleGcResult | null {
+  return lastStorageLifecycleGcResult;
+}
+
+export function installStorageLifecycleMaintenance(): void {
+  if (maintenanceTimer !== null) return;
+  if (process.env["NODE_ENV"] === "test") return;
+  const intervalMs = parsePositiveIntegerEnv(
+    "AGENT_INSPECTOR_STORAGE_GC_INTERVAL_MS",
+    DEFAULT_MAINTENANCE_INTERVAL_MS,
+  );
+  maintenanceTimer = setInterval(() => {
+    runStorageLifecycleGc();
+  }, intervalMs);
+  maintenanceTimer.unref();
+}
+
+export function stopStorageLifecycleMaintenanceForTests(): void {
+  if (maintenanceTimer === null) return;
+  clearInterval(maintenanceTimer);
+  maintenanceTimer = null;
+}