agent_sessions 0.3.0

data/lib/agent/sessions/adapters/claude.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Adapters
+          class Claude < Base
+            agent :claude
+            label "Claude Code"
+            documented true
+            verified_on "2026-08-05"
+            fidelity :full
+
+            homedir :claude_code
+
+            store :projects, dir: "projects", glob: "*/*.jsonl", format: :jsonl
+            store :history, path: "history.jsonl", format: :jsonl, optional: true
+
+            def self.reader_class = Readers::Claude
+
+            DEFAULT_CLEANUP_PERIOD_DAYS = 30
+
+            def retention
+              configured_retention || DEFAULT_CLEANUP_PERIOD_DAYS
+            end
+
+            def retention_source
+              configured_retention ? :setting : :default
+            end
+
+            def warnings
+              list = super
+              if env_active?("CLAUDE_CODE_SKIP_PROMPT_HISTORY")
+                list << "CLAUDE_CODE_SKIP_PROMPT_HISTORY is set: history.jsonl is not being written"
+              end
+              list
+            end
+
+            # Every non-alphanumeric character becomes "-" (design doc section 7).
+            # dir must already be absolute and expanded — sessions_for_project
+            # guarantees that; a direct caller passing "app", "~/app", or a
+            # trailing slash gets a nonsense encoding (see Base#encode_project).
+            # Verified against real project directories on 2026-08-05:
+            # /Users/dev/.local -> -Users-dev--local
+            def encode_project(dir)
+              dir.gsub(/[^a-zA-Z0-9]/, "-")
+            end
+
+            # cwd is NOT on line 1. Real sessions open with a kebab-case preamble
+            # (ai-title, agent-name, mode, permission-mode) followed by a
+            # variable-length run of file-history-snapshot records — that run is
+            # what pushes the first cwd-bearing record out further on some files,
+            # and nothing bounds its length. Observed on this machine on 2026-08-05:
+            # line 3 (19 files), line 4 (48 files), line 9 (1 file, a longer
+            # snapshot run). limit: 25 is ~2.8x that observed maximum — headroom
+            # for the variable-length run, not a tight fit to the common case — and
+            # keeps this a few-KB read even on multi-GB files.
+            #
+            # The block guards against a record that carries "cwd" but not usably:
+            # null shadows a later valid record, and a wrong type (Integer, Hash)
+            # would otherwise reach project_paths' .uniq.sort and raise there.
+            # scan_jsonl_for_key already guarantees the key is present once the
+            # block accepts, so a plain fetch (no default) is safe.
+            def project_path_for(path)
+              scan_jsonl_for_key(path, "cwd", limit: 25) { |record| record["cwd"].is_a?(String) }&.fetch("cwd")
+            end
+
+            # Claude Code writes a directory beside each transcript, named after the
+            # session id with the extension dropped: subagents/ holds the transcripts
+            # of agents this session spawned, tool-results/ holds tool output too
+            # large to inline. Those bytes are this session's, and until they were
+            # counted `du` reported 122.1 MB for a store `audit` reported 173.0 MB
+            # for — 71% — because audit sums the store directory whole while du sums
+            # sessions. Two commands, one directory, a 29% disagreement.
+            #
+            # Measured over 128 real sessions on 2026-08-10: 0.002 ms per session
+            # when there is no sidecar (one stat, the common case on a fresh install)
+            # and 0.080 ms when there is. That is under half what project_path's
+            # content read costs, and unlike project_path this cannot be deferred —
+            # bytes is eager, and a lazily-corrected byte total would leave `list`
+            # printing one number while `du` summed another.
+            def bytes_for(path, stat)
+              stat.size + sidecar_bytes(path)
+            end
+
+            private
+
+            # Not File.basename: the sidecar sits beside the transcript, so only the
+            # extension comes off. A path with no extension leaves the name unchanged
+            # and File.directory? then answers false for the transcript itself.
+            #
+            # SystemCallError, not a narrower list, and rescued rather than raised
+            # for the reason Base#bytes_for's comment gives: this runs eagerly for
+            # every session, so an unreadable sidecar must cost its own byte total
+            # and nothing else. Missing bytes beat a missing session.
+            def sidecar_bytes(path)
+              sidecar = path.delete_suffix(File.extname(path))
+              # readable? as well as directory?: Dir.glob answers [] for a directory
+              # it cannot open, but warns while doing it under -w, which is how the
+              # test suite runs. It does not cover an unreadable directory NESTED in
+              # a readable sidecar — the rescue below is what covers that.
+              return 0 unless File.directory?(sidecar) && File.readable?(sidecar)
+
+              # FNM_DOTMATCH for Audit#bytes_under's reason: a total that quietly
+              # omits dotfiles is worse than no total at all.
+              Dir.glob(File.join(escape_glob(sidecar), "**", "*"), File::FNM_DOTMATCH).sum do |entry|
+                File.file?(entry) ? File.size(entry) : 0
+              end
+            rescue SystemCallError
+              0
+            end
+
+            def settings
+              @settings ||= read_json(File.join(base_dir, "settings.json"))
+            end
+
+            def configured_retention
+              value = settings["cleanupPeriodDays"]
+              value if value.is_a?(Integer) && !value.negative?
+            end
+          end
+        end
+  end
+end

