agent_sessions 0.3.0 → 0.3.1

data/doc/Agent/Sessions.md

@@ -0,0 +1,177 @@
+# Module Agent::Sessions <a id="module-Agent-Sessions"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/agent/sessions.rb, lib/agent/sessions/cli.rb, lib/agent/sessions/node.rb, lib/agent/sessions/part.rb, lib/agent/sessions/audit.rb, lib/agent/sessions/check.rb, lib/agent/sessions/error.rb, lib/agent/sessions/store.rb, lib/agent/sessions/usage.rb, lib/agent/sessions/sqlite.rb, lib/agent/sessions/message.rb, lib/agent/sessions/session.rb, lib/agent/sessions/version.rb, lib/agent/sessions/location.rb, lib/agent/sessions/compaction.rb, lib/agent/sessions/readers/pi.rb, lib/agent/sessions/adapters/pi.rb, lib/agent/sessions/readers/amp.rb, lib/agent/sessions/adapters/amp.rb, lib/agent/sessions/env_override.rb, lib/agent/sessions/readers/base.rb, lib/agent/sessions/readers/grok.rb, lib/agent/sessions/readers/qwen.rb, lib/agent/sessions/adapters/base.rb, lib/agent/sessions/adapters/grok.rb, lib/agent/sessions/adapters/qwen.rb, lib/agent/sessions/readers/codex.rb, lib/agent/sessions/unknown_agent.rb, lib/agent/sessions/adapters/codex.rb, lib/agent/sessions/home_expansion.rb, lib/agent/sessions/readers/claude.rb, lib/agent/sessions/readers/gemini.rb, lib/agent/sessions/adapters/claude.rb, lib/agent/sessions/adapters/cursor.rb, lib/agent/sessions/adapters/gemini.rb, lib/agent/sessions/readers/copilot.rb, lib/agent/sessions/adapters/copilot.rb, lib/agent/sessions/readers/opencode.rb, lib/agent/sessions/unreadable_store.rb, lib/agent/sessions/adapters/opencode.rb, lib/agent/sessions/missing_dependency.rb, lib/agent/sessions/unsupported_format.rb, lib/agent/sessions/adapters/cursor_ide.rb, lib/agent/sessions/adapters/enumeration.rb |
+
+## Constants
+### `LOADER` <a id="constant-LOADER"></a> <a id="LOADER-constant"></a>
+Not documented.
+
+### `STALE_AFTER_DAYS` <a id="constant-STALE_AFTER_DAYS"></a> <a id="STALE_AFTER_DAYS-constant"></a>
+Not documented.
+
+### `VERIFIED_ON` <a id="constant-VERIFIED_ON"></a> <a id="VERIFIED_ON-constant"></a>
+The oldest verified_on among the built-in adapters. A claim about somebody
+else's software is only as current as its weakest link, so this is the honest
+answer to "when was this last known to be true".
+
+### `VERSION` <a id="constant-VERSION"></a> <a id="VERSION-constant"></a>
+Not documented.
+
+## Public Class Methods
+### `agents()` <a id="method-c-agents"></a> <a id="agents-class_method"></a>
+Not documented.
+
+### `all(env: ENV)` <a id="method-c-all"></a> <a id="all-class_method"></a>
+Not documented.
+
+### `audit(env: ENV)` <a id="method-c-audit"></a> <a id="audit-class_method"></a>
+Not documented.
+
+### `doctor(agent = nil, env: ENV, today: Date.today)` <a id="method-c-doctor"></a> <a id="doctor-class_method"></a>
+Not documented.
+
+### `for_project(dir, env: ENV, agents: nil)` <a id="method-c-for_project"></a> <a id="for_project-class_method"></a>
+One project across every agent (or the agents: subset), lazily: adapters
+earlier in the sweep satisfy `first(n)` without the later ones ever being
+asked. Within one adapter, though, laziness cannot skip non-matching sessions
+— sessions_for_project must still stat and check each candidate to know it
+does not match, so an adapter with zero matches costs a full scan of its store
+before the sweep moves on. True of the six Base-driven adapters; opencode
+pushes the filter into SQL (WHERE directory = ?) and stats nothing.
+
+Deliberately does NOT rescue MissingDependency or UnreadableStore: opencode
+without the sqlite3 gem, or with a corrupt/locked database, raises. Since
+`flat_map` is lazy, that raise surfaces only once enumeration reaches the
+failing adapter — possibly after other agents' sessions have already been
+yielded to the caller mid-iteration, and possibly not at all if `first(n)` is
+satisfied first. Silently omitting an agent's sessions is this gem's worst
+failure mode (design doc decision 11), so this method never trades a raised,
+attributable error for a quietly incomplete list. A caller that wants the
+sweep to survive one bad agent should rescue per call, e.g. by driving
+<code>agents:</code> itself and catching around each adapter; a caller who
+just wants to route around a known-bad agent can pass <code>agents:</code>
+naming every registered agent except it. The CLI (Task 10) does the former,
+turning the same exceptions into per-agent "skipped" lines instead of one
+failed sweep. Note a rescue cannot resume this enumerator: re-calling each
+after a raise re-raises from the same adapter. The only recovery is a fresh
+call with a narrower <code>agents:</code>. Adapters are resolved eagerly, so
+an unknown name in <code>agents:</code> raises here rather than mid-sweep. The
+deferral above is about DATA conditions, where the raise carries information
+about a store; a typo'd agent symbol is a programmer error knowable before any
+I/O, and `agents: [:claude, :nope]` otherwise hands back Claude's sessions and
+then crashes. Base#initialize only stores @env, so constructing all seven up
+front costs nothing, and the sweep stays lazy — first(n) still stops at the
+first matching adapter.
+
+### `installed(env: ENV)` <a id="method-c-installed"></a> <a id="installed-class_method"></a>
+Not documented.
+
+### `locate(agent, env: ENV)` <a id="method-c-locate"></a> <a id="locate-class_method"></a>
+Not documented.
+
+### `projects(agent, env: ENV)` <a id="method-c-projects"></a> <a id="projects-class_method"></a>
+Eager, unlike sessions/for_project: project_paths already reads every session
+to answer (design doc section 7 — the on-disk encodings are lossy, so the
+recorded cwd is the only reliable source), sorts, and dedupes, so a lazy
+return type here would promise a laziness the work underneath cannot honor.
+Returns a plain, already-sorted Array. Raises MissingDependency or
+UnreadableStore for opencode, as sessions does.
+
+### `read(session, **options)` <a id="method-c-read"></a> <a id="read-class_method"></a>
+Layer 3. Takes a Session (from `sessions`, `for_project`), not an agent name,
+because reading is per-session — the adapter comes from the session itself.
+Raises UnsupportedFormat for an agent with no reader yet, rather than
+returning a reader that yields nothing: "this gem cannot read that format" and
+"that session has no messages" must never look alike.
+
+include_events: true adds the agent's UI-level records to the stream where an
+adapter has them. They are excluded by default because they are bookkeeping,
+not conversation, and they outnumber real messages.
+
+### `register(adapter_class)` <a id="method-c-register"></a> <a id="register-class_method"></a>
+Re-registering a name deliberately replaces it, so a consumer can ship a
+corrected adapter for an agent whose layout moved before the gem catches up.
+- **@raise** [Error]
+
+### `registry()` <a id="method-c-registry"></a> <a id="registry-class_method"></a>
+Not documented.
+
+### `sessions(agent, env: ENV, since: nil)` <a id="method-c-sessions"></a> <a id="sessions-class_method"></a>
+Lazy: consuming N sessions stats N files, never more. `since`, when given,
+must be a Time (or anything Time#>= accepts) — comparing updated_at (always a
+Time; every adapter populates it, from mtime or store metadata) against a
+Date, Integer, or String raises ArgumentError("comparison of Time with ...
+failed"), which already names the mistake, so no extra guard is added here.
+That raise happens on enumeration, not on this call, because the filter itself
+is lazy — `sessions(:x, since: bad).first(1)` can raise from inside `first`,
+not from this line. Raises MissingDependency or UnreadableStore for opencode
+under the same conditions described on for_project below.
+
+### `unresolved_project_count(agent, env: ENV)` <a id="method-c-unresolved_project_count"></a> <a id="unresolved_project_count-class_method"></a>
+Companion to `projects`/`project_paths`, which both exclude a session whose
+project could not be resolved rather than counting it (design doc section 7) —
+so "this agent genuinely records no projects" and "this agent's project
+resolution is broken" read identically from the outside. Three of seven
+adapters can legitimately return a nil project_path (Amp threads with no
+`trees`, cursor_ide by design, pi whenever its unverified header assumption is
+wrong); this counts it for any of them, uniformly, using only the public
+`sessions` enumerator —no adapter needs to know this exists. Eager and a
+second full sweep of the store, same cost class as `projects` itself, so it is
+opt-in (called by the CLI only under `list --project`, never under plain
+`list`) rather than folded into `projects`' own return value, which is a
+documented, tested plain Array and would otherwise need a shape change to
+carry both numbers. Raises MissingDependency or UnreadableStore for opencode,
+as sessions does.
+
+### `verify(agent = nil, env: ENV)` <a id="method-c-verify"></a> <a id="verify-class_method"></a>
+Not documented.
+
+# Documentation
+
+- [Sessions/Adapters.md](Sessions/Adapters.md)
+- [Sessions/Adapters/Amp.md](Sessions/Adapters/Amp.md)
+- [Sessions/Adapters/Base.md](Sessions/Adapters/Base.md)
+- [Sessions/Adapters/Claude.md](Sessions/Adapters/Claude.md)
+- [Sessions/Adapters/Codex.md](Sessions/Adapters/Codex.md)
+- [Sessions/Adapters/Copilot.md](Sessions/Adapters/Copilot.md)
+- [Sessions/Adapters/Cursor.md](Sessions/Adapters/Cursor.md)
+- [Sessions/Adapters/CursorIde.md](Sessions/Adapters/CursorIde.md)
+- [Sessions/Adapters/Enumeration.md](Sessions/Adapters/Enumeration.md)
+- [Sessions/Adapters/Gemini.md](Sessions/Adapters/Gemini.md)
+- [Sessions/Adapters/Grok.md](Sessions/Adapters/Grok.md)
+- [Sessions/Adapters/Opencode.md](Sessions/Adapters/Opencode.md)
+- [Sessions/Adapters/Pi.md](Sessions/Adapters/Pi.md)
+- [Sessions/Adapters/Qwen.md](Sessions/Adapters/Qwen.md)
+- [Sessions/Audit.md](Sessions/Audit.md)
+- [Sessions/Audit/Finding.md](Sessions/Audit/Finding.md)
+- [Sessions/CLI.md](Sessions/CLI.md)
+- [Sessions/Check.md](Sessions/Check.md)
+- [Sessions/Compaction.md](Sessions/Compaction.md)
+- [Sessions/EnvOverride.md](Sessions/EnvOverride.md)
+- [Sessions/Error.md](Sessions/Error.md)
+- [Sessions/HomeExpansion.md](Sessions/HomeExpansion.md)
+- [Sessions/Location.md](Sessions/Location.md)
+- [Sessions/Message.md](Sessions/Message.md)
+- [Sessions/MissingDependency.md](Sessions/MissingDependency.md)
+- [Sessions/Node.md](Sessions/Node.md)
+- [Sessions/Part.md](Sessions/Part.md)
+- [Sessions/Readers.md](Sessions/Readers.md)
+- [Sessions/Readers/Amp.md](Sessions/Readers/Amp.md)
+- [Sessions/Readers/Base.md](Sessions/Readers/Base.md)
+- [Sessions/Readers/Claude.md](Sessions/Readers/Claude.md)
+- [Sessions/Readers/Codex.md](Sessions/Readers/Codex.md)
+- [Sessions/Readers/Copilot.md](Sessions/Readers/Copilot.md)
+- [Sessions/Readers/Gemini.md](Sessions/Readers/Gemini.md)
+- [Sessions/Readers/Grok.md](Sessions/Readers/Grok.md)
+- [Sessions/Readers/Opencode.md](Sessions/Readers/Opencode.md)
+- [Sessions/Readers/Pi.md](Sessions/Readers/Pi.md)
+- [Sessions/Readers/Qwen.md](Sessions/Readers/Qwen.md)
+- [Sessions/Session.md](Sessions/Session.md)
+- [Sessions/Sqlite.md](Sessions/Sqlite.md)
+- [Sessions/Store.md](Sessions/Store.md)
+- [Sessions/UnknownAgent.md](Sessions/UnknownAgent.md)
+- [Sessions/UnreadableStore.md](Sessions/UnreadableStore.md)
+- [Sessions/UnsupportedFormat.md](Sessions/UnsupportedFormat.md)
+- [Sessions/Usage.md](Sessions/Usage.md)

data/doc/Agent.md

@@ -0,0 +1,5 @@
+# Module Agent <a id="module-Agent"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/agent/sessions.rb, lib/agent/sessions/cli.rb, lib/agent/sessions/node.rb, lib/agent/sessions/part.rb, lib/agent/sessions/audit.rb, lib/agent/sessions/check.rb, lib/agent/sessions/error.rb, lib/agent/sessions/store.rb, lib/agent/sessions/usage.rb, lib/agent/sessions/sqlite.rb, lib/agent/sessions/message.rb, lib/agent/sessions/session.rb, lib/agent/sessions/version.rb, lib/agent/sessions/location.rb, lib/agent/sessions/compaction.rb, lib/agent/sessions/readers/pi.rb, lib/agent/sessions/adapters/pi.rb, lib/agent/sessions/readers/amp.rb, lib/agent/sessions/adapters/amp.rb, lib/agent/sessions/env_override.rb, lib/agent/sessions/readers/base.rb, lib/agent/sessions/readers/grok.rb, lib/agent/sessions/readers/qwen.rb, lib/agent/sessions/adapters/base.rb, lib/agent/sessions/adapters/grok.rb, lib/agent/sessions/adapters/qwen.rb, lib/agent/sessions/readers/codex.rb, lib/agent/sessions/unknown_agent.rb, lib/agent/sessions/adapters/codex.rb, lib/agent/sessions/home_expansion.rb, lib/agent/sessions/readers/claude.rb, lib/agent/sessions/readers/gemini.rb, lib/agent/sessions/adapters/claude.rb, lib/agent/sessions/adapters/cursor.rb, lib/agent/sessions/adapters/gemini.rb, lib/agent/sessions/readers/copilot.rb, lib/agent/sessions/adapters/copilot.rb, lib/agent/sessions/readers/opencode.rb, lib/agent/sessions/unreadable_store.rb, lib/agent/sessions/adapters/opencode.rb, lib/agent/sessions/missing_dependency.rb, lib/agent/sessions/unsupported_format.rb, lib/agent/sessions/adapters/cursor_ide.rb, lib/agent/sessions/adapters/enumeration.rb |

data/doc/CHANGELOG.md

@@ -0,0 +1,69 @@
+## 0.3.1 (2026-08-26)
+
+- Add tracked Markdown YARD documentation and a consolidated `llm.txt`, package both with the gem, and validate every local documentation link
+- Add a deterministic, warning-free documentation generator and a fail-fast `bin/prepare_release` workflow that tests, rebuilds documentation, refreshes `llm.txt`, and builds without publishing
+- Verify the supported Ruby floor and current release in CI on Ruby 3.2 and 4.0.1, and harden gem builds with a Git-independent manifest plus isolated installation and CLI checks
+- Strengthen adapter conformance coverage and remove order dependence from the affected tests and fixtures
+- Keep YARD tooling development-only; runtime dependencies remain `agent_homedir` and `zeitwerk`
+
+## 0.3.0 (2026-08-25)
+
+- Breaking: the Ruby namespace is now `Agent::Sessions`; `AgentSessions` is removed with no alias. `require "agent_sessions"` still works through the shim and defines the new namespace
+- Base-dir resolution now delegates to `agent_homedir` and runs through a per-instance resolver instead of this gem's own expansion rules
+- Relative base-dir environment overrides now join `HOME` instead of the current working directory, `~user` no longer stays literal, and whitespace-only overrides fall back to adapter defaults
+- `cursor_ide` now honors `XDG_CONFIG_HOME` on Linux and `APPDATA` on Windows
+- Blank or non-absolute XDG overrides now fall back to defaults for Amp and opencode, and `OPENCODE_DATA_DIR` now appears in `env_overrides`
+- Adapters whose base-dir rules do not define the current host OS now raise instead of silently assuming Linux
+
+- `Usage` (`input`, `output`, `cache_read`, `cache_creation`, `reasoning`, `cost`): token counts normalized to disjoint buckets across agents. `nil` means "this format does not record that dimension", never zero; `cost` is only ever agent-reported, never derived from a pricing table
+- `Message#usage` and `Message#model`, populated where the format puts them on the message (Claude); `reader.usage` returns session totals or nil
+- Claude usage dedups by `message.id` before summing: one API response streams into one record per content block repeating identical usage (94 of 124 message ids in one real transcript), so a naive sum roughly doubles what was billed
+- Codex usage reads the last `token_count` record's running total and subtracts `cached_input_tokens` from `input_tokens` (Codex counts them inclusively; Claude disjointly — verified against real stores on both sides, 2026-08-24)
+- Claude reader recognizes `atis-latch` and `bridge-session` (session state postdating the 2026-08-12 corpus, observed live 2026-08-24) instead of warning about them
+- opencode reader — the first over SQLite: 13,804 messages from 365 real sessions with zero warnings, and its summed usage equals the store's own per-session rollup columns on all 365. One `tool` part becomes a `:tool_use` and a `:tool_result`; a `subtask` spawn becomes a `:tool_use` named after its agent; step markers, patches and file attachments stay in `raw`. Needs the optional `sqlite3` gem
+- pi reader, explicitly provisional: written against tokentelemetry's working parser of the format, since no pi session files exist on the machine it was written on — every mapping degrades to `:unknown` + warning rather than crashing if real pi output disagrees
+- **Four new agents: Gemini CLI, GitHub Copilot CLI, Qwen Code and Grok Build**, taking the gem from 7 adapters to 11
+- Gemini CLI adapter + reader, verified against a real store (12 sessions, 121 records): `~/.gemini/tmp/<projectHash>/chats/session-*.json`, one JSON document per chat. Its `cached` count sits INSIDE `input` — established arithmetically across all 97 real token records, where `total` equals `input + output + thoughts + tool` and never adds `cached` — so the reader subtracts it, as it does for Codex. `thoughts` become `:thinking` parts carrying subject and description; `info` records are opt-in events. Filenames are UTC, unlike Codex's and pi's local-clock ones, and their trailing hex is NOT a session id (two real files share one), so the id is the whole basename
+- GitHub Copilot CLI adapter + reader, verified against a real store: **the format has moved** to `~/.copilot/session-store.db` (SQLite, schema_version 3) from the `session-state/<id>/events.jsonl` layout the reference tooling still reads — an adapter following the older spec reports nothing on a current install. One `turns` row is a whole exchange and becomes two messages. No token or cost column exists anywhere in that schema, and the adapter says so rather than letting nil read as zero
+- Qwen Code adapter + reader, and Grok Build adapter + reader — both PROVISIONAL and declared as such at runtime: neither store exists on the machine they were written on, so they follow tokentelemetry's parsers rather than observation, and every mapping degrades to `:unknown` + a warning rather than crashing if real output disagrees
+- Grok's session is a directory, not a file: Layer 2 enumerates `summary.json`, the reader streams `chat_history.jsonl` beside it, and billed usage comes from a third file — `~/.grok/logs/unified.jsonl`, shared by every session and keyed by session id. `Readers::Base#record_path` is a new hook for exactly that split
+- **Cursor IDE is repointed at the store it actually uses** — `~/Library/Application Support/Cursor/User/globalStorage/state.vscdb`, table `cursorDiskKV`, keys `composerData:<uuid>` — confirmed by opening it (6 real sessions on the machine this was written on, where the 0.2 declaration `~/.cursor/projects/*/agent-transcripts/*` did not exist at all). Fidelity rises from `:unsupported` to `:metadata`; content is still unread, because every record seen carried an empty `conversation`, and the adapter says so rather than guessing the turn format
+- opencode store discovery now tries `OPENCODE_DATA_DIR`, `XDG_DATA_HOME`, `~/.local/share/opencode`, macOS `~/Library/Application Support/opencode` and the Windows app-data dirs, and matches `opencode*.db` rather than the plain name — a macOS user, or one on a release channel that renames the database, previously got an empty result from an agent they had used. A candidate must actually hold a database to win, so an empty directory cannot shadow a real store; two databases holding the same session report it once
+- `base_dir default:` accepts a Hash keyed by platform (`:macos`, `:linux`, `:windows`) for IDE-hosted agents whose store genuinely moves between operating systems; a Hash missing this machine's platform raises rather than falling back to another platform's path
+- `AgentSessions::Sqlite` extracts the one safe way this gem opens a SQLite store (read-only URI, escaped path, 5s busy timeout), now shared by the opencode adapter and reader
+- Layer 3 begins: `AgentSessions.read(session)` returns a streaming reader — `each_message`, `messages`, `compactions`, `warnings`, `fidelity`, `partial?`
+- `Message` (`role`, `at`, `parts`, `text`, `raw`) and `Part` (`:text`, `:thinking`, `:tool_use`, `:tool_result`, `:image`, `:unknown`); `raw` is never dropped
+- Codex reader, the first: reads 73,946 messages from 415 real sessions with zero warnings and zero exceptions, at 4.5 ms per session
+- `compacted` records become boundaries rather than messages — replaying their `replacement_history` would report the same turns twice
+- `event_msg` records (38% of the corpus) are excluded unless `include_events: true`
+- Readers stream at an 8 MB per-record cap, not Layer 2's 1 MB: 14 real records exceed 1 MB and the largest is 2.41 MB, so the smaller cap would have dropped real messages. A record past the cap is reported, never silently skipped
+- `AgentSessions.read` raises `UnsupportedFormat` for an agent with no reader, so "cannot read this format" never looks like "this session is empty"
+- Claude reader: 18,111 messages from 142 real transcripts, zero exceptions, 5.6 ms per session
+- Claude's spilled tool output is resolved from the sidecar file, so a `:tool_result` carries content instead of a pointer — bounded to the session's own sidecar tree, because the path is read out of tool output and must never become a file-read primitive. `resolve_spills: false` turns it off
+- `reader.subagents` returns readers for the transcripts a session spawned, never merged into its own messages — 124 of them on the machine this was written against
+- Claude's nine session-state record types and its `system`/`attachment` context records are separated from turns; the latter two arrive with `include_events: true`
+- Amp reader: `partial?` is true there, since the server holds the canonical copy. A thread is one JSON document rather than JSONL, so it is read whole under a 32 MB cap — the bound the gem's one unbounded read never had
+- `reader.tree` returns the conversation as roots and continuations for an agent that records parent links, with `reader.branching?` to ask first. Claude branches at 374 points across 83 of 151 real transcripts — a turn edited and re-run leaves two children under one parent, which reading in file order shows as two histories interleaved
+- Readers that record no parent links raise `UnsupportedFormat` from `tree` rather than returning an empty list, so "this format does not record that" never reads as "this session has none"
+- Agents other than Codex, Claude and Amp have no reader yet; `Session#fidelity` already says what each one will support
+
+## 0.2.0 (2026-08-10)
+
+First public release. 0.1.0 was never tagged or published, so its work is
+folded into this entry rather than shipping a changelog with two consecutive
+"(unreleased)" headings under two different version numbers.
+
+- Layer 1: resolve session store paths for Claude Code, Codex CLI, Cursor CLI, Cursor IDE, Amp CLI, opencode, and pi
+- Layer 2: `Session`, lazy `sessions`, `for_project`, `projects` across all seven adapters
+- `AgentSessions.sessions(agent, since:)`, `.for_project(dir, agents:)`, `.projects(agent)`
+- `Session` is a plain, lazily-resolved value object: `project_path` is computed on first access and memoized
+- `Location#files` replaces `matches`, aware of single-file layers (`single_file`, `enumerable?`)
+- opencode session enumeration via a deferred read-only SQLite query, behind an **optional** `sqlite3` gem — the gemspec stays runtime-dependency-free
+- CLI: `where`, `doctor`, `audit`, `list` (`--agent`, `--project`, `--since`), and `du` (`--by agent|project`), all with `--json` output
+- Amp's `secrets.json` is now optional: a missing file reports drift, not failure
+- `verify`'s skip gate now keys on store existence, not base-dir existence
+- `doctor` takes its agent positionally, matching `where`
+- `list`/`du` now exit non-zero when any agent's store had to be skipped, instead of exiting 0 with only a stderr notice
+- Codex declares `archived_sessions/` (flat, optional) and enumerates it: an archived rollout file is a session, and `sessions`, `list`, `du`, and `audit` all report it now
+- Claude's `Session#bytes` counts the sidecar directory each transcript gets — `<id>/subagents/`, `<id>/tool-results/` — so `du` and `audit` no longer disagree by 29% about the same store
+- `Adapters::Base#bytes_for(path, stat)` is a new overridable hook, defaulting to the transcript's own size

data/doc/README.md

@@ -0,0 +1,162 @@
+# agent_sessions
+
+Where do AI coding agents store their session logs? This gem knows.
+
+Resolves session store paths for Claude Code, Codex CLI, Cursor (CLI and IDE), Amp CLI, opencode, pi, Gemini CLI, GitHub Copilot CLI, Qwen Code, and Grok Build. Verifies those paths against disk. Audits whether plaintext transcripts sit inside anything that syncs.
+
+Read-only by design. Runtime dependencies: `agent_homedir` and `zeitwerk`.
+
+Most of these eleven layouts are undocumented, or only partly documented, by their vendors and can move in any release — Copilot CLI's moved from JSONL files to SQLite, and Cursor IDE's was found in a different directory than the one previously believed. Each adapter carries the date its claims were last checked against a real install, and `agent-sessions doctor` reports both that date and what disk says now.
+
+Two adapters, Qwen Code and Grok Build, are marked provisional: no such store existed on the machine they were written against, so they follow another tool's working parser of the same format rather than direct observation. They say so at runtime.
+
+## Installation
+
+Use Ruby 3.2 or newer.
+
+Install the CLI directly:
+
+```sh
+gem install agent_sessions
+```
+
+Or add to your application's Gemfile:
+
+```ruby
+gem "agent_sessions"
+```
+
+Enumerating the SQLite-backed agents — opencode, Cursor IDE, and GitHub Copilot CLI — needs the optional `sqlite3` gem. Every other adapter works without it.
+
+## Quick start
+
+```sh
+agent-sessions where
+agent-sessions doctor
+agent-sessions audit
+agent-sessions list --since 30d
+agent-sessions du --by project
+```
+
+Add `--json` to `where`, `doctor`, `audit`, `list`, or `du` for machine-readable output. `du --by project` is the one command in the gem that is not stat-only: resolving a project name pays one bounded read per session for the file-based agents (opencode answers from its own SQL query instead, so it pays nothing extra).
+
+## Supported agents
+
+Use the bare name in CLI arguments and the symbol in Ruby calls:
+
+| Agent | CLI | Ruby |
+| --- | --- | --- |
+| Claude Code | `claude` | `:claude` |
+| Codex CLI | `codex` | `:codex` |
+| Cursor CLI | `cursor` | `:cursor` |
+| Cursor IDE | `cursor_ide` | `:cursor_ide` |
+| Amp CLI | `amp` | `:amp` |
+| opencode | `opencode` | `:opencode` |
+| pi | `pi` | `:pi` |
+| Gemini CLI | `gemini` | `:gemini` |
+| GitHub Copilot CLI | `copilot` | `:copilot` |
+| Qwen Code | `qwen` | `:qwen` |
+| Grok Build | `grok` | `:grok` |
+
+Ruby callers passing any other symbol get `Agent::Sessions::UnknownAgent`; its message lists the valid names. The CLI catches that error, prints its message, and exits with status 1.
+
+## Ruby API
+
+Browse the [generated API documentation](https://github.com/lucianghinda/agent_sessions/blob/main/doc/Agent/Sessions.md) or the consolidated [`llm.txt`](https://github.com/lucianghinda/agent_sessions/blob/main/llm.txt) reference.
+
+```ruby
+require "agent_sessions" # compatibility shim for Agent::Sessions
+
+store = Agent::Sessions.locate(:codex)
+store.effective.path   # => "/Users/you/.codex/sessions"
+store.format           # => :jsonl
+store.documented?      # => false
+store.retention        # => nil ("grows forever")
+```
+
+List agents:
+
+```ruby
+Agent::Sessions.all        # every supported agent
+Agent::Sessions.installed  # only agents present on this machine
+```
+
+Verify claims against disk:
+
+```ruby
+Agent::Sessions.verify(:codex)
+# => [#<Check status: :pass, claim: "store sessions exists", ...>]
+```
+
+Resolve for an environment that is not your own:
+
+```ruby
+Agent::Sessions.locate(:codex, env: { "CODEX_HOME" => "/tmp/x" })
+```
+
+Enumerate sessions and map them to projects:
+
+```ruby
+Agent::Sessions.sessions(:claude).first(5)      # lazy; stats files, never parses them
+Agent::Sessions.for_project(Dir.pwd)            # every agent's sessions for one project
+Agent::Sessions.projects(:codex)                # distinct recorded project paths (reads headers)
+```
+
+Among the SQLite-backed agents, readers exist for opencode and Copilot CLI; Cursor IDE remains metadata-only.
+
+Read a session's messages and token usage (Claude, Codex, Amp, opencode, pi, Gemini CLI, Copilot CLI, Qwen and Grok):
+
+```ruby
+reader = Agent::Sessions.read(session)
+reader.each_message { |m| puts "#{m.role}: #{m.text}" }  # streams; raw is never dropped
+reader.usage                                  # session token totals, or nil if not recorded
+reader.usage&.input                           # disjoint buckets: input, output, cache_read,
+                                              #   cache_creation, reasoning, cost
+```
+
+`Usage` is normalized across agents: `input` never includes cached tokens (Codex counts them inclusively; the reader subtracts), and a `nil` dimension means the format does not record it — never zero. `cost` is only ever what the agent itself reported; this gem ships no pricing table.
+
+`Session#bytes` is what that session occupies on disk, not just its transcript. Claude Code writes a sidecar directory beside each transcript — `<id>/subagents/`, `<id>/tool-results/` — and those bytes belong to the session that produced them, which is why `du` and `audit` agree on the same store.
+
+### Errors
+
+Every domain-specific error the gem raises descends from `Agent::Sessions::Error`:
+
+- Catch `Agent::Sessions::UnknownAgent` for a name outside the supported-agents table; the message lists valid names.
+- Catch `Agent::Sessions::MissingDependency` when a SQLite-backed agent is enumerated without the optional `sqlite3` gem installed.
+- Catch `Agent::Sessions::UnsupportedFormat` when `read` is called on a session whose format has no reader (Cursor CLI and Cursor IDE).
+- Catch `Agent::Sessions::UnreadableStore` when a store exists but cannot be opened.
+
+## Roadmap
+
+- 0.2: enumerate sessions, map them to projects (`list`, `du`)
+- **0.3 (this release):** read and normalize messages; Ruby API renamed to `Agent::Sessions` while `require "agent_sessions"` stays as the compatibility shim, and base-dir resolution delegates to `agent_homedir`
+- 0.4: a reader for Cursor IDE, which is metadata-only today
+- 0.5: `export` with secret redaction
+
+## Contributing
+
+Activate Ruby 3.2 or newer.
+
+Run the tests before sending a change:
+
+```sh
+bundle install
+bundle exec rake test
+```
+
+Before a release, run:
+
+```sh
+bin/prepare_release
+```
+
+It runs the test suite, regenerates the API documentation and `llm.txt`, and builds the gem without publishing it.
+
+## License
+
+MIT
+
+## History
+
+View the [changelog](CHANGELOG.md).