agent_sessions 0.3.0 → 0.3.1

data/doc/Agent/Sessions/Readers/Codex.md

@@ -0,0 +1,81 @@
+# Class Agent::Sessions::Readers::Codex <a id="class-Agent-Sessions-Readers-Codex"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Readers::Base](Base.md) |
+| **Defined in** | lib/agent/sessions/readers/codex.rb |
+
+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.
+
+## Constants
+### `CALL_INPUTS` <a id="constant-CALL_INPUTS"></a> <a id="CALL_INPUTS-constant"></a>
+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_OUTPUTS` <a id="constant-CALL_OUTPUTS"></a> <a id="CALL_OUTPUTS-constant"></a>
+And where an output keeps its result.
+
+### `CONTENT_PARTS` <a id="constant-CONTENT_PARTS"></a> <a id="CONTENT_PARTS-constant"></a>
+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.
+
+### `NON_MESSAGE_ITEMS` <a id="constant-NON_MESSAGE_ITEMS"></a> <a id="NON_MESSAGE_ITEMS-constant"></a>
+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_TYPES` <a id="constant-NON_MESSAGE_TYPES"></a> <a id="NON_MESSAGE_TYPES-constant"></a>
+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.
+
+### `ROLES` <a id="constant-ROLES"></a> <a id="ROLES-constant"></a>
+"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.
+
+### `TOOL_CALLS` <a id="constant-TOOL_CALLS"></a> <a id="TOOL_CALLS-constant"></a>
+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_OUTPUTS` <a id="constant-TOOL_OUTPUTS"></a> <a id="TOOL_OUTPUTS-constant"></a>
+Not documented.
+
+## Public Instance Methods
+### `usage()` <a id="method-i-usage"></a> <a id="usage-instance_method"></a>
+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.

data/doc/Agent/Sessions/Readers/Copilot.md

@@ -0,0 +1,31 @@
+# Class Agent::Sessions::Readers::Copilot <a id="class-Agent-Sessions-Readers-Copilot"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Readers::Base](Base.md) |
+| **Defined in** | lib/agent/sessions/readers/copilot.rb |
+
+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.
+
+## Public Instance Methods
+### `each_message()` <a id="method-i-each_message"></a> <a id="each_message-instance_method"></a>
+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.
+
+### `usage()` <a id="method-i-usage"></a> <a id="usage-instance_method"></a>
+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.

data/doc/Agent/Sessions/Readers/Gemini.md

@@ -0,0 +1,38 @@
+# Class Agent::Sessions::Readers::Gemini <a id="class-Agent-Sessions-Readers-Gemini"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Readers::Base](Base.md) |
+| **Defined in** | lib/agent/sessions/readers/gemini.rb |
+
+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.
+
+## Constants
+### `MAX_DOCUMENT_BYTES` <a id="constant-MAX_DOCUMENT_BYTES"></a> <a id="MAX_DOCUMENT_BYTES-constant"></a>
+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.
+
+### `ROLES` <a id="constant-ROLES"></a> <a id="ROLES-constant"></a>
+"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.
+
+## Public Instance Methods
+### `header()` <a id="method-i-header"></a> <a id="header-instance_method"></a>
+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.
+
+### `usage()` <a id="method-i-usage"></a> <a id="usage-instance_method"></a>
+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).

data/doc/Agent/Sessions/Readers/Grok.md

@@ -0,0 +1,45 @@
+# Class Agent::Sessions::Readers::Grok <a id="class-Agent-Sessions-Readers-Grok"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Readers::Base](Base.md) |
+| **Defined in** | lib/agent/sessions/readers/grok.rb |
+
+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.
+
+## Constants
+### `INFERENCE` <a id="constant-INFERENCE"></a> <a id="INFERENCE-constant"></a>
+The row that records one completed request, per the reference parser.
+
+### `ROLES` <a id="constant-ROLES"></a> <a id="ROLES-constant"></a>
+Not documented.
+
+### `TRANSCRIPT` <a id="constant-TRANSCRIPT"></a> <a id="TRANSCRIPT-constant"></a>
+Not documented.
+
+### `UNIFIED_LOG` <a id="constant-UNIFIED_LOG"></a> <a id="UNIFIED_LOG-constant"></a>
+Not documented.
+
+## Public Instance Methods
+### `summary()` <a id="method-i-summary"></a> <a id="summary-instance_method"></a>
+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.
+
+### `usage()` <a id="method-i-usage"></a> <a id="usage-instance_method"></a>
+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.

data/doc/Agent/Sessions/Readers/Opencode.md

@@ -0,0 +1,37 @@
+# Class Agent::Sessions::Readers::Opencode <a id="class-Agent-Sessions-Readers-Opencode"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Readers::Base](Base.md) |
+| **Defined in** | lib/agent/sessions/readers/opencode.rb |
+
+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.
+
+## Constants
+### `CONTENT_PARTS` <a id="constant-CONTENT_PARTS"></a> <a id="CONTENT_PARTS-constant"></a>
+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.
+
+### `STATE_PARTS` <a id="constant-STATE_PARTS"></a> <a id="STATE_PARTS-constant"></a>
+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).
+
+## Public Instance Methods
+### `usage()` <a id="method-i-usage"></a> <a id="usage-instance_method"></a>
+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.

data/doc/Agent/Sessions/Readers/Pi.md

@@ -0,0 +1,38 @@
+# Class Agent::Sessions::Readers::Pi <a id="class-Agent-Sessions-Readers-Pi"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Readers::Base](Base.md) |
+| **Defined in** | lib/agent/sessions/readers/pi.rb |
+
+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.
+
+## Constants
+### `NON_MESSAGE_TYPES` <a id="constant-NON_MESSAGE_TYPES"></a> <a id="NON_MESSAGE_TYPES-constant"></a>
+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.
+
+### `ROLES` <a id="constant-ROLES"></a> <a id="ROLES-constant"></a>
+Not documented.
+
+## Public Instance Methods
+### `usage()` <a id="method-i-usage"></a> <a id="usage-instance_method"></a>
+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.

data/doc/Agent/Sessions/Readers/Qwen.md

@@ -0,0 +1,30 @@
+# Class Agent::Sessions::Readers::Qwen <a id="class-Agent-Sessions-Readers-Qwen"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Readers::Base](Base.md) |
+| **Defined in** | lib/agent/sessions/readers/qwen.rb |
+
+Qwen Code chat files. PROVISIONAL, like the adapter: written against
+tokentelemetry's parser of this format, not against real Qwen output.
+
+The record shape is Anthropic's — type user/assistant, message.content as an
+array of typed parts, message.usage with the same five spellings Claude uses.
+This is deliberately NOT a subclass of Readers::Claude despite that overlap:
+Claude's reader also carries Claude Code's sidecar machinery (spilled tool
+output, subagent transcripts, uuid/parentUuid branching), none of which is
+known to exist here, and inheriting would mean disabling each one and then
+re-checking every future Claude change against an agent nobody can test. Two
+readers with two evidence bases will drift honestly; one reader pretending to
+serve both will drift silently.
+
+## Constants
+### `CONTENT_PARTS` <a id="constant-CONTENT_PARTS"></a> <a id="CONTENT_PARTS-constant"></a>
+Not documented.
+
+## Public Instance Methods
+### `usage()` <a id="method-i-usage"></a> <a id="usage-instance_method"></a>
+Session totals, deduplicated by message.id the way Claude's are: the same API
+response can stream into one record per content block, and both agents speak
+the same wire format. Unverified for Qwen — if its writer does not repeat ids,
+this dedup is simply a no-op.

data/doc/Agent/Sessions/Readers.md

@@ -0,0 +1,5 @@
+# Module Agent::Sessions::Readers <a id="module-Agent-Sessions-Readers"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/agent/sessions/readers/pi.rb, lib/agent/sessions/readers/amp.rb, lib/agent/sessions/readers/base.rb, lib/agent/sessions/readers/grok.rb, lib/agent/sessions/readers/qwen.rb, lib/agent/sessions/readers/codex.rb, lib/agent/sessions/readers/claude.rb, lib/agent/sessions/readers/gemini.rb, lib/agent/sessions/readers/copilot.rb, lib/agent/sessions/readers/opencode.rb |

data/doc/Agent/Sessions/Session.md

@@ -0,0 +1,73 @@
+# Class Agent::Sessions::Session <a id="class-Agent-Sessions-Session"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Object |
+| **Defined in** | lib/agent/sessions/session.rb |
+
+One recorded conversation. Everything here comes from a stat or the store's
+own metadata — except project_path, which may need to read inside the session
+file (design doc section 7: the on-disk directory encodings are lossy, so the
+recorded cwd inside the file is the only reliable source). It is computed on
+first access and memoized, which is why this is a plain class rather than a
+frozen Data: an instance is immutable except for that one memo.
+
+Equality is identity, not value — unlike every sibling value object here,
+which gets value equality for free from Data. A value comparison would have to
+force project_path on both operands, turning a `uniq` over thousands of
+sessions into the full content sweep the design works to avoid. A caller
+keying a mixed-agent collection should use `uid`, which exists for exactly
+that. Note `to_h` includes `uid`, so its output does not round-trip back
+through `new`.
+
+## Constants
+### `UNRESOLVED` <a id="constant-UNRESOLVED"></a> <a id="UNRESOLVED-constant"></a>
+Not documented.
+
+## Attributes
+### `agent` [R] <a id="attribute-i-agent"></a> <a id="agent-instance_method"></a>
+Returns the value of attribute agent.
+
+### `bytes` [R] <a id="attribute-i-bytes"></a> <a id="bytes-instance_method"></a>
+Returns the value of attribute bytes.
+
+### `fidelity` [R] <a id="attribute-i-fidelity"></a> <a id="fidelity-instance_method"></a>
+Returns the value of attribute fidelity.
+
+### `format` [R] <a id="attribute-i-format"></a> <a id="format-instance_method"></a>
+Returns the value of attribute format.
+
+### `id` [R] <a id="attribute-i-id"></a> <a id="id-instance_method"></a>
+Returns the value of attribute id.
+
+### `path` [R] <a id="attribute-i-path"></a> <a id="path-instance_method"></a>
+Returns the value of attribute path.
+
+### `started_at` [R] <a id="attribute-i-started_at"></a> <a id="started_at-instance_method"></a>
+Returns the value of attribute started_at.
+
+### `updated_at` [R] <a id="attribute-i-updated_at"></a> <a id="updated_at-instance_method"></a>
+Returns the value of attribute updated_at.
+
+## Public Instance Methods
+### `initialize(agent:, id:, path:, started_at:, updated_at:, bytes:, format:, fidelity:, project_path: UNRESOLVED, &project_path_resolver)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@return** [Session] a new instance of Session
+
+### `inspect()` <a id="method-i-inspect"></a> <a id="inspect-instance_method"></a>
+Never calls project_path: inspecting a session in a debugger must not trigger
+the read that enumeration deliberately deferred.
+
+### `project_path()` <a id="method-i-project_path"></a> <a id="project_path-instance_method"></a>
+A resolver that raises is deliberately not memoized: a failed read is not an
+answer, so the next call retries rather than freezing the failure in place.
+
+Not thread-safe by design: concurrent first access can run the resolver more
+than once, but every run yields the same value and the assignment is atomic on
+MRI, so there is no torn read to guard against. Do not add a mutex.
+
+### `to_h()` <a id="method-i-to_h"></a> <a id="to_h-instance_method"></a>
+The honest full dump — includes project_path, so it forces that read. Callers
+listing thousands of sessions should build their own slimmer rows.
+
+### `uid()` <a id="method-i-uid"></a> <a id="uid-instance_method"></a>
+Collision-free across a mixed-agent collection, where bare ids may repeat.

