agent_session_context 1.0.0

data/lib/agent/session_context/session_resolver.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    class SessionResolver
+      SUPPORTED = %i[claude codex].freeze
+
+      def initialize(catalog: Agent::Sessions, env: ENV)
+        @catalog = catalog
+        @env = env
+      end
+
+      def resolve(identifier, agent: nil)
+        parsed_agent, session_id = parse_identifier(identifier)
+        requested_agent = (agent && normalize_agent(agent, source: "agent")) || parsed_agent
+
+        return resolve_for_agent(requested_agent, session_id) if requested_agent
+
+        matches = SUPPORTED.flat_map do |candidate|
+          matching_sessions(candidate, session_id)
+        end
+
+        resolve_cardinality(
+          matches,
+          not_found_message: "Session #{session_id.inspect} was not found for claude or codex.",
+          ambiguous_message: "Session #{session_id.inspect} matches multiple sessions: " \
+                             "#{matches.map(&:uid).join(", ")}. Use an exact agent-prefixed identifier."
+        )
+      end
+
+      def current(agent: nil, &)
+        generic_identifier = fetch_env("AGENT_SESSION_ID")
+        if present?(generic_identifier)
+          agent_name = fetch_env("AGENT_NAME")
+          unless present?(agent_name)
+            raise CurrentSessionUnavailable,
+                  "AGENT_SESSION_ID is set but AGENT_NAME is missing."
+          end
+
+          return resolve(generic_identifier, agent: normalize_agent(agent_name, source: "AGENT_NAME"))
+        end
+
+        claude_identifier = fetch_env("CLAUDE_CODE_SESSION_ID")
+        codex_identifier = current_codex_identifier
+
+        if present?(claude_identifier) && present?(codex_identifier)
+          codex_source = present?(fetch_env("CODEX_SESSION_ID")) ? "CODEX_SESSION_ID" : "CODEX_THREAD_ID"
+          raise CurrentSessionUnavailable,
+                "Conflicting current session variables: CLAUDE_CODE_SESSION_ID and " \
+                "#{codex_source}. Clear one and retry."
+        end
+
+        return resolve(claude_identifier, agent: :claude) if present?(claude_identifier)
+        return resolve(codex_identifier, agent: :codex) if present?(codex_identifier)
+
+        current_from_disk(agent:, &)
+      end
+
+      private
+
+      def parse_identifier(identifier)
+        identifier = identifier.to_s
+        prefix, remainder = identifier.split(":", 2)
+
+        return [normalize_agent(prefix, source: "identifier prefix"), remainder] if remainder
+
+        [nil, identifier]
+      end
+
+      def resolve_for_agent(agent, session_id)
+        matches = matching_sessions(agent, session_id)
+        resolve_cardinality(
+          matches,
+          not_found_message: "Session #{session_id.inspect} was not found for #{agent}.",
+          ambiguous_message: "Session #{session_id.inspect} matches multiple sessions for #{agent}: " \
+                             "#{matches.map(&:uid).join(", ")}."
+        )
+      end
+
+      def matching_sessions(agent, session_id)
+        @catalog.sessions(agent, env: @env)
+                .select { |session| session.id == session_id }
+                .force
+      end
+
+      def resolve_cardinality(matches, not_found_message:, ambiguous_message:)
+        return matches.first if matches.one?
+        raise SessionNotFound, not_found_message if matches.empty?
+
+        raise AmbiguousSession, ambiguous_message
+      end
+
+      def current_codex_identifier
+        session_identifier = fetch_env("CODEX_SESSION_ID")
+        return session_identifier if present?(session_identifier)
+
+        fetch_env("CODEX_THREAD_ID")
+      end
+
+      def current_from_disk(agent:, &block)
+        agents = agent ? [normalize_agent(agent, source: "agent")] : SUPPORTED
+        sessions = agents.flat_map { |candidate| @catalog.sessions(candidate, env: @env).force }
+
+        if sessions.empty?
+          raise CurrentSessionUnavailable,
+                "Current session is unavailable: no sessions found for #{agent_scope(agents)}. " \
+                "Set AGENT_SESSION_ID with AGENT_NAME, CLAUDE_CODE_SESSION_ID, CODEX_SESSION_ID, or CODEX_THREAD_ID."
+        end
+
+        latest_updated_at = sessions.map(&:updated_at).max
+        latest_sessions = sessions.select { |session| session.updated_at == latest_updated_at }
+
+        if latest_sessions.size > 1
+          raise AmbiguousSession,
+                "Multiple sessions share the latest update at #{latest_updated_at.iso8601(9)}: " \
+                "#{latest_sessions.map(&:uid).sort.join(", ")}. Pass an explicit SESSION."
+        end
+
+        session = latest_sessions.first
+        block&.call(session)
+        session
+      end
+
+      def agent_scope(agents)
+        return agents.first.to_s if agents.size == 1
+
+        agents.join(" or ")
+      end
+
+      def normalize_agent(agent, source:)
+        normalized = agent.to_s.downcase.to_sym
+        return normalized if SUPPORTED.include?(normalized)
+
+        raise UnsupportedAgent,
+              "Unsupported agent #{agent.inspect} from #{source}. Supported agents: #{SUPPORTED.join(", ")}."
+      end
+
+      def fetch_env(key)
+        @env[key]
+      end
+
+      def present?(value)
+        !value.nil? && !value.empty?
+      end
+    end
+  end
+end

