agent_sessions 0.3.0

data/lib/agent/sessions/missing_dependency.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+          class MissingDependency < Error; end
+  end
+end

data/lib/agent/sessions/node.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+          # One message in a branching conversation, with the messages that follow it.
+          # Agents that let a turn be edited and re-run record two children under one
+          # parent: 380 such branch points sit across 85 of 151 real Claude transcripts,
+          # so a caller reading `messages` in file order is reading two alternative
+          # histories interleaved without being told.
+          #
+          # children is a plain Array and the Node is frozen, so the shape is settled
+          # before anyone sees it.
+          Node = Data.define(:message, :children)
+  end
+end

data/lib/agent/sessions/part.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+          # One piece of a message. `type` is the normalized vocabulary (design doc §5);
+          # everything an agent said that this gem could not classify arrives as
+          # :unknown rather than as an exception, and the message's `raw` still holds it.
+          #
+          # text carries the readable content for :text, :thinking and :tool_result.
+          # name and call_id are tool plumbing, nil elsewhere. An :image part has
+          # neither — its URL or payload stays in raw, because normalizing an image
+          # would mean deciding whether to load it, and reading is stat-cheap by design.
+          Part = Data.define(:type, :text, :name, :call_id) do
+            self::TYPES = %i[text thinking tool_use tool_result image unknown].freeze
+
+            def initialize(type:, text: nil, name: nil, call_id: nil)
+              types = self.class::TYPES
+              raise ArgumentError, "part type #{type.inspect} must be one of #{types.join(", ")}" unless types.include?(type)
+
+              super
+            end
+          end
+  end
+end

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

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Readers
+          # Amp threads. Written against the one real thread available (2026-08-14):
+          # 24 messages, content parts tool_use 14, tool_result 14, text 2, thinking 1.
+          # One thread is thin evidence beside Codex's 415 files, and this reader says
+          # so through partial? rather than pretending otherwise.
+          #
+          # Two things make Amp unlike the JSONL readers:
+          #
+          # A thread is ONE JSON document, so it cannot be streamed a record at a
+          # time. Reading any of it means holding all of it, which is the gem's one
+          # unbounded read (0.2 follow-up 8). each_record below is where that bound
+          # finally lives.
+          #
+          # And its tool results are spelled its own way — toolUseID rather than
+          # tool_use_id, the payload under run.result rather than content. A mapper
+          # copied from Claude's would produce empty tool results and no warning,
+          # which is why each reader maps its own agent rather than sharing one.
+          class Amp < Base
+            # 150x the observed thread. A cap has to exist because nothing about a
+            # thread file announces its size before it is opened, and JSON.parse of a
+            # 200 MB document costs several times that in live objects. Refused and
+            # reported beats NoMemoryError, and beats silence either way.
+            MAX_DOCUMENT_BYTES = 32_000_000
+
+            CONTENT_PARTS = { "text" => :text, "thinking" => :thinking,
+                              "tool_use" => :tool_use, "tool_result" => :tool_result,
+                              "image" => :image }.freeze
+
+            ROLES = { "user" => :user, "assistant" => :assistant,
+                      "system" => :system, "tool" => :tool }.freeze
+
+            # The server holds the canonical copy; a local thread may be a mirror of
+            # part of the conversation. The adapter carries the same warning.
+            def partial? = true
+
+            private
+
+            # Overrides the line-oriented reader wholesale: there are no lines here.
+            # Yields each message of the document with its index, so everything above
+            # this method works unchanged.
+            def each_record
+              size = File.size(session.path)
+              if size > MAX_DOCUMENT_BYTES
+                return warn_about("thread document is too large to read " \
+                                  "(#{size} bytes, over #{MAX_DOCUMENT_BYTES}); skipped")
+              end
+
+              document = JSON.parse(File.read(session.path))
+              messages = document.is_a?(Hash) ? document["messages"] : nil
+              return warn_about("thread document has no messages array; nothing to read") unless messages.is_a?(Array)
+
+              messages.each_with_index { |record, index| yield record, index + 1 if record.is_a?(Hash) }
+            rescue JSON::ParserError, EncodingError
+              warn_about("thread document is not valid JSON; nothing to read")
+            rescue SystemCallError => e
+              warn_about("#{session.path} could not be read (#{e.class.name.split("::").last})")
+            end
+
+            def message_for(record, index)
+              parts = Array(record["content"]).map { |item| part_for(item, index) }
+              Message.new(role: role_for(record["role"], index), at: sent_at(record),
+                          parts: parts, raw: record)
+            end
+
+            def part_for(item, index)
+              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["toolUseID"], text: tool_result_text(item))
+              else
+                warn_about("message #{index}: unrecognized content part #{item["type"].inspect}")
+                Part.new(type: :unknown, text: item["text"])
+              end
+            end
+
+            # A tool call that failed carries run.error and no run.result — 2 of the
+            # 14 tool results in the one real thread. Reading only run.result rendered
+            # those as empty text, which reads as "the tool returned nothing" rather
+            # than "the tool failed, and here is why". The status stays in raw.
+            def tool_result_text(item)
+              run = item["run"]
+              return "" unless run.is_a?(Hash)
+              return stringify(run["result"]) if run.key?("result")
+
+              error = run["error"]
+              return "" unless error
+              return error["message"] if error.is_a?(Hash) && error["message"].is_a?(String)
+
+              stringify(error)
+            end
+
+            def role_for(role, index)
+              ROLES.fetch(role) do
+                warn_about("message #{index}: unrecognized role #{role.inspect}")
+                :unknown
+              end
+            end
+
+            # Epoch milliseconds, not seconds and not a string. nil where the thread
+            # records no time, rather than a guess derived from the file.
+            #
+            # Split into whole seconds and a millisecond remainder rather than divided
+            # by 1000.0: a Float cannot hold .503 exactly, so the divided form built a
+            # Time whose subsecond was 2109735/4194304 and compared unequal to the
+            # instant it was meant to be.
+            def sent_at(record)
+              millis = record.dig("meta", "sentAt")
+              return nil unless millis.is_a?(Integer)
+
+              Time.at(millis / 1000, millis % 1000, :millisecond).utc
+            end
+
+            def stringify(value)
+              value.is_a?(String) || value.nil? ? value.to_s : JSON.generate(value)
+            end
+          end
+        end
+  end
+end

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

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Readers
+          # Layer 3: turning one session file into messages. Subclasses supply the
+          # mapping; everything about *how the file is read* lives here, because the
+          # three rules that make this layer survivable (design doc §5) are properties
+          # of the reading, not of any one agent's format:
+          #
+          #   1. raw is never dropped.
+          #   2. Unknown records become :unknown parts and warnings, never exceptions.
+          #   3. Reading streams. No code path may assume a file fits in memory.
+          #
+          # Rule 3 is why this does not use File.foreach without a chunk size. A
+          # truncated log can hold no newline at all, and "read one line" would then
+          # mean "read 2.6 GB into a String" — the file the article that started this
+          # gem found on a real machine.
+          class Base
+            # Chunk size, and so the largest record that can be read whole. Measured
+            # against 415 real Codex rollout files (128,987 records, 2026-08-12): 14
+            # records exceed 1 MB and the largest is 2.41 MB, so Layer 2's
+            # MAX_LINE_BYTES of 1 MB would silently drop real messages. 8 MB is ~3.3x
+            # the observed maximum. A record beyond it is reported, never dropped in
+            # silence, because a missing message is this gem's worst failure mode.
+            MAX_RECORD_BYTES = 8_000_000
+
+            attr_reader :session
+
+            def initialize(session, include_events: false)
+              @session = session
+              @include_events = include_events
+              @warnings = []
+            end
+
+            def fidelity = session.fidelity
+
+            # True where the local file is not the whole story — Amp, whose server
+            # holds the canonical copy. Overridden there, false everywhere else.
+            def partial? = false
+
+            # Populated as records are read, so this answers for whatever has been
+            # consumed so far. uniq because a second pass over the same file would
+            # otherwise repeat every warning it already reported.
+            def warnings = @warnings.uniq
+
+            # Streams. Yields each message as it is parsed; a caller that breaks after
+            # one has read one record, not the file.
+            def each_message
+              return enum_for(:each_message) unless block_given?
+
+              each_record do |record, line_number|
+                message = message_for(record, line_number)
+                yield message if message
+              end
+            end
+
+            # Eager, for sessions small enough to hold. The design doc offers both and
+            # names this the convenience: `messages` is what a script wants, and
+            # `each_message` is what a 2.6 GB file requires.
+            def messages = each_message.to_a
+
+            # Whether this agent records which turn each turn followed. False here:
+            # most stores are an append-only list and a tree would have to be invented.
+            def branching? = false
+
+            # The conversation as roots and their continuations, for an agent that
+            # records parent links. Unlike every other method here this cannot stream
+            # — a tree is not knowable until the last record is read — so it holds one
+            # session's messages at once and says so rather than pretending otherwise.
+            #
+            # Raises rather than returning an empty list or nil for a store with no
+            # parent links, for the reason Agent::Sessions.read raises: "this format
+            # does not record that" must never read as "this session has none".
+            def tree
+              unless branching?
+                raise UnsupportedFormat,
+                      "#{session.agent} does not record parent links; its messages are a flat list"
+              end
+
+              build_tree
+            end
+
+            # This session's token totals as a Usage, or nil where the format does
+            # not record them (Amp) or this reader has not learned where they live.
+            # nil, not an empty Usage: "this store does not say" must never read as
+            # "this session cost nothing" — the same rule tree() enforces by raising.
+            #
+            # Each reader that overrides this also decides its own summation rule,
+            # because that rule is format knowledge: Claude repeats one API
+            # response's usage across several records (94 of 124 message ids in one
+            # real transcript), Codex writes a running total where only the last
+            # record counts. A base-class sum would get both wrong.
+            def usage = nil
+
+            # Boundaries where the agent replaced earlier turns with a summary. Its
+            # own pass: a caller asking only for compactions should not have to
+            # materialize every message to get them.
+            def compactions
+              found = []
+              each_record { |record, _line| (boundary = compaction_for(record)) && found << boundary }
+              found
+            end
+
+            private
+
+            attr_reader :include_events
+
+            # nil means "this record is not a message" — a header, a turn context, a
+            # compaction boundary. Subclasses override.
+            def message_for(_record, _line_number) = nil
+
+            # This record's own id and the id of the record it followed. nil from
+            # either means the record takes no part in the tree. A branching reader
+            # overrides both; the tree algorithm itself stays here, so an agent only
+            # has to say where its links live, never how to assemble them.
+            def node_id_for(_record) = nil
+            def parent_id_for(_record) = nil
+
+            # Two passes over one session. The first records every uuid-bearing
+            # record's parent and which of them became messages; the second links
+            # each message to the nearest ANCESTOR that is also a message.
+            #
+            # That second part is the whole difficulty. Records that are not turns sit
+            # in the same parent chain — 5,006 of 25,633 in the real Claude corpus are
+            # attachments and system records — so a message's recorded parent is
+            # frequently not a message. Walking up until one is found keeps the tree
+            # holding exactly the messages `messages` reports, no more and no fewer,
+            # and makes include_events change what is in the tree without changing
+            # whether it is well formed.
+            def build_tree
+              order = []
+              parents = {}
+              messages = {}
+
+              each_record do |record, line_number|
+                id = node_id_for(record)
+                next unless id
+
+                order << id
+                parents[id] = parent_id_for(record)
+                message = message_for(record, line_number)
+                messages[id] = message if message
+              end
+
+              link_tree(order, parents, messages)
+            end
+
+            def link_tree(order, parents, messages)
+              children = Hash.new { |hash, key| hash[key] = [] }
+              roots = []
+
+              order.each do |id|
+                next unless messages.key?(id)
+
+                ancestor = nearest_message_ancestor(parents, messages, id)
+                ancestor ? children[ancestor] << id : roots << id
+              end
+
+              # Built in reverse file order so a parent is always assembled after the
+              # children it needs, without recursion — a linear session of several
+              # thousand turns would otherwise be several thousand stack frames deep.
+              built = {}
+              order.reverse_each do |id|
+                next unless messages.key?(id)
+
+                built[id] = Node.new(message: messages[id], children: children[id].map { |child| built[child] }.compact)
+              end
+
+              roots.map { |id| built[id] }.compact
+            end
+
+            # Walks up the recorded chain until it reaches a record that became a
+            # message, or runs out. A cycle would spin here, so ids already visited
+            # end the walk: nothing in the real corpus contains one, and a malformed
+            # file must not hang a reader.
+            def nearest_message_ancestor(parents, messages, id)
+              seen = { id => true }
+              current = parents[id]
+              while current && !messages.key?(current)
+                break if seen[current]
+
+                seen[current] = true
+                current = parents[current]
+              end
+              current && messages.key?(current) ? current : nil
+            end
+
+            # nil means "not a compaction". Subclasses that have them override.
+            def compaction_for(_record) = nil
+
+            def warn_about(message)
+              @warnings << message
+              nil
+            end
+
+            # Yields one parsed record per complete line, with its 1-based line
+            # number. Three things can go wrong and none of them may raise:
+            #
+            #   the file is unreadable      -> one warning, no records
+            #   a line is not JSON          -> one warning naming the line, skipped
+            #   a record exceeds the cap    -> one warning naming the line, skipped
+            #
+            # The oversized case is detected structurally rather than by measuring:
+            # File.foreach with a chunk size hands back a chunk that does NOT end in a
+            # newline when the record is longer than the cap, and the following chunks
+            # are its continuation. A chunk shorter than the cap without a newline is
+            # simply the last line of a file that does not end in one.
+            # The file this reader streams. session.path for every agent that keeps
+            # its conversation in the file Layer 2 enumerated — which is all of them
+            # but Grok, whose session is a DIRECTORY: Layer 2 points at its
+            # summary.json while the turns are in chat_history.jsonl beside it.
+            # A hook here rather than an each_record override there, because the
+            # rest of the streaming (the chunk cap, the oversized report, the
+            # per-line warnings) is exactly what such a reader still wants.
+            def record_path = session.path
+
+            def each_record
+              line_number = 0
+              oversized_at = nil
+
+              File.foreach(record_path, "\n", MAX_RECORD_BYTES) do |chunk|
+                complete = chunk.end_with?("\n") || chunk.bytesize < MAX_RECORD_BYTES
+
+                unless complete
+                  oversized_at ||= line_number + 1
+                  next
+                end
+
+                if oversized_at
+                  warn_about("record at line #{oversized_at} is too large to read " \
+                             "(over #{MAX_RECORD_BYTES} bytes); skipped")
+                  oversized_at = nil
+                  line_number += 1
+                  next
+                end
+
+                line_number += 1
+                record = parse(chunk, line_number)
+                yield record, line_number if record
+              end
+
+              warn_about("record at line #{oversized_at} is too large to read " \
+                         "(over #{MAX_RECORD_BYTES} bytes); skipped") if oversized_at
+            rescue SystemCallError => e
+              warn_about("#{record_path} could not be read (#{e.class.name.split("::").last})")
+            end
+
+            def parse(chunk, line_number)
+              record = JSON.parse(chunk)
+              return record if record.is_a?(Hash)
+
+              warn_about("line #{line_number} is not a JSON object; skipped")
+            rescue JSON::ParserError, EncodingError
+              warn_about("line #{line_number} is not valid JSON; skipped")
+            end
+
+            # A token count is a whole number or absent. The type check is rule 2's
+            # container check applied to numbers: a format that writes "1234" as a
+            # String, or null, or a float where a count belongs, yields nil here
+            # rather than a value that would poison a sum three callers later.
+            def count_from(value) = value.is_a?(Integer) ? value : nil
+
+            # Cost arrives as a Float (or an Integer zero) where an agent reports
+            # it at all. Same guard, wider type: a cost is money, not a count, and
+            # 0 is a real answer — a subscription session genuinely costs $0
+            # marginal — so only a non-number is absent.
+            def cost_from(value) = value.is_a?(Numeric) ? value : nil
+
+            # Agents write ISO 8601 with a Z suffix. nil beats a wrong guess: a
+            # timestamp that cannot be parsed is missing, not epoch zero.
+            def time_from(value)
+              return nil unless value.is_a?(String)
+
+              Time.iso8601(value)
+            rescue ArgumentError
+              nil
+            end
+          end
+        end
+  end
+end