data/lib/agent/sessions/adapters/codex.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Adapters
+          class Codex < Base
+            agent :codex
+            label "Codex CLI"
+            documented false
+            verified_on "2026-07-21"
+            fidelity :full
+
+            homedir :codex
+
+            store :sessions, dir: "sessions", glob: "*/*/*/rollout-*.jsonl", format: :jsonl
+            # Flat, unlike sessions/YYYY/MM/DD/ — the one real archived file found
+            # (2026-08-10) sat directly in the directory. Optional because most
+            # machines have never archived anything, so absence is drift, not a
+            # failed claim. Declared second so primary_layer stays `sessions`.
+            store :archived, dir: "archived_sessions", glob: "rollout-*.jsonl", format: :jsonl, optional: true
+            store :history, path: "history.jsonl", format: :jsonl, optional: true
+            store :index, path: "session_index.jsonl", format: :jsonl, optional: true
+
+            warning "the [history] config section governs history.jsonl only; " \
+                    "persistence = \"none\" does not stop rollout files"
+
+            def self.reader_class = Readers::Codex
+
+            # rollout-<YYYY-MM-DDTHH-MM-SS>-<uuid>.jsonl (verified 2026-08-05 against
+            # 360 real session files on this machine — every one matched). The
+            # timestamp uses the local clock and dashes where ISO 8601 has colons.
+            # started_at_for's comment says what "local" costs elsewhere. The uuid
+            # group is pinned to its actual shape (8-4-4-4-12 hex), not (.+): greedy
+            # against \.jsonl\z, (.+) would swallow a sync tool's or backup's
+            # " (conflicted copy)" suffix into what looks like a canonical id rather
+            # than falling back to the basename, where such a copy is at least
+            # visibly non-canonical.
+            FILENAME = /\Arollout-(\d{4})-(\d{2})-(\d{2})T(\d{2})-(\d{2})-(\d{2})-(\h{8}-\h{4}-\h{4}-\h{4}-\h{12})\.jsonl\z/
+
+            # Codex writes rollout files to two stores, and Base enumerates only the
+            # primary one. An archived session is still a session — a real one was
+            # found outside the sessions/ glob on 2026-08-10 — and a session the gem
+            # does not report is the silent under-reporting this design treats as its
+            # worst failure mode. Every filename hook below applies unchanged: the
+            # archived files carry the same rollout-<timestamp>-<uuid>.jsonl name.
+            #
+            # `super` first, so the guard it raises when the primary store has no
+            # known layout still fires, and so live sessions come out before archived
+            # ones. Chained rather than concatenated to keep the result lazy: a
+            # caller taking first(n) must not stat an archived file it never asked
+            # about.
+            def sessions
+              super.chain(enumerate(layer(:archived).files)).lazy
+            end
+
+            def session_id_from(path)
+              captures = FILENAME.match(File.basename(path))&.captures or return super
+
+              captures.last
+            end
+
+            # The digit groups accept 00-99 each, which Time.new does not: month 13,
+            # minute 60, and similar out-of-range values raise ArgumentError rather
+            # than being normalized. That is file DATA, not an adapter bug, so it
+            # must not cross the line build_session draws between the two (a raising
+            # hook is meant to surface as a programming error) — one such filename
+            # among many good ones would otherwise take sessions, project_paths, and
+            # sessions_for_project down to zero for every agent, not just Codex.
+            #
+            # Local, not UTC: session_meta's own "timestamp" field is UTC and agrees
+            # with this to within 1s across all 360 real files here, but a machine
+            # whose TZ changed, or a store copied from another machine, would make
+            # this off by the offset delta while Claude's birthtime-based
+            # started_at stays an absolute instant. Harmless today because Task 10
+            # sorts sessions by updated_at, not started_at.
+            # The rescue wraps Time.new alone rather than the whole method. A
+            # method-scoped rescue would also swallow an ArgumentError from a future
+            # signature change — the commonest Ruby programming error — and silently
+            # return birthtime for every Codex session: a plausible-looking wrong
+            # started_at with no signal, which is worse than a crash.
+            def started_at_for(path, stat)
+              parts = FILENAME.match(File.basename(path))&.captures or return super
+
+              begin
+                Time.new(*parts.first(6).map(&:to_i))
+              rescue ArgumentError # the digits matched but do not form a real date
+                super
+              end
+            end
+
+            # Line 1 is session_meta; the cwd lives in its payload (design doc
+            # section 6 and 8.2, verified 2026-08-05 — 360/360 real files carry a
+            # usable session_meta/payload/cwd on line 1). limit: 3 is slack against
+            # that guarantee, not a fit to any observed multi-line case: it tolerates
+            # a truncated or blank first line without paying for an unbounded scan.
+            # "3" counts iterations of File.foreach(path, "\n", MAX_LINE_BYTES), not
+            # lines: a >1MB record is chunked and each chunk is one iteration, so
+            # this is really 3MB of read headroom, not "3 records." A future adapter
+            # copying this pattern with limit: 1 would lose that tolerance entirely.
+            #
+            # The predicate requires more than scan_jsonl_for_key's key-presence
+            # check can: real sessions on this machine also carry a "payload" key on
+            # later, non-session_meta records (turn_context observed 2026-08-05)
+            # whose payload itself carries "cwd" — a presence-only scan would stop
+            # at whichever comes first, right only by coincidence. Requiring
+            # type == "session_meta" pins the read to the one documented source of
+            # truth (design doc 8.2), and requiring a Hash payload with a String cwd
+            # stops a malformed record (payload not a Hash, or cwd not a String)
+            # from permanently shadowing a later, usable session_meta or reaching
+            # project_paths' .uniq.sort with the wrong type.
+            def project_path_for(path)
+              scan_jsonl_for_key(path, "payload", limit: 3) do |record|
+                record["type"] == "session_meta" &&
+                  record["payload"].is_a?(Hash) &&
+                  record["payload"]["cwd"].is_a?(String)
+              end&.dig("payload", "cwd")
+            end
+          end
+        end
+  end
+end

