agent_sessions 0.3.0

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

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Readers
+          # Gemini CLI chat files. Written against a real store on this machine
+          # (2026-08-24): 12 sessions, 121 records — user 20, gemini 97, info 4.
+          #
+          # A chat is one JSON document, not JSONL, so it is read whole under a cap
+          # the way Amp's thread is. The cap is the reason this does not simply
+          # JSON.parse the file: the largest real chat here is 103 KB, but nothing
+          # in the format bounds it, and an unbounded read is the failure the base
+          # reader's chunked streaming exists to prevent.
+          class Gemini < Base
+            # Amp's bound, for the same reason: a whole document must fit in memory
+            # to be parsed at all, so the only protection available is refusing to
+            # read one that is absurdly large.
+            MAX_DOCUMENT_BYTES = 32_000_000
+
+            # "gemini" is the assistant. "info" is the CLI talking to the user
+            # ("Update successful! The new version will be used on your next run."),
+            # which is neither turn — context the operator saw, the same judgement
+            # Claude's system records get, so it arrives with include_events.
+            ROLES = { "user" => :user, "gemini" => :assistant }.freeze
+
+            # The document's own header, exposed because Layer 2's session id is the
+            # filename (the trailing hex in it is shared between sessions) while the
+            # agent's own sessionId lives in here.
+            def header
+              document.reject { |key, _| key == "messages" }
+            end
+
+            # Session totals, summed per message — the counts are per API call, not
+            # a running total (verified: the real series falls as well as rises,
+            # 64138 then 8069 then 8265, which no cumulative counter does).
+            def usage
+              total = nil
+              each_record do |record, _index|
+                usage = usage_from(record)
+                next unless usage
+
+                total = total ? total + usage : usage
+              end
+              total
+            end
+
+            private
+
+            # Overridden wholesale, like Amp's: the unit here is an element of the
+            # document's messages array, not a line of the file.
+            def each_record
+              Array(document["messages"]).each_with_index do |record, index|
+                next unless record.is_a?(Hash)
+
+                yield record, index + 1
+              end
+            end
+
+            def document
+              @document ||= begin
+                size = File.size(session.path)
+                if size > MAX_DOCUMENT_BYTES
+                  warn_about("#{session.path} is larger than #{MAX_DOCUMENT_BYTES} bytes; not read")
+                  {}
+                else
+                  parsed = JSON.parse(File.read(session.path))
+                  parsed.is_a?(Hash) ? parsed : warn_about("#{session.path} is not a JSON object") || {}
+                end
+              rescue SystemCallError
+                warn_about("#{session.path} could not be read") || {}
+              rescue JSON::ParserError
+                warn_about("#{session.path} does not hold valid JSON") || {}
+              end
+            end
+
+            def message_for(record, index)
+              type = record["type"]
+              return event_message(record) if type == "info"
+
+              role = ROLES[type]
+              unless role
+                warn_about("message #{index}: unrecognized type #{type.inspect}")
+                return build(record, :unknown, [Part.new(type: :unknown, text: record["content"])])
+              end
+
+              build(record, role, content_parts(record))
+            end
+
+            # content is a plain String; thoughts and toolCalls sit beside it rather
+            # than inside a parts array, so the document's shape is flattened into
+            # this gem's vocabulary here rather than mapped one-to-one.
+            #
+            # A thought is {subject, description}: the subject alone reads as a
+            # heading with no body, so both are kept, joined — losing the
+            # description would make :thinking parts look empty.
+            def content_parts(record)
+              parts = []
+              Array(record["thoughts"]).each do |thought|
+                next unless thought.is_a?(Hash)
+
+                parts << Part.new(type: :thinking, text: [thought["subject"], thought["description"]]
+                                  .compact.join(": "))
+              end
+              content = record["content"]
+              parts << Part.new(type: :text, text: content.to_s) if content.is_a?(String) && !content.empty?
+              parts.concat(tool_parts(record))
+              parts
+            end
+
+            # One toolCalls entry holds both the call and its result — the same
+            # shape opencode's `tool` part has — so it becomes two Parts. The result
+            # appears only when the entry carries one: an entry still running
+            # answered nothing, and an empty result would claim it did.
+            def tool_parts(record)
+              Array(record["toolCalls"]).flat_map do |call|
+                next [] unless call.is_a?(Hash)
+
+                parts = [Part.new(type: :tool_use, name: call["name"], call_id: call["id"],
+                                  text: stringify(call["args"]))]
+                parts << Part.new(type: :tool_result, call_id: call["id"],
+                                  text: stringify(call["result"])) if call.key?("result")
+                parts
+              end
+            end
+
+            def event_message(record)
+              return nil unless include_events
+
+              build(record, :system, [Part.new(type: :text, text: record["content"].to_s)])
+            end
+
+            def build(record, role, parts)
+              model = record["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
+
+            # tokens: {input, output, cached, thoughts, tool, total}.
+            #
+            # `cached` is INSIDE `input`, not beside it — verified arithmetically
+            # across every one of the 97 real token records: total equals
+            # input + output + thoughts + tool, with cached never added, so a cached
+            # count is part of the input it accompanies. Subtracted here for the
+            # same reason Codex's cached_input_tokens is, so Usage#input means one
+            # thing across agents. Clamped at zero: a negative token count would
+            # mean the two fields disagree, and a wrong zero beats a negative.
+            #
+            # `total` is deliberately unmapped (it restates the others), and so is
+            # `tool` — this gem's Usage has no bucket for tokens spent inside a
+            # tool, and folding them into output would misreport what the model
+            # generated. Both stay reachable in raw.
+            def usage_from(record)
+              tokens = record["tokens"]
+              return nil unless tokens.is_a?(Hash)
+
+              input = count_from(tokens["input"])
+              cached = count_from(tokens["cached"])
+              mapped = Usage.new(input: input && cached ? [input - cached, 0].max : input,
+                                 output: count_from(tokens["output"]),
+                                 cache_read: cached,
+                                 reasoning: count_from(tokens["thoughts"]))
+              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
+          end
+        end
+  end
+end

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

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Readers
+          # Grok Build sessions. PROVISIONAL, like the adapter: written against
+          # tokentelemetry's parser of this format, not against real Grok output.
+          #
+          # Two things make this reader unlike every other one here. The session it
+          # is handed points at summary.json, while the conversation is in
+          # chat_history.jsonl beside it — so the streaming base reads a SIBLING
+          # file. And billed usage is not in the session directory at all: it lives
+          # in ~/.grok/logs/unified.jsonl, one row per request across every session,
+          # keyed by session id. A rotated log means no usage, which is why `usage`
+          # answers nil rather than zero when the log is gone.
+          class Grok < Base
+            TRANSCRIPT = "chat_history.jsonl"
+            UNIFIED_LOG = "unified.jsonl"
+
+            # The row that records one completed request, per the reference parser.
+            INFERENCE = "shell.turn.inference_done"
+
+            ROLES = { "user" => :user, "assistant" => :assistant, "system" => :system,
+                      "tool" => :tool }.freeze
+
+            # The session's summary.json, exposed because it holds what Layer 2 does
+            # not surface: generated_title, session_summary, current_model_id, the
+            # git branch and commit the work happened on.
+            def summary
+              @summary ||= begin
+                parsed = JSON.parse(File.read(session.path))
+                parsed.is_a?(Hash) ? parsed : {}
+              rescue SystemCallError, JSON::ParserError
+                warn_about("#{session.path} could not be read")
+                {}
+              end
+            end
+
+            # Summed across this session's rows in the shared inference log.
+            #
+            # prompt_tokens INCLUDES cached_prompt_tokens (the reference parser
+            # subtracts one from the other, as this gem does for Codex and Gemini),
+            # so `input` is the difference and `cache_read` the cached share. The
+            # cached count is clamped to the prompt first: a log row claiming more
+            # cached than prompt would otherwise produce a negative input.
+            def usage
+              rows = 0
+              input = output = cached = reasoning = 0
+              each_log_row do |record|
+                ctx = record["ctx"]
+                next unless ctx.is_a?(Hash)
+
+                prompt = count_from(ctx["prompt_tokens"]).to_i
+                hit = [count_from(ctx["cached_prompt_tokens"]).to_i, prompt].min
+                rows += 1
+                input += prompt - hit
+                cached += hit
+                output += count_from(ctx["completion_tokens"]).to_i
+                reasoning += count_from(ctx["reasoning_tokens"]).to_i
+              end
+              return nil if rows.zero?
+
+              Usage.new(input: input, output: output, cache_read: cached, reasoning: reasoning)
+            end
+
+            private
+
+            # The conversation, beside the summary Layer 2 pointed at. This is the
+            # hook Readers::Base provides for exactly this case, so all of its
+            # streaming and reporting still applies.
+            def record_path = File.join(File.dirname(session.path), TRANSCRIPT)
+
+            # <base>/sessions/<project>/<id>/summary.json → <base>/logs/unified.jsonl.
+            # Four levels up rather than a stored root, because a Session carries a
+            # path and nothing else about where its store began.
+            def unified_log_path
+              base = File.dirname(File.dirname(File.dirname(File.dirname(session.path))))
+              File.join(base, "logs", UNIFIED_LOG)
+            end
+
+            # Streams the shared log, keeping only this session's completed
+            # requests. The whole file is walked because rows for many sessions are
+            # interleaved; the cheap string check comes before the JSON parse, since
+            # most rows belong to other sessions or other event types.
+            def each_log_row
+              path = unified_log_path
+              return unless File.exist?(path)
+
+              File.foreach(path, "\n", MAX_RECORD_BYTES) do |chunk|
+                next unless chunk.include?(INFERENCE) && chunk.include?(session.id)
+
+                record = begin
+                  JSON.parse(chunk)
+                rescue JSON::ParserError, EncodingError
+                  next
+                end
+                next unless record.is_a?(Hash) && record["msg"] == INFERENCE && record["sid"] == session.id
+
+                yield record
+              end
+            rescue SystemCallError
+              warn_about("#{path} could not be read; token usage is unavailable for this session")
+            end
+
+            def message_for(record, line_number)
+              role = ROLES[record["role"]]
+              unless role
+                warn_about("line #{line_number}: unrecognized role #{record["role"].inspect}")
+                return Message.new(role: :unknown, at: time_from(record["timestamp"]),
+                                   parts: [Part.new(type: :unknown)], raw: record)
+              end
+
+              Message.new(role: role, at: time_from(record["timestamp"]), parts: content_parts(record),
+                          raw: record, usage: nil, model: model_for(record))
+            end
+
+            # content is a String, or an array of typed blocks of which only text is
+            # mapped by the reference parser — anything else stays in raw rather
+            # than being guessed at.
+            def content_parts(record)
+              content = record["content"]
+              return [Part.new(type: :text, text: content)] if content.is_a?(String)
+
+              Array(content).filter_map do |block|
+                next unless block.is_a?(Hash)
+
+                case block["type"]
+                when "text" then Part.new(type: :text, text: block["text"].to_s)
+                when "tool_use", "tool_call"
+                  Part.new(type: :tool_use, name: block["name"], call_id: block["id"],
+                           text: stringify(block["input"] || block["arguments"]))
+                when "tool_result"
+                  Part.new(type: :tool_result, call_id: block["tool_use_id"] || block["id"],
+                           text: stringify(block["content"] || block["output"]))
+                when "thinking", "reasoning"
+                  Part.new(type: :thinking, text: (block["thinking"] || block["text"]).to_s)
+                end
+              end
+            end
+
+            # Per-message model where one is recorded, falling back to the session's
+            # current model from summary.json — which is what it says it is, the
+            # model in force now, so it is a fallback and never an override.
+            def model_for(record)
+              model = record["model"] || summary["current_model_id"]
+              model.is_a?(String) ? model : nil
+            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/opencode.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Readers
+          # opencode sessions, read from the shared SQLite database the adapter
+          # already enumerates. Written against a real store on this machine
+          # (2026-08-24): 365 sessions, whose message and part rows settled every
+          # mapping below — this is the first reader whose "corpus" is a database
+          # rather than files.
+          #
+          # A "record" here is synthetic: one message row's parsed `data` plus every
+          # part row belonging to it, as {"message" => ..., "parts" => [...]}. That
+          # composite IS the raw a Message carries — rule 1 needs the parts included,
+          # because the content lives in them, not in the message row.
+          class Opencode < Base
+            # Conversation content. text and reasoning map 1:1; a `tool` part holds
+            # BOTH the call and its result in one row (state.input / state.output),
+            # so it becomes two Parts — the assistant's act and the tool answering —
+            # rather than flattening one of them away.
+            CONTENT_PARTS = %w[text reasoning tool].freeze
+
+            # State, not conversation, skipped in silence — the same judgement
+            # Claude's session-state records get. Observed counts in the real store:
+            # step-start 4,391, step-finish 4,380 (consumed for usage below), patch
+            # 569 (files a step touched), file 25 (attachments), agent 1, compaction
+            # 1 (surfaced through `compactions`, not as a message).
+            STATE_PARTS = %w[step-start step-finish patch file agent compaction snapshot].freeze
+
+            # Session totals, summed per message. No dedup is needed: one row is one
+            # API response, and the sum was verified against the store's own
+            # per-session rollup columns — 9,727,437 input / 94,266 output /
+            # 22,184,157 cache-read, exactly equal both ways on the real store.
+            def usage
+              total = nil
+              each_record do |record, _row_number|
+                usage = usage_from(record)
+                next unless usage
+
+                total = total ? total + usage : usage
+              end
+              total
+            end
+
+            private
+
+            # Message rows for this session, oldest first. time_created is epoch
+            # millis; id is the tiebreak so two messages written in the same
+            # millisecond keep a stable order. Parts are fetched per message rather
+            # than per session: a session's tool outputs can be arbitrarily large,
+            # and rule 3 (never assume it fits in memory) applies to a database
+            # exactly as it does to a 2.6 GB file.
+            #
+            # A failure to read the DATABASE warns and yields nothing — one
+            # unreadable session must not take down a sweep — unlike the adapter,
+            # which raises UnreadableStore because enumeration has nothing partial
+            # to return. A missing sqlite3 gem still raises: that is the caller's
+            # environment, not this session's data.
+            def each_record
+              require_sqlite!
+              db = nil
+              row_number = 0
+              begin
+                db = Sqlite.open_readonly(session.path)
+                db.execute("SELECT id, data FROM message WHERE session_id = ? ORDER BY time_created, id",
+                           [session.id]) do |(id, data)|
+                  row_number += 1
+                  message = parse_row(data, "message #{id}") or next
+                  yield({ "message" => message, "parts" => parts_rows(db, id) }, row_number)
+                end
+              rescue SQLite3::Exception => e
+                warn_about("#{session.path} could not be read (#{e.class.name.split("::").last})")
+              ensure
+                db&.close
+              end
+            end
+
+            def parts_rows(db, message_id)
+              db.execute("SELECT id, data FROM part WHERE message_id = ? ORDER BY time_created, id",
+                         [message_id]).filter_map { |(id, data)| parse_row(data, "part #{id}") }
+            end
+
+            def parse_row(data, label)
+              record = JSON.parse(data)
+              return record if record.is_a?(Hash)
+
+              warn_about("#{label} is not a JSON object; skipped")
+            rescue JSON::ParserError, TypeError
+              warn_about("#{label} does not hold valid JSON; skipped")
+            end
+
+            def message_for(record, row_number)
+              data = record["message"]
+              role = data["role"]
+              unless %w[user assistant].include?(role)
+                warn_about("message #{row_number}: unrecognized role #{role.inspect}")
+                return build(record, :unknown)
+              end
+
+              build(record, role.to_sym)
+            end
+
+            def build(record, role)
+              data = record["message"]
+              Message.new(role: role, at: epoch_ms(data.dig("time", "created")),
+                          parts: content_parts(record), raw: record,
+                          usage: usage_from(record), model: model_from(data))
+            end
+
+            def content_parts(record)
+              record["parts"].flat_map do |part|
+                type = part["type"]
+                next [] if STATE_PARTS.include?(type)
+
+                case type
+                when "text" then [Part.new(type: :text, text: part["text"].to_s)]
+                when "reasoning" then [Part.new(type: :thinking, text: part["text"].to_s)]
+                when "tool" then tool_parts(part)
+                # A subagent spawn: {prompt, description, agent, model, command} —
+                # found by running this reader over all 365 real sessions and
+                # reading its one warning. The assistant's act of delegating, so
+                # :tool_use like Claude's Task; the child's turns are its own
+                # session row (parent_id), never inlined here.
+                when "subtask"
+                  [Part.new(type: :tool_use, name: part["agent"] || "subtask", text: part["prompt"].to_s)]
+                else
+                  warn_about("unrecognized part type #{type.inspect}")
+                  [Part.new(type: :unknown, text: part["text"])]
+                end
+              end
+            end
+
+            # state.input is a Hash (the tool's arguments), state.output a String.
+            # The result Part appears only when the state carries an output — a
+            # pending or errored call answered nothing, and an empty result would
+            # claim it did.
+            def tool_parts(part)
+              state = part["state"]
+              state = {} unless state.is_a?(Hash)
+              parts = [Part.new(type: :tool_use, name: part["tool"], call_id: part["callID"],
+                                text: stringify(state["input"]))]
+              parts << Part.new(type: :tool_result, call_id: part["callID"],
+                                text: state["output"].to_s) if state.key?("output")
+              parts
+            end
+
+            # An assistant row carries its own tokens and cost (every one of the
+            # 4,000+ assistant rows in the real store does). The step-finish
+            # fallback covers the schema generation tokentelemetry observed, where
+            # only parts carried tokens; the two sources are per-message equal where
+            # both exist (verified: 10,557/221/489 both ways on a real message), so
+            # preferring the message row can never double-count.
+            def usage_from(record)
+              data = record["message"]
+              tokens = data["tokens"]
+              return tokens_usage(tokens, data["cost"]) if tokens.is_a?(Hash)
+
+              step_usage(record["parts"])
+            end
+
+            def tokens_usage(tokens, cost)
+              mapped = Usage.new(input: count_from(tokens["input"]),
+                                 output: count_from(tokens["output"]),
+                                 reasoning: count_from(tokens["reasoning"]),
+                                 cache_read: count_from(tokens.dig("cache", "read")),
+                                 cache_creation: count_from(tokens.dig("cache", "write")),
+                                 cost: cost_from(cost))
+              mapped.to_h.each_value.any? ? mapped : nil
+            end
+
+            def step_usage(parts)
+              total = nil
+              parts.each do |part|
+                next unless part["type"] == "step-finish" && part["tokens"].is_a?(Hash)
+
+                usage = tokens_usage(part["tokens"], part["cost"])
+                next unless usage
+
+                total = total ? total + usage : usage
+              end
+              total
+            end
+
+            def model_from(data)
+              model = data["modelID"] # an assistant row's spelling
+              model = data.dig("model", "modelID") unless model.is_a?(String) # a user row's
+              model.is_a?(String) ? model : nil
+            end
+
+            # {"type":"compaction","auto":false} is the whole record observed — no
+            # count of what it replaced, so replaced_count is nil rather than a zero
+            # that would read as "stood in for nothing".
+            def compaction_for(record)
+              part = record["parts"].find { |candidate| candidate["type"] == "compaction" }
+              return nil unless part
+
+              Compaction.new(at: epoch_ms(record["message"].dig("time", "created")),
+                             replaced_count: nil, raw: part)
+            end
+
+            def stringify(value)
+              value.is_a?(String) || value.nil? ? value.to_s : JSON.generate(value)
+            end
+
+            # Epoch millis to Time, with the adapter's session_time guards: a
+            # non-Numeric is nil, and a huge-but-real Integer that overflows to
+            # Infinity once divided must not reach Time.at.
+            def epoch_ms(millis)
+              return nil unless millis.is_a?(Numeric)
+
+              seconds = millis / 1000.0
+              Time.at(seconds) if seconds.finite?
+            end
+
+            def require_sqlite!
+              require "sqlite3"
+            rescue LoadError
+              raise MissingDependency,
+                    "opencode messages live in opencode.db (SQLite); add the sqlite3 gem to read them"
+            end
+          end
+        end
+  end
+end

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

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Agent
+  module Sessions
+        module Readers
+          # pi session files. PROVISIONAL in a way no other reader is: this machine
+          # holds nine real pi project directories and zero session files inside
+          # them (2026-08-24), so every mapping below is written against
+          # tokentelemetry's working parser of the same format
+          # (resources/tokentelemetry, backend/main.py, _scan_pi_sessions) rather
+          # than a corpus of pi's own output. That is observation of running code,
+          # not of data — one step better than the design doc's prose, one step
+          # short of every other reader's evidence. Where the two could disagree,
+          # rule 2 already decides the outcome: a shape this reader has not seen
+          # becomes an :unknown part and a warning, never an exception, and raw
+          # carries what really happened.
+          #
+          # The format per that parser: a header record {"type":"session", id, cwd,
+          # timestamp}, then typed records — "model_change" (provider, modelId) and
+          # "message" ({role, model, content[], usage}). usage spells its keys
+          # camelCase (cacheRead, cacheWrite) and carries agent-computed cost.
+          class Pi < Base
+            # The header and settings records are session state, not conversation —
+            # the same judgement Codex's session_meta gets. model_change is state
+            # too: the model a LATER message used is on that message.
+            NON_MESSAGE_TYPES = %w[session model_change].freeze
+
+            ROLES = { "user" => :user, "assistant" => :assistant }.freeze
+
+            # Session totals, summed per message record. No dedup: nothing observed
+            # or reported suggests pi repeats one response across records the way
+            # Claude does — but nothing proves it either, so if pi totals ever read
+            # roughly double a provider's bill, this is where to look.
+            def usage
+              total = nil
+              each_record do |record, _line_number|
+                usage = usage_from(record)
+                next unless usage
+
+                total = total ? total + usage : usage
+              end
+              total
+            end
+
+            private
+
+            def message_for(record, line_number)
+              type = record["type"]
+              return nil if NON_MESSAGE_TYPES.include?(type)
+
+              unless type == "message" && record["message"].is_a?(Hash)
+                warn_about("line #{line_number}: unrecognized record type #{type.inspect}")
+                return Message.new(role: :unknown, at: time_from(record["timestamp"]),
+                                   parts: [Part.new(type: :unknown)], raw: record)
+              end
+
+              data = record["message"]
+              Message.new(role: role_for(data["role"], line_number),
+                          at: time_from(record["timestamp"]),
+                          parts: content_parts(data, line_number), raw: record,
+                          usage: usage_from(record), model: model_from(data))
+            end
+
+            def role_for(role, line_number)
+              ROLES.fetch(role) do
+                warn_about("line #{line_number}: unrecognized role #{role.inspect}")
+                :unknown
+              end
+            end
+
+            # content carries text and toolCall items per the reference parser. A
+            # toolCall's inner keys are the least-verified mapping in this file —
+            # name/id/arguments are the spellings pi's TypeScript types suggest, and
+            # every one is fetched nil-safe so a different spelling degrades to an
+            # emptier Part, never to a crash. raw holds the truth either way.
+            def content_parts(data, line_number)
+              Array(data["content"]).map do |item|
+                next Part.new(type: :unknown) unless item.is_a?(Hash)
+
+                case 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 "toolCall"
+                  Part.new(type: :tool_use, name: item["name"], call_id: item["id"],
+                           text: stringify(item["arguments"] || item["input"]))
+                when "toolResult"
+                  Part.new(type: :tool_result, call_id: item["toolCallId"] || item["id"],
+                           text: item["output"].is_a?(String) ? item["output"] : item["text"])
+                else
+                  warn_about("line #{line_number}: unrecognized content part #{item["type"].inspect}")
+                  Part.new(type: :unknown, text: item["text"])
+                end
+              end
+            end
+
+            # usage keys observed by the reference parser: input, output, cacheRead,
+            # cacheWrite, reasoning, totalTokens, cost. totalTokens is deliberately
+            # unmapped — it restates the others, and any bucket it landed in would
+            # double-count. Whether input already excludes cacheRead the way the
+            # field names suggest (Anthropic-style disjoint spelling) is UNVERIFIED;
+            # if pi turns out to count inclusively the way Codex does, the fix is a
+            # subtraction here, not in any caller.
+            def usage_from(record)
+              usage = record.dig("message", "usage")
+              return nil unless usage.is_a?(Hash)
+
+              cost = usage["cost"]
+              cost = cost["total"] if cost.is_a?(Hash)
+              mapped = Usage.new(input: count_from(usage["input"]),
+                                 output: count_from(usage["output"]),
+                                 cache_read: count_from(usage["cacheRead"]),
+                                 cache_creation: count_from(usage["cacheWrite"]),
+                                 reasoning: count_from(usage["reasoning"]),
+                                 cost: cost_from(cost))
+              mapped.to_h.each_value.any? ? mapped : nil
+            end
+
+            def model_from(data)
+              model = data["model"]
+              model.is_a?(String) ? model : nil
+            end
+
+            def stringify(value)
+              value.is_a?(String) || value.nil? ? value.to_s : JSON.generate(value)
+            end
+          end
+        end
+  end
+end