data/doc/Agent/Sessions/Sqlite.md

@@ -0,0 +1,43 @@
+# Module Agent::Sessions::Sqlite <a id="module-Agent-Sessions-Sqlite"></a>
+
+|  |  |
+| --- | --- |
+| **Defined in** | lib/agent/sessions/sqlite.rb |
+
+The one way this gem opens a SQLite store: read-only, URI-escaped, with a
+bounded retry against a live writer's lock. Extracted from the opencode
+adapter when the opencode reader became its second caller — two copies of
+escape_uri_path would drift, and the bug it guards is subtle enough that a
+drifted copy would look correct in review.
+
+What differs between callers stays with them: the adapter raises
+UnreadableStore on a query failure because a vanished database means no
+sessions at all, while a reader warns and yields nothing because one
+unreadable session must not take down a sweep (Layer 3 rule 2). This module
+only opens; it never decides what a failure means.
+
+## Public Class Methods
+### `escape_uri_path(path)` <a id="method-c-escape_uri_path"></a> <a id="escape_uri_path-class_method"></a>
+IMPORTANT, caught in review: SQLite's URI parser gives `%`, `#` and `?`
+syntactic meaning, and the path was being interpolated raw. `#` starts a
+fragment (silently truncating the path there); `?` starts the query string,
+colliding with the `?mode=ro` open_readonly appends. The worst case, confirmed
+directly: a path segment that merely CONTAINS a valid-looking percent-escape —
+a directory literally named "a%23b" —gets that escape DECODED by the URI
+parser into a different path ("a#b"), so a second, unrelated database sitting
+at THAT path is read instead, silently, with no exception at all. One pass,
+not two sequential gsubs: escaping # to %23 and THEN escaping the % that
+produced would double-encode it to %2523.
+
+### `open_readonly(path)` <a id="method-c-open_readonly"></a> <a id="open_readonly-class_method"></a>
+No immutable=1: it tells SQLite to trust that the file will never change and
+skip locking AND the WAL entirely — against a live, WAL-mode opencode.db that
+means silently missing every committed-but-not-yet- checkpointed session.
+Opening a WAL db even read-only touches its -shm and -wal sidecars (SQLite's
+own reader bookkeeping, confirmed directly); the recorded sessions themselves
+are never written.
+
+busy_timeout gives SQLite up to 5s to retry internally against a lock held by
+the agent's own live writer. A WAL writer's lock is normally held only for the
+instant of a commit, so a lock that has not cleared within 5s is a stuck
+process, not ordinary contention.

