agent-inspect 2.3.0 → 2.5.0

package/packages/core/dist/advanced.d.cts

@@ -1,12 +1,14 @@
-export { C as CreateInspectorOptions, D as DEFAULT_MAX_EVENT_BYTES, f as DEFAULT_MAX_METADATA_VALUE_LENGTH, h as DEFAULT_MAX_PREVIEW_LENGTH, I as Inspector, a as InspectorCaptureOptions, b as InspectorObserveOptions, c as InspectorRunOptions, i as InspectorRuntime, j as InspectorRuntimeContext, k as InspectorRuntimeDiagnostics, l as InspectorRuntimeOptions, d as InspectorStepOptions, T as TraceSafetyOptions, e as createInspector, n as createInspectorRuntime, o as getCurrentContext, g as getCurrentCorrelationMetadata, p as getCurrentDepth, q as getCurrentRunId, r as getCurrentRunName, s as getCurrentStepId, t as getParentStepId, u as getTraceDirFromContext, v as getTraceSafetyFromContext, w as hasActiveContext, x as isAgentInspectEnabled, y as isSilentContext, m as maybeInspectRun, z as prepareMetadataForDisk, A as prepareTraceEventForDisk, B as resolveTraceSafetyOptions, E as runWithContext, F as runWithStepContext } from './context-CSKnzpXR.cjs';
-import { R as RedactionProfile, E as ErrorInfo, b as RunStatus, e as StepStatus, h as TraceEvent, j as RunSummary, k as TraceMetadata, l as TraceMetadataStatus, f as StepType, g as TraceCorrelationMetadata } from './types-DgMN3qow.cjs';
-export { A as ActiveStepContext, i as ExecutionContext, I as InspectRunOptions, O as ObserveOptions, a as Run, m as RunCompletedEvent, n as RunStartedEvent, c as Step, o as StepCompletedEvent, d as StepMetadata, S as StepOptions, p as StepStartedEvent, T as TokenMetadata, q as TraceEventBase, r as TraceSchemaVersion, s as isStepStatus, t as isStepType, u as isTraceEvent } from './types-DgMN3qow.cjs';
-import { a as InspectRunTree } from './inspect-event-CevRYp58.cjs';
-export { A as AttributionConfidence, E as EventSource, c as InspectEvent, I as InspectKind, b as InspectNode } from './inspect-event-CevRYp58.cjs';
-import { P as PersistedInspectEvent } from './persisted-inspect-event-DHcHPUKv.cjs';
+export { C as CreateInspectorOptions, D as DEFAULT_MAX_EVENT_BYTES, f as DEFAULT_MAX_METADATA_VALUE_LENGTH, h as DEFAULT_MAX_PREVIEW_LENGTH, I as Inspector, a as InspectorCaptureOptions, b as InspectorObserveOptions, c as InspectorRunOptions, i as InspectorRuntime, j as InspectorRuntimeContext, k as InspectorRuntimeDiagnostics, l as InspectorRuntimeOptions, d as InspectorStepOptions, T as TraceSafetyOptions, e as createInspector, n as createInspectorRuntime, o as getCurrentContext, g as getCurrentCorrelationMetadata, p as getCurrentDepth, q as getCurrentRunId, r as getCurrentRunName, s as getCurrentStepId, t as getParentStepId, u as getTraceDirFromContext, v as getTraceSafetyFromContext, w as hasActiveContext, x as isAgentInspectEnabled, y as isSilentContext, m as maybeInspectRun, z as prepareMetadataForDisk, A as prepareTraceEventForDisk, B as resolveTraceSafetyOptions, E as runWithContext, F as runWithStepContext } from './context-DjY-jvQk.cjs';
+import { R as RedactionProfile, E as ErrorInfo, b as RunStatus, e as StepStatus, h as TraceEvent, j as RunSummary, k as TraceMetadata, l as TraceMetadataStatus, f as StepType, g as TraceCorrelationMetadata } from './types-C-llnPH0.cjs';
+export { A as ActiveStepContext, i as ExecutionContext, I as InspectRunOptions, O as ObserveOptions, a as Run, m as RunCompletedEvent, n as RunStartedEvent, c as Step, o as StepCompletedEvent, d as StepMetadata, S as StepOptions, p as StepStartedEvent, T as TokenMetadata, q as TraceEventBase, r as TraceSchemaVersion, s as isStepStatus, t as isStepType, u as isTraceEvent } from './types-C-llnPH0.cjs';
+import { b as InspectRunTree } from './inspect-event-CYAV7Hxm.cjs';
+export { A as AttributionConfidence, E as EventSource, a as InspectEvent, I as InspectKind, c as InspectNode } from './inspect-event-CYAV7Hxm.cjs';
+import { P as PersistedInspectEvent } from './persisted-inspect-event-D5SjBz9b.cjs';
 import { Stats } from 'node:fs';