data/lib/agent/session_context/snapshot.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    Snapshot = Data.define(
+      :session_uid,
+      :agent,
+      :project_path,
+      :captured_at,
+      :message_count,
+      :prompts,
+      :injected_context,
+      :files,
+      :documents,
+      :tool_activity,
+      :goals,
+      :decisions,
+      :terms,
+      :constraints,
+      :open_questions,
+      :next_actions,
+      :warnings,
+      :summary_metadata
+    ) do
+      def initialize(
+        session_uid:,
+        agent:,
+        project_path:,
+        captured_at:,
+        message_count:,
+        prompts: [],
+        injected_context: [],
+        files: [],
+        documents: [],
+        tool_activity: [],
+        goals: [],
+        decisions: [],
+        terms: [],
+        constraints: [],
+        open_questions: [],
+        next_actions: [],
+        warnings: [],
+        summary_metadata: {}
+      )
+        super(
+          session_uid: normalize_string(session_uid, :session_uid),
+          agent: normalize_agent(agent),
+          project_path: normalize_optional_string(project_path, :project_path),
+          captured_at: captured_at,
+          message_count: normalize_message_count(message_count),
+          prompts: duplicate_collection(prompts),
+          injected_context: duplicate_collection(injected_context),
+          files: duplicate_collection(files),
+          documents: duplicate_collection(documents),
+          tool_activity: duplicate_collection(tool_activity),
+          goals: duplicate_collection(goals),
+          decisions: duplicate_collection(decisions),
+          terms: duplicate_collection(terms),
+          constraints: duplicate_collection(constraints),
+          open_questions: duplicate_collection(open_questions),
+          next_actions: duplicate_collection(next_actions),
+          warnings: normalize_warnings(warnings),
+          summary_metadata: normalize_summary_metadata(summary_metadata)
+        )
+      end
+
+      private
+
+      def duplicate_collection(value)
+        ImmutableValue.copy(Array(value))
+      end
+
+      def normalize_agent(value)
+        return value if value.is_a?(Symbol)
+        return value.to_sym if value.respond_to?(:to_sym)
+
+        raise TypeError, "agent must be symbolizable"
+      end
+
+      def normalize_message_count(value)
+        count =
+          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, "message_count must be an Integer or integer-like value" if count.nil?
+        raise ArgumentError, "message_count must be greater than or equal to 0" if count.negative?
+
+        count
+      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
+
+      def normalize_summary_metadata(value)
+        raise TypeError, "summary_metadata must be a Hash" unless value.is_a?(Hash)
+
+        value.each_with_object({}) do |(key, metadata_value), normalized|
+          normalized[normalize_summary_metadata_key(key)] = ImmutableValue.copy(metadata_value)
+        end.freeze
+      end
+
+      def normalize_summary_metadata_key(key)
+        return key if key.is_a?(Symbol)
+        return key.to_sym if key.respond_to?(:to_sym)
+
+        raise TypeError, "summary_metadata keys must be symbolizable"
+      end
+
+      def normalize_warnings(value)
+        Array(value).map { |warning| normalize_string(warning, :warning) }.freeze
+      end
+    end
+  end
+end

