agent-inspect 3.3.0 → 3.5.0

package/packages/cli/dist/index.mjs

@@ -5,7 +5,7 @@ import { fileURLToPath, pathToFileURL } from 'url';
 import { Command, Option } from 'commander';
 import { AsyncLocalStorage } from 'async_hooks';
 import crypto, { webcrypto, createHash } from 'crypto';
-import { unlink, stat, mkdir, writeFile, appendFile, readdir, readFile, access, open, constants } from 'fs/promises';
+import { unlink, stat, mkdir, writeFile, appendFile, rm, readdir, readFile, access, open, constants } from 'fs/promises';
 import os from 'os';
 import process3, { stdin, stdout } from 'process';
 import tty from 'tty';
@@ -14,7 +14,7 @@ import { createServer } from 'http';
 import { createRequire } from 'module';
 
 // package.json
-var version = "3.3.0";
+var version = "3.5.0";
 
 // packages/core/src/correlation-metadata.ts
 var TRACE_CORRELATION_KEYS = [
@@ -3060,12 +3060,12 @@ function buildCriticalPath(runs, handoffs) {
     handoffs.filter((edge) => edge.confidence === "explicit").map((edge) => edge.from)
   );
   const ordered = [...runs].sort(compareRuns);
-  const path18 = [];
+  const path19 = [];
   const visited = /* @__PURE__ */ new Set();
   const pushRun = (run, confidence, source) => {
     if (visited.has(run.runId)) return;
     visited.add(run.runId);
-    path18.push({
+    path19.push({
       runId: run.runId,
       name: run.name,
       startedAt: run.startedAt,
@@ -3090,7 +3090,7 @@ function buildCriticalPath(runs, handoffs) {
     const confidence = explicitTargets.has(run.runId) || explicitSources.has(run.runId) ? "explicit" : "correlated";
     pushRun(run, confidence, confidence === "explicit" ? "manual" : "inferred");
   }
-  return path18;
+  return path19;
 }
 function metaRunIdMatches(run, token, runById) {
   const meta = extractSessionWorkflowMetadata(run.metadata);
@@ -3203,6 +3203,62 @@ async function isAgentInspectTrace(filePath) {
   }
 }
 
+// packages/cli/src/trace-dir-scale.ts
+var TRACE_COUNT_WARN = 1e3;
+var TRACE_COUNT_SEVERE = 1e4;
+var LARGE_TRACE_FILE_BYTES = 50 * 1024 * 1024;
+function buildScaleWarnings(traceCount, largeFileCount) {
+  const warnings = [];
+  if (traceCount >= TRACE_COUNT_SEVERE) {
+    warnings.push(
+      `trace directory has ${traceCount} runs (>= ${TRACE_COUNT_SEVERE}); archive or split traces \u2014 see docs/SCALE-LIMITS.md`
+    );
+  } else if (traceCount >= TRACE_COUNT_WARN) {
+    warnings.push(
+      `trace directory has ${traceCount} runs (>= ${TRACE_COUNT_WARN}); list/search/stats may be slow \u2014 consider agent-inspect index build`
+    );
+  }
+  if (largeFileCount > 0) {
+    warnings.push(
+      `${largeFileCount} trace file(s) exceed ${Math.round(LARGE_TRACE_FILE_BYTES / (1024 * 1024))}MB; open/check/report may be slow`
+    );
+  }
+  return warnings;
+}
+async function assessTraceDirectoryScale(td, options = {}) {
+  const files = await td.list();
+  const sample = options.sampleLargeFiles ?? 25;
+  let largeFileCount = 0;
+  if (files.length > 0 && files.length <= sample * 4) {
+    for (const file of files) {
+      try {
+        const stats = await td.getFileStats(file);
+        if (stats.size >= LARGE_TRACE_FILE_BYTES) largeFileCount += 1;
+      } catch {
+      }
+    }
+  } else if (files.length > sample) {
+    for (const file of files.slice(0, sample)) {
+      try {
+        const stats = await td.getFileStats(file);
+        if (stats.size >= LARGE_TRACE_FILE_BYTES) largeFileCount += 1;
+      } catch {
+      }
+    }
+    if (largeFileCount > 0) {
+      largeFileCount = Math.max(largeFileCount, 1);
+    }
+  }
+  const warnings = buildScaleWarnings(files.length, largeFileCount);
+  return { traceCount: files.length, largeFileCount, warnings };
+}
+function emitScaleWarnings(assessment, options = {}) {
+  if (options.json || assessment.warnings.length === 0) return;
+  for (const warning of assessment.warnings) {
+    console.error(`[AgentInspect] warning: ${warning}`);
+  }
+}
+
 // packages/cli/src/list.ts
 function parseLimit(raw) {
   const fallback = 20;
@@ -3237,6 +3293,8 @@ async function list(options = {}) {
       parseDuration(options.since.trim());
     }
     const files = await td.list();
+    const scale = await assessTraceDirectoryScale(td);
+    emitScaleWarnings(scale, { json: options.json });
     if (files.length === 0) {
       if (options.json) {
         console.log("[]");
@@ -8333,13 +8391,13 @@ function pairSteps(left, right) {
   return pairs;
 }
 function compareLeafSteps(L, R, segments, opts, out) {
-  const path18 = buildPath(segments);
+  const path19 = buildPath(segments);
   if (L.name !== R.name) {
     out.push({
       kind: "structure",
       severity: "warning",
       message: "Step name differs",
-      path: path18,
+      path: path19,
       left: L.name,
       right: R.name
     });
@@ -8349,7 +8407,7 @@ function compareLeafSteps(L, R, segments, opts, out) {
       kind: "step-type",
       severity: "warning",
       message: "Step type differs",
-      path: path18,
+      path: path19,
       left: L.type,
       right: R.type
     });
@@ -8359,7 +8417,7 @@ function compareLeafSteps(L, R, segments, opts, out) {
       kind: "step-status",
       severity: "warning",
       message: "Step status differs",
-      path: path18,
+      path: path19,
       left: L.status,
       right: R.status
     });
@@ -8371,7 +8429,7 @@ function compareLeafSteps(L, R, segments, opts, out) {
       kind: "error",
       severity: "error",
       message: "Step error message differs",
-      path: path18,
+      path: path19,
       left: le || void 0,
       right: re || void 0
     });
@@ -8389,20 +8447,20 @@ function compareLeafSteps(L, R, segments, opts, out) {
         kind: "duration",
         severity: "info",
         message: "Step duration differs",
-        path: path18,
+        path: path19,
         left: ld,
         right: rd
       });
     }
   }
   const lm = stableJson(L.metadata ?? {});
-  const rm = stableJson(R.metadata ?? {});
-  if (lm !== rm) {
+  const rm2 = stableJson(R.metadata ?? {});
+  if (lm !== rm2) {
     out.push({
       kind: "metadata",
       severity: "info",
       message: "Step metadata differs",
-      path: path18,
+      path: path19,
       left: L.metadata,
       right: R.metadata
     });
@@ -8414,7 +8472,7 @@ function compareLeafSteps(L, R, segments, opts, out) {
       kind: "output",
       severity: "info",
       message: "Output preview differs",
-      path: path18,
+      path: path19,
       left: L.outputPreview,
       right: R.outputPreview
     });
@@ -8574,11 +8632,11 @@ function diffRuns(left, right, options) {
 }
 
 // packages/core/src/diff/renderer.ts
-function formatPath(path18) {
-  if (path18 === void 0 || path18.path.length === 0) {
+function formatPath(path19) {
+  if (path19 === void 0 || path19.path.length === 0) {
     return "(run)";
   }
-  return path18.path.map((s) => s.name).join(" > ");
+  return path19.path.map((s) => s.name).join(" > ");
 }
 function formatValue(v, verbose) {
   if (v === void 0) return "(undefined)";
@@ -8804,6 +8862,8 @@ async function statsCommand(options = {}) {
       parseDuration(options.since.trim());
     }
     const files = await td.list();
+    const scale = await assessTraceDirectoryScale(td);
+    emitScaleWarnings(scale, { json: options.json });
     if (files.length === 0) {
       if (options.json) {
         console.log(
@@ -8874,6 +8934,8 @@ async function searchCommand(options = {}) {
       parseDurationFilter(options.duration);
     }
     const files = await td.list();
+    const scale = await assessTraceDirectoryScale(td);
+    emitScaleWarnings(scale, { json: options.json });
     let metas = await loadTraceMetadataList(
       traceDir,
       files,
@@ -9456,17 +9518,17 @@ function applyRule(rule, value, replacement) {
   }
   return value;
 }
-function childPath(path18, key) {
+function childPath(path19, key) {
   if (/^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)) {
-    return path18 ? `${path18}.${key}` : key;
+    return path19 ? `${path19}.${key}` : key;
   }
-  return `${path18 || "$"}[${JSON.stringify(key)}]`;
+  return `${path19 || "$"}[${JSON.stringify(key)}]`;
 }
-function indexPath(path18, index) {
-  return `${path18 || "$"}[${index}]`;
+function indexPath(path19, index) {
+  return `${path19 || "$"}[${index}]`;
 }
-function makeFinding(path18, detector, action, matchKind, severity = "warning", preview) {
-  return preview === void 0 ? { path: path18, detector, action, severity, matchKind } : { path: path18, detector, action, severity, matchKind, preview };
+function makeFinding(path19, detector, action, matchKind, severity = "warning", preview) {
+  return preview === void 0 ? { path: path19, detector, action, severity, matchKind } : { path: path19, detector, action, severity, matchKind, preview };
 }
 function createRedactionProfile(profile = "local") {
   switch (profile) {
@@ -9535,11 +9597,11 @@ var Redactor2 = class {
   #recordFinding(state, finding) {
     if (this.#collectFindings) state.findings.push(finding);
   }
-  #redactValue(value, key, path18, depth, state) {
+  #redactValue(value, key, path19, depth, state) {
     if (depth > this.#maxDepth) {
       this.#recordFinding(
         state,
-        makeFinding(path18, "structure.maxDepth", "truncate", "value", "warning")
+        makeFinding(path19, "structure.maxDepth", "truncate", "value", "warning")
       );
       return "[Truncated]";
     }
@@ -9548,19 +9610,19 @@ var Redactor2 = class {
       if (rule) {
         this.#recordFinding(
           state,
-          makeFinding(path18, `key.${rule.key}`, actionForRule(rule), "key", "warning")
+          makeFinding(path19, `key.${rule.key}`, actionForRule(rule), "key", "warning")
         );
         return applyRule(rule, value, this.#replacement);
       }
     }
     for (const detector of this.#detectors) {
-      const detections = detector.detect({ path: path18, key, value });
+      const detections = detector.detect({ path: path19, key, value });
       for (const detection of detections) {
         const action = detection.action ?? "replace";
         this.#recordFinding(
           state,
           makeFinding(
-            path18,
+            path19,
             detector.id,
             action,
             detection.matchKind ?? detector.matchKind ?? "custom",
@@ -9578,7 +9640,7 @@ var Redactor2 = class {
       const out = [];
       state.seen.set(value, out);
       value.forEach((item, index) => {
-        out[index] = this.#redactValue(item, void 0, indexPath(path18, index), depth + 1, state);
+        out[index] = this.#redactValue(item, void 0, indexPath(path19, index), depth + 1, state);
       });
       return out;
     }
@@ -9590,7 +9652,7 @@ var Redactor2 = class {
         out[entryKey] = this.#redactValue(
           entryValue,
           entryKey,
-          childPath(path18 === "$" ? "" : path18, entryKey),
+          childPath(path19 === "$" ? "" : path19, entryKey),
           depth + 1,
           state
         );
@@ -10462,7 +10524,7 @@ function stripPrefix(name, prefixes) {
   }
   return name;
 }
-function eventEvidence(event, path18) {
+function eventEvidence(event, path19) {
   return {
     runId: event.runId,
     eventId: event.eventId,
@@ -10472,7 +10534,7 @@ function eventEvidence(event, path18) {
     kind: event.kind,
     name: event.name,
     status: event.status,
-    ...path18 ? { path: path18 } : {}
+    ...path19 ? { path: path19 } : {}
   };
 }
 function runEvidence(run) {
@@ -10535,9 +10597,9 @@ function eventEndMs(event) {
 function normalizedKey(value) {
   return value.toLowerCase().replace(/[^a-z0-9_]/g, "");
 }
-function lastPathSegment(path18) {
-  const parts = path18.split(".");
-  return parts[parts.length - 1] ?? path18;
+function lastPathSegment(path19) {
+  const parts = path19.split(".");
+  return parts[parts.length - 1] ?? path19;
 }
 function valueType(value) {
   if (Array.isArray(value)) return "array";
@@ -10551,12 +10613,12 @@ function serializedByteLength(value) {
     return void 0;
   }
 }
-function pushValueEntries(entries, event, value, path18, key, depth = 0) {
-  entries.push({ event, path: path18, key, value });
+function pushValueEntries(entries, event, value, path19, key, depth = 0) {
+  entries.push({ event, path: path19, key, value });
   if (depth >= 8) return;
   if (Array.isArray(value)) {
     for (const [index, item] of value.entries()) {
-      pushValueEntries(entries, event, item, `${path18}.${index}`, String(index), depth + 1);
+      pushValueEntries(entries, event, item, `${path19}.${index}`, String(index), depth + 1);
     }
     return;
   }
@@ -10566,7 +10628,7 @@ function pushValueEntries(entries, event, value, path18, key, depth = 0) {
       entries,
       event,
       value[nestedKey],
-      `${path18}.${nestedKey}`,
+      `${path19}.${nestedKey}`,
       nestedKey,
       depth + 1
     );
@@ -10647,9 +10709,9 @@ function eventDurationMs(event) {
 }
 function treeShape(nodes) {
   const lines = [];
-  const visit = (node, path18) => {
-    lines.push(`${path18}:${node.event.kind}:${node.event.name}:${node.event.status ?? "unknown"}`);
-    node.children.forEach((child, index) => visit(child, `${path18}.${index}`));
+  const visit = (node, path19) => {
+    lines.push(`${path19}:${node.event.kind}:${node.event.name}:${node.event.status ?? "unknown"}`);
+    node.children.forEach((child, index) => visit(child, `${path19}.${index}`));
   };
   nodes.forEach((node, index) => visit(node, String(index)));
   return lines;
@@ -10698,9 +10760,9 @@ function retrievalShape(context) {
 function guardrailShape(context) {
   return guardrailEvents(context).map((event) => signalName(event, ["guardrailName", "guardrail", "guardrailId"], ["guardrail:"])).sort((a, b) => a.localeCompare(b));
 }
-function firstEvidenceForKind(context, kind, path18) {
+function firstEvidenceForKind(context, kind, path19) {
   const event = context.events.find((candidate) => candidate.kind === kind);
-  return event ? [eventEvidence(event, path18)] : runEvidence(context.selectedRun);
+  return event ? [eventEvidence(event, path19)] : runEvidence(context.selectedRun);
 }
 function baselineDiffFinding(message, evidence, expected, actual) {
   return failFinding("baseline.regression", message, evidence, expected, actual);
@@ -10764,6 +10826,108 @@ function createRunDurationRule(options) {
     }
   };
 }
+function createMaxStepDurationRule(options) {
+  return {
+    id: "run.maxStepDuration",
+    category: "run",
+    defaultSeverity: "error",
+    evaluate(context) {
+      const over = context.events.filter((event) => {
+        const duration = eventDurationMs(event);
+        return duration !== void 0 && duration > options.maxDurationMs;
+      });
+      if (over.length === 0) return [];
+      return [
+        failFinding(
+          "run.maxStepDuration",
+          `${over.length} step(s) exceeded max duration ${options.maxDurationMs}ms.`,
+          over.map((event) => eventEvidence(event, "durationMs")),
+          { maxDurationMs: options.maxDurationMs },
+          over.map((event) => ({
+            eventId: event.eventId,
+            name: event.name,
+            durationMs: eventDurationMs(event)
+          }))
+        )
+      ];
+    }
+  };
+}
+function createStallDetectionRule(options = {}) {
+  const requireEndedAt = options.requireEndedAt === true;
+  return {
+    id: "run.stall",
+    category: "run",
+    defaultSeverity: "warning",
+    evaluate(context) {
+      const findings = [];
+      const running = context.events.filter((event) => event.status === "running");
+      if (running.length > 0) {
+        findings.push(
+          failFinding(
+            "run.stall",
+            `Found ${running.length} event(s) still running (possible stall).`,
+            running.map((event) => eventEvidence(event, "status")),
+            "no running events",
+            running.length
+          )
+        );
+      }
+      if (requireEndedAt) {
+        const incomplete = context.events.filter(
+          (event) => event.startedAt !== void 0 && event.endedAt === void 0 && event.status !== "running"
+        );
+        if (incomplete.length > 0) {
+          findings.push(
+            failFinding(
+              "run.stall",
+              `Found ${incomplete.length} started event(s) without endedAt.`,
+              incomplete.map((event) => eventEvidence(event, "endedAt")),
+              "endedAt for started events",
+              incomplete.length
+            )
+          );
+        }
+      }
+      return findings;
+    }
+  };
+}
+function createRequireCompletedRule() {
+  return {
+    id: "run.requireCompleted",
+    category: "run",
+    defaultSeverity: "error",
+    evaluate(context) {
+      const findings = [];
+      const runStatus = context.selectedRun?.status;
+      if (runStatus === "running") {
+        findings.push(
+          failFinding(
+            "run.requireCompleted",
+            "Run is still running.",
+            runEvidence(context.selectedRun),
+            "completed run",
+            runStatus
+          )
+        );
+      }
+      const running = context.events.filter((event) => event.status === "running");
+      if (running.length > 0) {
+        findings.push(
+          failFinding(
+            "run.requireCompleted",
+            `Run has ${running.length} incomplete running event(s).`,
+            running.map((event) => eventEvidence(event, "status")),
+            "no running events",
+            running.length
+          )
+        );
+      }
+      return findings;
+    }
+  };
+}
 function createRunDepthRule(options) {
   return {
     id: "run.depth",
@@ -10948,13 +11112,13 @@ function createStructureCycleRule() {
       const seenCycles = /* @__PURE__ */ new Set();
       const findings = [];
       for (const event of [...context.events].sort((a, b) => a.eventId.localeCompare(b.eventId))) {
-        const path18 = [];
+        const path19 = [];
         const seenAt = /* @__PURE__ */ new Map();
         let current = event;
         while (current) {
           const existing = seenAt.get(current.eventId);
           if (existing !== void 0) {
-            const cycle = path18.slice(existing);
+            const cycle = path19.slice(existing);
             const key = cycle.map((item) => item.eventId).sort().join("\0");
             if (!seenCycles.has(key)) {
               seenCycles.add(key);
@@ -10970,8 +11134,8 @@ function createStructureCycleRule() {
             }
             break;
           }
-          seenAt.set(current.eventId, path18.length);
-          path18.push(current);
+          seenAt.set(current.eventId, path19.length);
+          path19.push(current);
           current = current.parentId ? byId.get(current.parentId) : void 0;
         }
       }
@@ -11768,23 +11932,23 @@ function evaluatePromptInjection(text, options = {}) {
   }
   return fail(ruleId, `Matched ${evidence.length} injection pattern(s).`, evidence, "warning");
 }
-function validateSchemaField(value, field, path18, evidence) {
+function validateSchemaField(value, field, path19, evidence) {
   const ruleId = "guardrail.structured-output";
   if (field.type) {
     const actual = value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
     if (actual !== field.type) {
-      evidence.push({ ruleId, path: path18, preview: `expected ${field.type}, got ${actual}` });
+      evidence.push({ ruleId, path: path19, preview: `expected ${field.type}, got ${actual}` });
       return;
     }
   }
   if (field.enum && !field.enum.some((item) => Object.is(item, value))) {
-    evidence.push({ ruleId, path: path18, preview: "value not in enum" });
+    evidence.push({ ruleId, path: path19, preview: "value not in enum" });
   }
   if (field.type === "object" && field.required && value && typeof value === "object" && !Array.isArray(value)) {
     const record = value;
     for (const key of field.required) {
       if (!(key in record)) {
-        evidence.push({ ruleId, path: `${path18}.${key}`, preview: "missing required key" });
+        evidence.push({ ruleId, path: `${path19}.${key}`, preview: "missing required key" });
       }
     }
   }
@@ -12145,6 +12309,17 @@ function buildRules(config, options) {
   const safety = checks2.safety ?? {};
   const maxDurationMs = parseNumber(options.maxDurationMs, "--max-duration-ms") ?? run.maxDurationMs;
   const maxTotalTokens = parseNumber(options.maxTotalTokens, "--max-total-tokens") ?? llm.maxTotalTokens;
+  let maxStepDurationMs;
+  if (options.maxStepDuration !== void 0) {
+    try {
+      maxStepDurationMs = parseDuration(options.maxStepDuration.trim());
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      diagnostics.push(
+        diagnostic2("AI_CHECK_INVALID_ARGUMENTS", `--max-step-duration: ${message}`)
+      );
+    }
+  }
   const rules = [
     createRunStatusRule(run),
     createStructureOrphanRule(),
@@ -12155,6 +12330,15 @@ function buildRules(config, options) {
   if (maxDurationMs !== void 0) {
     rules.push(createRunDurationRule({ maxDurationMs }));
   }
+  if (maxStepDurationMs !== void 0) {
+    rules.push(createMaxStepDurationRule({ maxDurationMs: maxStepDurationMs }));
+  }
+  if (options.requireCompleted) {
+    rules.push(createRequireCompletedRule());
+  }
+  if (options.detectStalls) {
+    rules.push(createStallDetectionRule({ requireEndedAt: true }));
+  }
   if (run.maxDepth !== void 0) {
     rules.push(createRunDepthRule({ maxDepth: run.maxDepth }));
   }
@@ -12249,10 +12433,10 @@ function printHuman(result) {
     console.log(`- ${diagnostic4.code}: ${diagnostic4.message}`);
   }
   for (const finding of result.findings) {
-    const path18 = finding.evidence[0]?.path;
+    const path19 = finding.evidence[0]?.path;
     const run = finding.evidence[0]?.runId;
     const runPrefix = run ? `[${run}] ` : "";
-    console.log(`- ${runPrefix}${finding.ruleId}: ${finding.message}${path18 ? ` (${path18})` : ""}`);
+    console.log(`- ${runPrefix}${finding.ruleId}: ${finding.message}${path19 ? ` (${path19})` : ""}`);
   }
 }
 function readErrorResult(error) {
@@ -12790,10 +12974,10 @@ async function evalRun(input3, options = {}) {
     diagnostics: []
   };
 }
-function evidenceForRun(run, path18) {
-  return [{ runId: run.runId, ...path18 !== void 0 ? { path: path18 } : {} }];
+function evidenceForRun(run, path19) {
+  return [{ runId: run.runId, ...path19 !== void 0 ? { path: path19 } : {} }];
 }
-function evidenceForEvent(event, path18) {
+function evidenceForEvent(event, path19) {
   return [
     {
       runId: event.runId,
@@ -12801,7 +12985,7 @@ function evidenceForEvent(event, path18) {
       ...event.parentId !== void 0 ? { parentId: event.parentId } : {},
       kind: event.kind,
       name: event.name,
-      ...path18 !== void 0 ? { path: path18 } : {}
+      ...path19 !== void 0 ? { path: path19 } : {}
     }
   ];
 }
@@ -12959,9 +13143,9 @@ function collectTextFields(nodes, keys, preferredKinds = []) {
 function tokenize(text) {
   return [...text.toLowerCase().matchAll(/[a-z0-9][a-z0-9'-]{2,}/g)].map((match) => match[0].replace(/^['-]+|['-]+$/g, "")).filter((token) => token.length > 2 && !STOP_WORDS.has(token));
 }
-function firstEvidence(fields, run, path18) {
+function firstEvidence(fields, run, path19) {
   const first = fields[0];
-  return first === void 0 ? evidenceForRun(run, path18) : evidenceForEvent(first.node.event, first.path);
+  return first === void 0 ? evidenceForRun(run, path19) : evidenceForEvent(first.node.event, first.path);
 }
 function collectSourceIds(nodes, keys) {
   const wanted = keySet(keys);
@@ -13338,8 +13522,8 @@ function renderEvalMarkdown(result) {
   if (result.findings.length > 0) {
     lines.push("", "## Findings");
     for (const finding of result.findings) {
-      const path18 = finding.evidence[0]?.path;
-      lines.push(`- ${finding.ruleId}: ${finding.message}${path18 ? ` (${path18})` : ""}`);
+      const path19 = finding.evidence[0]?.path;
+      lines.push(`- ${finding.ruleId}: ${finding.message}${path19 ? ` (${path19})` : ""}`);
     }
   }
   return `${lines.join("\n")}
@@ -13532,8 +13716,8 @@ function printHuman2(result) {
     console.log(`- ${diagnostic4.code}: ${diagnostic4.message}`);
   }
   for (const finding of result.findings) {
-    const path18 = finding.evidence[0]?.path;
-    console.log(`- ${finding.ruleId}: ${finding.message}${path18 ? ` (${path18})` : ""}`);
+    const path19 = finding.evidence[0]?.path;
+    console.log(`- ${finding.ruleId}: ${finding.message}${path19 ? ` (${path19})` : ""}`);
   }
 }
 function readErrorResult2(error) {
@@ -13771,8 +13955,8 @@ function printHuman3(result) {
     console.log(`- ${diagnostic4.code}: ${diagnostic4.message}`);
   }
   for (const finding of result.findings) {
-    const path18 = finding.evidence[0]?.path;
-    console.log(`- ${finding.ruleId}: ${finding.message}${path18 ? ` (${path18})` : ""}`);
+    const path19 = finding.evidence[0]?.path;
+    console.log(`- ${finding.ruleId}: ${finding.message}${path19 ? ` (${path19})` : ""}`);
   }
   console.log(`Note: ${result.note}`);
 }
@@ -13891,8 +14075,8 @@ function renderCheckSection(result) {
     `Diagnostics: ${result.diagnostics.length}`
   ];
   for (const finding of result.findings.slice(0, 10)) {
-    const path18 = finding.evidence[0]?.path ?? "(run)";
-    lines.push(`- ${finding.ruleId}: ${finding.message} (${path18})`);
+    const path19 = finding.evidence[0]?.path ?? "(run)";
+    lines.push(`- ${finding.ruleId}: ${finding.message} (${path19})`);
   }
   for (const diagnostic4 of result.diagnostics.slice(0, 10)) {
     lines.push(`- ${diagnostic4.code}: ${diagnostic4.message}`);
@@ -14894,6 +15078,174 @@ Summary: ${failed} failed, ${warned} warnings`);
   if (failed > 0) process3.exitCode = 1;
 }
 
+// packages/adapter-sdk/src/indexer.ts
+function defineIndexer(indexer) {
+  if (!indexer.id.trim()) throw new Error("indexer id is required");
+  return indexer;
+}
+async function indexIsStale(snapshot, traceDir) {
+  const builtMs = Date.parse(snapshot.builtAt);
+  if (Number.isNaN(builtMs)) return true;
+  const td = new TraceDirectory({ dir: traceDir });
+  const files = await td.list();
+  for (const file of files) {
+    const stats = await td.getFileStats(file);
+    if (stats.mtimeMs > builtMs) return true;
+  }
+  return false;
+}
+function createTraceDirectoryIndexer() {
+  return defineIndexer({
+    id: "trace-directory-metadata",
+    async rebuild(traceDir, options = {}) {
+      const warnings = [];
+      const td = new TraceDirectory({ dir: traceDir });
+      const files = await td.list();
+      const maxEntries = options.maxEntries ?? 1e4;
+      if (files.length > maxEntries) {
+        warnings.push(
+          `indexer.truncated: trace directory has ${files.length} files; indexing first ${maxEntries}`
+        );
+      }
+      const slice = files.slice(0, maxEntries);
+      const metas = await loadTraceMetadataList(
+        traceDir,
+        slice,
+        (fileName) => td.getPath(fileName)
+      );
+      const entries = metas.map((meta) => ({
+        runId: meta.runId,
+        path: meta.filePath,
+        name: meta.name,
+        startedAt: meta.startedAt,
+        status: meta.status
+      })).sort((a, b) => a.runId.localeCompare(b.runId));
+      if (entries.length < slice.length) {
+        warnings.push(
+          `indexer.partial: indexed ${entries.length} of ${slice.length} trace files`
+        );
+      }
+      return {
+        traceDir,
+        builtAt: (/* @__PURE__ */ new Date()).toISOString(),
+        entries,
+        warnings
+      };
+    }
+  });
+}
+
+// packages/cli/src/index-cmd.ts
+var INDEX_FILENAME = ".agent-inspect-index.json";
+function traceIndexPath(traceDir) {
+  return path14.join(traceDir, INDEX_FILENAME);
+}
+function parseMaxEntries(raw) {
+  if (raw === void 0 || raw.trim() === "") return void 0;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error("--max-entries must be a positive integer.");
+  }
+  return parsed;
+}
+async function readSnapshot(indexPath2) {
+  try {
+    const raw = await readFile(indexPath2, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+}
+async function indexBuildCommand(options = {}) {
+  try {
+    const traceDir = resolveTraceDir({ dir: options.dir });
+    await mkdir(traceDir, { recursive: true });
+    const indexer = createTraceDirectoryIndexer();
+    const snapshot = await indexer.rebuild(traceDir, {
+      maxEntries: parseMaxEntries(options.maxEntries)
+    });
+    const indexPath2 = traceIndexPath(traceDir);
+    await writeFile(indexPath2, `${JSON.stringify(snapshot, null, 2)}
+`, "utf8");
+    if (options.json) {
+      console.log(JSON.stringify({ ok: true, indexPath: indexPath2, ...snapshot }, null, 2));
+      return;
+    }
+    console.log(`Built trace index: ${indexPath2}`);
+    console.log(`Entries: ${snapshot.entries.length}`);
+    if (snapshot.warnings.length > 0) {
+      for (const warning of snapshot.warnings) {
+        console.log(`warning: ${warning}`);
+      }
+    }
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error(`[AgentInspect] index build failed: ${msg}`);
+    process.exitCode = 1;
+  }
+}
+async function indexStatusCommand(options = {}) {
+  try {
+    const traceDir = resolveTraceDir({ dir: options.dir });
+    const indexPath2 = traceIndexPath(traceDir);
+    const snapshot = await readSnapshot(indexPath2);
+    if (!snapshot) {
+      const payload2 = { ok: true, exists: false, indexPath: indexPath2, traceDir, stale: true };
+      if (options.json) {
+        console.log(JSON.stringify(payload2, null, 2));
+      } else {
+        console.log(`No index at ${indexPath2}`);
+        console.log("Run: agent-inspect index build");
+      }
+      return;
+    }
+    const stale = await indexIsStale(snapshot, traceDir);
+    const payload = {
+      ok: true,
+      exists: true,
+      indexPath: indexPath2,
+      traceDir,
+      stale,
+      builtAt: snapshot.builtAt,
+      entries: snapshot.entries.length,
+      warnings: snapshot.warnings
+    };
+    if (options.json) {
+      console.log(JSON.stringify(payload, null, 2));
+      return;
+    }
+    console.log(`Index: ${indexPath2}`);
+    console.log(`Built: ${snapshot.builtAt}`);
+    console.log(`Entries: ${snapshot.entries.length}`);
+    console.log(`Stale: ${stale ? "yes" : "no"}`);
+    if (snapshot.warnings.length > 0) {
+      for (const warning of snapshot.warnings) {
+        console.log(`warning: ${warning}`);
+      }
+    }
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error(`[AgentInspect] index status failed: ${msg}`);
+    process.exitCode = 1;
+  }
+}
+async function indexCleanCommand(options = {}) {
+  try {
+    const traceDir = resolveTraceDir({ dir: options.dir });
+    const indexPath2 = traceIndexPath(traceDir);
+    await rm(indexPath2, { force: true });
+    if (options.json) {
+      console.log(JSON.stringify({ ok: true, removed: indexPath2 }, null, 2));
+      return;
+    }
+    console.log(`Removed index: ${indexPath2}`);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error(`[AgentInspect] index clean failed: ${msg}`);
+    process.exitCode = 1;
+  }
+}
+
 // packages/cli/src/index.ts
 function runCommand(action) {
   void action().catch((error) => {
@@ -15018,7 +15370,10 @@ function createCliProgram() {
   ]).option("--allowed-model <model>", "allow an LLM model (repeatable)", (value, previous = []) => [
     ...previous,
     value
-  ]).option("--max-total-tokens <number>", "add llm.usage with a max total-token budget").option("--session <id>", "check all runs in a workflow session (requires --dir)").option("--group <id>", "check all runs sharing a groupId (requires --dir)").option(
+  ]).option("--max-total-tokens <number>", "add llm.usage with a max total-token budget").option(
+    "--max-step-duration <duration>",
+    "add run.maxStepDuration (e.g. 30s, 5m)"
+  ).option("--require-completed", "add run.requireCompleted").option("--detect-stalls", "add run.stall for running or incomplete events").option("--session <id>", "check all runs in a workflow session (requires --dir)").option("--group <id>", "check all runs sharing a groupId (requires --dir)").option(
     "--correlate-group",
     "when using --session, also match synthetic group: session keys"
   ).option(
@@ -15212,6 +15567,16 @@ function createCliProgram() {
   ).action((opts) => {
     runCommand(() => doctorCommand(opts));
   });
+  const indexCmd = program.command("index").description("Optional local trace directory index (rebuildable metadata cache)");
+  indexCmd.command("build").description("Build or refresh .agent-inspect-index.json").option("--dir <path>", "trace directory").option("--json", "print JSON result").option("--max-entries <n>", "cap indexed entries (default 10000)").action((opts) => {
+    runCommand(() => indexBuildCommand(opts));
+  });
+  indexCmd.command("status").description("Show index freshness and entry count").option("--dir <path>", "trace directory").option("--json", "print JSON result").action((opts) => {
+    runCommand(() => indexStatusCommand(opts));
+  });
+  indexCmd.command("clean").description("Remove the local index file").option("--dir <path>", "trace directory").option("--json", "print JSON result").action((opts) => {
+    runCommand(() => indexCleanCommand(opts));
+  });
   return program;
 }
 function isPrimaryModule() {