agent_session_context 1.0.0

data/lib/agent/session_context/transcript.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    TranscriptPart = Data.define(:index, :type, :text, :name, :call_id, :injected, :source_ref) do
+      def initialize(index:, type:, injected:, source_ref:, text: nil, name: nil, call_id: nil)
+        super(
+          index: normalize_positive_index(index, :index),
+          type: normalize_symbol(type, :type),
+          text: normalize_optional_string(text, :text),
+          name: normalize_optional_string(name, :name),
+          call_id: normalize_optional_string(call_id, :call_id),
+          injected: normalize_boolean(injected),
+          source_ref: normalize_source_ref(source_ref)
+        )
+      end
+
+      private
+
+      def normalize_positive_index(value, name)
+        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, "#{name} must be an Integer or integer-like value" if index.nil?
+        raise ArgumentError, "#{name} must be greater than or equal to 1" if index < 1
+
+        index
+      end
+
+      def normalize_symbol(value, name)
+        return value if value.is_a?(Symbol)
+        return value.to_sym if value.respond_to?(:to_sym)
+
+        raise TypeError, "#{name} must be symbolizable"
+      end
+
+      def normalize_optional_string(value, name)
+        return if value.nil?
+
+        raise TypeError, "#{name} must be a String" unless value.respond_to?(:to_str)
+
+        String.new(value.to_str).freeze
+      end
+
+      def normalize_boolean(value)
+        return value if [true, false].include?(value)
+
+        raise TypeError, "injected must be true or false"
+      end
+
+      def normalize_source_ref(value)
+        raise TypeError, "source_ref must be an Agent::SessionContext::SourceRef" unless value.is_a?(SourceRef)
+
+        value
+      end
+    end
+
+    TranscriptEntry = Data.define(:index, :role, :at, :parts) do
+      def initialize(index:, role:, at:, parts:)
+        super(
+          index: normalize_positive_index(index, :index),
+          role: normalize_symbol(role, :role),
+          at: at,
+          parts: normalize_parts(parts)
+        )
+      end
+
+      private
+
+      def normalize_positive_index(value, name)
+        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, "#{name} must be an Integer or integer-like value" if index.nil?
+        raise ArgumentError, "#{name} must be greater than or equal to 1" if index < 1
+
+        index
+      end
+
+      def normalize_symbol(value, name)
+        return value if value.is_a?(Symbol)
+        return value.to_sym if value.respond_to?(:to_sym)
+
+        raise TypeError, "#{name} must be symbolizable"
+      end
+
+      def normalize_parts(value)
+        Array(value).map do |part|
+          unless part.is_a?(TranscriptPart)
+            raise TypeError,
+                  "parts must contain only Agent::SessionContext::TranscriptPart values"
+          end
+
+          part
+        end.freeze
+      end
+    end
+
+    Transcript = Data.define(:session, :captured_at, :entries, :warnings) do
+      class << self
+        def capture(session, reader: Agent::Sessions.read(session), now: Time.now)
+          entries = []
+
+          reader.each_message.with_index(1) do |message, message_index|
+            entries << TranscriptEntry.new(
+              index: message_index,
+              role: message.role,
+              at: message.at,
+              parts: capture_parts(session, message, message_index)
+            )
+          end
+
+          new(
+            session: session,
+            captured_at: now,
+            entries: entries.freeze,
+            warnings: capture_warnings(reader)
+          )
+        end
+
+        def injection_kind(agent, text)
+          return unless text.is_a?(String)
+
+          stripped_text = text.b.lstrip
+          marker_kinds = Transcript::INJECTION_MARKERS.fetch(agent&.to_sym, {})
+          match = marker_kinds.find { |marker, _kind| stripped_text.start_with?(marker.b) }
+          match&.last
+        end
+
+        private
+
+        def capture_parts(session, message, message_index)
+          message.parts.each_with_index.map do |part, part_index|
+            TranscriptPart.new(
+              index: part_index + 1,
+              type: part.type,
+              text: part.text,
+              name: part.name,
+              call_id: part.call_id,
+              injected: injected_part?(session.agent, message, part),
+              source_ref: SourceRef.new(
+                session_uid: session.uid,
+                message_index: message_index,
+                part_index: part_index + 1
+              )
+            )
+          end.freeze
+        end
+
+        def capture_warnings(reader)
+          Array(reader.warnings).map do |warning|
+            raise TypeError, "warning must be a String" unless warning.respond_to?(:to_str)
+
+            String.new(warning.to_str).freeze
+          end.freeze
+        end
+
+        def injected_part?(agent, message, part)
+          return false unless message.role == :user
+          return false unless part.type == :text
+
+          raw_meta_message?(message.raw) || marker_injected?(agent, part.text)
+        end
+
+        def raw_meta_message?(raw)
+          raw.is_a?(Hash) && raw["isMeta"] == true
+        end
+
+        def marker_injected?(agent, text)
+          !injection_kind(agent, text).nil?
+        end
+      end
+
+      def initialize(session:, captured_at:, entries:, warnings:)
+        super(
+          session: session,
+          captured_at: captured_at,
+          entries: normalize_entries(entries),
+          warnings: normalize_warnings(warnings)
+        )
+      end
+
+      private
+
+      def normalize_entries(value)
+        Array(value).map do |entry|
+          unless entry.is_a?(TranscriptEntry)
+            raise TypeError,
+                  "entries must contain only Agent::SessionContext::TranscriptEntry values"
+          end
+
+          entry
+        end.freeze
+      end
+
+      def normalize_warnings(value)
+        Array(value).map do |warning|
+          raise TypeError, "warning must be a String" unless warning.respond_to?(:to_str)
+
+          String.new(warning.to_str).freeze
+        end.freeze
+      end
+    end
+
+    Transcript.const_set(
+      :INJECTION_MARKERS,
+      {
+        claude: {
+          "<command-name>" => :command_name,
+          "<command-message>" => :command_message,
+          "<command-args>" => :command_args,
+          "<local-command-stdout>" => :local_command_stdout,
+          "<local-command-stderr>" => :local_command_stderr,
+          "<system-reminder>" => :system_reminder
+        }.freeze,
+        codex: {
+          "<environment_context>" => :environment_context,
+          "<user_instructions>" => :user_instructions,
+          "# AGENTS.md instructions" => :agents_instructions
+        }.freeze
+      }.freeze
+    )
+  end
+end

