agent-inspect 2.3.0 → 2.4.0

package/packages/core/dist/advanced.cjs

@@ -3866,10 +3866,12 @@ async function searchTraces(metas, options) {
     durationFilter = parseDurationFilter(options.duration);
   }
   const limit = options.limit ?? 50;
+  const sessionId = options.session?.trim();
   const hasContentFilter = Boolean(
     options.status || stepTypeFilter || nameQuery || toolQuery || durationFilter
   );
   const results = [];
+  const sessionLabel = sessionId && sessionId !== "" ? sessionId : void 0;
   if (!hasContentFilter) {
     for (const m of filtered) {
       results.push({
@@ -3878,9 +3880,10 @@ async function searchTraces(metas, options) {
         runStatus: m.status,
         timestamp: m.startedAt,
         durationMs: m.durationMs,
-        matchReason: "trace in directory",
-        matchedFields: ["run"],
-        filePath: m.filePath
+        matchReason: sessionLabel ? `trace in session ${sessionLabel}` : "trace in directory",
+        matchedFields: sessionLabel ? ["run", "session"] : ["run"],
+        filePath: m.filePath,
+        ...sessionLabel ? { sessionId: sessionLabel } : {}
       });
     }
     return results.slice(0, limit);
@@ -4019,6 +4022,571 @@ async function loadTraceMetadataList(_traceDir, fileNames, getPath) {
   }
   return metas;
 }
+
+// packages/core/src/sessions/metadata.ts
+function isNonEmptyString3(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+function finitePositiveInt(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
+    return void 0;
+  }
+  return Math.trunc(value);
+}
+function extractSessionWorkflowMetadata(record) {
+  if (!record) return void 0;
+  const out = {};
+  let found = false;
+  const assignString = (key, value) => {
+    if (isNonEmptyString3(value)) {
+      out[key] = value.trim();
+      found = true;
+    }
+  };
+  assignString("sessionId", record.sessionId);
+  assignString("conversationId", record.conversationId);
+  assignString("groupId", record.groupId);
+  assignString("parentGroupId", record.parentGroupId);
+  assignString("retryOf", record.retryOf);
+  assignString("retryReason", record.retryReason);
+  assignString("handoffFrom", record.handoffFrom);
+  assignString("handoffTo", record.handoffTo);
+  assignString("subAgentId", record.subAgentId);
+  assignString("subAgentName", record.subAgentName);
+  assignString("jobId", record.jobId);
+  assignString("queueName", record.queueName);
+  assignString("workflowName", record.workflowName);
+  assignString("workflowStep", record.workflowStep);
+  assignString("toolCallId", record.toolCallId);
+  assignString("mcpToolCallId", record.mcpToolCallId);
+  assignString("linkedStepId", record.linkedStepId);
+  assignString("correlationId", record.correlationId);
+  assignString("requestId", record.requestId);
+  assignString("decisionId", record.decisionId);
+  const attempt = finitePositiveInt(record.attempt);
+  if (attempt !== void 0) {
+    out.attempt = attempt;
+    found = true;
+  }
+  return found ? out : void 0;
+}
+function sessionKeyForRun(meta, options) {
+  if (meta?.sessionId) return meta.sessionId;
+  if (options?.correlateByGroupId && meta?.groupId) {
+    return `group:${meta.groupId}`;
+  }
+  return void 0;
+}
+
+// packages/core/src/sessions/types.ts
+var SESSION_WORKFLOW_KEYS = [
+  "sessionId",
+  "conversationId",
+  "groupId",
+  "parentGroupId",
+  "attempt",
+  "retryOf",
+  "retryReason",
+  "handoffFrom",
+  "handoffTo",
+  "subAgentId",
+  "subAgentName",
+  "jobId",
+  "queueName",
+  "workflowName",
+  "workflowStep",
+  "toolCallId",
+  "mcpToolCallId",
+  "linkedStepId",
+  "correlationId",
+  "requestId",
+  "decisionId"
+];
+
+// packages/core/src/sessions/load.ts
+async function enrichSessionRunRecord(meta) {
+  let metadata;
+  try {
+    const events = await readTraceEventsFromFile(meta.filePath);
+    for (const event of events) {
+      if (event.event !== "run_started") continue;
+      if (event.metadata && typeof event.metadata === "object") {
+        metadata = event.metadata;
+      }
+      break;
+    }
+  } catch {
+  }
+  return {
+    runId: meta.runId,
+    name: meta.name,
+    status: meta.status,
+    startedAt: meta.startedAt,
+    endedAt: meta.endedAt,
+    durationMs: meta.durationMs,
+    filePath: meta.filePath,
+    metadata
+  };
+}
+async function loadSessionRunRecords(metas) {
+  const out = [];
+  for (const meta of metas) {
+    out.push(await enrichSessionRunRecord(meta));
+  }
+  return out;
+}
+
+// packages/core/src/sessions/scope.ts
+function metaToSessionRunRecord(meta) {
+  return {
+    runId: meta.runId,
+    name: meta.name,
+    status: meta.status,
+    startedAt: meta.startedAt,
+    endedAt: meta.endedAt,
+    durationMs: meta.durationMs,
+    filePath: meta.filePath,
+    metadata: void 0
+  };
+}
+function filterMetasBySessionScope(metas, records, options) {
+  const sessionId = options.sessionId?.trim();
+  const groupId = options.groupId?.trim();
+  const warnings = [];
+  if (sessionId) {
+    const index = buildSessionIndex(records, {
+      correlateByGroupId: options.correlateByGroupId === true
+    });
+    warnings.push(...index.warnings);
+    const session = index.sessions.find((item) => item.sessionId === sessionId);
+    if (!session) {
+      return {
+        metas: [],
+        scopeLabel: sessionId,
+        scopeKind: "session",
+        runIds: [],
+        warnings,
+        notFound: true
+      };
+    }
+    const runIdSet = new Set(session.runIds);
+    const filtered = metas.filter((meta) => runIdSet.has(meta.runId));
+    return {
+      metas: filtered,
+      scopeLabel: sessionId,
+      scopeKind: "session",
+      runIds: session.runIds,
+      warnings,
+      notFound: false
+    };
+  }
+  if (groupId) {
+    const runIds = records.filter((run) => extractSessionWorkflowMetadata(run.metadata)?.groupId === groupId).map((run) => run.runId).sort();
+    if (runIds.length === 0) {
+      return {
+        metas: [],
+        scopeLabel: groupId,
+        scopeKind: "group",
+        runIds: [],
+        warnings,
+        notFound: true
+      };
+    }
+    const runIdSet = new Set(runIds);
+    return {
+      metas: metas.filter((meta) => runIdSet.has(meta.runId)),
+      scopeLabel: groupId,
+      scopeKind: "group",
+      runIds,
+      warnings,
+      notFound: false
+    };
+  }
+  return {
+    metas: [...metas],
+    scopeLabel: "",
+    scopeKind: "session",
+    runIds: [],
+    warnings,
+    notFound: false
+  };
+}
+function traceMetasToSessionRunRecords(metas) {
+  return metas.map(metaToSessionRunRecord);
+}
+
+// packages/core/src/sessions/cohort.ts
+function groupSessionCohorts(runs, options = {}) {
+  const groupBy = options.groupBy ?? "session";
+  const cohorts = [];
+  if (groupBy === "session") {
+    const index = buildSessionIndex(runs, options);
+    for (const session of index.sessions) {
+      cohorts.push({
+        key: session.sessionId,
+        kind: "session",
+        runIds: [...session.runIds]
+      });
+    }
+    if (index.unscopedRunIds.length > 0) {
+      cohorts.push({
+        key: "__unscoped__",
+        kind: "session",
+        runIds: [...index.unscopedRunIds]
+      });
+    }
+    return cohorts.sort((a, b) => a.key.localeCompare(b.key));
+  }
+  const byGroup = /* @__PURE__ */ new Map();
+  const unscoped = [];
+  for (const run of runs) {
+    const groupId = extractSessionWorkflowMetadata(run.metadata)?.groupId;
+    if (!groupId) {
+      unscoped.push(run.runId);
+      continue;
+    }
+    const bucket = byGroup.get(groupId) ?? [];
+    bucket.push(run.runId);
+    byGroup.set(groupId, bucket);
+  }
+  for (const [key, runIds] of [...byGroup.entries()].sort(
+    ([a], [b]) => a.localeCompare(b)
+  )) {
+    cohorts.push({
+      key,
+      kind: "group",
+      runIds: runIds.sort()
+    });
+  }
+  if (unscoped.length > 0) {
+    cohorts.push({
+      key: "__unscoped__",
+      kind: "group",
+      runIds: unscoped.sort()
+    });
+  }
+  return cohorts;
+}
+
+// packages/core/src/sessions/checks.ts
+function emptySummary() {
+  return { passed: 0, failed: 0, warnings: 0, errors: 0 };
+}
+function mergeSummary(target, source) {
+  return {
+    passed: target.passed + source.passed,
+    failed: target.failed + source.failed,
+    warnings: target.warnings + source.warnings,
+    errors: target.errors + source.errors
+  };
+}
+function sessionDiagnostic(code, message) {
+  return { code, message, severity: "error" };
+}
+function aggregateSessionCheckResults(perRun, scope) {
+  if (scope.notFound) {
+    return {
+      ok: false,
+      status: "error",
+      format: perRun[0]?.format ?? "agent-inspect-jsonl",
+      scopeKind: scope.scopeKind,
+      scopeLabel: scope.scopeLabel,
+      runIds: [],
+      runResults: [],
+      summary: { ...emptySummary(), errors: 1 },
+      findings: [],
+      diagnostics: [
+        sessionDiagnostic(
+          "AI_CHECK_INVALID_ARGUMENTS",
+          `${scope.scopeKind} not found: ${scope.scopeLabel}`
+        )
+      ],
+      ...scope.sessionWarnings?.length ? { sessionWarnings: [...scope.sessionWarnings] } : {}
+    };
+  }
+  if (scope.empty || perRun.length === 0) {
+    return {
+      ok: false,
+      status: "error",
+      format: perRun[0]?.format ?? "agent-inspect-jsonl",
+      scopeKind: scope.scopeKind,
+      scopeLabel: scope.scopeLabel,
+      runIds: scope.runIds,
+      runResults: [],
+      summary: { ...emptySummary(), errors: 1 },
+      findings: [],
+      diagnostics: [
+        sessionDiagnostic(
+          "AI_CHECK_TRACE_UNREADABLE",
+          `No readable traces in ${scope.scopeKind}: ${scope.scopeLabel}`
+        )
+      ],
+      ...scope.sessionWarnings?.length ? { sessionWarnings: [...scope.sessionWarnings] } : {}
+    };
+  }
+  let summary = emptySummary();
+  const findings = [];
+  const diagnostics = [];
+  const runResults = [];
+  for (const result of perRun) {
+    summary = mergeSummary(summary, result.summary);
+    findings.push(...result.findings);
+    diagnostics.push(...result.diagnostics);
+    if (result.runId) {
+      runResults.push({ runId: result.runId, status: result.status });
+    }
+  }
+  runResults.sort((a, b) => a.runId.localeCompare(b.runId));
+  findings.sort((a, b) => {
+    const runCmp = (a.evidence[0]?.runId ?? "").localeCompare(
+      b.evidence[0]?.runId ?? ""
+    );
+    if (runCmp !== 0) return runCmp;
+    return a.ruleId.localeCompare(b.ruleId);
+  });
+  const hasErrors = diagnostics.some((item) => item.severity === "error");
+  const status = hasErrors ? "error" : summary.failed > 0 ? "fail" : "pass";
+  return {
+    ok: status === "pass",
+    status,
+    format: perRun[0]?.format ?? "agent-inspect-jsonl",
+    scopeKind: scope.scopeKind,
+    scopeLabel: scope.scopeLabel,
+    runIds: scope.runIds,
+    runResults,
+    summary,
+    findings,
+    diagnostics,
+    ...scope.sessionWarnings?.length ? { sessionWarnings: [...scope.sessionWarnings] } : {}
+  };
+}
+
+// packages/core/src/sessions/index.ts
+function compareRuns(a, b) {
+  const aStart = a.startedAt ?? 0;
+  const bStart = b.startedAt ?? 0;
+  if (aStart !== bStart) return aStart - bStart;
+  return a.runId.localeCompare(b.runId);
+}
+function buildGroups(runIds, metaByRunId) {
+  const byGroup = /* @__PURE__ */ new Map();
+  for (const runId of runIds) {
+    const groupId = metaByRunId.get(runId)?.groupId;
+    if (!groupId) continue;
+    const existing = byGroup.get(groupId);
+    if (existing) {
+      existing.runIds.push(runId);
+    } else {
+      byGroup.set(groupId, {
+        groupId,
+        parentGroupId: metaByRunId.get(runId)?.parentGroupId,
+        runIds: [runId]
+      });
+    }
+  }
+  return [...byGroup.values()].map((group) => ({
+    ...group,
+    runIds: [...group.runIds].sort((a, b) => a.localeCompare(b))
+  }));
+}
+function buildHandoffs(runIds, metaByRunId, warnings, sessionId) {
+  const edges = [];
+  const seen = /* @__PURE__ */ new Set();
+  const pushEdge = (edge) => {
+    const key = `${edge.from}->${edge.to}:${edge.confidence}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    edges.push(edge);
+  };
+  for (const runId of runIds) {
+    const meta = metaByRunId.get(runId);
+    if (!meta) continue;
+    if (meta.handoffFrom && meta.handoffTo) {
+      pushEdge({
+        from: meta.handoffFrom,
+        to: meta.handoffTo,
+        source: "manual",
+        confidence: "explicit"
+      });
+      continue;
+    }
+    if (meta.handoffFrom) {
+      pushEdge({
+        from: meta.handoffFrom,
+        to: runId,
+        source: "manual",
+        confidence: "explicit"
+      });
+    }
+    if (meta.handoffTo) {
+      pushEdge({
+        from: runId,
+        to: meta.handoffTo,
+        source: "manual",
+        confidence: "explicit"
+      });
+    }
+    if (meta.subAgentId && meta.parentGroupId && !meta.handoffFrom && !meta.handoffTo) {
+      pushEdge({
+        from: meta.parentGroupId,
+        to: meta.subAgentId,
+        source: "inferred",
+        confidence: "correlated"
+      });
+      warnings.push({
+        code: "ambiguous-handoff-endpoints",
+        message: "Handoff inferred from parentGroupId and subAgentId without explicit handoffFrom/handoffTo.",
+        runId,
+        sessionId
+      });
+    }
+  }
+  return edges.sort((a, b) => {
+    const from = a.from.localeCompare(b.from);
+    if (from !== 0) return from;
+    return a.to.localeCompare(b.to);
+  });
+}
+function buildRetries(runIds, metaByRunId, warnings, sessionId) {
+  const retries = [];
+  for (const runId of runIds) {
+    const meta = metaByRunId.get(runId);
+    if (!meta) continue;
+    if (meta.retryOf) {
+      retries.push({
+        runId,
+        retryOf: meta.retryOf,
+        attempt: meta.attempt,
+        source: "manual",
+        confidence: "explicit"
+      });
+      continue;
+    }
+    if (meta.attempt !== void 0 && meta.attempt > 1) {
+      retries.push({
+        runId,
+        attempt: meta.attempt,
+        source: "inferred",
+        confidence: "correlated"
+      });
+      warnings.push({
+        code: "ambiguous-retry-link",
+        message: "attempt > 1 without retryOf; retry link is correlated only.",
+        runId,
+        sessionId
+      });
+    }
+  }
+  return retries.sort((a, b) => a.runId.localeCompare(b.runId));
+}
+function buildCriticalPath(runs, handoffs) {
+  const runById = new Map(runs.map((run) => [run.runId, run]));
+  const explicitTargets = new Set(
+    handoffs.filter((edge) => edge.confidence === "explicit").map((edge) => edge.to)
+  );
+  const explicitSources = new Set(
+    handoffs.filter((edge) => edge.confidence === "explicit").map((edge) => edge.from)
+  );
+  const ordered = [...runs].sort(compareRuns);
+  const path5 = [];
+  const visited = /* @__PURE__ */ new Set();
+  const pushRun = (run, confidence, source) => {
+    if (visited.has(run.runId)) return;
+    visited.add(run.runId);
+    path5.push({
+      runId: run.runId,
+      name: run.name,
+      startedAt: run.startedAt,
+      durationMs: run.durationMs,
+      confidence,
+      source
+    });
+  };
+  for (const edge of handoffs) {
+    if (edge.confidence !== "explicit") continue;
+    const fromRun = [...runById.values()].find(
+      (run) => run.runId === edge.from || metaRunIdMatches(run, edge.from, runById)
+    );
+    const toRun = [...runById.values()].find(
+      (run) => run.runId === edge.to || metaRunIdMatches(run, edge.to, runById)
+    );
+    if (fromRun) pushRun(fromRun, "explicit", "manual");
+    if (toRun) pushRun(toRun, "explicit", "manual");
+  }
+  for (const run of ordered) {
+    if (visited.has(run.runId)) continue;
+    const confidence = explicitTargets.has(run.runId) || explicitSources.has(run.runId) ? "explicit" : "correlated";
+    pushRun(run, confidence, confidence === "explicit" ? "manual" : "inferred");
+  }
+  return path5;
+}
+function metaRunIdMatches(run, token, runById) {
+  const meta = extractSessionWorkflowMetadata(run.metadata);
+  return meta?.subAgentId === token || meta?.groupId === token || runById.has(token);
+}
+function buildSessionIndex(inputRuns, options = {}) {
+  const warnings = [];
+  const runs = [...inputRuns].sort(compareRuns);
+  const metaByRunId = /* @__PURE__ */ new Map();
+  for (const run of runs) {
+    metaByRunId.set(run.runId, extractSessionWorkflowMetadata(run.metadata));
+  }
+  const sessionsByKey = /* @__PURE__ */ new Map();
+  const unscopedRunIds = [];
+  for (const run of runs) {
+    const meta = metaByRunId.get(run.runId);
+    const key = sessionKeyForRun(meta, {
+      correlateByGroupId: options.correlateByGroupId === true
+    });
+    if (!key) {
+      unscopedRunIds.push(run.runId);
+      continue;
+    }
+    const bucket = sessionsByKey.get(key) ?? [];
+    bucket.push(run);
+    sessionsByKey.set(key, bucket);
+  }
+  const sessions = [...sessionsByKey.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([sessionId, sessionRuns]) => {
+    const runIds = sessionRuns.map((run) => run.runId).sort();
+    const handoffs = buildHandoffs(runIds, metaByRunId, warnings, sessionId);
+    const retries = buildRetries(runIds, metaByRunId, warnings, sessionId);
+    const groups = buildGroups(runIds, metaByRunId);
+    const criticalPath = buildCriticalPath(sessionRuns, handoffs);
+    const confidences = new Set(handoffs.map((edge) => edge.confidence));
+    if (confidences.has("explicit") && confidences.has("correlated")) {
+      warnings.push({
+        code: "mixed-confidence-group",
+        message: "Session aggregates explicit and correlated handoff edges.",
+        sessionId
+      });
+    }
+    return {
+      sessionId,
+      runIds,
+      groups,
+      handoffs,
+      retries,
+      criticalPath
+    };
+  });
+  if (sessions.length === 0 && runs.length > 0) {
+    warnings.push({
+      code: "missing-session-id",
+      message: "No sessionId (or correlated groupId) found on input runs."
+    });
+  }
+  warnings.sort((a, b) => {
+    const code = a.code.localeCompare(b.code);
+    if (code !== 0) return code;
+    return (a.runId ?? "").localeCompare(b.runId ?? "");
+  });
+  return {
+    runs,
+    sessions,
+    unscopedRunIds: unscopedRunIds.sort(),
+    warnings
+  };
+}
 var KNOWN_EVENTS = /* @__PURE__ */ new Set([
   "run_started",
   "run_completed",
@@ -4202,19 +4770,25 @@ exports.MAX_NAME_LENGTH = MAX_NAME_LENGTH;
 exports.MAX_TERMINAL_DEPTH = MAX_TERMINAL_DEPTH;
 exports.MAX_TERMINAL_NAME_LENGTH = MAX_TERMINAL_NAME_LENGTH;
 exports.RUNS_DIR_NAME = RUNS_DIR_NAME;
+exports.SESSION_WORKFLOW_KEYS = SESSION_WORKFLOW_KEYS;
 exports.TERMINAL_INDENT = TERMINAL_INDENT;
 exports.TraceDirectory = TraceDirectory;
+exports.aggregateSessionCheckResults = aggregateSessionCheckResults;
 exports.buildLocalExplanation = buildLocalExplanation;
 exports.buildRunSummary = buildRunSummary;
 exports.buildRunTimeline = buildRunTimeline;
 exports.buildRunWhatSummary = buildRunWhatSummary;
+exports.buildSessionIndex = buildSessionIndex;
 exports.buildTraceStats = buildTraceStats;
 exports.createInspector = createInspector;
 exports.createInspectorRuntime = createInspectorRuntime;
 exports.createRunId = createRunId;
 exports.createStepId = createStepId;
+exports.enrichSessionRunRecord = enrichSessionRunRecord;
 exports.ensureTraceDir = ensureTraceDir;
 exports.extractMetadata = extractMetadata;
+exports.extractSessionWorkflowMetadata = extractSessionWorkflowMetadata;
+exports.filterMetasBySessionScope = filterMetasBySessionScope;
 exports.filterTraces = filterTraces;
 exports.formatDuration = formatDuration2;
 exports.formatError = formatError;
@@ -4233,6 +4807,7 @@ exports.getRunIdFromTraceFileName = getRunIdFromTraceFileName;
 exports.getTraceDirFromContext = getTraceDirFromContext;
 exports.getTraceFilePath = getTraceFilePath;
 exports.getTraceSafetyFromContext = getTraceSafetyFromContext;
+exports.groupSessionCohorts = groupSessionCohorts;
 exports.hasActiveContext = hasActiveContext;
 exports.initializeTraceFile = initializeTraceFile;
 exports.isAgentInspectEnabled = isAgentInspectEnabled;
@@ -4242,6 +4817,7 @@ exports.isStepStatus = isStepStatus;
 exports.isStepType = isStepType;
 exports.isTraceEvent = isTraceEvent;
 exports.listTraceFiles = listTraceFiles;
+exports.loadSessionRunRecords = loadSessionRunRecords;
 exports.loadTraceMetadataList = loadTraceMetadataList;
 exports.maybeInspectRun = maybeInspectRun;
 exports.parseDuration = parseDuration;
@@ -4270,6 +4846,8 @@ exports.runWithContext = runWithContext;
 exports.runWithStepContext = runWithStepContext;
 exports.searchTraces = searchTraces;
 exports.serializeEvent = serializeEvent;
+exports.sessionKeyForRun = sessionKeyForRun;
+exports.traceMetasToSessionRunRecords = traceMetasToSessionRunRecords;
 exports.truncateName = truncateName;
 exports.unknownTraceFormatMessage = unknownTraceFormatMessage;
 exports.validateEvent = validateEvent;