agent-session_context 0.1.0

data/lib/agent/session_context/summarizers/command_execution_policy.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    module Summarizers
+      module CommandExecutionPolicy
+        COMMON_ENV_KEYS = %w[
+          ALL_PROXY
+          HOME
+          HTTP_PROXY
+          HTTPS_PROXY
+          LANG
+          NO_PROXY
+          PATH
+          SSL_CERT_DIR
+          SSL_CERT_FILE
+          all_proxy
+          http_proxy
+          https_proxy
+          no_proxy
+        ].freeze
+        private_constant :COMMON_ENV_KEYS
+
+        private
+
+        def initialize_command_execution_policy(runner:, timeout_seconds:, max_output_bytes:, provider_env_keys:)
+          @timeout_seconds = timeout_seconds
+          @max_output_bytes = max_output_bytes
+          @provider_env_keys = provider_env_keys.dup.freeze
+          @runner = runner || SubprocessRunner.new(timeout_seconds:, max_output_bytes:)
+        end
+
+        def run_command!(prompt:, argv:)
+          response = @runner.call(env: child_env, argv:, stdin_data: prompt)
+          validate_runner_response!(response)
+        rescue Errno::ENOENT => e
+          raise SummarizerUnavailable, "#{name} summarizer is unavailable: #{e.message}"
+        rescue SubprocessRunner::TimeoutError
+          raise SummarizerFailed, "#{name} summarizer exceeded its #{@timeout_seconds}-second timeout"
+        rescue SubprocessRunner::OutputLimitError => e
+          raise SummarizerFailed,
+                "#{name} summarizer #{translated_stream_label(e.stream)} exceeded #{@max_output_bytes} bytes"
+        end
+
+        def validate_runner_response!(response)
+          unless response.is_a?(Array) && response.length == 3
+            raise SummarizerFailed, "#{name} summarizer runner must return [stdout, stderr, status]"
+          end
+
+          stdout, stderr, status = response
+
+          unless status.respond_to?(:success?)
+            raise SummarizerFailed, "#{name} summarizer runner must return a status with #success?"
+          end
+
+          unless stdout.nil? || stdout.is_a?(String)
+            raise SummarizerFailed, "#{name} summarizer runner must return stdout as a String"
+          end
+
+          unless stderr.nil? || stderr.is_a?(String)
+            raise SummarizerFailed, "#{name} summarizer runner must return stderr as a String"
+          end
+
+          stdout = stdout.to_s
+          stderr = stderr.to_s
+          enforce_output_bounds!("stdout", stdout, status:)
+          enforce_output_bounds!("stderr", stderr, status:)
+
+          [stdout, stderr, status]
+        end
+
+        def failure_message(summary, stdout: nil, stderr: nil, output: nil, status: nil)
+          fragments = [summary]
+          append_stream_metadata(fragments, "stdout", stdout)
+          append_stream_metadata(fragments, "stderr", stderr)
+          append_stream_metadata(fragments, "output", output)
+          append_status_metadata(fragments, status)
+          fragments.join(". ")
+        end
+
+        def child_env
+          ENV.each_with_object({}) do |(key, value), filtered|
+            filtered[key] = value if allowed_env_key?(key)
+          end
+        end
+
+        def allowed_env_key?(key)
+          COMMON_ENV_KEYS.include?(key) || @provider_env_keys.include?(key) || key.start_with?("LC_")
+        end
+
+        def enforce_output_bounds!(label, value, status:)
+          return if value.bytesize <= @max_output_bytes
+
+          raise SummarizerFailed, failure_message(
+            "#{name} summarizer #{label} exceeded #{@max_output_bytes} bytes",
+            status:,
+            stdout: label == "stdout" ? value : nil,
+            stderr: label == "stderr" ? value : nil
+          )
+        end
+
+        def append_stream_metadata(fragments, label, value)
+          state =
+            if value.nil?
+              "absent"
+            elsif value.empty?
+              "empty"
+            else
+              "present"
+            end
+
+          bytesize = value.nil? ? 0 : value.bytesize
+          fragments << "#{label}=#{state}(#{bytesize} bytes)"
+        end
+
+        def append_status_metadata(fragments, status)
+          return unless status.respond_to?(:exitstatus)
+
+          exitstatus = status.exitstatus
+          return if exitstatus.nil?
+
+          fragments << "exit_status=#{exitstatus}"
+        end
+
+        def translated_stream_label(stream)
+          return "stdout" if stream.equal?(:stdout)
+          return "stderr" if stream.equal?(:stderr)
+
+          "output"
+        end
+      end
+    end
+  end
+end