data/lib/agent/session_context/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    VERSION = "1.0.0"
+  end
+end

data/lib/agent/session_context.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "agent_sessions"
+require "zeitwerk"
+require_relative "session_context/errors"
+
+module Agent
+  module SessionContext
+    LOADER = Zeitwerk::Loader.for_gem_extension(Agent)
+    LOADER.ignore(File.expand_path("session_context/errors.rb", __dir__))
+    LOADER.inflector.inflect("cli" => "CLI", "json" => "JSON", "json_lines" => "JSONLines")
+    LOADER.setup
+    private_constant :LOADER
+
+    class << self
+      def resolve(identifier, agent: nil, env: ENV, catalog: Agent::Sessions)
+        SessionResolver.new(catalog:, env: env).resolve(identifier, agent: agent)
+      end
+
+      def current(agent: nil, env: ENV, catalog: Agent::Sessions)
+        SessionResolver.new(catalog:, env: env).current(agent:)
+      end
+
+      def show(session, include_injected: false, **)
+        Builder.new(**).show(session, include_injected:)
+      end
+
+      def prompts(session, **)
+        Builder.new(**).prompts(session)
+      end
+
+      def loop(session, **)
+        Builder.new(**).loop(session)
+      end
+
+      def summarize(
+        session,
+        using: nil,
+        summarizer: nil,
+        timeout: nil,
+        env: ENV,
+        config_loader: Config,
+        backend_factory: Summarizers,
+        **
+      )
+        if summarizer
+          raise ArgumentError, "timeout applies only to built-in summarizers" unless timeout.nil?
+
+          return Builder.new(**).summarize(session, summarizer:)
+        end
+
+        config = config_loader.load(session:, env:, timeout:)
+        backend = backend_factory.for(using || session.agent, timeout_seconds: config.timeout_seconds)
+        Builder.new(**).summarize(session, summarizer: backend)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: agent_session_context
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Lucian Ghinda
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: agent_sessions
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+description: Shows exact prompts and evidence-backed context summaries for Claude
+  Code and Codex CLI sessions.
+email:
+- dev@ghinda.com
+executables:
+- agent-session-context
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/agent-session-context
+- lib/agent/session_context.rb
+- lib/agent/session_context/builder.rb
+- lib/agent/session_context/cli.rb
+- lib/agent/session_context/cli/options.rb
+- lib/agent/session_context/config.rb
+- lib/agent/session_context/errors.rb
+- lib/agent/session_context/evidence_collector.rb
+- lib/agent/session_context/evidence_packet.rb
+- lib/agent/session_context/immutable_value.rb
+- lib/agent/session_context/injected_context.rb
+- lib/agent/session_context/injected_context_collector.rb
+- lib/agent/session_context/item.rb
+- lib/agent/session_context/loop.rb
+- lib/agent/session_context/loop_view.rb
+- lib/agent/session_context/prompt.rb
+- lib/agent/session_context/prompt_extractor.rb
+- lib/agent/session_context/renderers/human_display.rb
+- lib/agent/session_context/renderers/json.rb
+- lib/agent/session_context/renderers/json_lines.rb
+- lib/agent/session_context/renderers/markdown.rb
+- lib/agent/session_context/renderers/serializer.rb
+- lib/agent/session_context/renderers/text.rb
+- lib/agent/session_context/semantic_categories.rb
+- lib/agent/session_context/semantic_pipeline.rb
+- lib/agent/session_context/semantic_schema.rb
+- lib/agent/session_context/session_resolver.rb
+- lib/agent/session_context/snapshot.rb
+- lib/agent/session_context/source_ref.rb
+- lib/agent/session_context/subprocess_runner.rb
+- lib/agent/session_context/summarizers.rb
+- lib/agent/session_context/summarizers/claude.rb
+- lib/agent/session_context/summarizers/codex.rb
+- lib/agent/session_context/summarizers/command_execution_policy.rb
+- lib/agent/session_context/summary_parser.rb
+- lib/agent/session_context/tool_call.rb
+- lib/agent/session_context/transcript.rb
+- lib/agent/session_context/version.rb
+homepage: https://github.com/lucianghinda/agent_session_context
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/lucianghinda/agent_session_context/issues
+  changelog_uri: https://github.com/lucianghinda/agent_session_context/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/lucianghinda/agent_session_context
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.11
+specification_version: 4
+summary: Inspect and summarize recorded AI agent session context
+test_files: []