data/lib/agent/session_context/source_ref.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    SourceRef = Data.define(:session_uid, :message_index, :part_index) do
+      def initialize(session_uid:, message_index:, part_index:)
+        super(
+          session_uid: normalize_string(session_uid, :session_uid),
+          message_index: normalize_positive_index(message_index, :message_index),
+          part_index: normalize_positive_index(part_index, :part_index)
+        )
+      end
+
+      def to_s
+        format("%<session_uid>s/message:%<message_index>06d/part:%<part_index>06d",
+               session_uid: session_uid,
+               message_index: message_index,
+               part_index: part_index)
+      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_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/subprocess_runner.rb

@@ -0,0 +1,362 @@
+# frozen_string_literal: true
+
+require "English"
+require "open3"
+
+module Agent
+  module SessionContext
+    class SubprocessRunner
+      DEFAULT_CLOCK = lambda {
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      }
+      private_constant :DEFAULT_CLOCK
+
+      class TimeoutError < StandardError
+        attr_reader :timeout_seconds
+
+        def initialize(timeout_seconds)
+          @timeout_seconds = timeout_seconds
+          super("subprocess exceeded #{timeout_seconds} seconds")
+        end
+      end
+
+      class OutputLimitError < StandardError
+        attr_reader :stream, :max_output_bytes
+
+        def initialize(stream:, max_output_bytes:)
+          @stream = stream
+          @max_output_bytes = max_output_bytes
+          super("#{stream} exceeded #{max_output_bytes} bytes")
+        end
+      end
+
+      def initialize(timeout_seconds:, max_output_bytes:, clock: DEFAULT_CLOCK, termination_grace_seconds: 0.5)
+        @timeout_seconds = validate_timeout!(timeout_seconds)
+        @max_output_bytes = validate_max_output_bytes!(max_output_bytes)
+        @clock = validate_clock!(clock)
+        @termination_grace_seconds = validate_termination_grace!(termination_grace_seconds)
+      end
+
+      def call(env:, argv:, stdin_data:)
+        deadline = monotonic_now + @timeout_seconds
+        stdin = stdout = stderr = wait_thread = stdin_thread = nil
+        stdin_error = nil
+        completed = false
+        stdout_buffer = String.new.b
+        stderr_buffer = String.new.b
+
+        stdin, stdout, stderr, wait_thread = Open3.popen3(
+          env,
+          *argv,
+          unsetenv_others: true,
+          **process_group_options
+        )
+        prepare_streams!(stdin, stdout, stderr)
+        stdin_thread, stdin_error = start_stdin_writer(stdin, stdin_data)
+
+        status = monitor_process(
+          deadline:,
+          wait_thread:,
+          stdout:,
+          stderr:,
+          stdout_buffer:,
+          stderr_buffer:,
+          stdin_thread:,
+          stdin_error:
+        )
+
+        join_stdin_thread!(stdin_thread, stdin_error)
+        completed = true
+        [stdout_buffer, stderr_buffer, status]
+      ensure
+        cleanup_call(
+          wait_thread:,
+          stdin:,
+          stdout:,
+          stderr:,
+          stdin_thread:,
+          stdin_error:,
+          completed:,
+          primary_error: $ERROR_INFO
+        )
+      end
+
+      private
+
+      def validate_timeout!(value)
+        validate_numeric!(value, name: "timeout_seconds", allow_zero: false)
+      end
+
+      def validate_max_output_bytes!(value)
+        unless value.is_a?(Integer) && value.positive?
+          raise ArgumentError,
+                "max_output_bytes must be a positive Integer"
+        end
+
+        value
+      end
+
+      def validate_clock!(value)
+        raise ArgumentError, "clock must respond to call" unless value.respond_to?(:call)
+
+        value
+      end
+
+      def validate_termination_grace!(value)
+        validate_numeric!(value, name: "termination_grace_seconds", allow_zero: true)
+      end
+
+      def validate_numeric!(value, name:, allow_zero:)
+        valid_type = value.is_a?(Integer) || value.is_a?(Float)
+        unless valid_type
+          raise ArgumentError,
+                "#{name} must be a #{allow_zero ? "nonnegative" : "positive"} finite number"
+        end
+
+        finite = !value.is_a?(Float) || value.finite?
+        positive_enough = allow_zero ? value >= 0 : value.positive?
+        unless finite && positive_enough
+          raise ArgumentError,
+                "#{name} must be a #{allow_zero ? "nonnegative" : "positive"} finite number"
+        end
+
+        value
+      end
+
+      def process_group_options
+        return { new_pgroup: true } if Gem.win_platform?
+
+        { pgroup: true }
+      end
+
+      def prepare_streams!(stdin, stdout, stderr)
+        stdin.binmode
+        stdout.binmode
+        stderr.binmode
+      end
+
+      def start_stdin_writer(stdin, stdin_data)
+        error_box = { error: nil }
+        writer_thread = Thread.new do
+          write_stdin(stdin, stdin_data)
+        rescue Errno::EPIPE
+          nil
+        rescue IOError => e
+          error_box[:error] = e unless stdin.closed?
+        rescue StandardError => e
+          error_box[:error] = e
+        ensure
+          close_stream(stdin)
+        end
+
+        [writer_thread, error_box]
+      end
+
+      def write_stdin(stdin, stdin_data)
+        return if stdin_data.nil?
+
+        payload = stdin_data.dup.force_encoding(Encoding::BINARY)
+        stdin.write(payload)
+        stdin.flush
+      end
+
+      def monitor_process(deadline:, wait_thread:, stdout:, stderr:, stdout_buffer:, stderr_buffer:, stdin_thread:,
+                          stdin_error:)
+        streams = { stdout: stdout, stderr: stderr }
+        status = nil
+
+        loop do
+          raise_writer_error!(stdin_thread, stdin_error)
+          stdin_writer_finished = stdin_writer_finished?(stdin_thread)
+
+          raise TimeoutError, @timeout_seconds if timed_out?(deadline)
+
+          status = wait_thread.value if wait_thread.join(0)
+          break if status && streams.empty? && stdin_writer_finished
+
+          ready = wait_for_ready_streams(wait_thread, stdin_thread, streams.values, deadline)
+
+          ready.each do |stream|
+            name = streams.key(stream)
+            next unless name
+
+            drain_stream!(
+              name:,
+              stream:,
+              buffer: name == :stdout ? stdout_buffer : stderr_buffer,
+              streams:
+            )
+          end
+        end
+
+        status || wait_thread.value
+      end
+
+      def drain_stream!(name:, stream:, buffer:, streams:)
+        chunk = stream.read_nonblock(4096, exception: false)
+
+        case chunk
+        when :wait_readable
+          nil
+        when nil
+          close_stream(stream)
+          streams.delete(name)
+        else
+          append_chunk!(buffer, chunk, name)
+        end
+      end
+
+      def append_chunk!(buffer, chunk, stream_name)
+        remaining = @max_output_bytes - buffer.bytesize
+        if chunk.bytesize > remaining
+          buffer << chunk.byteslice(0, remaining) if remaining.positive?
+          raise OutputLimitError.new(stream: stream_name, max_output_bytes: @max_output_bytes)
+        end
+
+        buffer << chunk
+      end
+
+      def wait_for_ready_streams(wait_thread, stdin_thread, readable_streams, deadline)
+        interval = poll_interval(deadline)
+        return [] if interval <= 0
+
+        if readable_streams.empty?
+          wait_deadline = monotonic_now + interval
+          wait_thread.join(remaining_poll_time(wait_deadline))
+          stdin_thread&.join(remaining_poll_time(wait_deadline))
+          return []
+        end
+
+        IO.select(readable_streams, nil, nil, interval)&.first || []
+      end
+
+      def raise_writer_error!(stdin_thread, error_box)
+        return unless stdin_thread
+        return unless stdin_thread.join(0)
+        return unless error_box[:error]
+
+        raise error_box[:error]
+      end
+
+      def stdin_writer_finished?(stdin_thread)
+        return true unless stdin_thread
+
+        !stdin_thread.join(0).nil?
+      end
+
+      def cleanup_call(wait_thread:, stdin:, stdout:, stderr:, stdin_thread:, stdin_error:, completed:, primary_error:)
+        terminate_process(wait_thread) if wait_thread && !completed
+      rescue StandardError
+        nil
+      ensure
+        close_stream(stdin)
+        close_stream(stdout)
+        close_stream(stderr)
+        begin
+          join_stdin_thread!(stdin_thread, stdin_error, suppress_error: !primary_error.nil?) if stdin_thread
+        rescue StandardError
+          nil
+        end
+      end
+
+      def terminate_process(wait_thread)
+        pid = wait_thread.pid
+
+        if Gem.win_platform?
+          terminate_direct_child(wait_thread)
+        else
+          terminate_process_group(pid)
+        end
+
+        wait_thread.value
+      rescue Errno::ECHILD
+        nil
+      end
+
+      def terminate_direct_child(wait_thread)
+        pid = wait_thread.pid
+
+        begin
+          Process.kill("TERM", pid)
+        rescue Errno::EINVAL
+          kill_direct_child(pid)
+          return
+        rescue Errno::ESRCH
+          return
+        end
+
+        return unless wait_thread.join(@termination_grace_seconds).nil?
+
+        kill_direct_child(pid)
+      end
+
+      def terminate_process_group(pid)
+        Process.kill("TERM", -pid)
+      rescue Errno::ESRCH
+        nil
+      else
+        sleep_cleanup_grace(@termination_grace_seconds)
+
+        begin
+          Process.kill("KILL", -pid)
+        rescue Errno::ESRCH
+          nil
+        end
+      end
+
+      def kill_direct_child(pid)
+        Process.kill("KILL", pid)
+      rescue Errno::ESRCH
+        nil
+      end
+
+      def timed_out?(deadline)
+        monotonic_now >= deadline
+      end
+
+      def remaining_seconds(deadline)
+        [deadline - monotonic_now, 0].max
+      end
+
+      def poll_interval(deadline)
+        [remaining_seconds(deadline), 0.05].min
+      end
+
+      def remaining_poll_time(wait_deadline)
+        [wait_deadline - monotonic_now, 0].max
+      end
+
+      def monotonic_now
+        @clock.call
+      end
+
+      def cleanup_monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def sleep_cleanup_grace(duration)
+        return if duration.zero?
+
+        deadline = cleanup_monotonic_now + duration
+
+        sleep([deadline - cleanup_monotonic_now, 0.01].min) while cleanup_monotonic_now < deadline
+      end
+
+      def close_stream(stream)
+        return unless stream
+        return if stream.closed?
+
+        stream.close
+      rescue IOError, Errno::EBADF
+        nil
+      end
+
+      def join_stdin_thread!(stdin_thread, error_box, suppress_error: false)
+        return unless stdin_thread
+
+        stdin_thread.join
+        raise error_box[:error] if !suppress_error && error_box && error_box[:error]
+      end
+    end
+  end
+end