data/lib/agent/sessions/adapters/copilot.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Adapters
+          # GitHub Copilot CLI. Verified against a real store on this machine
+          # (2026-08-24): ~/.copilot/session-store.db, schema_version 3, one session.
+          #
+          # This store has MOVED since tokentelemetry's parser was written against
+          # it: that reads ~/.copilot/session-state/<id>/events.jsonl, and no such
+          # file exists here. The session-state/<id>/ directory does still exist as
+          # a companion (workspace.yaml, checkpoints/, files/, research/), but the
+          # session record itself is now a row in SQLite. An adapter following the
+          # older spec would report nothing on a current install — the failure this
+          # gem's `verified_on` dates exist to make visible.
+          class Copilot < Base
+            agent :copilot
+            label "GitHub Copilot CLI"
+            documented false
+            verified_on "2026-08-24"
+            fidelity :messages
+
+            def self.reader_class = Readers::Copilot
+
+            homedir :github_copilot_cli
+
+            store :database, path: "session-store.db", format: :sqlite
+            store :session_state, dir: "session-state", format: :json, optional: true
+
+            warning "token usage is not recorded in this store: the sessions and turns tables carry " \
+                    "no token or cost columns, so `usage` is nil for every Copilot session"
+
+            # created_at/updated_at are ISO 8601 strings here, not the epoch
+            # milliseconds opencode and Cursor use — verified against a real row
+            # ("2026-05-26T04:36:01.288Z").
+            SESSION_COLUMNS = "id, cwd, created_at, updated_at"
+
+            def sessions
+              db_path = primary_layer.path
+              return [].lazy unless File.exist?(db_path)
+
+              Enumerator.new do |yielder|
+                each_session_row(db_path, "SELECT #{SESSION_COLUMNS} FROM sessions") do |row|
+                  yielder << build_row_session(db_path, row)
+                end
+              end.lazy
+            end
+
+            # cwd is a real column holding a real absolute path, so filtering is a
+            # WHERE clause rather than a read-and-compare loop.
+            def sessions_for_project(dir)
+              dir = File.expand_path(dir)
+              db_path = primary_layer.path
+              return [].lazy unless File.exist?(db_path)
+
+              Enumerator.new do |yielder|
+                each_session_row(db_path, "SELECT #{SESSION_COLUMNS} FROM sessions WHERE cwd = ?", [dir]) do |row|
+                  yielder << build_row_session(db_path, row)
+                end
+              end.lazy
+            end
+
+            def project_paths
+              db_path = primary_layer.path
+              return [] unless File.exist?(db_path)
+
+              paths = []
+              each_session_row(db_path, "SELECT DISTINCT cwd FROM sessions ORDER BY cwd") do |row|
+                paths << row.first if row.first.is_a?(String)
+              end
+              paths.uniq
+            end
+
+            private
+
+            def build_row_session(db_path, row)
+              id, cwd, created, updated = row
+              Session.new(
+                agent: self.class.agent_name, id: id, path: db_path,
+                project_path: cwd.is_a?(String) ? cwd : nil,
+                started_at: parse_time(created),
+                updated_at: parse_time(updated) || parse_time(created) || db_mtime(db_path),
+                bytes: nil, # a row in a shared database has no file size of its own
+                format: primary_layer.format, fidelity: self.class.fidelity_value
+              )
+            end
+
+            def parse_time(value)
+              return nil unless value.is_a?(String)
+
+              Time.iso8601(value)
+            rescue ArgumentError
+              nil
+            end
+
+            # updated_at is never nil across adapters; see opencode's db_mtime for
+            # the full reasoning. Reached only when both timestamps are unusable.
+            def db_mtime(db_path)
+              @db_mtime ||= begin
+                File.mtime(db_path)
+              rescue SystemCallError
+                Time.now
+              end
+            end
+
+            def each_session_row(db_path, sql, params = [], &block)
+              require_sqlite!
+              db = nil
+              begin
+                db = Sqlite.open_readonly(db_path)
+                db.execute(sql, params, &block)
+              rescue SQLite3::Exception => e
+                raise UnreadableStore, "#{db_path}: #{e.message}"
+              ensure
+                db&.close
+              end
+            end
+
+            def require_sqlite!
+              require "sqlite3"
+            rescue LoadError
+              raise MissingDependency,
+                    "Copilot CLI sessions live in session-store.db (SQLite); add the sqlite3 gem to enumerate them"
+            end
+          end
+        end
+  end
+end

