agent_session_context 1.0.0

data/lib/agent/session_context/item.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    Item = Data.define(:kind, :label, :detail, :evidence, :source_refs, :attributes) do
+      EVIDENCE_VALUES = %i[observed explicit inferred].freeze
+
+      def initialize(kind:, label:, evidence:, source_refs:, detail: nil, attributes: {})
+        unless EVIDENCE_VALUES.include?(evidence)
+          raise ArgumentError,
+                "evidence must be one of: #{EVIDENCE_VALUES.join(", ")}"
+        end
+
+        super(
+          kind: kind.to_sym,
+          label: normalize_string(label, :label),
+          detail: normalize_optional_string(detail, :detail),
+          evidence: evidence,
+          source_refs: ImmutableValue.copy(Array(source_refs)),
+          attributes: normalize_attributes(attributes)
+        )
+      end
+
+      private
+
+      def normalize_attributes(attributes)
+        raise TypeError, "attributes must be a Hash" unless attributes.is_a?(Hash)
+
+        attributes.each_with_object({}) do |(key, value), normalized|
+          normalized[normalize_attribute_key(key)] = ImmutableValue.copy(value)
+        end.freeze
+      end
+
+      def normalize_attribute_key(key)
+        return key if key.is_a?(Symbol)
+        return key.to_sym if key.respond_to?(:to_sym)
+
+        raise TypeError, "attribute keys must be symbolizable"
+      end
+
+      def normalize_string(value, name)
+        raise TypeError, "#{name} must be a String" unless value.respond_to?(:to_str)
+
+        String.new(value.to_str).freeze
+      end
+
+      def normalize_optional_string(value, name)
+        return if value.nil?
+
+        normalize_string(value, name)
+      end
+    end
+  end
+end

data/lib/agent/session_context/loop.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    # One session read as an agent loop: round trips, the tool calls paired
+    # across them, who spoke at each step, and how the loop ended.
+    #
+    # `recorded` is false for an empty session — nothing was recorded, and
+    # "absence must never read as presence" is this gem's standing rule
+    # (RoundTrip carries the same rule for one group).
+    #
+    # `warnings` is the reader's warnings first, then this object's own, so
+    # the order is deterministic regardless of what the reader happened to
+    # find.
+    Loop = Data.define(:session, :round_trips, :tool_calls, :speakers, :ending, :recorded, :warnings) do
+      # The exact sentence for each ending, so the Loop and whatever renders
+      # it say the same words.
+      ENDINGS = {
+        answered: "the model answered without asking for a tool",
+        stopped_in_the_loop: "a tool was asked for and nothing answered it",
+        not_a_model_record: "the session stops on a record the model did not write",
+        empty: "no round trips were recorded"
+      }.freeze
+
+      # Always true: no store on disk records WHY a session stopped — the
+      # on-disk transcript holds no stop reason and no turn count, because
+      # those live in the streamed output of a non-interactive run, not in
+      # the session file. So the ending is always deduced, and must always
+      # be labelled as such rather than presented as a recorded fact.
+      def ending_inferred? = true
+
+      def ending_detail = ENDINGS.fetch(ending)
+
+      class << self
+        # Reads the WHOLE session and says so by returning one built object
+        # rather than streaming — it cannot stream, because a tool result
+        # can arrive many records after the call it answers, and a
+        # streaming pass cannot look forward to find it.
+        # Readers::Base#tree carries the same shape of honesty for the same
+        # reason.
+        def for(reader)
+          warnings = []
+          trips = reader.round_trips
+          speakers = {}
+          trips.each { |trip| speakers[trip.index] = speaker_of(trip, warnings) }
+          calls = pair(trips, warnings)
+          new(session: reader.session, round_trips: trips, tool_calls: calls, speakers: speakers,
+              ending: ending_for(trips, speakers), recorded: trips.any? && trips.all?(&:recorded),
+              warnings: reader.warnings + warnings)
+        end
+
+        private
+
+        # The speaker is read from the roles AND the parts together, never
+        # the role alone — Claude files a tool result as a `user` message,
+        # so a person's prompt and the harness answering a tool look
+        # identical by role. A message carrying tool results is the
+        # harness whatever role it carries.
+        def speaker_of(round_trip, warnings)
+          roles = round_trip.roles
+          return :model   if roles.include?(:assistant)
+          return :harness if roles.include?(:tool)
+          return :event   if roles.include?(:system)
+          return :unknown if roles.include?(:unknown)
+
+          parts   = round_trip.parts
+          results = parts.select { |part| part.type == :tool_result }
+          return :person if results.empty?
+
+          warnings << "round trip #{round_trip.index} mixes a tool result with other parts" if results.size < parts.size
+          :harness
+        end
+
+        # Pairs each call with the result that answers it, by call id —
+        # never by position, since two calls can be in flight at once and
+        # position would match the wrong one.
+        #
+        # Gemini and opencode record a call and its result in ONE message,
+        # so there answered_in == asked_in; the same call-id pairing covers
+        # it without a special case.
+        def pair(round_trips, warnings)
+          results = {}
+          round_trips.each do |trip|
+            trip.parts.each do |part|
+              # a nil call_id cannot be paired and must not collide with another nil
+              next unless part.type == :tool_result && part.call_id
+
+              results[part.call_id] = [trip.index, part]
+            end
+          end
+
+          calls = round_trips.flat_map do |trip|
+            trip.calls.map do |part|
+              # results.delete returns nil when absent, and destructuring nil
+              # gives both index and answer as nil — that is intended, and is
+              # exactly an unanswered call.
+              pair = part.call_id ? results.delete(part.call_id) : nil
+              index, answer = pair
+              ToolCall.new(name: part.name.to_s, call_id: part.call_id,
+                           input_bytes: part.text.to_s.bytesize,
+                           result_bytes: answer && answer.text.to_s.bytesize,
+                           asked_in: trip.index, answered_in: index)
+            end
+          end
+
+          results.each_key { |id| warnings << "tool result #{id} answers no call" }
+          calls
+        end
+
+        def ending_for(round_trips, speakers)
+          return :empty if round_trips.empty?
+
+          last = round_trips.last
+          return :not_a_model_record unless speakers[last.index] == :model
+          return :stopped_in_the_loop if last.calls.any?
+
+          :answered
+        end
+      end
+    end
+  end
+end