data/doc/Agent/Sessions/Store.md

@@ -0,0 +1,57 @@
+# Class Agent::Sessions::Store <a id="class-Agent-Sessions-Store"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Data |
+| **Defined in** | lib/agent/sessions/store.rb |
+
+## Attributes
+### `agent` [R] <a id="attribute-i-agent"></a> <a id="agent-instance_method"></a>
+Returns the value of attribute agent
+- **@return** [Object] the current value of agent
+
+### `documented` [R] <a id="attribute-i-documented"></a> <a id="documented-instance_method"></a>
+Returns the value of attribute documented
+- **@return** [Object] the current value of documented
+
+### `effective` [R] <a id="attribute-i-effective"></a> <a id="effective-instance_method"></a>
+Returns the value of attribute effective
+- **@return** [Object] the current value of effective
+
+### `env_overrides` [R] <a id="attribute-i-env_overrides"></a> <a id="env_overrides-instance_method"></a>
+Returns the value of attribute env_overrides
+- **@return** [Object] the current value of env_overrides
+
+### `label` [R] <a id="attribute-i-label"></a> <a id="label-instance_method"></a>
+Returns the value of attribute label
+- **@return** [Object] the current value of label
+
+### `layers` [R] <a id="attribute-i-layers"></a> <a id="layers-instance_method"></a>
+Returns the value of attribute layers
+- **@return** [Object] the current value of layers
+
+### `retention` [R] <a id="attribute-i-retention"></a> <a id="retention-instance_method"></a>
+Returns the value of attribute retention
+- **@return** [Object] the current value of retention
+
+### `retention_source` [R] <a id="attribute-i-retention_source"></a> <a id="retention_source-instance_method"></a>
+Returns the value of attribute retention_source
+- **@return** [Object] the current value of retention_source
+
+### `verified_on` [R] <a id="attribute-i-verified_on"></a> <a id="verified_on-instance_method"></a>
+Returns the value of attribute verified_on
+- **@return** [Object] the current value of verified_on
+
+### `warnings` [R] <a id="attribute-i-warnings"></a> <a id="warnings-instance_method"></a>
+Returns the value of attribute warnings
+- **@return** [Object] the current value of warnings
+
+## Public Instance Methods
+### `documented?()` <a id="method-i-documented-3F"></a> <a id="documented?-instance_method"></a>
+- **@return** [Boolean]
+
+### `format()` <a id="method-i-format"></a> <a id="format-instance_method"></a>
+Not documented.
+
+### `installed?()` <a id="method-i-installed-3F"></a> <a id="installed?-instance_method"></a>
+- **@return** [Boolean]