+import { TraceCheckResult, TraceCheckStatus } from './checks.cjs';
 import './writers.cjs';
-import './log-config-8aE5Kxtr.cjs';
+import './log-config-BNQ9UTmP.cjs';
+import './readers.cjs';
 
 interface ResolvedRedactionProfile {
     profile: RedactionProfile;
@@ -365,6 +367,8 @@ interface TraceSearchOptions {
     tool?: string;
     duration?: string;
     limit?: number;
+    session?: string;
+    correlateGroup?: boolean;
 }
 interface TraceSearchResult {
     runId: string;
@@ -378,6 +382,7 @@ interface TraceSearchResult {
     matchReason: string;
     matchedFields: string[];
     filePath: string;
+    sessionId?: string;
 }
 interface ParsedDurationFilter {
     op: ">" | ">=" | "<" | "<=";
@@ -387,6 +392,165 @@ declare function parseDurationFilter(expr: string): ParsedDurationFilter;
 declare function searchTraces(metas: TraceMetadata[], options: TraceSearchOptions): Promise<TraceSearchResult[]>;
 declare function loadTraceMetadataList(_traceDir: string, fileNames: string[], getPath: (fileName: string) => string): Promise<TraceMetadata[]>;
 
+/** Known session/workflow metadata keys (v2.4 RFC). */
+declare const SESSION_WORKFLOW_KEYS: readonly ["sessionId", "conversationId", "groupId", "parentGroupId", "attempt", "retryOf", "retryReason", "handoffFrom", "handoffTo", "subAgentId", "subAgentName", "jobId", "queueName", "workflowName", "workflowStep", "toolCallId", "mcpToolCallId", "linkedStepId", "correlationId", "requestId", "decisionId"];
+type SessionWorkflowKey = (typeof SESSION_WORKFLOW_KEYS)[number];
+type SessionConfidence = "explicit" | "correlated" | "heuristic" | "unknown";
+type SessionEdgeSource = "manual" | "adapter" | "json-log" | "log4js" | "mcp-client" | "inferred";
+interface SessionWorkflowMetadata {
+    sessionId?: string;
+    conversationId?: string;
+    groupId?: string;
+    parentGroupId?: string;
+    attempt?: number;
+    retryOf?: string;
+    retryReason?: string;
+    handoffFrom?: string;
+    handoffTo?: string;
+    subAgentId?: string;
+    subAgentName?: string;
+    jobId?: string;
+    queueName?: string;
+    workflowName?: string;
+    workflowStep?: string;
+    toolCallId?: string;
+    mcpToolCallId?: string;
+    linkedStepId?: string;
+    correlationId?: string;
+    requestId?: string;
+    decisionId?: string;
+}
+interface SessionRunRecord {
+    runId: string;
+    name?: string;
+    status?: TraceMetadataStatus;
+    startedAt?: number;
+    endedAt?: number;
+    durationMs?: number;
+    filePath?: string;
+    metadata?: Record<string, unknown>;
+}
+interface SessionWarning {
+    code: string;
+    message: string;
+    runId?: string;
+    sessionId?: string;
+}
+interface HandoffEdge {
+    from: string;
+    to: string;
+    source: SessionEdgeSource;
+    confidence: SessionConfidence;
+}
+interface RetryLink {
+    runId: string;
+    retryOf?: string;
+    attempt?: number;
+    source: SessionEdgeSource;
+    confidence: SessionConfidence;
+}
+interface SessionGroup {
+    groupId: string;
+    parentGroupId?: string;
+    runIds: string[];
+}
+interface CriticalPathStep {
+    runId: string;
+    name?: string;
+    startedAt?: number;
+    durationMs?: number;
+    source: SessionEdgeSource;
+    confidence: SessionConfidence;
+}
+interface SessionSummary {
+    sessionId: string;
+    runIds: string[];
+    groups: SessionGroup[];
+    handoffs: HandoffEdge[];
+    retries: RetryLink[];
+    criticalPath: CriticalPathStep[];
+}
+interface SessionIndex {
+    runs: SessionRunRecord[];
+    sessions: SessionSummary[];
+    unscopedRunIds: string[];
+    warnings: SessionWarning[];
+}
+interface BuildSessionIndexOptions {
+    /** When true, group runs that share only `groupId` under a synthetic session key. */
+    correlateByGroupId?: boolean;
+}
+
+/** Extracts session/workflow metadata from a run metadata or attributes bag. */
+declare function extractSessionWorkflowMetadata(record: Record<string, unknown> | undefined): SessionWorkflowMetadata | undefined;
+declare function sessionKeyForRun(meta: SessionWorkflowMetadata | undefined, options?: {
+    correlateByGroupId?: boolean;
+}): string | undefined;
+
+/** Enriches trace metadata with run_started metadata for session indexing. */
+declare function enrichSessionRunRecord(meta: TraceMetadata): Promise<SessionRunRecord>;
+/** Builds session run records from extracted trace metadata rows. */
+declare function loadSessionRunRecords(metas: readonly TraceMetadata[]): Promise<SessionRunRecord[]>;
+
+interface SessionScopeOptions {
+    sessionId?: string;
+    groupId?: string;
+    correlateByGroupId?: boolean;
+}
+interface SessionScopeResult {
+    metas: TraceMetadata[];
+    scopeLabel: string;
+    scopeKind: "session" | "group";
+    runIds: string[];
+    warnings: SessionWarning[];
+    notFound: boolean;
+}
+/** Filters trace metadata rows to runs in a session or group scope. */
+declare function filterMetasBySessionScope(metas: readonly TraceMetadata[], records: readonly SessionRunRecord[], options: SessionScopeOptions): SessionScopeResult;
+/** Lightweight metadata rows for scope resolution when run_started metadata is absent. */
+declare function traceMetasToSessionRunRecords(metas: readonly TraceMetadata[]): SessionRunRecord[];
+
+type SessionCohortKind = "session" | "group";
+interface SessionCohort {
+    key: string;
+    kind: SessionCohortKind;
+    runIds: string[];
+}
+interface GroupSessionCohortsOptions extends BuildSessionIndexOptions {
+    groupBy?: "session" | "group";
+}
+/**
+ * Groups runs into session or group cohort buckets for local search/check aggregation.
+ * Deterministic; does not infer causality from timestamps.
+ */
+declare function groupSessionCohorts(runs: readonly SessionRunRecord[], options?: GroupSessionCohortsOptions): SessionCohort[];
+
+interface TraceSessionCheckResult extends TraceCheckResult {
+    scopeKind: "session" | "group";
+    scopeLabel: string;
+    runIds: string[];
+    runResults: Array<{
+        runId: string;
+        status: TraceCheckStatus;
+    }>;
+    sessionWarnings?: SessionWarning[];
+}
+/** Aggregates per-run check results for a session or group scope. */
+declare function aggregateSessionCheckResults(perRun: readonly TraceCheckResult[], scope: {
+    scopeKind: "session" | "group";
+    scopeLabel: string;
+    runIds: string[];
+    sessionWarnings?: SessionWarning[];
+    notFound?: boolean;
+    empty?: boolean;
+}): TraceSessionCheckResult;
+
+/**
+ * Builds a deterministic session index from local run records and metadata.
+ * Does not read files or infer causality from timestamps alone.
+ */
+declare function buildSessionIndex(inputRuns: readonly SessionRunRecord[], options?: BuildSessionIndexOptions): SessionIndex;
+
 /**
  * Safety check for cleanup workflows: returns true only when the file appears to be an AgentInspect trace.
  * This should be conservative: false positives are more dangerous than false negatives.
@@ -401,4 +565,4 @@ declare function isAgentInspectTrace(filePath: string): Promise<boolean>;
  */
 declare function parseDuration(duration: string): number;
 
-export { DEFAULT_TRACE_DIR_NAME, type DurationStats, ErrorInfo, type ExplainFact, type ExplainInference, type ExplainMode, type ExplainOptions, type ExplainResult, FALLBACK_TRACE_DIR, InspectRunTree, MAX_NAME_LENGTH, MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, type ParseTraceJsonlOptions, type ParseTraceJsonlResult, type ParsedDurationFilter, RUNS_DIR_NAME, RedactionProfile, type RenderTimelineOptions, type RenderWhatOptions, type ResolvedRedactionProfile, RunStatus, RunSummary, type RunTimeline, type RunWhatSummary, StepStatus, StepType, TERMINAL_INDENT, type TimelineEntry, type TimelineFocus, type TimelineOptions, TraceCorrelationMetadata, TraceDirectory, type TraceDirectoryOptions, TraceEvent, type TraceFilterOptions, type TraceJsonlFormat, TraceMetadata, TraceMetadataStatus, type TraceSearchOptions, type TraceSearchResult, type TraceStats, type TraceStatsOptions, type TraceStatsRankedRun, type TraceStatsRankedStep, buildLocalExplanation, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildTraceStats, createRunId, createStepId, ensureTraceDir, extractMetadata, filterTraces, formatDuration, formatError, formatTerminalName, formatTimestamp, getDefaultTraceDir, getIndent, getRunIdFromTraceFileName, getTraceFilePath, initializeTraceFile, isAgentInspectTrace, listTraceFiles, loadTraceMetadataList, parseDuration, parseDurationFilter, parseTraceJsonl, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, readTraceEvents, readTraceFile, renderErrorLine, renderRunSummary, renderRunWhat, renderStepLine, renderTimeline, renderTraceStats, resolveRedactionProfile, resolveTraceDir, searchTraces, serializeEvent, truncateName, unknownTraceFormatMessage, validateEvent, warn, writeTraceEvent };
+export { type BuildSessionIndexOptions, type CriticalPathStep, DEFAULT_TRACE_DIR_NAME, type DurationStats, ErrorInfo, type ExplainFact, type ExplainInference, type ExplainMode, type ExplainOptions, type ExplainResult, FALLBACK_TRACE_DIR, type GroupSessionCohortsOptions, type HandoffEdge, InspectRunTree, MAX_NAME_LENGTH, MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, type ParseTraceJsonlOptions, type ParseTraceJsonlResult, type ParsedDurationFilter, RUNS_DIR_NAME, RedactionProfile, type RenderTimelineOptions, type RenderWhatOptions, type ResolvedRedactionProfile, type RetryLink, RunStatus, RunSummary, type RunTimeline, type RunWhatSummary, SESSION_WORKFLOW_KEYS, type SessionCohort, type SessionCohortKind, type SessionConfidence, type SessionEdgeSource, type SessionGroup, type SessionIndex, type SessionRunRecord, type SessionScopeOptions, type SessionScopeResult, type SessionSummary, type SessionWarning, type SessionWorkflowKey, type SessionWorkflowMetadata, StepStatus, StepType, TERMINAL_INDENT, type TimelineEntry, type TimelineFocus, type TimelineOptions, TraceCorrelationMetadata, TraceDirectory, type TraceDirectoryOptions, TraceEvent, type TraceFilterOptions, type TraceJsonlFormat, TraceMetadata, TraceMetadataStatus, type TraceSearchOptions, type TraceSearchResult, type TraceSessionCheckResult, type TraceStats, type TraceStatsOptions, type TraceStatsRankedRun, type TraceStatsRankedStep, aggregateSessionCheckResults, buildLocalExplanation, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildSessionIndex, buildTraceStats, createRunId, createStepId, enrichSessionRunRecord, ensureTraceDir, extractMetadata, extractSessionWorkflowMetadata, filterMetasBySessionScope, filterTraces, formatDuration, formatError, formatTerminalName, formatTimestamp, getDefaultTraceDir, getIndent, getRunIdFromTraceFileName, getTraceFilePath, groupSessionCohorts, initializeTraceFile, isAgentInspectTrace, listTraceFiles, loadSessionRunRecords, loadTraceMetadataList, parseDuration, parseDurationFilter, parseTraceJsonl, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, readTraceEvents, readTraceFile, renderErrorLine, renderRunSummary, renderRunWhat, renderStepLine, renderTimeline, renderTraceStats, resolveRedactionProfile, resolveTraceDir, searchTraces, serializeEvent, sessionKeyForRun, traceMetasToSessionRunRecords, truncateName, unknownTraceFormatMessage, validateEvent, warn, writeTraceEvent };

package/packages/core/dist/advanced.d.ts

@@ -1,12 +1,14 @@
-export { C as CreateInspectorOptions, D as DEFAULT_MAX_EVENT_BYTES, f as DEFAULT_MAX_METADATA_VALUE_LENGTH, h as DEFAULT_MAX_PREVIEW_LENGTH, I as Inspector, a as InspectorCaptureOptions, b as InspectorObserveOptions, c as InspectorRunOptions, i as InspectorRuntime, j as InspectorRuntimeContext, k as InspectorRuntimeDiagnostics, l as InspectorRuntimeOptions, d as InspectorStepOptions, T as TraceSafetyOptions, e as createInspector, n as createInspectorRuntime, o as getCurrentContext, g as getCurrentCorrelationMetadata, p as getCurrentDepth, q as getCurrentRunId, r as getCurrentRunName, s as getCurrentStepId, t as getParentStepId, u as getTraceDirFromContext, v as getTraceSafetyFromContext, w as hasActiveContext, x as isAgentInspectEnabled, y as isSilentContext, m as maybeInspectRun, z as prepareMetadataForDisk, A as prepareTraceEventForDisk, B as resolveTraceSafetyOptions, E as runWithContext, F as runWithStepContext } from './context-yv2VSDQF.js';
-import { R as RedactionProfile, E as ErrorInfo, b as RunStatus, e as StepStatus, h as TraceEvent, j as RunSummary, k as TraceMetadata, l as TraceMetadataStatus, f as StepType, g as TraceCorrelationMetadata } from './types-D-Y1kOU-.js';
-export { A as ActiveStepContext, i as ExecutionContext, I as InspectRunOptions, O as ObserveOptions, a as Run, m as RunCompletedEvent, n as RunStartedEvent, c as Step, o as StepCompletedEvent, d as StepMetadata, S as StepOptions, p as StepStartedEvent, T as TokenMetadata, q as TraceEventBase, r as TraceSchemaVersion, s as isStepStatus, t as isStepType, u as isTraceEvent } from './types-D-Y1kOU-.js';
-import { a as InspectRunTree } from './inspect-event-CevRYp58.js';
-export { A as AttributionConfidence, E as EventSource, c as InspectEvent, I as InspectKind, b as InspectNode } from './inspect-event-CevRYp58.js';
-import { P as PersistedInspectEvent } from './persisted-inspect-event-D-WpXeZX.js';
+export { C as CreateInspectorOptions, D as DEFAULT_MAX_EVENT_BYTES, f as DEFAULT_MAX_METADATA_VALUE_LENGTH, h as DEFAULT_MAX_PREVIEW_LENGTH, I as Inspector, a as InspectorCaptureOptions, b as InspectorObserveOptions, c as InspectorRunOptions, i as InspectorRuntime, j as InspectorRuntimeContext, k as InspectorRuntimeDiagnostics, l as InspectorRuntimeOptions, d as InspectorStepOptions, T as TraceSafetyOptions, e as createInspector, n as createInspectorRuntime, o as getCurrentContext, g as getCurrentCorrelationMetadata, p as getCurrentDepth, q as getCurrentRunId, r as getCurrentRunName, s as getCurrentStepId, t as getParentStepId, u as getTraceDirFromContext, v as getTraceSafetyFromContext, w as hasActiveContext, x as isAgentInspectEnabled, y as isSilentContext, m as maybeInspectRun, z as prepareMetadataForDisk, A as prepareTraceEventForDisk, B as resolveTraceSafetyOptions, E as runWithContext, F as runWithStepContext } from './context-BDZmi53V.js';
+import { R as RedactionProfile, E as ErrorInfo, b as RunStatus, e as StepStatus, h as TraceEvent, j as RunSummary, k as TraceMetadata, l as TraceMetadataStatus, f as StepType, g as TraceCorrelationMetadata } from './types-CQun9LW6.js';
+export { A as ActiveStepContext, i as ExecutionContext, I as InspectRunOptions, O as ObserveOptions, a as Run, m as RunCompletedEvent, n as RunStartedEvent, c as Step, o as StepCompletedEvent, d as StepMetadata, S as StepOptions, p as StepStartedEvent, T as TokenMetadata, q as TraceEventBase, r as TraceSchemaVersion, s as isStepStatus, t as isStepType, u as isTraceEvent } from './types-CQun9LW6.js';
+import { b as InspectRunTree } from './inspect-event-CYAV7Hxm.js';
+export { A as AttributionConfidence, E as EventSource, a as InspectEvent, I as InspectKind, c as InspectNode } from './inspect-event-CYAV7Hxm.js';
+import { P as PersistedInspectEvent } from './persisted-inspect-event-BLvb0jSX.js';
 import { Stats } from 'node:fs';
+import { TraceCheckResult, TraceCheckStatus } from './checks.js';
 import './writers.js';
-import './log-config-DVimQJho.js';
+import './log-config-D3Yp1SZN.js';
+import './readers.js';
 
 interface ResolvedRedactionProfile {
     profile: RedactionProfile;
@@ -365,6 +367,8 @@ interface TraceSearchOptions {
     tool?: string;
     duration?: string;
     limit?: number;
+    session?: string;
+    correlateGroup?: boolean;
 }
 interface TraceSearchResult {
     runId: string;
@@ -378,6 +382,7 @@ interface TraceSearchResult {
     matchReason: string;
     matchedFields: string[];
     filePath: string;
+    sessionId?: string;
 }
 interface ParsedDurationFilter {
     op: ">" | ">=" | "<" | "<=";
@@ -387,6 +392,165 @@ declare function parseDurationFilter(expr: string): ParsedDurationFilter;
 declare function searchTraces(metas: TraceMetadata[], options: TraceSearchOptions): Promise<TraceSearchResult[]>;
 declare function loadTraceMetadataList(_traceDir: string, fileNames: string[], getPath: (fileName: string) => string): Promise<TraceMetadata[]>;
 
+/** Known session/workflow metadata keys (v2.4 RFC). */
+declare const SESSION_WORKFLOW_KEYS: readonly ["sessionId", "conversationId", "groupId", "parentGroupId", "attempt", "retryOf", "retryReason", "handoffFrom", "handoffTo", "subAgentId", "subAgentName", "jobId", "queueName", "workflowName", "workflowStep", "toolCallId", "mcpToolCallId", "linkedStepId", "correlationId", "requestId", "decisionId"];
+type SessionWorkflowKey = (typeof SESSION_WORKFLOW_KEYS)[number];
+type SessionConfidence = "explicit" | "correlated" | "heuristic" | "unknown";
+type SessionEdgeSource = "manual" | "adapter" | "json-log" | "log4js" | "mcp-client" | "inferred";
+interface SessionWorkflowMetadata {
+    sessionId?: string;
+    conversationId?: string;
+    groupId?: string;
+    parentGroupId?: string;
+    attempt?: number;
+    retryOf?: string;
+    retryReason?: string;
+    handoffFrom?: string;
+    handoffTo?: string;
+    subAgentId?: string;
+    subAgentName?: string;
+    jobId?: string;
+    queueName?: string;
+    workflowName?: string;
+    workflowStep?: string;
+    toolCallId?: string;
+    mcpToolCallId?: string;
+    linkedStepId?: string;
+    correlationId?: string;
+    requestId?: string;
+    decisionId?: string;
+}
+interface SessionRunRecord {
+    runId: string;
+    name?: string;
+    status?: TraceMetadataStatus;
+    startedAt?: number;
+    endedAt?: number;
+    durationMs?: number;
+    filePath?: string;
+    metadata?: Record<string, unknown>;
+}
+interface SessionWarning {
+    code: string;
+    message: string;
+    runId?: string;
+    sessionId?: string;
+}
+interface HandoffEdge {
+    from: string;
+    to: string;
+    source: SessionEdgeSource;
+    confidence: SessionConfidence;
+}
+interface RetryLink {
+    runId: string;
+    retryOf?: string;
+    attempt?: number;
+    source: SessionEdgeSource;
+    confidence: SessionConfidence;
+}
+interface SessionGroup {
+    groupId: string;
+    parentGroupId?: string;
+    runIds: string[];
+}
+interface CriticalPathStep {
+    runId: string;
+    name?: string;
+    startedAt?: number;
+    durationMs?: number;
+    source: SessionEdgeSource;
+    confidence: SessionConfidence;
+}
+interface SessionSummary {
+    sessionId: string;
+    runIds: string[];
+    groups: SessionGroup[];
+    handoffs: HandoffEdge[];
+    retries: RetryLink[];
+    criticalPath: CriticalPathStep[];
+}
+interface SessionIndex {
+    runs: SessionRunRecord[];
+    sessions: SessionSummary[];
+    unscopedRunIds: string[];
+    warnings: SessionWarning[];
+}
+interface BuildSessionIndexOptions {
+    /** When true, group runs that share only `groupId` under a synthetic session key. */
+    correlateByGroupId?: boolean;
+}
+
+/** Extracts session/workflow metadata from a run metadata or attributes bag. */
+declare function extractSessionWorkflowMetadata(record: Record<string, unknown> | undefined): SessionWorkflowMetadata | undefined;
+declare function sessionKeyForRun(meta: SessionWorkflowMetadata | undefined, options?: {
+    correlateByGroupId?: boolean;
+}): string | undefined;
+
+/** Enriches trace metadata with run_started metadata for session indexing. */
+declare function enrichSessionRunRecord(meta: TraceMetadata): Promise<SessionRunRecord>;
+/** Builds session run records from extracted trace metadata rows. */
+declare function loadSessionRunRecords(metas: readonly TraceMetadata[]): Promise<SessionRunRecord[]>;
+
+interface SessionScopeOptions {
+    sessionId?: string;
+    groupId?: string;
+    correlateByGroupId?: boolean;
+}
+interface SessionScopeResult {
+    metas: TraceMetadata[];
+    scopeLabel: string;
+    scopeKind: "session" | "group";
+    runIds: string[];
+    warnings: SessionWarning[];
+    notFound: boolean;
+}
+/** Filters trace metadata rows to runs in a session or group scope. */
+declare function filterMetasBySessionScope(metas: readonly TraceMetadata[], records: readonly SessionRunRecord[], options: SessionScopeOptions): SessionScopeResult;
+/** Lightweight metadata rows for scope resolution when run_started metadata is absent. */
+declare function traceMetasToSessionRunRecords(metas: readonly TraceMetadata[]): SessionRunRecord[];
+
+type SessionCohortKind = "session" | "group";
+interface SessionCohort {
+    key: string;
+    kind: SessionCohortKind;
+    runIds: string[];
+}
+interface GroupSessionCohortsOptions extends BuildSessionIndexOptions {
+    groupBy?: "session" | "group";
+}
+/**
+ * Groups runs into session or group cohort buckets for local search/check aggregation.
+ * Deterministic; does not infer causality from timestamps.
+ */
+declare function groupSessionCohorts(runs: readonly SessionRunRecord[], options?: GroupSessionCohortsOptions): SessionCohort[];
+
+interface TraceSessionCheckResult extends TraceCheckResult {
+    scopeKind: "session" | "group";
+    scopeLabel: string;
+    runIds: string[];
+    runResults: Array<{
+        runId: string;
+        status: TraceCheckStatus;
+    }>;
+    sessionWarnings?: SessionWarning[];
+}
+/** Aggregates per-run check results for a session or group scope. */
+declare function aggregateSessionCheckResults(perRun: readonly TraceCheckResult[], scope: {
+    scopeKind: "session" | "group";
+    scopeLabel: string;
+    runIds: string[];
+    sessionWarnings?: SessionWarning[];
+    notFound?: boolean;
+    empty?: boolean;
+}): TraceSessionCheckResult;
+
+/**
+ * Builds a deterministic session index from local run records and metadata.
+ * Does not read files or infer causality from timestamps alone.
+ */
+declare function buildSessionIndex(inputRuns: readonly SessionRunRecord[], options?: BuildSessionIndexOptions): SessionIndex;
+
 /**
  * Safety check for cleanup workflows: returns true only when the file appears to be an AgentInspect trace.
  * This should be conservative: false positives are more dangerous than false negatives.
@@ -401,4 +565,4 @@ declare function isAgentInspectTrace(filePath: string): Promise<boolean>;
  */
 declare function parseDuration(duration: string): number;
 
-export { DEFAULT_TRACE_DIR_NAME, type DurationStats, ErrorInfo, type ExplainFact, type ExplainInference, type ExplainMode, type ExplainOptions, type ExplainResult, FALLBACK_TRACE_DIR, InspectRunTree, MAX_NAME_LENGTH, MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, type ParseTraceJsonlOptions, type ParseTraceJsonlResult, type ParsedDurationFilter, RUNS_DIR_NAME, RedactionProfile, type RenderTimelineOptions, type RenderWhatOptions, type ResolvedRedactionProfile, RunStatus, RunSummary, type RunTimeline, type RunWhatSummary, StepStatus, StepType, TERMINAL_INDENT, type TimelineEntry, type TimelineFocus, type TimelineOptions, TraceCorrelationMetadata, TraceDirectory, type TraceDirectoryOptions, TraceEvent, type TraceFilterOptions, type TraceJsonlFormat, TraceMetadata, TraceMetadataStatus, type TraceSearchOptions, type TraceSearchResult, type TraceStats, type TraceStatsOptions, type TraceStatsRankedRun, type TraceStatsRankedStep, buildLocalExplanation, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildTraceStats, createRunId, createStepId, ensureTraceDir, extractMetadata, filterTraces, formatDuration, formatError, formatTerminalName, formatTimestamp, getDefaultTraceDir, getIndent, getRunIdFromTraceFileName, getTraceFilePath, initializeTraceFile, isAgentInspectTrace, listTraceFiles, loadTraceMetadataList, parseDuration, parseDurationFilter, parseTraceJsonl, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, readTraceEvents, readTraceFile, renderErrorLine, renderRunSummary, renderRunWhat, renderStepLine, renderTimeline, renderTraceStats, resolveRedactionProfile, resolveTraceDir, searchTraces, serializeEvent, truncateName, unknownTraceFormatMessage, validateEvent, warn, writeTraceEvent };
+export { type BuildSessionIndexOptions, type CriticalPathStep, DEFAULT_TRACE_DIR_NAME, type DurationStats, ErrorInfo, type ExplainFact, type ExplainInference, type ExplainMode, type ExplainOptions, type ExplainResult, FALLBACK_TRACE_DIR, type GroupSessionCohortsOptions, type HandoffEdge, InspectRunTree, MAX_NAME_LENGTH, MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, type ParseTraceJsonlOptions, type ParseTraceJsonlResult, type ParsedDurationFilter, RUNS_DIR_NAME, RedactionProfile, type RenderTimelineOptions, type RenderWhatOptions, type ResolvedRedactionProfile, type RetryLink, RunStatus, RunSummary, type RunTimeline, type RunWhatSummary, SESSION_WORKFLOW_KEYS, type SessionCohort, type SessionCohortKind, type SessionConfidence, type SessionEdgeSource, type SessionGroup, type SessionIndex, type SessionRunRecord, type SessionScopeOptions, type SessionScopeResult, type SessionSummary, type SessionWarning, type SessionWorkflowKey, type SessionWorkflowMetadata, StepStatus, StepType, TERMINAL_INDENT, type TimelineEntry, type TimelineFocus, type TimelineOptions, TraceCorrelationMetadata, TraceDirectory, type TraceDirectoryOptions, TraceEvent, type TraceFilterOptions, type TraceJsonlFormat, TraceMetadata, TraceMetadataStatus, type TraceSearchOptions, type TraceSearchResult, type TraceSessionCheckResult, type TraceStats, type TraceStatsOptions, type TraceStatsRankedRun, type TraceStatsRankedStep, aggregateSessionCheckResults, buildLocalExplanation, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildSessionIndex, buildTraceStats, createRunId, createStepId, enrichSessionRunRecord, ensureTraceDir, extractMetadata, extractSessionWorkflowMetadata, filterMetasBySessionScope, filterTraces, formatDuration, formatError, formatTerminalName, formatTimestamp, getDefaultTraceDir, getIndent, getRunIdFromTraceFileName, getTraceFilePath, groupSessionCohorts, initializeTraceFile, isAgentInspectTrace, listTraceFiles, loadSessionRunRecords, loadTraceMetadataList, parseDuration, parseDurationFilter, parseTraceJsonl, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, readTraceEvents, readTraceFile, renderErrorLine, renderRunSummary, renderRunWhat, renderStepLine, renderTimeline, renderTraceStats, resolveRedactionProfile, resolveTraceDir, searchTraces, serializeEvent, sessionKeyForRun, traceMetasToSessionRunRecords, truncateName, unknownTraceFormatMessage, validateEvent, warn, writeTraceEvent };