data/lib/agent/session_context/loop_view.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    # Renders one Loop for a human (#ascii, #markdown) or a machine (#to_h).
+    #
+    # Every rendering prints SIZES, never BODIES. A transcript can hold a
+    # credential or a customer's data anywhere — even a shell command line
+    # can carry a token — and this gem has no redaction before milestone
+    # 0.5, so a truncated preview is not a safer middle ground; it is the
+    # same leak with extra steps. A byte count and a tool name carry
+    # enough signal to see what a loop did without carrying what it said.
+    #
+    # Every timestamp goes through #utc: two renderings of the same file
+    # must be byte-identical no matter which machine or time zone reads
+    # it, and a local time would make that false for a fact (the
+    # recorded instant) that has not actually changed.
+    #
+    # The ending is always printed as inferred, because Loop#ending is
+    # always a deduction — no on-disk transcript records WHY a session
+    # stopped, since that fact lives in a non-interactive run's streamed
+    # output, never in the file itself. Printing it as a plain fact would
+    # claim information the file does not hold.
+    class LoopView
+      YOU_LANE = 2
+      HARNESS_LANE = 15
+      MODEL_LANE = 50
+
+      # A label is a record TYPE name (hook_success, turn_duration), never
+      # prose — but the field carrying it is a free String, so this shape
+      # check is what actually keeps R9 (no bodies) true the day a format
+      # starts putting a sentence there instead of a type name.
+      LABEL_SHAPE = /\A[A-Za-z0-9_.:-]{1,64}\z/
+
+      def initialize(loop_model)
+        @loop = loop_model
+      end
+
+      def ascii
+        lines = [
+          "session #{@loop.session.uid}",
+          "round trips: #{@loop.round_trips.size}  (grouping: #{grouping})",
+          "tool calls: #{@loop.tool_calls.size}  (#{unanswered_count} unanswered)",
+          "",
+          ascii_header
+        ]
+        @loop.round_trips.each { |trip| lines.concat(ascii_round_trip(trip)) }
+        lines << "" << "ending: #{@loop.ending} (inferred) — #{@loop.ending_detail}"
+        if @loop.warnings.any?
+          lines << "" << "warnings:"
+          @loop.warnings.each { |warning| lines << "  - #{warning}" }
+        end
+        "#{lines.join("\n")}\n"
+      end
+
+      def markdown
+        lines = ["# session #{@loop.session.uid}", "",
+                 "- round trips: #{@loop.round_trips.size} (grouping: #{grouping})",
+                 "- tool calls: #{@loop.tool_calls.size} (#{unanswered_count} unanswered)",
+                 "", "## Round trips", ""]
+        @loop.round_trips.each { |trip| lines << markdown_round_trip(trip) }
+        lines << "" << "## Tool calls" << ""
+        lines.concat(markdown_tool_calls_table)
+        lines << "" << "## Ending" << "" << "#{@loop.ending} (inferred) — #{@loop.ending_detail}"
+        if @loop.warnings.any?
+          lines << "" << "## Warnings" << ""
+          @loop.warnings.each { |warning| lines << "- #{warning}" }
+        end
+        "#{lines.join("\n")}\n"
+      end
+
+      def to_h
+        {
+          session: { agent: @loop.session.agent, id: @loop.session.id, uid: @loop.session.uid },
+          round_trips: @loop.round_trips.map { |trip| round_trip_h(trip) },
+          tool_calls: @loop.tool_calls.map { |call| tool_call_h(call) },
+          ending: { name: @loop.ending, detail: @loop.ending_detail, inferred: true },
+          recorded: @loop.recorded,
+          warnings: @loop.warnings
+        }
+      end
+
+      private
+
+      def lane(text, column) = (" " * column) + text
+
+      # The only "size" a body may leak as: a count, never the bytes themselves.
+      def size_of(part) = part.text.to_s.bytesize
+
+      # UTC, never local: local time would make one recorded instant print
+      # two different strings depending on which machine reads the file,
+      # which breaks the determinism R8 requires.
+      def utc(time) = time&.utc&.iso8601
+
+      # Counts, never a bare "recorded"/"assumed". Loop#recorded is
+      # round_trips.all?(&:recorded), so ONE assumed group collapses the
+      # whole answer to false — and on Claude, the one format that does
+      # name its groups, every user and harness turn carries no message.id
+      # and is assumed by construction. A real session therefore reports
+      # false while 54 of its 109 groups were in fact named by the store,
+      # and printing that as the single word "assumed" tells the reader
+      # this format records nothing. That is the confusion the gem's
+      # standing rule forbids: "the store does not record this" must never
+      # read the same as "the store recorded none here", in either
+      # direction. So say how many, and let the two cases differ visibly.
+      def grouping
+        named = @loop.round_trips.count(&:recorded)
+        return "no round trips" if @loop.round_trips.empty?
+        return "all #{named} named by the store" if named == @loop.round_trips.size
+        return "none named by the store; one round trip per message" if named.zero?
+
+        "#{named} of #{@loop.round_trips.size} named by the store"
+      end
+
+      def unanswered_count = @loop.tool_calls.count { |call| !call.answered? }
+
+      def ascii_header
+        line = "#{lane("YOU", YOU_LANE).ljust(HARNESS_LANE)}HARNESS"
+        "#{line.ljust(MODEL_LANE)}MODEL"
+      end
+
+      def ascii_round_trip(trip)
+        case @loop.speakers[trip.index]
+        when :person  then [ascii_person(trip)]
+        when :model   then ascii_model(trip)
+        when :harness then ascii_harness(trip)
+        when :event   then [lane("#{trip.index} [event] #{event_labels(trip)}", HARNESS_LANE)]
+        else               [lane("#{trip.index} [unrecognized record]", HARNESS_LANE)]
+        end
+      end
+
+      def ascii_person(trip)
+        bytes = trip.parts.sum { |part| size_of(part) }
+        lane("#{trip.index} prompt  #{bytes} B", YOU_LANE)
+      end
+
+      def ascii_model(trip)
+        lines = [lane("#{trip.index} == round trip ==>", HARNESS_LANE)]
+        trip.parts.each { |part| lines << lane(part_line(part), MODEL_LANE) }
+        lines << lane(usage_line(trip.usage), MODEL_LANE) if trip.usage
+        verdict = trip.calls.any? ? "tool_use: keep looping" : "no tool_use: exit"
+        lines << lane("#{trip.index} <== #{verdict}", HARNESS_LANE)
+      end
+
+      def ascii_harness(trip)
+        trip.parts.select { |part| part.type == :tool_result }.map do |part|
+          lane("#{trip.index} <- tool_result  #{tool_name_for(part.call_id)}  #{size_of(part)} B  " \
+               "(#{part.call_id || "no call id"})", HARNESS_LANE)
+        end
+      end
+
+      # T4: how ONE content part is shown, inside any round trip that
+      # prints its parts one by one. tool_use gets its name plus the size
+      # of what it asked for; text/thinking/tool_result get a bare size;
+      # image/unknown get only their type name, because the gem never
+      # loads those payloads and so has no size worth calling meaningful.
+      def part_line(part)
+        case part.type
+        when :tool_use    then "tool_use  #{part.name}  #{size_of(part)} B"
+        when :tool_result then "tool_result  #{size_of(part)} B"
+        when :text        then "text  #{size_of(part)} B"
+        when :thinking    then "thinking  #{size_of(part)} B"
+        else part.type.to_s
+        end
+      end
+
+      def usage_line(usage) = "usage #{usage_fields(usage).join(" ")}"
+
+      def usage_fields(usage)
+        { "in" => usage.input, "out" => usage.output, "cache_read" => usage.cache_read,
+          "cache_creation" => usage.cache_creation, "reasoning" => usage.reasoning }
+          .compact
+          .map { |key, value| "#{key}=#{value}" }
+      end
+
+      # `?` here means exactly what it means everywhere else in this gem:
+      # the fact is not knowable from what was recorded, never zero.
+      def tool_name_for(call_id)
+        return "?" if call_id.nil?
+
+        @loop.tool_calls.find { |call| call.call_id == call_id }&.name || "?"
+      end
+
+      # R11: a part's text prints as a label only when it is label-shaped
+      # (a record TYPE name); anything else — including a stray sentence a
+      # future format might put in this free-String field — prints the
+      # part's own type name instead, so R9 (no bodies) cannot be broken
+      # by a format that starts putting prose where a type name belongs.
+      def event_labels(trip)
+        trip.parts.map { |part| label_shaped?(part.text) ? part.text : part.type.to_s }.join(", ")
+      end
+
+      def label_shaped?(text) = text.is_a?(String) && LABEL_SHAPE.match?(text)
+
+      def markdown_round_trip(trip)
+        speaker = @loop.speakers[trip.index]
+        parts = speaker == :event ? event_labels(trip) : markdown_parts(trip)
+        entry = "#{trip.index}. **#{speaker}** — #{parts}"
+        at = utc(trip.at)
+        entry += " — at #{at}" if at
+        entry += " — #{usage_line(trip.usage)}" if trip.usage
+        entry
+      end
+
+      def markdown_parts(trip)
+        return "(no parts)" if trip.parts.empty?
+
+        trip.parts.map { |part| part_line(part) }.join("; ")
+      end
+
+      def markdown_tool_calls_table
+        [
+          "| tool | call id | input | result | asked in | answered in |",
+          "|---|---|---|---|---|---|",
+          *@loop.tool_calls.map { |call| markdown_tool_call_row(call) }
+        ]
+      end
+
+      def markdown_tool_call_row(call)
+        # An unanswered call must read as "no answer recorded", never
+        # "0 B" — the same distinction ToolCall#result_bytes itself draws,
+        # repeated here because nil-to-string interpolation would
+        # otherwise silently print an empty cell instead of saying so.
+        result = call.answered? ? "#{call.result_bytes} B" : "no answer recorded"
+        "| #{call.name} | #{call.call_id || "no call id"} | #{call.input_bytes} B | #{result} | " \
+          "#{call.asked_in} | #{call.answered_in || "-"} |"
+      end
+
+      def round_trip_h(trip)
+        { index: trip.index, speaker: @loop.speakers[trip.index], recorded: trip.recorded,
+          roles: trip.roles, at: utc(trip.at), model: trip.model, usage: trip.usage&.to_h,
+          parts: trip.parts.map { |part| part_h(part) } }
+      end
+
+      # name is populated for :tool_use alone (the tool's own name); every
+      # other type — including :image/:unknown — carries nil, since a
+      # size is not a body but any other free-text field on the part
+      # would be.
+      def part_h(part) = { type: part.type, name: part.type == :tool_use ? part.name : nil, bytes: size_of(part) }
+
+      def tool_call_h(call)
+        { name: call.name, call_id: call.call_id, input_bytes: call.input_bytes,
+          result_bytes: call.result_bytes, asked_in: call.asked_in, answered_in: call.answered_in,
+          answered: call.answered? }
+      end
+    end
+  end
+end

