agent-inspect 4.0.0 → 4.2.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 4.2.0
+
+### Minor Changes
+
+- Add sessions and activity as first-class local concepts (v4.2).
+
+  - Derive session status, timing, last error, and retry counts on enriched `SessionSummary` (builds on v2.4 vocabulary; no timestamp-only causality).
+  - Add `buildActivitySummary` for windowed activity feeds.
+  - Expand CLI: `sessions latest`, `activity`, `show`, `handoffs`, `errors` (bare `sessions` list and `session <id>` unchanged).
+  - Optional SQLite index acceleration for session loading with automatic scan fallback when the index is absent, stale, or corrupt.
+  - Docs: CLI reference update.
+
+## 4.1.0
+
+### Minor Changes
+
+- Add the optional local trace index (v4.1).
+
+  - New optional package `@agent-inspect/index-sqlite`: a disposable, rebuildable SQLite index over AgentInspect JSONL traces for faster local queries. JSONL stays the source of truth, trace files are never mutated, deleting the index is always safe, and there is no network access. SQLite (`better-sqlite3`) lives only in this optional package — never in root/core.
+  - New `agent-inspect index sqlite` CLI subcommands (`build`, `rebuild`, `status`, `query`, `clean`) that load the optional package on demand and print an install hint when it is absent.
+  - Non-throwing read APIs (`queryRuns`, `indexStatus`, `isIndexStale`) with corruption/staleness recovery so callers can transparently fall back to a directory scan.
+  - Docs: `docs/INDEX.md` plus `docs/CLI.md` reference.
+
 ## 4.0.0
 
 ### Major Changes

package/docs/CLI.md

@@ -30,6 +30,7 @@ Core commands:
 - `init` — scaffold local AgentInspect config and demo files (v3.1+)
 - `doctor` — diagnose local setup without network or installs (v3.1+)
 - `workspace` — manage a project-local trace workspace (`.agent-inspect/workspace.json`) (v4.0+)
+- `index sqlite` — optional SQLite-backed trace index for faster queries (requires `@agent-inspect/index-sqlite`) (v4.1+)
 - `check` — run deterministic local trace checks with stable JSON and exit codes
 - `eval` — run deterministic local evals over existing traces
 - `redact` — redact a local JSON/JSONL file or trace copy
@@ -41,7 +42,7 @@ Core commands:
 - `timeline` — chronological view of one run (local JSONL)
 - `stats` — local aggregate stats over a trace directory
 - `search` — deterministic local search over traces
-- `sessions` — list workflow sessions from trace metadata
+- `sessions` — list workflow sessions; v4.2+ subcommands: `latest`, `activity`, `show`, `handoffs`, `errors`
 - `session` — inspect one session (handoffs, retries, optional timeline)
 - `what` — concise summary of a single run (local JSONL)
 - `report` — markdown or HTML inspection report for a single run
@@ -680,23 +681,34 @@ npx agent-inspect search --session sess-retry-001 --dir ./.agent-inspect
 
 ### 6.19 `sessions`
 
-List workflow sessions grouped from local trace metadata (`sessionId`, optional `groupId` correlation). Read-only; no network.
+Workflow sessions and activity from local trace metadata. v4.2 adds session status, activity summaries, and optional SQLite index acceleration (falls back to directory scan). Read-only; no network.
 
 ```bash
-agent-inspect sessions [options]
+agent-inspect sessions [options]                    # list sessions (default)
+agent-inspect sessions latest [--json]
+agent-inspect sessions activity [--since 7d] [--json]
+agent-inspect sessions show <session-id> [--timeline] [--json]
+agent-inspect sessions handoffs [--session <id>] [--json]
+agent-inspect sessions errors [--since 7d] [--json]
 ```
 
-Options:
+Shared options:
 
 - `--dir <path>`
 - `--correlate-group` — treat shared `groupId` as a synthetic session when `sessionId` is absent
-- `--json` — `SessionIndex` JSON (`sessions`, `unscopedRunIds`, `warnings`)
+- `--stale-after <duration>` — mark sessions stale after inactivity (e.g. `24h`, `7d`)
+- `--json` — deterministic JSON output
+
+`activity` and `errors` accept `--since <duration>` (e.g. `7d`, `24h`). Session summaries include derived `status`, `lastActivity`, `lastError`, and `retryCount` without changing trace files.
 
 Example:
 
 ```bash
 npx agent-inspect sessions --dir ./.agent-inspect
-npx agent-inspect sessions --json
+npx agent-inspect sessions latest --json
+npx agent-inspect sessions activity --since 7d
+npx agent-inspect sessions handoffs --session sess-handoff-001
+npx agent-inspect sessions errors --since 30d --json
 ```
 
 ### 6.20 `session`