data/doc/Agent/Sessions/UnknownAgent.md

@@ -0,0 +1,6 @@
+# Class Agent::Sessions::UnknownAgent <a id="class-Agent-Sessions-UnknownAgent"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Error](Error.md) |
+| **Defined in** | lib/agent/sessions/unknown_agent.rb |

data/doc/Agent/Sessions/UnreadableStore.md

@@ -0,0 +1,6 @@
+# Class Agent::Sessions::UnreadableStore <a id="class-Agent-Sessions-UnreadableStore"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Error](Error.md) |
+| **Defined in** | lib/agent/sessions/unreadable_store.rb |

data/doc/Agent/Sessions/UnsupportedFormat.md

@@ -0,0 +1,6 @@
+# Class Agent::Sessions::UnsupportedFormat <a id="class-Agent-Sessions-UnsupportedFormat"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | [Agent::Sessions::Error](Error.md) |
+| **Defined in** | lib/agent/sessions/unsupported_format.rb |

data/doc/Agent/Sessions/Usage.md

@@ -0,0 +1,56 @@
+# Class Agent::Sessions::Usage <a id="class-Agent-Sessions-Usage"></a>
+
+|  |  |
+| --- | --- |
+| **Inherits** | Data |
+| **Defined in** | lib/agent/sessions/usage.rb |
+
+Token counts an agent reported, for one message or one whole session,
+normalized to five DISJOINT buckets: `input` never includes what was read from
+or written to cache, and `output` never includes `reasoning`. Agents disagree
+here — Codex's input_tokens includes its cached_input_tokens, Claude's does
+not (both verified against real stores on this machine, 2026-08-24) — and a
+caller summing across agents needs one rule, not one per agent. Readers do the
+subtraction; this object only holds the result.
+
+nil means "this format does not record that dimension", and it is load-
+bearing: absence must never read as zero, for the same reason
+Agent::Sessions.read raises on a format with no reader. `cost` is reported by
+the agent or absent — never derived from a pricing table, which would go stale
+in a gem and is a consumer's decision anyway.
+
+## Attributes
+### `cache_creation` [R] <a id="attribute-i-cache_creation"></a> <a id="cache_creation-instance_method"></a>
+Returns the value of attribute cache_creation
+- **@return** [Object] the current value of cache_creation
+
+### `cache_read` [R] <a id="attribute-i-cache_read"></a> <a id="cache_read-instance_method"></a>
+Returns the value of attribute cache_read
+- **@return** [Object] the current value of cache_read
+
+### `cost` [R] <a id="attribute-i-cost"></a> <a id="cost-instance_method"></a>
+Returns the value of attribute cost
+- **@return** [Object] the current value of cost
+
+### `input` [R] <a id="attribute-i-input"></a> <a id="input-instance_method"></a>
+Returns the value of attribute input
+- **@return** [Object] the current value of input
+
+### `output` [R] <a id="attribute-i-output"></a> <a id="output-instance_method"></a>
+Returns the value of attribute output
+- **@return** [Object] the current value of output
+
+### `reasoning` [R] <a id="attribute-i-reasoning"></a> <a id="reasoning-instance_method"></a>
+Returns the value of attribute reasoning
+- **@return** [Object] the current value of reasoning
+
+## Public Instance Methods
+### `+(other)` <a id="method-i--2B"></a> <a id="+-instance_method"></a>
+Sums dimension-wise, keeping the nil/zero distinction: nil + nil stays nil
+("neither side records this"), nil + n is n — one recorded value is a real
+value, not a value plus an unknown, because per-message absence under a format
+that does record the dimension means "none reported for this message", the one
+place absence and zero do coincide.
+
+### `initialize(input: nil, output: nil, cache_read: nil, cache_creation: nil, reasoning: nil, cost: nil)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
+- **@return** [Usage] a new instance of Usage