data/lib/agent/session_context/prompt.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    Prompt = Data.define(:index, :at, :text, :source_refs) do
+      def initialize(index:, at:, text:, source_refs:)
+        super(
+          index: normalize_positive_index(index),
+          at: at,
+          text: normalize_string(text, :text),
+          source_refs: ImmutableValue.copy(Array(source_refs))
+        )
+      end
+
+      private
+
+      def normalize_positive_index(value)
+        index =
+          if value.is_a?(Integer)
+            value
+          elsif value.respond_to?(:to_int)
+            value.to_int
+          elsif value.is_a?(String)
+            Integer(value, exception: false)
+          end
+
+        raise TypeError, "index must be an Integer or integer-like value" if index.nil?
+        raise ArgumentError, "index must be greater than or equal to 1" if index < 1
+
+        index
+      end
+
+      def normalize_string(value, name)
+        raise TypeError, "#{name} must be a String" unless value.respond_to?(:to_str)
+
+        String.new(value.to_str).freeze
+      end
+    end
+  end
+end

data/lib/agent/session_context/prompt_extractor.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    class PromptExtractor
+      def call(transcript)
+        prompt_index = 0
+
+        prompts = transcript.entries.each_with_object([]) do |entry, collected|
+          next unless entry.role == :user
+
+          contributing_parts = entry.parts.select { |part| part.type == :text && !part.injected }
+          next if contributing_parts.empty?
+
+          text = contributing_parts.map(&:text).join
+          next if text.empty?
+
+          prompt_index += 1
+          collected << Prompt.new(
+            index: prompt_index,
+            at: entry.at,
+            text: text,
+            source_refs: contributing_parts.map(&:source_ref)
+          )
+        end
+
+        prompts.freeze
+      end
+    end
+  end
+end

