agent-inspect 4.0.0 → 4.2.0

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

@@ -462,6 +462,47 @@ interface CriticalPathStep {
     source: SessionEdgeSource;
     confidence: SessionConfidence;
 }
+/** Session lifecycle status (v4.2 RFC). */
+type SessionStatus = "running" | "waiting_input" | "idle" | "completed" | "error" | "stale" | "unknown";
+interface SessionLastError {
+    runId: string;
+    message: string;
+    code?: string;
+}
+interface SessionCheckSummary {
+    pass: number;
+    fail: number;
+    warn: number;
+}
+interface EnrichSessionSummaryOptions {
+    /** Reference clock for staleness (default Date.now()). */
+    nowMs?: number;
+    /** Inactivity threshold before marking a session stale (default 24h). */
+    staleThresholdMs?: number;
+}
+interface ActivityEntry {
+    sessionId: string;
+    status: SessionStatus;
+    summary: string;
+    lastActivity: string;
+    runCount: number;
+}
+interface ActivitySummary {
+    since: string;
+    sessions: number;
+    failed: number;
+    stale: number;
+    guardrailWarnings: number;
+    entries: ActivityEntry[];
+}
+interface BuildActivitySummaryOptions {
+    /** Duration window (e.g. 7d, 24h). Default 7d. */
+    since?: string;
+    /** Reference clock (default Date.now()). */
+    nowMs?: number;
+    /** Max entries returned (default 20). */
+    limit?: number;
+}
 interface SessionSummary {
     sessionId: string;
     runIds: string[];
@@ -469,6 +510,23 @@ interface SessionSummary {
     handoffs: HandoffEdge[];
     retries: RetryLink[];
     criticalPath: CriticalPathStep[];
+    /** Derived session status (v4.2+). */
+    status: SessionStatus;
+    /** Earliest run start time in the session. */
+    startedAt?: number;
+    /** Latest run end time when all runs have ended. */
+    endedAt?: number;
+    /** endedAt - startedAt when both are present. */
+    durationMs?: number;
+    correlationId?: string;
+    jobId?: string;
+    workflowId?: string;
+    lastError?: SessionLastError;
+    /** ISO-8601 timestamp of the most recent run activity. */
+    lastActivity: string;
+    retryCount: number;
+    observationSummary?: string;
+    checkSummary?: SessionCheckSummary;
 }
 interface SessionIndex {
     runs: SessionRunRecord[];
@@ -479,6 +537,10 @@ interface SessionIndex {
 interface BuildSessionIndexOptions {
     /** When true, group runs that share only `groupId` under a synthetic session key. */
     correlateByGroupId?: boolean;
+    /** Reference clock for session staleness (v4.2+). */
+    nowMs?: number;
+    /** Inactivity threshold before marking a session stale (v4.2+, default 24h). */
+    staleThresholdMs?: number;
 }
 
 /** Extracts session/workflow metadata from a run metadata or attributes bag. */
@@ -487,6 +549,22 @@ declare function sessionKeyForRun(meta: SessionWorkflowMetadata | undefined, opt
     correlateByGroupId?: boolean;
 }): string | undefined;
 
+/** Derives session status from run records per the v4.2 RFC (no timestamp-only causality). */
+declare function deriveSessionStatus(runs: readonly SessionRunRecord[], options?: EnrichSessionSummaryOptions): SessionStatus;
+/**
+ * Enriches a session summary with v4.2 derived fields (status, timing, errors).
+ * Pure function; does not read trace files.
+ */
+declare function enrichSessionSummary(summary: Omit<SessionSummary, "status" | "lastActivity" | "retryCount" | "startedAt" | "endedAt" | "durationMs" | "correlationId" | "jobId" | "workflowId" | "lastError" | "observationSummary" | "checkSummary">, runs: readonly SessionRunRecord[], options?: EnrichSessionSummaryOptions): SessionSummary;
+
+/**
+ * Builds a deterministic activity summary from a session index (v4.2).
+ * Read-only; does not mutate traces or invent relationships.
+ */
+declare function buildActivitySummary(index: SessionIndex, options?: BuildActivitySummaryOptions): ActivitySummary;
+/** Renders a human activity summary for terminal output. */
+declare function renderActivitySummaryHuman(summary: ActivitySummary): string;
+
 /** 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. */
@@ -565,4 +643,4 @@ declare function isAgentInspectTrace(filePath: string): Promise<boolean>;
  */
 declare function parseDuration(duration: string): number;
 
-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 };
+export { type ActivityEntry, type ActivitySummary, type BuildActivitySummaryOptions, type BuildSessionIndexOptions, type CriticalPathStep, DEFAULT_TRACE_DIR_NAME, type DurationStats, type EnrichSessionSummaryOptions, 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 SessionCheckSummary, type SessionCohort, type SessionCohortKind, type SessionConfidence, type SessionEdgeSource, type SessionGroup, type SessionIndex, type SessionLastError, type SessionRunRecord, type SessionScopeOptions, type SessionScopeResult, type SessionStatus, 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, buildActivitySummary, buildLocalExplanation, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildSessionIndex, buildTraceStats, createRunId, createStepId, deriveSessionStatus, enrichSessionRunRecord, enrichSessionSummary, 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, renderActivitySummaryHuman, renderErrorLine, renderRunSummary, renderRunWhat, renderStepLine, renderTimeline, renderTraceStats, resolveRedactionProfile, resolveTraceDir, searchTraces, serializeEvent, sessionKeyForRun, traceMetasToSessionRunRecords, truncateName, unknownTraceFormatMessage, validateEvent, warn, writeTraceEvent };

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

@@ -462,6 +462,47 @@ interface CriticalPathStep {
     source: SessionEdgeSource;
     confidence: SessionConfidence;
 }
+/** Session lifecycle status (v4.2 RFC). */
+type SessionStatus = "running" | "waiting_input" | "idle" | "completed" | "error" | "stale" | "unknown";
+interface SessionLastError {
+    runId: string;
+    message: string;
+    code?: string;
+}
+interface SessionCheckSummary {
+    pass: number;
+    fail: number;
+    warn: number;
+}
+interface EnrichSessionSummaryOptions {
+    /** Reference clock for staleness (default Date.now()). */
+    nowMs?: number;
+    /** Inactivity threshold before marking a session stale (default 24h). */
+    staleThresholdMs?: number;
+}
+interface ActivityEntry {
+    sessionId: string;
+    status: SessionStatus;
+    summary: string;
+    lastActivity: string;
+    runCount: number;
+}
+interface ActivitySummary {
+    since: string;
+    sessions: number;
+    failed: number;
+    stale: number;
+    guardrailWarnings: number;
+    entries: ActivityEntry[];
+}
+interface BuildActivitySummaryOptions {
+    /** Duration window (e.g. 7d, 24h). Default 7d. */
+    since?: string;
+    /** Reference clock (default Date.now()). */
+    nowMs?: number;
+    /** Max entries returned (default 20). */
+    limit?: number;
+}
 interface SessionSummary {
     sessionId: string;
     runIds: string[];
@@ -469,6 +510,23 @@ interface SessionSummary {
     handoffs: HandoffEdge[];
     retries: RetryLink[];
     criticalPath: CriticalPathStep[];
+    /** Derived session status (v4.2+). */
+    status: SessionStatus;
+    /** Earliest run start time in the session. */
+    startedAt?: number;
+    /** Latest run end time when all runs have ended. */
+    endedAt?: number;
+    /** endedAt - startedAt when both are present. */
+    durationMs?: number;
+    correlationId?: string;
+    jobId?: string;
+    workflowId?: string;
+    lastError?: SessionLastError;
+    /** ISO-8601 timestamp of the most recent run activity. */
+    lastActivity: string;
+    retryCount: number;
+    observationSummary?: string;
+    checkSummary?: SessionCheckSummary;
 }
 interface SessionIndex {
     runs: SessionRunRecord[];
@@ -479,6 +537,10 @@ interface SessionIndex {
 interface BuildSessionIndexOptions {
     /** When true, group runs that share only `groupId` under a synthetic session key. */
     correlateByGroupId?: boolean;
+    /** Reference clock for session staleness (v4.2+). */
+    nowMs?: number;
+    /** Inactivity threshold before marking a session stale (v4.2+, default 24h). */
+    staleThresholdMs?: number;
 }
 
 /** Extracts session/workflow metadata from a run metadata or attributes bag. */
@@ -487,6 +549,22 @@ declare function sessionKeyForRun(meta: SessionWorkflowMetadata | undefined, opt
     correlateByGroupId?: boolean;
 }): string | undefined;
 
+/** Derives session status from run records per the v4.2 RFC (no timestamp-only causality). */
+declare function deriveSessionStatus(runs: readonly SessionRunRecord[], options?: EnrichSessionSummaryOptions): SessionStatus;
+/**
+ * Enriches a session summary with v4.2 derived fields (status, timing, errors).
+ * Pure function; does not read trace files.
+ */
+declare function enrichSessionSummary(summary: Omit<SessionSummary, "status" | "lastActivity" | "retryCount" | "startedAt" | "endedAt" | "durationMs" | "correlationId" | "jobId" | "workflowId" | "lastError" | "observationSummary" | "checkSummary">, runs: readonly SessionRunRecord[], options?: EnrichSessionSummaryOptions): SessionSummary;
+
+/**
+ * Builds a deterministic activity summary from a session index (v4.2).
+ * Read-only; does not mutate traces or invent relationships.
+ */
+declare function buildActivitySummary(index: SessionIndex, options?: BuildActivitySummaryOptions): ActivitySummary;
+/** Renders a human activity summary for terminal output. */
+declare function renderActivitySummaryHuman(summary: ActivitySummary): string;
+
 /** 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. */
@@ -565,4 +643,4 @@ declare function isAgentInspectTrace(filePath: string): Promise<boolean>;
  */
 declare function parseDuration(duration: string): number;
 
-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 };
+export { type ActivityEntry, type ActivitySummary, type BuildActivitySummaryOptions, type BuildSessionIndexOptions, type CriticalPathStep, DEFAULT_TRACE_DIR_NAME, type DurationStats, type EnrichSessionSummaryOptions, 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 SessionCheckSummary, type SessionCohort, type SessionCohortKind, type SessionConfidence, type SessionEdgeSource, type SessionGroup, type SessionIndex, type SessionLastError, type SessionRunRecord, type SessionScopeOptions, type SessionScopeResult, type SessionStatus, 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, buildActivitySummary, buildLocalExplanation, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildSessionIndex, buildTraceStats, createRunId, createStepId, deriveSessionStatus, enrichSessionRunRecord, enrichSessionSummary, 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, renderActivitySummaryHuman, renderErrorLine, renderRunSummary, renderRunWhat, renderStepLine, renderTimeline, renderTraceStats, resolveRedactionProfile, resolveTraceDir, searchTraces, serializeEvent, sessionKeyForRun, traceMetasToSessionRunRecords, truncateName, unknownTraceFormatMessage, validateEvent, warn, writeTraceEvent };

package/packages/core/dist/advanced.mjs

@@ -644,6 +644,252 @@ function sessionKeyForRun(meta, options) {
   return void 0;
 }
 
+// packages/core/src/sessions/status.ts
+var DEFAULT_STALE_THRESHOLD_MS = 864e5;
+var EXPLICIT_STATUS_PRIORITY = {
+  error: 5,
+  waiting_input: 4,
+  idle: 3,
+  stale: 2,
+  completed: 1
+};
+var EXPLICIT_SESSION_STATUSES = /* @__PURE__ */ new Set([
+  "running",
+  "waiting_input",
+  "idle",
+  "completed",
+  "error",
+  "stale",
+  "unknown"
+]);
+function isExplicitSessionStatus(value) {
+  return typeof value === "string" && EXPLICIT_SESSION_STATUSES.has(value);
+}
+function activityMs(run) {
+  return run.endedAt ?? run.startedAt ?? 0;
+}
+function latestActivityMs(runs) {
+  let latest = 0;
+  for (const run of runs) {
+    const ms = activityMs(run);
+    if (ms > latest) latest = ms;
+  }
+  return latest;
+}
+function earliestStart(runs) {
+  let earliest;
+  for (const run of runs) {
+    if (run.startedAt === void 0) continue;
+    if (earliest === void 0 || run.startedAt < earliest) {
+      earliest = run.startedAt;
+    }
+  }
+  return earliest;
+}
+function latestEndWhenAllEnded(runs) {
+  if (runs.length === 0) return void 0;
+  let latest;
+  for (const run of runs) {
+    if (run.endedAt === void 0) return void 0;
+    if (latest === void 0 || run.endedAt > latest) latest = run.endedAt;
+  }
+  return latest;
+}
+function pickExplicitStatus(runs) {
+  let best;
+  let bestPriority = 0;
+  for (const run of runs) {
+    const raw = run.metadata?.sessionStatus;
+    if (!isExplicitSessionStatus(raw)) continue;
+    const priority = EXPLICIT_STATUS_PRIORITY[raw] ?? 0;
+    if (priority > bestPriority) {
+      bestPriority = priority;
+      best = raw;
+    }
+  }
+  return best;
+}
+function deriveLastError(runs) {
+  const errorRuns = runs.filter((run) => run.status === "error").sort((a, b) => activityMs(b) - activityMs(a));
+  const latest = errorRuns[0];
+  if (!latest) return void 0;
+  const meta = latest.metadata ?? {};
+  const message = typeof meta.errorMessage === "string" && meta.errorMessage.trim() !== "" ? meta.errorMessage.trim() : latest.name ?? latest.runId;
+  const code = typeof meta.errorCode === "string" && meta.errorCode.trim() !== "" ? meta.errorCode.trim() : void 0;
+  return { runId: latest.runId, message, code };
+}
+function deriveCheckSummary(runs) {
+  let pass = 0;
+  let fail = 0;
+  let warn2 = 0;
+  let found = false;
+  for (const run of runs) {
+    const summary = run.metadata?.checkSummary;
+    if (!summary || typeof summary !== "object") continue;
+    const record = summary;
+    if (typeof record.pass === "number") {
+      pass += record.pass;
+      found = true;
+    }
+    if (typeof record.fail === "number") {
+      fail += record.fail;
+      found = true;
+    }
+    if (typeof record.warn === "number") {
+      warn2 += record.warn;
+      found = true;
+    }
+  }
+  return found ? { pass, fail, warn: warn2 } : void 0;
+}
+function deriveObservationSummary(runs) {
+  for (const run of [...runs].sort((a, b) => activityMs(b) - activityMs(a))) {
+    const value = run.metadata?.observationSummary;
+    if (typeof value === "string" && value.trim() !== "") {
+      return value.trim();
+    }
+  }
+  return void 0;
+}
+function deriveSessionStatus(runs, options = {}) {
+  if (runs.length === 0) return "unknown";
+  if (runs.some((run) => run.status === "running")) return "running";
+  const explicit = pickExplicitStatus(runs);
+  if (explicit && explicit !== "running") return explicit;
+  if (runs.some((run) => run.status === "error")) return "error";
+  if (runs.every((run) => run.status === "success")) return "completed";
+  const nowMs = options.nowMs ?? Date.now();
+  const staleThresholdMs = options.staleThresholdMs ?? DEFAULT_STALE_THRESHOLD_MS;
+  const lastMs = latestActivityMs(runs);
+  if (lastMs > 0 && nowMs - lastMs > staleThresholdMs) return "stale";
+  return "unknown";
+}
+function enrichSessionSummary(summary, runs, options = {}) {
+  const sessionRuns = runs.filter((run) => summary.runIds.includes(run.runId)).sort((a, b) => a.runId.localeCompare(b.runId));
+  const startedAt = earliestStart(sessionRuns);
+  const endedAt = latestEndWhenAllEnded(sessionRuns);
+  const durationMs = startedAt !== void 0 && endedAt !== void 0 ? endedAt - startedAt : void 0;
+  let correlationId;
+  let jobId;
+  let workflowId;
+  for (const run of sessionRuns) {
+    const meta = extractSessionWorkflowMetadata(run.metadata);
+    if (!correlationId && meta?.correlationId) correlationId = meta.correlationId;
+    if (!jobId && meta?.jobId) jobId = meta.jobId;
+    if (!workflowId && meta?.workflowName) workflowId = meta.workflowName;
+    else if (!workflowId && meta?.workflowStep) workflowId = meta.workflowStep;
+  }
+  const lastMs = latestActivityMs(sessionRuns);
+  const lastActivity = lastMs > 0 ? new Date(lastMs).toISOString() : (/* @__PURE__ */ new Date(0)).toISOString();
+  const retryCount = summary.retries.filter(
+    (retry) => retry.retryOf !== void 0 || (retry.attempt ?? 0) > 1
+  ).length;
+  return {
+    ...summary,
+    status: deriveSessionStatus(sessionRuns, options),
+    startedAt,
+    endedAt,
+    durationMs,
+    correlationId,
+    jobId,
+    workflowId,
+    lastError: deriveLastError(sessionRuns),
+    lastActivity,
+    retryCount,
+    observationSummary: deriveObservationSummary(sessionRuns),
+    checkSummary: deriveCheckSummary(sessionRuns)
+  };
+}
+
+// packages/core/src/sessions/activity.ts
+function statusLine(session) {
+  const name = session.workflowId ?? session.correlationId ?? session.sessionId;
+  const status = session.status;
+  if (session.lastError) {
+    return `${name} session ${session.sessionId} failed at ${session.lastError.message}`;
+  }
+  if (session.observationSummary) {
+    return `${name} session ${session.sessionId} ${status} with observation warning`;
+  }
+  return `${name} session ${session.sessionId} ${status}`;
+}
+function parseSinceMs(since, nowMs) {
+  if (!since || since.trim() === "") return nowMs - 7 * 864e5;
+  const trimmed = since.trim().toLowerCase();
+  const match = /^(\d+)([smhd])$/.exec(trimmed);
+  if (!match) return nowMs - 7 * 864e5;
+  const amount = Number.parseInt(match[1], 10);
+  const unit = match[2];
+  const mult = unit === "s" ? 1e3 : unit === "m" ? 6e4 : unit === "h" ? 36e5 : 864e5;
+  return nowMs - amount * mult;
+}
+function isFailed(status) {
+  return status === "error";
+}
+function isStale(status) {
+  return status === "stale";
+}
+function guardrailWarnings(session) {
+  const summary = session.checkSummary;
+  if (!summary) return 0;
+  return summary.warn;
+}
+function buildActivitySummary(index, options = {}) {
+  const nowMs = options.nowMs ?? Date.now();
+  const sinceMs = parseSinceMs(options.since, nowMs);
+  const sinceIso = new Date(sinceMs).toISOString();
+  const limit = Number.isInteger(options.limit) && options.limit > 0 ? options.limit : 20;
+  const inWindow = index.sessions.filter((session) => {
+    const activityMs2 = Date.parse(session.lastActivity);
+    return Number.isFinite(activityMs2) && activityMs2 >= sinceMs;
+  });
+  const entries = [...inWindow].sort((a, b) => Date.parse(b.lastActivity) - Date.parse(a.lastActivity)).slice(0, limit).map((session) => ({
+    sessionId: session.sessionId,
+    status: session.status,
+    summary: statusLine(session),
+    lastActivity: session.lastActivity,
+    runCount: session.runIds.length
+  }));
+  let failed = 0;
+  let stale = 0;
+  let guardrailWarningTotal = 0;
+  for (const session of inWindow) {
+    if (isFailed(session.status)) failed += 1;
+    if (isStale(session.status)) stale += 1;
+    guardrailWarningTotal += guardrailWarnings(session);
+  }
+  return {
+    since: sinceIso,
+    sessions: inWindow.length,
+    failed,
+    stale,
+    guardrailWarnings: guardrailWarningTotal,
+    entries
+  };
+}
+function renderActivitySummaryHuman(summary) {
+  const lines = [];
+  const todayStart = /* @__PURE__ */ new Date();
+  todayStart.setHours(0, 0, 0, 0);
+  const todayMs = todayStart.getTime();
+  const today = summary.entries.filter(
+    (entry) => Date.parse(entry.lastActivity) >= todayMs
+  );
+  if (today.length > 0) {
+    lines.push("Today");
+    for (const entry of today) {
+      lines.push(`  ${entry.summary}`);
+    }
+    lines.push("");
+  }
+  lines.push(`Since ${summary.since}`);
+  lines.push(`  ${summary.sessions} sessions`);
+  lines.push(`  ${summary.failed} failed`);
+  lines.push(`  ${summary.stale} stale`);
+  lines.push(`  ${summary.guardrailWarnings} guardrail warnings`);
+  return lines.join("\n");
+}
+
 // packages/core/src/sessions/types.ts
 var SESSION_WORKFLOW_KEYS = [
   "sessionId",
@@ -1126,14 +1372,21 @@ function buildSessionIndex(inputRuns, options = {}) {
         sessionId
       });
     }
-    return {
-      sessionId,
-      runIds,
-      groups,
-      handoffs,
-      retries,
-      criticalPath
-    };
+    return enrichSessionSummary(
+      {
+        sessionId,
+        runIds,
+        groups,
+        handoffs,
+        retries,
+        criticalPath
+      },
+      runs,
+      {
+        nowMs: options.nowMs,
+        staleThresholdMs: options.staleThresholdMs
+      }
+    );
   });
   if (sessions.length === 0 && runs.length > 0) {
     warnings.push({
@@ -1197,6 +1450,6 @@ async function isAgentInspectTrace(filePath) {
   }
 }
 
-export { SESSION_WORKFLOW_KEYS, aggregateSessionCheckResults, buildLocalExplanation, buildSessionIndex, buildTraceStats, enrichSessionRunRecord, extractSessionWorkflowMetadata, filterMetasBySessionScope, filterTraces, groupSessionCohorts, isAgentInspectTrace, loadSessionRunRecords, loadTraceMetadataList, parseDurationFilter, renderTraceStats, searchTraces, sessionKeyForRun, traceMetasToSessionRunRecords };
+export { SESSION_WORKFLOW_KEYS, aggregateSessionCheckResults, buildActivitySummary, buildLocalExplanation, buildSessionIndex, buildTraceStats, deriveSessionStatus, enrichSessionRunRecord, enrichSessionSummary, extractSessionWorkflowMetadata, filterMetasBySessionScope, filterTraces, groupSessionCohorts, isAgentInspectTrace, loadSessionRunRecords, loadTraceMetadataList, parseDurationFilter, renderActivitySummaryHuman, renderTraceStats, searchTraces, sessionKeyForRun, traceMetasToSessionRunRecords };
 //# sourceMappingURL=advanced.mjs.map
 //# sourceMappingURL=advanced.mjs.map