agent_sessions 0.3.0

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

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Readers
+          # Claude Code transcripts. Written against 142 real transcripts, 29,688
+          # records, inventoried 2026-08-12.
+          #
+          # The content vocabulary is a straight match for this gem's: text, thinking,
+          # tool_use, tool_result and image are exactly the five part types the design
+          # doc names, so nothing here has to invent a mapping. What Claude adds is
+          # everything *around* the conversation — a third of all records are session
+          # state, and two more kinds carry context the model saw without being a turn
+          # anyone took.
+          class Claude < Base
+            # State, not conversation, and together 11,000+ of the records written.
+            # Skipped in silence: warning about a record deliberately classified would
+            # teach a caller that warnings are noise.
+            #
+            # atis-latch and bridge-session postdate the corpus above — found by
+            # running this reader over a live 2026-08-24 transcript and reading its
+            # own warnings (23 and 17 records), the same way Codex's tool list grew.
+            # Both are session plumbing: a latch marker, and the record tying a
+            # local transcript to its cloud session id (bridgeSessionId, owner
+            # uuids). Neither is a turn anyone took.
+            NON_MESSAGE_TYPES = %w[ai-title mode permission-mode agent-name last-prompt
+                                   file-history-snapshot file-history-delta queue-operation
+                                   pr-link summary atis-latch bridge-session].freeze
+
+            # Context the model saw, but not a turn: `system` is turn_duration,
+            # stop_hook_summary, away_summary, local_command; `attachment` is hook
+            # output, skill listings, task reminders, pasted files. Same judgement
+            # Codex's event_msg gets — available on request, never on by default.
+            EVENT_TYPES = %w[system attachment].freeze
+
+            CONTENT_PARTS = { "text" => :text, "thinking" => :thinking, "tool_use" => :tool_use,
+                              "tool_result" => :tool_result, "image" => :image }.freeze
+
+            # How Claude Code points at output too large to inline. It is prose, not a
+            # structured field — 24 real tool_result parts and 149 attachments carry
+            # this sentence — so the path has to be matched out of the text.
+            SPILL = /Full output saved to:\s*(\S+)/
+
+            # A spilled file is read whole. The largest observed is well under this;
+            # the cap exists because the pointer says nothing about the size.
+            MAX_SPILL_BYTES = 4_000_000
+
+            # Every uuid-bearing record names the record it followed, and 380 branch
+            # points sit across 85 of 151 real transcripts — a turn edited and re-run
+            # leaves two children under one parent. Exactly one root per file and no
+            # orphaned parent link was found in that corpus, so the links are
+            # trustworthy enough to build a tree from.
+            def branching? = true
+
+            def initialize(session, resolve_spills: true, **rest)
+              super(session, **rest)
+              @resolve_spills = resolve_spills
+            end
+
+            # The transcripts of agents this session spawned, as readers of their own.
+            # Exposed rather than inlined, per design doc 8.1: a subagent's turns are
+            # not the parent's turns, and merging them would break every count taken
+            # from this reader. 124 of these sit beside real sessions on this machine.
+            #
+            # isSidechain is false on all 22,072 records in the main transcripts, so
+            # there is nothing to filter out there — the separation is already how
+            # Claude Code writes them.
+            def subagents
+              entries = begin
+                Dir.children(File.join(sidecar_root, "subagents"))
+              rescue SystemCallError
+                return []
+              end
+
+              entries.sort.filter_map do |name|
+                next unless File.extname(name) == ".jsonl"
+
+                child = child_session(File.join(sidecar_root, "subagents", name))
+                child && self.class.new(child, resolve_spills: @resolve_spills, include_events: include_events)
+              end
+            end
+
+            # Session totals, summed over assistant records but deduplicated by
+            # message.id first — and the dedup is most of the number. One API
+            # response streams into one record PER CONTENT BLOCK, each carrying the
+            # same message.id and the same usage: in one real transcript on this
+            # machine (2026-08-24), 260 assistant records share 124 message ids, 94
+            # of which repeat with byte-identical usage. A naive sum reports roughly
+            # double what Anthropic billed. An id-less record (not observed, but
+            # rule 2 says formats drift) is counted rather than dropped: overcounting
+            # a novelty beats silently ignoring it.
+            def usage
+              seen = {}
+              total = nil
+              each_record do |record, _line_number|
+                usage = usage_from(record)
+                next unless usage
+
+                id = record.dig("message", "id")
+                next if id && seen[id]
+
+                seen[id] = true if id
+                total = total ? total + usage : usage
+              end
+              total
+            end
+
+            private
+
+            attr_reader :resolve_spills
+
+            def node_id_for(record) = record["uuid"]
+            def parent_id_for(record) = record["parentUuid"]
+
+            def message_for(record, line_number)
+              type = record["type"]
+              return nil if NON_MESSAGE_TYPES.include?(type)
+              return event_message(record, type) if EVENT_TYPES.include?(type)
+
+              unless %w[user assistant].include?(type)
+                warn_about("line #{line_number}: unrecognized record type #{type.inspect}")
+                return build(record, :unknown, [Part.new(type: :unknown)])
+              end
+
+              build(record, type.to_sym, content_parts(record, line_number))
+            end
+
+            # content is an Array of parts in 17,408 real messages and a bare String
+            # in 636. The String spelling is the same thing said shorter.
+            def content_parts(record, line_number)
+              content = record.dig("message", "content")
+              return [Part.new(type: :text, text: content)] if content.is_a?(String)
+
+              Array(content).map { |item| part_for(item, line_number) }
+            end
+
+            def part_for(item, line_number)
+              return Part.new(type: :unknown) unless item.is_a?(Hash)
+
+              case CONTENT_PARTS[item["type"]]
+              when :text then Part.new(type: :text, text: item["text"].to_s)
+              when :thinking then Part.new(type: :thinking, text: item["thinking"].to_s)
+              when :image then Part.new(type: :image)
+              when :tool_use
+                Part.new(type: :tool_use, name: item["name"], call_id: item["id"],
+                         text: stringify(item["input"]))
+              when :tool_result
+                Part.new(type: :tool_result, call_id: item["tool_use_id"],
+                         text: spilled(flatten_result(item["content"])))
+              else
+                warn_about("line #{line_number}: unrecognized content part #{item["type"].inspect}")
+                Part.new(type: :unknown, text: item["text"])
+              end
+            end
+
+            # A tool_result's content is a String, or an array of parts the same shape
+            # as a message's. Only its text is kept here; raw holds the rest.
+            def flatten_result(content)
+              return content if content.is_a?(String)
+
+              Array(content).filter_map { |item| item["text"] if item.is_a?(Hash) && item["type"] == "text" }.join
+            end
+
+            def event_message(record, type)
+              return nil unless include_events
+
+              label = type == "system" ? record["subtype"] : record.dig("attachment", "type")
+              build(record, :system, [Part.new(type: :unknown, text: label)])
+            end
+
+            def build(record, role, parts)
+              model = record.dig("message", "model")
+              Message.new(role: role, at: time_from(record["timestamp"]), parts: parts, raw: record,
+                          usage: usage_from(record), model: model.is_a?(String) ? model : nil)
+            end
+
+            # message.usage sits on assistant records; user and event records dig to
+            # nil and carry none. Key names verified against a real transcript on
+            # this machine (2026-08-24): input_tokens is already DISJOINT from the
+            # two cache counts (input_tokens 2 beside cache_read_input_tokens
+            # 24,332 in the sample — Anthropic semantics, no subtraction needed),
+            # and thinking tokens hide one level down in output_tokens_details.
+            # A usage hash whose every mapped key fails count_from yields nil, not
+            # an all-nil Usage: an empty answer should look absent, not present.
+            def usage_from(record)
+              usage = record.dig("message", "usage")
+              return nil unless usage.is_a?(Hash)
+
+              mapped = Usage.new(input: count_from(usage["input_tokens"]),
+                                 output: count_from(usage["output_tokens"]),
+                                 cache_read: count_from(usage["cache_read_input_tokens"]),
+                                 cache_creation: count_from(usage["cache_creation_input_tokens"]),
+                                 reasoning: count_from(usage.dig("output_tokens_details", "thinking_tokens")))
+              mapped.to_h.each_value.any? ? mapped : nil
+            end
+
+            def stringify(value)
+              value.is_a?(String) || value.nil? ? value.to_s : JSON.generate(value)
+            end
+
+            # Replaces "Output too large … Full output saved to: <path>" with what the
+            # file actually holds, so a :tool_result carries content rather than a
+            # pointer (design doc 8.1).
+            #
+            # The path is read out of tool output, which is untrusted: a transcript
+            # can say anything, including that its spill lives in /etc/passwd or in
+            # another project's directory. Resolving it blindly would turn this reader
+            # into a file-read primitive driven by content. Only the session's own
+            # sidecar directory is readable, checked before the path is opened and
+            # again through realpath so a symlink inside it cannot lead out.
+            def spilled(text)
+              return text unless resolve_spills && text.is_a?(String)
+
+              path = text[SPILL, 1]
+              return text unless path
+
+              candidate = File.expand_path(path)
+              unless readable_spill?(candidate)
+                return warn_about("spill path is outside this session's sidecar tree " \
+                                  "and was not read: #{path}") || text
+              end
+
+              read_spill(candidate) || text
+            end
+
+            # The trees a spill may legitimately live in. Own sidecar always; plus the
+            # enclosing one when this transcript is itself a subagent, because a
+            # subagent has no sidecar of its own — its oversized output spills to
+            # <parent-id>/tool-results/. Running this over 124 real subagent
+            # transcripts is what found that; a boundary drawn at the subagent's own
+            # id refused every spill they reference.
+            def spill_roots
+              @spill_roots ||= begin
+                roots = [sidecar_root]
+                roots << File.dirname(File.dirname(session.path)) if subagent_transcript?
+                roots
+              end
+            end
+
+            def subagent_transcript? = File.basename(File.dirname(session.path)) == "subagents"
+
+            def readable_spill?(candidate)
+              root = spill_roots.find { |dir| candidate.start_with?("#{dir}/") }
+              return false unless root
+
+              # Again through realpath, so a symlink planted inside the tree cannot
+              # lead out of it. A path that will not resolve is left to the read
+              # below to report, rather than being called a security problem.
+              File.realpath(candidate).start_with?("#{File.realpath(root)}/")
+            rescue SystemCallError
+              true
+            end
+
+            def read_spill(path)
+              return warn_about("spill file is larger than #{MAX_SPILL_BYTES} bytes; " \
+                                "left as a pointer: #{path}") if File.size(path) > MAX_SPILL_BYTES
+
+              File.read(path)
+            rescue SystemCallError
+              warn_about("spill file could not be read; left as a pointer: #{path}")
+            end
+
+            # The directory Claude Code names after the session id, holding
+            # subagents/ and tool-results/. Base#bytes_for already counts what is in
+            # it; this is the same convention read rather than measured.
+            def sidecar_root
+              @sidecar_root ||= session.path.delete_suffix(File.extname(session.path))
+            end
+
+            def child_session(path)
+              stat = File.stat(path)
+              Session.new(agent: session.agent, id: File.basename(path, ".jsonl"), path: path,
+                          started_at: nil, updated_at: stat.mtime, bytes: stat.size,
+                          format: session.format, fidelity: session.fidelity)
+            rescue SystemCallError
+              nil
+            end
+          end
+        end
+  end
+end

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

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Readers
+          # Codex rollout files. Every mapping here was written against a real corpus
+          # rather than from the format notes: 415 files, 128,987 records, inventoried
+          # 2026-08-12. The distribution is the reason for several decisions below —
+          # response_item 57%, event_msg 38%, turn_context 4%, session_meta 416,
+          # world_state 182, inter_agent_communication_metadata 129, compacted 18.
+          #
+          # Codex was chosen as the first reader for exactly this reason. pi was the
+          # planned reference implementation, but its store held no session files at
+          # all on the machine available, so every claim about its content would have
+          # been inference. A reference implementation has to be falsifiable.
+          class Codex < Base
+            # Known, and deliberately not messages: the session header, per-turn
+            # configuration, and two state records Codex added in July 2026. Silence
+            # here is a judgement, not an oversight — these are not conversation, and
+            # warning about them would train a caller to ignore warnings.
+            NON_MESSAGE_TYPES = %w[session_meta turn_context world_state
+                                   inter_agent_communication_metadata].freeze
+
+            # "developer" is what Codex writes where the normalized vocabulary says
+            # :system. It is 101 of 292 role-bearing records in the sample, so this is
+            # the common path, not an edge case.
+            ROLES = { "user" => :user, "assistant" => :assistant, "developer" => :system,
+                      "system" => :system, "tool" => :tool }.freeze
+
+            # encrypted_content maps to :unknown deliberately, not for want of a
+            # better bucket: 80 real content items are encrypted by the model and this
+            # gem will never read them. Recognized-and-unreadable is a different thing
+            # from unrecognized, and only the second deserves a warning — a warning
+            # that fires on a permanent, understood condition is noise on every read.
+            CONTENT_PARTS = { "input_text" => :text, "output_text" => :text, "text" => :text,
+                              "summary_text" => :text, "input_image" => :image,
+                              "output_image" => :image, "encrypted_content" => :unknown }.freeze
+
+            # Every entry past the first three in each list came from running this
+            # reader over all 415 files and reading its own warnings: a 25-file sample
+            # showed none of them. Counts in that corpus: web_search_call 288,
+            # ghost_snapshot 197, agent_message 129, tool_search_call and
+            # tool_search_output 26 each, image_generation_call 1.
+            TOOL_CALLS = %w[custom_tool_call function_call local_shell_call
+                            web_search_call tool_search_call].freeze
+            TOOL_OUTPUTS = %w[custom_tool_call_output function_call_output local_shell_call_output
+                              tool_search_output].freeze
+
+            # Internal state that happens to travel as a response_item. Skipped in
+            # silence for the same reason turn_context is: it is not conversation, and
+            # a warning a caller must learn to ignore is worse than no warning.
+            NON_MESSAGE_ITEMS = %w[ghost_snapshot].freeze
+
+            # Where a tool call keeps what it was called with. custom_tool_call uses
+            # input, function_call uses arguments, web_search_call uses action, and
+            # tool_search_call uses arguments as a Hash rather than a String.
+            CALL_INPUTS = %w[input arguments action].freeze
+
+            # And where an output keeps its result.
+            CALL_OUTPUTS = %w[output tools].freeze
+
+            # Session totals. Codex writes no usage on its messages; it writes
+            # token_count event records whose info.total_token_usage is a RUNNING
+            # TOTAL — verified against a real rollout on this machine (2026-08-24):
+            # consecutive records report total 33,751 then 69,135 while their
+            # last_token_usage differ, so the last record is the session and summing
+            # would multiply-count every earlier turn.
+            #
+            # Two normalizations, both from that same file:
+            #
+            #   input_tokens INCLUDES cached_input_tokens (33,431 including 19,200
+            #   in the sample) — the opposite of Claude's disjoint spelling — so the
+            #   cached share is subtracted to make Usage#input mean one thing across
+            #   agents. Clamped at zero: a count that went negative would mean the
+            #   two fields disagree, and a wrong zero beats a negative token count.
+            #
+            #   cache_write_input_tokens maps to cache_creation. total_tokens is
+            #   deliberately not mapped anywhere: it restates the other fields, and
+            #   any bucket it landed in would be double-counted by a caller summing
+            #   buckets.
+            def usage
+              info = nil
+              each_record do |record, _line_number|
+                next unless record["type"] == "event_msg"
+
+                candidate = record.dig("payload", "info", "total_token_usage")
+                info = candidate if record.dig("payload", "type") == "token_count" && candidate.is_a?(Hash)
+              end
+              return nil unless info
+
+              input = count_from(info["input_tokens"])
+              cached = count_from(info["cached_input_tokens"])
+              mapped = Usage.new(input: input && cached ? [input - cached, 0].max : input,
+                                 output: count_from(info["output_tokens"]),
+                                 cache_read: cached,
+                                 cache_creation: count_from(info["cache_write_input_tokens"]),
+                                 reasoning: count_from(info["reasoning_output_tokens"]))
+              # Same rule as Claude's usage_from: a token_count record whose every
+              # field failed the count check answers nil, not an all-nil Usage.
+              mapped.to_h.each_value.any? ? mapped : nil
+            end
+
+            private
+
+            def message_for(record, line_number)
+              type = record["type"]
+              return nil if NON_MESSAGE_TYPES.include?(type) || type == "compacted"
+              return event_message(record) if type == "event_msg"
+
+              payload = record["payload"]
+              unless type == "response_item" && payload.is_a?(Hash)
+                return warn_about("line #{line_number}: unrecognized record type #{type.inspect}") ||
+                       unknown_message(record)
+              end
+
+              item_message(record, payload, line_number)
+            end
+
+            def item_message(record, payload, line_number)
+              case payload["type"]
+              when "message" then text_message(record, payload, line_number)
+              # Multi-agent traffic: author and recipient instead of role, but the
+              # content array is a normal one. Conversation, so it is read as such.
+              when "agent_message" then build(record, :assistant, content_parts(payload, line_number))
+              when "reasoning" then reasoning_message(record, payload)
+              when *TOOL_CALLS then tool_call_message(record, payload)
+              when *TOOL_OUTPUTS then tool_output_message(record, payload)
+              when *NON_MESSAGE_ITEMS then nil
+              # The result is base64 and was 2.5 MB in the one real occurrence. It
+              # stays in raw: inlining it would make holding the message cost
+              # megabytes, and decoding pixels is not this layer's job.
+              when "image_generation_call" then build(record, :assistant, [Part.new(type: :image)])
+              else
+                warn_about("line #{line_number}: unrecognized response_item type #{payload["type"].inspect}")
+                unknown_message(record)
+              end
+            end
+
+            def text_message(record, payload, line_number)
+              build(record, role_for(payload["role"], line_number), content_parts(payload, line_number))
+            end
+
+            def content_parts(payload, line_number)
+              Array(payload["content"]).map do |item|
+                next Part.new(type: :unknown) unless item.is_a?(Hash)
+
+                kind = CONTENT_PARTS[item["type"]]
+                next Part.new(type: kind, text: %i[image unknown].include?(kind) ? nil : item["text"].to_s) if kind
+
+                warn_about("line #{line_number}: unrecognized content part #{item["type"].inspect}")
+                Part.new(type: :unknown, text: item["text"])
+              end
+            end
+
+            # content is null on every reasoning record observed; the readable text is
+            # in summary. encrypted_content holds the rest and this gem cannot decrypt
+            # it, so exposing a :thinking part built from summary alone is the honest
+            # maximum — claiming more would misreport fidelity.
+            def reasoning_message(record, payload)
+              parts = Array(payload["summary"]).filter_map do |item|
+                Part.new(type: :thinking, text: item["text"].to_s) if item.is_a?(Hash)
+              end
+              build(record, :assistant, parts)
+            end
+
+            # The call is the assistant's act; the output is the tool answering.
+            #
+            # Not every call carries a name: web_search_call and tool_search_call
+            # identify themselves only by record type, so the type minus its "_call"
+            # suffix is the name. That is a derivation, not a guess — it produces
+            # exactly the name the agent would use ("web_search", "tool_search").
+            def tool_call_message(record, payload)
+              name = payload["name"] || payload["type"].to_s.sub(/_call\z/, "")
+              part = Part.new(type: :tool_use, name: name, call_id: payload["call_id"],
+                              text: stringify(payload, CALL_INPUTS))
+              build(record, :assistant, [part])
+            end
+
+            def tool_output_message(record, payload)
+              part = Part.new(type: :tool_result, call_id: payload["call_id"],
+                              text: stringify(payload, CALL_OUTPUTS))
+              build(record, :tool, [part])
+            end
+
+            # A call's input is a String for some record types and a Hash for others
+            # (tool_search_call's arguments, web_search_call's action). Serializing the
+            # Hash keeps the value readable and lossless rather than rendering it as
+            # Ruby's inspect output; raw still holds the original either way.
+            def stringify(payload, keys)
+              key = keys.find { |candidate| payload.key?(candidate) }
+              value = key && payload[key]
+              value.is_a?(String) || value.nil? ? value.to_s : JSON.generate(value)
+            end
+
+            # Opt-in only: event_msg is 38% of the corpus and is UI bookkeeping (token
+            # counts, rate limits, task_started). Including it by default would inflate
+            # every message count a caller made. No warning — the caller asked.
+            def event_message(record)
+              return nil unless include_events
+
+              build(record, :system, [Part.new(type: :unknown, text: record.dig("payload", "type"))])
+            end
+
+            def unknown_message(record)
+              build(record, :unknown, [Part.new(type: :unknown)])
+            end
+
+            def build(record, role, parts)
+              Message.new(role: role, at: time_from(record["timestamp"]), parts: parts, raw: record)
+            end
+
+            def role_for(role, line_number)
+              ROLES.fetch(role) do
+                warn_about("line #{line_number}: unrecognized role #{role.inspect}")
+                :unknown
+              end
+            end
+
+            # replacement_history is a restatement of turns already yielded, so it is
+            # counted, never replayed. A reader that expanded it would report the same
+            # conversation twice — the miscount the design doc warns about, arriving
+            # through the reader instead of through a naive line count.
+            def compaction_for(record)
+              return nil unless record["type"] == "compacted"
+
+              history = record.dig("payload", "replacement_history")
+              Compaction.new(at: time_from(record["timestamp"]),
+                             replaced_count: history.is_a?(Array) ? history.size : 0,
+                             raw: record)
+            end
+          end
+        end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Readers
+          # GitHub Copilot CLI turns, from the SQLite store the adapter enumerates.
+          #
+          # The SCHEMA is verified (schema_version 3 on this machine, 2026-08-24):
+          # turns holds id, session_id, turn_index, user_message, assistant_response,
+          # timestamp. The CONTENT is not — the one real session here has zero turn
+          # rows, so no turn has ever been read. The column names are unambiguous
+          # enough to map without guessing at structure, which is why this reader
+          # exists at all rather than waiting; what it cannot promise is that a real
+          # turn holds plain text in those columns rather than, say, JSON.
+          #
+          # fidelity is :messages, not :full — one row is a whole exchange, so the
+          # tool calls and reasoning that happened inside it are not recoverable
+          # from this table. What a caller gets is what was said, not how.
+          class Copilot < Base
+            # One row is a user turn AND the assistant's reply, so each row yields
+            # two messages. They share a raw record: rule 1 keeps the row intact,
+            # and splitting it into two half-rows would misreport what was stored.
+            def each_message
+              return enum_for(:each_message) unless block_given?
+
+              each_record do |record, _index|
+                user = record["user_message"]
+                yield build(record, :user, user) if usable?(user)
+                reply = record["assistant_response"]
+                yield build(record, :assistant, reply) if usable?(reply)
+              end
+            end
+
+            # No token or cost column exists anywhere in this schema — not on
+            # sessions, not on turns. nil is the format speaking, and must not be
+            # mistaken for a session that cost nothing.
+            def usage = nil
+
+            private
+
+            def usable?(value) = value.is_a?(String) && !value.empty?
+
+            def build(record, role, text)
+              Message.new(role: role, at: time_from(record["timestamp"]), parts: [Part.new(type: :text, text: text)],
+                          raw: record, usage: nil, model: nil)
+            end
+
+            # Rows ordered by turn_index, the column that exists precisely to say
+            # what order they happened in; id is the tiebreak so a store with
+            # repeated indices still reads deterministically.
+            def each_record
+              require_sqlite!
+              db = nil
+              index = 0
+              begin
+                db = Sqlite.open_readonly(session.path)
+                db.execute("SELECT user_message, assistant_response, timestamp, turn_index " \
+                           "FROM turns WHERE session_id = ? ORDER BY turn_index, id", [session.id]) do |row|
+                  index += 1
+                  user, reply, timestamp, turn_index = row
+                  yield({ "user_message" => user, "assistant_response" => reply,
+                          "timestamp" => timestamp, "turn_index" => turn_index }, index)
+                end
+              rescue SQLite3::Exception => e
+                warn_about("#{session.path} could not be read (#{e.class.name.split("::").last})")
+              ensure
+                db&.close
+              end
+            end
+
+            def require_sqlite!
+              require "sqlite3"
+            rescue LoadError
+              raise MissingDependency,
+                    "Copilot CLI turns live in session-store.db (SQLite); add the sqlite3 gem to read them"
+            end
+          end
+        end
+  end
+end