data/lib/agent/session_context/renderers/human_display.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    module Renderers
+      module HumanDisplay
+        module_function
+
+        def text_inline(value)
+          sanitize_string(value, preserve_newlines: false)
+        end
+
+        def text_block(value)
+          sanitize_string(value, preserve_newlines: true).split("\n", -1).map { |line| "| #{line}" }.join("\n")
+        end
+
+        def markdown_text(value)
+          escape_markdown(text_inline(value))
+        end
+
+        def markdown_literal(value)
+          literal = text_inline(value)
+          return "<code></code>" if literal.empty?
+          return "<code>#{literal}</code>" if literal.match?(/\A +\z/)
+
+          fence = "`" * [longest_backtick_run(literal) + 1, 1].max
+          "#{fence}#{code_span_content(literal)}#{fence}"
+        end
+
+        def markdown_block(value)
+          content = sanitize_string(value, preserve_newlines: true)
+          fence = "`" * [longest_backtick_run(content) + 1, 3].max
+
+          ["#{fence}text", content, fence].join("\n")
+        end
+
+        def timestamp(value)
+          serialized = Serializer.serialize_timestamp(value)
+          return if serialized.nil?
+
+          serialized.to_s
+        end
+
+        def refs(source_refs)
+          Array(source_refs).map { |ref| "#{ref.message_index}:#{ref.part_index}" }.join(", ")
+        end
+
+        def attributes(hash, inline_formatter:)
+          Serializer.normalized_hash_entries(hash).map do |key, value|
+            "#{inline_formatter.call(key)}=#{attribute_value(value, inline_formatter)}"
+          end.join(", ")
+        end
+
+        def attribute_value(value, inline_formatter)
+          return "{#{attributes(value, inline_formatter:)}}" if value.is_a?(Hash)
+          return value.map { |entry| attribute_value(entry, inline_formatter) }.join(",") if value.is_a?(Array)
+
+          inline_formatter.call(Serializer.serialize(value).to_s)
+        end
+
+        def sanitize_string(value, preserve_newlines:)
+          scrubbed = Serializer.scrub_string(value.to_s)
+          buffer = String.new(encoding: Encoding::UTF_8)
+
+          scrubbed.each_codepoint do |codepoint|
+            if preserve_newlines && codepoint == 0x0A
+              buffer << "\n"
+              next
+            end
+
+            visible = visible_control_escape(codepoint)
+            buffer << (visible || codepoint)
+          end
+
+          buffer
+        end
+
+        def escape_markdown(value)
+          escaped = value.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+          escaped = escaped.gsub(/([\\`*\[\]#])/, "\\\\\\1")
+          escaped = escaped.gsub(/(^|[^[:alnum:]])_([^_]+)_([^[:alnum:]]|$)/, '\1\\_\2\\_\3')
+          escaped.gsub("-", "\\-")
+        end
+
+        def code_span_content(literal)
+          return " #{literal} " if literal.start_with?("`") || literal.end_with?("`")
+          return " #{literal} " if literal.start_with?(" ") && literal.end_with?(" ")
+
+          literal
+        end
+
+        def longest_backtick_run(value)
+          value.scan(/`+/).map(&:length).max || 0
+        end
+
+        def visible_control_escape(codepoint)
+          case codepoint
+          when 0x09
+            "\\t"
+          when 0x0A
+            "\\n"
+          when 0x0D
+            "\\r"
+          when 0x1B
+            "\\e"
+          when 0x00..0x08, 0x0B..0x0C, 0x0E..0x1A, 0x1C..0x1F, 0x7F, 0x80..0x9F
+            format("\\u%04X", codepoint)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agent/session_context/renderers/json.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    module Renderers
+      class JSON
+        def call(value)
+          # A Loop must never reach Serializer.serialize directly: Serializer
+          # walks any Data object generically by its members, and Loop holds
+          # round_trips -> Message#raw, the full on-disk record with every
+          # prompt and tool-result body. LoopView#to_h is the Hash that
+          # already strips bodies down to sizes and tool names — serialize
+          # THAT, never the Loop itself.
+          return ::JSON.generate(Serializer.serialize(LoopView.new(value).to_h)) if value.is_a?(Loop)
+
+          ::JSON.generate(Serializer.serialize(value))
+        end
+      end
+    end
+  end
+end

data/lib/agent/session_context/renderers/json_lines.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    module Renderers
+      class JSONLines
+        def call(value)
+          # Same privacy rule as Renderers::JSON: never hand the Loop itself
+          # (or its round trips, which carry Message#raw) to Serializer. One
+          # line per round trip, from the already-stripped LoopView Hash.
+          return loop_lines(value) if value.is_a?(Loop)
+
+          Array(value).map { |prompt| ::JSON.generate(Serializer.serialize(prompt)) }.join("\n")
+        end
+
+        private
+
+        def loop_lines(loop_model)
+          round_trips = LoopView.new(loop_model).to_h.fetch(:round_trips)
+          round_trips.map { |round_trip| ::JSON.generate(Serializer.serialize(round_trip)) }.join("\n")
+        end
+      end
+    end
+  end
+end