@@ -829,6 +841,25 @@ agent-inspect workspace path [--json]
 
 All subcommands accept `--json` for deterministic output.
 
+### 6.23 `index sqlite`
+
+Optional SQLite-backed index that accelerates local queries over large trace directories. Added in v4.1. Requires the optional `@agent-inspect/index-sqlite` package; the core CLI does not depend on SQLite. The index is derived from JSONL and always safe to delete — JSONL remains the source of truth and trace files are never mutated. Local-only; no network. See [INDEX.md](INDEX.md) for the full model.
+
+```bash
+agent-inspect index sqlite build [--dir <path>] [--max-runs <n>] [--json]
+agent-inspect index sqlite rebuild [--dir <path>] [--max-runs <n>] [--json]
+agent-inspect index sqlite status [--dir <path>] [--json]
+agent-inspect index sqlite query [--dir <path>] [--status <s>] [--session <id>] [--name <q>] [--kind <k>] [--tool <q>] [--limit <n>] [--json]
+agent-inspect index sqlite clean [--dir <path>] [--json]
+```
+
+- `build` / `rebuild` — build or fully rebuild `trace-index.sqlite` from the trace directory. Rebuilds are idempotent; a corrupt prior index is discarded and rebuilt cleanly.
+- `status` — report index health, run/step counts, build time, and staleness (stale when any trace is newer than the index).
+- `query` — filter indexed runs by status, session, name, step kind, or tool. Exits non-zero with an install/build hint when no usable index is present.
+- `clean` — delete the index database (and its WAL/SHM sidecars). Traces are never touched.
+
+If `@agent-inspect/index-sqlite` is not installed, these subcommands print a short install hint and exit non-zero.
+
 ## 7. Optional TUI behavior
 
 `view --tui` delegates to `@agent-inspect/tui` and requires an interactive terminal. If the package is not installed, the CLI prints a short install hint.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-inspect",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "license": "MIT",
   "type": "module",
   "description": "Trace, check, and safely share TypeScript AI-agent runs locally — no account, no upload, metadata-only by default",
@@ -206,7 +206,7 @@
   },
   "scripts": {
     "clean": "pnpm -r exec -- rm -rf dist",
-    "build": "pnpm exec tsup --config tsup.core.config.ts && pnpm exec tsup --config tsup.cli.config.ts && pnpm exec tsup --config tsup.langchain.config.ts && pnpm exec tsup --config tsup.tui.config.ts && pnpm exec tsup --config tsup.ai-sdk.config.ts && pnpm exec tsup --config tsup.vitest.config.ts && pnpm exec tsup --config tsup.jest.config.ts && pnpm exec tsup --config tsup.openai-agents.config.ts && pnpm exec tsup --config tsup.harness.config.ts && pnpm exec tsup --config tsup.redact.config.ts && pnpm exec tsup --config tsup.eval.config.ts && pnpm exec tsup --config tsup.mcp.config.ts && pnpm exec tsup --config tsup.guardrails.config.ts && pnpm exec tsup --config tsup.circuit.config.ts && pnpm exec tsup --config tsup.viewer.config.ts && pnpm exec tsup --config tsup.mcp-server.config.ts && pnpm exec tsup --config tsup.adapter-sdk.config.ts && pnpm exec tsup --config tsup.vscode.config.ts",
+    "build": "pnpm exec tsup --config tsup.core.config.ts && pnpm exec tsup --config tsup.cli.config.ts && pnpm exec tsup --config tsup.langchain.config.ts && pnpm exec tsup --config tsup.tui.config.ts && pnpm exec tsup --config tsup.ai-sdk.config.ts && pnpm exec tsup --config tsup.vitest.config.ts && pnpm exec tsup --config tsup.jest.config.ts && pnpm exec tsup --config tsup.openai-agents.config.ts && pnpm exec tsup --config tsup.harness.config.ts && pnpm exec tsup --config tsup.redact.config.ts && pnpm exec tsup --config tsup.eval.config.ts && pnpm exec tsup --config tsup.mcp.config.ts && pnpm exec tsup --config tsup.guardrails.config.ts && pnpm exec tsup --config tsup.circuit.config.ts && pnpm exec tsup --config tsup.viewer.config.ts && pnpm exec tsup --config tsup.mcp-server.config.ts && pnpm exec tsup --config tsup.adapter-sdk.config.ts && pnpm exec tsup --config tsup.vscode.config.ts && pnpm exec tsup --config tsup.index-sqlite.config.ts",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",