data/lib/agent/sessions/adapters/cursor.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Adapters
+          class Cursor < Base
+            agent :cursor
+            label "Cursor CLI"
+            documented false
+            verified_on "2026-07-21"
+            fidelity :metadata
+
+            # No env override. XDG_CONFIG_HOME was assumed here and disproved on
+            # 2026-08-04: with it set, Cursor still stored under ~/.cursor, so honouring
+            # it reported an installed agent as missing. Verified on macOS only.
+            homedir :cursor
+
+            store :chats, dir: "chats", glob: "*/*/store.db", format: :sqlite
+            store :acp_sessions, dir: "acp-sessions", format: :json, optional: true
+
+            warning "chat payloads use an undocumented blob encoding; " \
+                    "reads are metadata-only until it is decoded"
+            warning "no environment override is known for Cursor; XDG_CONFIG_HOME is not honoured"
+
+            # meta.json's field names (createdAtMs, updatedAtMs, cwd) are read from
+            # design doc 8.3, itself written from a machine that had them to check
+            # against — this machine has no ~/.cursor/chats (Cursor CLI is a
+            # separate product from the Cursor editor and is simply not installed
+            # here). Gated, the same shape as pi's identical warning about its own
+            # unverified header key and cursor_ide's about its real session
+            # location below: a "here is what breaks, please act on it" report
+            # reaches only someone whose declared store actually exists.
+            #
+            # Why THIS unverified assumption specifically needs a warning, where
+            # some others might get away without one: the failure is silent and
+            # looks correct. If createdAtMs/updatedAtMs are the wrong keys,
+            # meta_time returns nil and started_at_for/updated_at_for fall back to
+            # stat.birthtime/mtime — real file timestamps, not an obviously broken
+            # value. If cwd is the wrong key, project_path_for returns nil exactly
+            # the way it correctly does for a chat that genuinely has no recorded
+            # cwd. Nothing in the output distinguishes "Cursor recorded no
+            # project" from "the gem read the wrong key" — `projects`,
+            # `du --by project`, and `sessions_for_project` all silently
+            # under-report Cursor, with no error and no implausible-looking number
+            # anywhere to notice.
+            def warnings
+              list = super
+              if primary_layer.exists?
+                list << "Cursor's meta.json field names (createdAtMs, updatedAtMs, cwd) are unverified " \
+                        "against a real chat — this machine has none to check them against. If `projects` " \
+                        "or `du --by project` report nothing for Cursor despite it having chats, or every " \
+                        "session's started_at matches its file's own mtime exactly, those keys may be " \
+                        "wrong; please open an issue with the first bytes of one real meta.json"
+              end
+              list
+            end
+
+            # chats/<chat-id>/<uuid>/store.db — two nested ids (design doc 16 Q5), so
+            # the session id keeps both. The blob store is never opened here; the
+            # sibling meta.json is the metadata source (8.3), with stat as fallback.
+            #
+            # Pure string manipulation on `path` — File.basename/File.dirname never
+            # raise for any String input, so this hook cannot violate rule 3
+            # (build_session lets a raising hook propagate) regardless of shape. A
+            # path shallower than two segments is not reachable through this
+            # store's OWN enumeration: the glob above is "*/*/store.db", and Dir.glob's
+            # "*" never crosses a "/", so every path this adapter actually enumerates
+            # is exactly two directories deep, by construction, not by convention
+            # (see test_session_id_from_does_not_raise_for_a_shallow_path, which
+            # calls this hook directly to pin the behaviour for a caller that
+            # bypasses the glob).
+            def session_id_from(path)
+              uuid = File.basename(File.dirname(path))
+              chat = File.basename(File.dirname(File.dirname(path)))
+              "#{chat}/#{uuid}"
+            end
+
+            def started_at_for(path, stat)
+              meta_time(path, "createdAtMs") || super
+            end
+
+            def updated_at_for(path, stat)
+              meta_time(path, "updatedAtMs") || super
+            end
+
+            # cwd's presence in meta.json is not enough on its own (rule 1): the key
+            # can hold a Hash, an Integer, anything JSON allows, and project_paths'
+            # .uniq.sort raises on a non-String member. is_a?(String) is the guard,
+            # not merely a style preference.
+            def project_path_for(path)
+              cwd = meta_for(path)["cwd"]
+              cwd if cwd.is_a?(String)
+            end
+
+            private
+
+            # Normalizes the container's TYPE, not just checked its presence (rule
+            # 2): read_json already rescues a parse failure to {}, but a
+            # meta.json that parses fine into something other than an object —
+            # an array, a bare number, null — would otherwise reach ["cwd"] or
+            # ["createdAtMs"] as a non-Hash receiver. Array#[] and Integer#[] both
+            # raise TypeError for a String key; this is Amp's project_path_for bug
+            # (design doc / task rules), one layer further down the same JSON tree.
+            # Guarding once here, rather than at each of the three call sites
+            # above, is what keeps meta_time and project_path_for simple `[]` reads
+            # instead of three repeated type checks.
+            #
+            # Unbounded and per-instance, deliberately not fixed here — but the
+            # retention mechanism is NOT "adapter instances get dropped after
+            # resolution" (an earlier version of this comment claimed that, and it
+            # is wrong): build_session passes `{ project_path_for(path) }` as
+            # Session's resolver block, and that block's `self` is THIS ADAPTER,
+            # because project_path_for is called with no explicit receiver.
+            # session.rb's UNRESOLVED handling only releases the closure
+            # (`@project_path_resolver = nil`) on a Session's FIRST #project_path
+            # call, not before — so any Session a caller keeps without ever reading
+            # project_path stays holding a live reference to the whole adapter,
+            # @meta included. `list` is exactly that caller: it never touches
+            # project_path, so every Session it returns keeps this adapter (and
+            # whatever of @meta got populated enumerating them) alive for as long
+            # as the caller holds that Session array — not just for one
+            # enumeration pass. All N sessions from one `sessions` call share the
+            # SAME adapter instance, so this is one retained @meta hash, not N
+            # copies of it.
+            #
+            # What actually keeps this acceptable is SIZE, not lifetime: measured
+            # during code review at roughly 890 bytes per parsed meta.json, ~3.5 MB
+            # retained for a 4,000-chat `list` (not independently re-measured
+            # here) — small enough to leave unbounded even though it outlives the
+            # call that built it. Growth is still bounded by
+            # CONSUMPTION the way `sessions`' laziness promises elsewhere
+            # (`.first(n)` costs n entries; an early sessions_for_project match
+            # costs less than a full sweep) — only the LIFETIME claim above was
+            # wrong, not the size-is-bounded-by-consumption one. Revisit if
+            # meta.json stops being tiny (design doc 8.3, plan follow-up 8's
+            # contrast with Amp's unbounded read_json) or a caller holds a large
+            # unresolved Session array for a long time; 3.5 MB briefly retained is
+            # not worth engineering around today.
+            def meta_for(path)
+              @meta ||= {}
+              @meta[path] ||= begin
+                data = read_json(File.join(File.dirname(path), "meta.json"))
+                data.is_a?(Hash) ? data : {}
+              end
+            end
+
+            # millis.is_a?(Numeric) alone is not enough: JSON has no Infinity/NaN
+            # literal, but a finite-looking literal can still overflow to one.
+            # createdAtMs: 1e400 parses to Float::INFINITY (verified — JSON.parse
+            # accepts exponents past Float::MAX and Ruby overflows silently rather
+            # than raising at parse time), and a plain integer literal hundreds of
+            # digits long survives is_a?(Numeric) as an exact Integer but still
+            # overflows to Infinity the moment `/ 1000.0` forces it through Float
+            # (also verified). Either way Time.at(Float::INFINITY) raises
+            # FloatDomainError, uncaught, which is rule 3's failure mode — one
+            # adapter's bad timestamp taking down every agent's listing. The guard
+            # therefore checks the DIVISION's result, not just the input: a merely
+            # huge-but-finite value (an absurd but real millisecond count) is left
+            # alone and produces an absurd-but-real Time, same as a negative one
+            # produces a pre-1970 Time — neither raises, so neither is special-cased.
+            # A value that survives both guards but is still enormous (createdAtMs:
+            # 10**300, say) renders as a Time whose #to_s is hundreds of characters
+            # long — confirmed nothing here raises for it, so it is purely a
+            # rendering consequence for `list`'s column widths (Task 10) to bound,
+            # not a robustness gap this adapter needs to close.
+            def meta_time(path, key)
+              millis = meta_for(path)[key]
+              return nil unless millis.is_a?(Numeric)
+
+              seconds = millis / 1000.0
+              Time.at(seconds) if seconds.finite?
+            end
+          end
+        end
+  end
+end