data/lib/agent/session_context/summarizers.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    module Summarizers
+      module_function
+
+      def for(name, timeout_seconds: Config::DEFAULT_TIMEOUT_SECONDS)
+        case normalize_name(name)
+        when :codex then Codex.new(timeout_seconds:)
+        when :claude then Claude.new(timeout_seconds:)
+        else
+          raise unsupported_summarizer(name)
+        end
+      end
+
+      def normalize_name(name)
+        return name if name.is_a?(Symbol)
+        raise unsupported_summarizer(name) unless name.respond_to?(:to_sym)
+
+        normalized = name.to_sym
+        raise unsupported_summarizer(name) unless normalized.is_a?(Symbol)
+
+        normalized
+      rescue NoMethodError, TypeError, ArgumentError
+        raise unsupported_summarizer(name)
+      end
+
+      def unsupported_summarizer(name)
+        UnsupportedAgent.new("unsupported summarizer #{name.inspect}; use claude or codex")
+      end
+      private_class_method :normalize_name, :unsupported_summarizer
+    end
+  end
+end

data/lib/agent/session_context/summary_parser.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    class SummaryParser
+      Result = Data.define(:items, :warnings)
+
+      ALLOWED_EVIDENCE = %w[explicit inferred].freeze
+      TEXT_KEYS = %w[text evidence source_refs].freeze
+      TERM_KEYS = %w[term definition evidence source_refs].freeze
+      ITEM_KEYS = {
+        text: TEXT_KEYS,
+        term: TERM_KEYS
+      }.freeze
+      REQUIRED_CATEGORIES = SemanticCategories.external_keys
+
+      def call(json, allowed_refs:)
+        payload = parse_payload(json)
+        allowed_ref_index = build_allowed_ref_index(allowed_refs)
+        validate_known_categories!(payload)
+        warnings = []
+        merged_items = {}
+        ordered_items = []
+
+        payload.each do |category, value|
+          definition = SemanticCategories.lookup(category)
+          unless definition
+            warnings << "Dropped unknown category #{category.inspect}"
+            next
+          end
+
+          value.each_with_index do |raw_item, item_index|
+            item = parse_item(definition, raw_item, item_index, allowed_ref_index, warnings)
+            next unless item
+
+            key = [item.kind, item.label, item.detail]
+            existing = merged_items[key]
+
+            if existing
+              merged_items[key] = merge_item_refs(existing, item)
+            else
+              merged_items[key] = item
+              ordered_items << key
+            end
+          end
+        end
+
+        Result.new(
+          items: ordered_items.map { |key| merged_items.fetch(key) }.freeze,
+          warnings: warnings.map { |warning| String.new(warning).freeze }.freeze
+        )
+      end
+
+      private
+
+      def parse_payload(json)
+        payload = JSON.parse(json)
+      rescue JSON::ParserError
+        raise InvalidSummary, "Invalid JSON summary. Provide a JSON top-level object with the supported categories."
+      else
+        raise InvalidSummary, "Summary must be a JSON top-level object." unless payload.is_a?(Hash)
+
+        payload
+      end
+
+      def validate_known_categories!(payload)
+        REQUIRED_CATEGORIES.each do |category|
+          next unless payload.key?(category)
+
+          raise InvalidSummary, "#{category} must be an array" unless payload[category].is_a?(Array)
+        end
+
+        missing_categories = REQUIRED_CATEGORIES - payload.keys
+        return if missing_categories.empty?
+
+        raise InvalidSummary,
+              "Summary is missing required categories: #{missing_categories.join(", ")}"
+      end
+
+      def build_allowed_ref_index(allowed_refs)
+        normalize_allowed_refs(allowed_refs).to_h do |source_ref|
+          [source_ref.to_s, source_ref]
+        end
+      end
+
+      def normalize_allowed_refs(allowed_refs)
+        refs =
+          if allowed_refs.is_a?(Array)
+            allowed_refs
+          elsif allowed_refs.respond_to?(:to_a) && !allowed_refs.is_a?(String)
+            allowed_refs.to_a
+          elsif allowed_refs.respond_to?(:each) && !allowed_refs.is_a?(String)
+            allowed_refs.each_with_object([]) { |source_ref, collected| collected << source_ref }
+          else
+            raise TypeError, "allowed_refs must be an enumerable of Agent::SessionContext::SourceRef objects"
+          end
+
+        refs.each do |source_ref|
+          unless source_ref.is_a?(SourceRef)
+            raise TypeError,
+                  "allowed_refs must contain only Agent::SessionContext::SourceRef objects"
+          end
+        end
+
+        refs
+      end
+
+      def parse_item(category, raw_item, item_index, allowed_ref_index, warnings)
+        category_name = category.external_key
+
+        unless raw_item.is_a?(Hash)
+          warnings << "Dropped #{category_name}[#{item_index}] because items must be objects"
+          return
+        end
+
+        expected_keys = ITEM_KEYS.fetch(category.item_shape)
+        raw_keys = raw_item.keys.sort
+
+        unless raw_keys == expected_keys.sort
+          warnings << key_mismatch_warning(category_name, item_index, raw_keys, expected_keys)
+          return
+        end
+
+        evidence = raw_item["evidence"]
+        unless ALLOWED_EVIDENCE.include?(evidence)
+          warnings << "Dropped #{category_name}[#{item_index}] because evidence must be explicit or inferred"
+          return
+        end
+
+        refs = resolve_source_refs(category_name, item_index, raw_item["source_refs"], allowed_ref_index, warnings)
+        return unless refs
+
+        case category.item_shape
+        when :term
+          term = raw_item["term"]
+          definition = raw_item["definition"]
+
+          unless term.is_a?(String)
+            warnings << "Dropped #{category_name}[#{item_index}] because term must be a string"
+            return
+          end
+
+          unless definition.is_a?(String)
+            warnings << "Dropped #{category_name}[#{item_index}] because definition must be a string"
+            return
+          end
+
+          Item.new(
+            kind: category.internal_kind,
+            label: term,
+            detail: definition,
+            evidence: evidence.to_sym,
+            source_refs: refs
+          )
+        else
+          text = raw_item["text"]
+          unless text.is_a?(String)
+            warnings << "Dropped #{category_name}[#{item_index}] because text must be a string"
+            return
+          end
+
+          Item.new(
+            kind: category.internal_kind,
+            label: text,
+            detail: nil,
+            evidence: evidence.to_sym,
+            source_refs: refs
+          )
+        end
+      end
+
+      def resolve_source_refs(category, item_index, raw_refs, allowed_ref_index, warnings)
+        unless raw_refs.is_a?(Array) && !raw_refs.empty? && raw_refs.all?(String)
+          warnings << "Dropped #{category}[#{item_index}] because source_refs must be a non-empty array of strings"
+          return
+        end
+
+        resolved = raw_refs.map { |value| allowed_ref_index[value] }
+        if resolved.any?(&:nil?)
+          warnings << "Dropped #{category}[#{item_index}] because it referenced an unknown source ref"
+          return
+        end
+
+        resolved.uniq.freeze
+      end
+
+      def merge_item_refs(existing, item)
+        Item.new(
+          kind: existing.kind,
+          label: existing.label,
+          detail: existing.detail,
+          evidence: merged_evidence(existing.evidence, item.evidence),
+          source_refs: (existing.source_refs + item.source_refs).uniq,
+          attributes: existing.attributes
+        )
+      end
+
+      def merged_evidence(left, right)
+        return :explicit if left == :explicit || right == :explicit
+
+        :inferred
+      end
+
+      def key_mismatch_warning(category, item_index, raw_keys, expected_keys)
+        missing_keys = expected_keys - raw_keys
+        extra_keys = raw_keys - expected_keys
+        details = []
+        details << "missing #{missing_keys.join(", ")}" unless missing_keys.empty?
+        details << "extra keys #{extra_keys.join(", ")}" unless extra_keys.empty?
+        details << "additional properties are not allowed" unless extra_keys.empty?
+        detail_text = details.join("; ")
+        detail_suffix = " (#{detail_text})" unless detail_text.empty?
+
+        "Dropped #{category}[#{item_index}] because item keys must exactly match " \
+          "#{expected_keys.join(", ")}#{detail_suffix}"
+      end
+    end
+  end
+end

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 = "0.1.0"
+  end
+end

data/lib/agent/session_context.rb

@@ -0,0 +1,56 @@
+# 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 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