agent_session_context 1.0.0

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Agent
+  module SessionContext
+    module Summarizers
+      class Claude
+        include CommandExecutionPolicy
+
+        MAX_OUTPUT_BYTES = 1_048_576
+        PROVIDER_ENV_KEYS = %w[ANTHROPIC_API_KEY CLAUDE_CODE_OAUTH_TOKEN CLAUDE_CONFIG_DIR].freeze
+        private_constant :PROVIDER_ENV_KEYS
+
+        def initialize(runner: nil, timeout_seconds: Config::DEFAULT_TIMEOUT_SECONDS)
+          initialize_command_execution_policy(
+            runner:,
+            timeout_seconds:,
+            max_output_bytes: MAX_OUTPUT_BYTES,
+            provider_env_keys: PROVIDER_ENV_KEYS
+          )
+        end
+
+        def name
+          :claude
+        end
+
+        def call(prompt:, schema:)
+          stdout, stderr, status = run_command!(prompt:, argv: command_argv(schema))
+          fail_command!(stdout:, stderr:, status:) unless status.success?
+          if stdout.strip.empty?
+            raise SummarizerFailed, failure_message(
+              "#{name} summarizer produced empty stdout",
+              stdout:,
+              stderr:
+            )
+          end
+
+          envelope = parse_envelope!(stdout, stderr:)
+          field_name, value = extract_structured_value!(envelope)
+
+          normalize_value!(value, field_name:, stdout:, stderr:)
+        end
+
+        private
+
+        def command_argv(schema)
+          [
+            "claude",
+            "--print",
+            "--safe-mode",
+            "--tools",
+            "",
+            "--no-session-persistence",
+            "--output-format",
+            "json",
+            "--json-schema",
+            JSON.generate(schema)
+          ]
+        end
+
+        def parse_envelope!(stdout, stderr:)
+          envelope = JSON.parse(stdout)
+          unless envelope.is_a?(Hash)
+            raise SummarizerFailed, failure_message(
+              "#{name} summarizer produced a non-object JSON envelope",
+              stdout:,
+              stderr:
+            )
+          end
+
+          envelope
+        rescue JSON::ParserError, EncodingError, ArgumentError
+          raise SummarizerFailed, failure_message(
+            "#{name} summarizer produced invalid JSON envelope",
+            stdout:,
+            stderr:
+          )
+        end
+
+        def extract_structured_value!(envelope)
+          return ["structured_output", envelope["structured_output"]] if envelope.key?("structured_output")
+          return ["result", envelope["result"]] if envelope.key?("result")
+
+          raise SummarizerFailed, "#{name} summarizer JSON envelope did not include structured_output or result"
+        end
+
+        def normalize_value!(value, field_name:, stdout:, stderr:)
+          case value
+          when String
+            normalize_json_string!(value, stdout:, stderr:, label: field_name)
+          else
+            JSON.generate(JSON.parse(JSON.generate(value)))
+          end
+        rescue JSON::GeneratorError, TypeError
+          raise SummarizerFailed, failure_message(
+            "#{name} summarizer produced a non-JSON #{field_name} value",
+            stdout:,
+            stderr:,
+            output: value.inspect
+          )
+        end
+
+        def normalize_json_string!(value, stdout:, stderr:, label:)
+          JSON.generate(JSON.parse(value))
+        rescue JSON::ParserError, EncodingError, ArgumentError
+          raise SummarizerFailed, failure_message(
+            "#{name} summarizer produced invalid JSON in #{label}",
+            stdout:,
+            stderr:,
+            output: value
+          )
+        end
+
+        def fail_command!(stdout:, stderr:, status:)
+          raise SummarizerFailed, failure_message(
+            "#{name} summarizer command failed",
+            stdout:,
+            stderr:,
+            status:
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "json"
+require "tempfile"
+
+module Agent
+  module SessionContext
+    module Summarizers
+      class Codex
+        include CommandExecutionPolicy
+
+        MAX_OUTPUT_BYTES = 1_048_576
+        PROVIDER_ENV_KEYS = %w[CODEX_HOME OPENAI_API_KEY].freeze
+        WHITESPACE_BYTES = [9, 10, 11, 12, 13, 32].freeze
+        private_constant :PROVIDER_ENV_KEYS, :WHITESPACE_BYTES
+
+        def initialize(runner: nil, timeout_seconds: Config::DEFAULT_TIMEOUT_SECONDS)
+          initialize_command_execution_policy(
+            runner:,
+            timeout_seconds:,
+            max_output_bytes: MAX_OUTPUT_BYTES,
+            provider_env_keys: PROVIDER_ENV_KEYS
+          )
+        end
+
+        def name
+          :codex
+        end
+
+        def call(prompt:, schema:)
+          Tempfile.create(["agent-context-codex-schema", ".json"]) do |schema_file|
+            schema_file.write(JSON.generate(schema))
+            schema_file.flush
+
+            Tempfile.create(["agent-context-codex-output", ".json"]) do |output_file|
+              stdout, stderr, status = run_command!(
+                prompt:,
+                argv: command_argv(schema_path: schema_file.path, output_path: output_file.path)
+              )
+
+              fail_command!(stdout:, stderr:, status:) unless status.success?
+
+              payload = read_last_message!(output_file.path, stdout:, stderr:)
+              normalize_json!(payload, source: "last message", stdout:, stderr:)
+            end
+          end
+        end
+
+        private
+
+        def command_argv(schema_path:, output_path:)
+          [
+            "codex",
+            "exec",
+            "--ephemeral",
+            "--sandbox",
+            "read-only",
+            "--ignore-user-config",
+            "--ignore-rules",
+            "--skip-git-repo-check",
+            "--output-schema",
+            schema_path,
+            "--output-last-message",
+            output_path,
+            "-"
+          ]
+        end
+
+        def read_last_message!(path, stdout:, stderr:)
+          payload = bounded_file_read(path, "last message", stdout:, stderr:)
+        rescue Errno::ENOENT
+          raise SummarizerFailed, failure_message(
+            "#{name} summarizer did not produce a last message file; output was missing",
+            stdout:,
+            stderr:
+          )
+        else
+          if blank_bytes?(payload)
+            raise SummarizerFailed, failure_message(
+              "#{name} summarizer produced an empty last message file",
+              stdout:,
+              stderr:,
+              output: payload
+            )
+          end
+
+          payload
+        end
+
+        def normalize_json!(payload, source:, stdout:, stderr:)
+          JSON.generate(JSON.parse(payload))
+        rescue JSON::ParserError, EncodingError, ArgumentError
+          raise SummarizerFailed, failure_message(
+            "#{name} summarizer produced invalid JSON in #{source}",
+            stdout:,
+            stderr:,
+            output: payload
+          )
+        end
+
+        def fail_command!(stdout:, stderr:, status:)
+          raise SummarizerFailed, failure_message(
+            "#{name} summarizer command failed",
+            stdout:,
+            stderr:,
+            status:
+          )
+        end
+
+        def bounded_file_read(path, label, stdout:, stderr:)
+          File.open(path, "rb") do |file|
+            payload = file.read(MAX_OUTPUT_BYTES + 1) || "".b
+            if payload.bytesize > MAX_OUTPUT_BYTES
+              raise SummarizerFailed, failure_message(
+                "#{name} summarizer #{label} exceeded #{MAX_OUTPUT_BYTES} bytes",
+                stdout:,
+                stderr:,
+                output: payload
+              )
+            end
+
+            payload
+          end
+        end
+
+        def blank_bytes?(value)
+          value.empty? || value.bytes.all? { |byte| WHITESPACE_BYTES.include?(byte) }
+        end
+      end
+    end
+  end
+end

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/tool_call.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    # One tool call, paired with whatever answered it. The pairing is by
+    # CALL ID, never by position — a model can have two calls in flight at
+    # once, and pairing by position would match the wrong call to the wrong
+    # result.
+    #
+    # result_bytes is nil, not 0, when nothing answered the call: an
+    # unanswered call and a call answered with an empty body are different
+    # facts, and defaulting the body to "" would report a 0-byte answer for
+    # a call that was never answered.
+    #
+    # Only sizes are carried, never bodies — transcripts hold credentials
+    # and customer data, and this gem has no redaction before milestone 0.5.
+    ToolCall = Data.define(:name, :call_id, :input_bytes, :result_bytes, :asked_in, :answered_in) do
+      def answered? = !result_bytes.nil?
+    end
+  end
+end