agent_session_context 1.0.0

data/lib/agent/session_context/cli/options.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Agent
+  module SessionContext
+    class CLI
+      class Options
+        AGENTS = %w[claude codex].freeze
+        BACKENDS = %w[auto claude codex].freeze
+        OPTION_DEFINITIONS = {
+          current: {
+            long: "--current",
+            value: false,
+            register: lambda do |parser, options|
+              parser.on("--current") { options[:current] = true }
+            end
+          }.freeze,
+          agent: {
+            long: "--agent",
+            value: true,
+            register: lambda do |parser, options|
+              parser.on("--agent AGENT", AGENTS) { |value| options[:agent] = value.to_sym }
+            end
+          }.freeze,
+          format: {
+            long: "--format",
+            value: true,
+            register: lambda do |parser, options|
+              parser.on("--format FORMAT", CLI::FORMATS) { |value| options[:format] = value.to_sym }
+            end
+          }.freeze,
+          using: {
+            long: "--using",
+            value: true,
+            register: lambda do |parser, options|
+              parser.on("--using BACKEND", BACKENDS) { |value| options[:using] = value.to_sym }
+            end
+          }.freeze,
+          timeout: {
+            long: "--timeout",
+            value: true,
+            register: lambda do |parser, options|
+              parser.on("--timeout SECONDS") { |value| options[:timeout] = parse_timeout_argument(value) }
+            end
+          }.freeze,
+          include_injected: {
+            long: "--include-injected",
+            value: false,
+            register: lambda do |parser, options|
+              parser.on("--include-injected") { options[:include_injected] = true }
+            end
+          }.freeze
+        }.freeze
+        COMMANDS = {
+          show: { formats: %i[text markdown json], options: %i[current agent format include_injected] }.freeze,
+          prompts: { formats: %i[text markdown json jsonl], options: %i[current agent format] }.freeze,
+          loop: { formats: %i[text markdown json jsonl], options: %i[current agent format] }.freeze,
+          summarize: { formats: %i[text markdown json], options: %i[current agent format using timeout] }.freeze,
+          help: { formats: nil, options: [].freeze }.freeze,
+          version: { formats: nil, options: [].freeze }.freeze
+        }.transform_values do |descriptor|
+          option_names = descriptor.fetch(:options)
+          long_options = option_names.each_with_object({}) do |name, rules|
+            definition = OPTION_DEFINITIONS.fetch(name)
+            rules[definition.fetch(:long)] = definition.fetch(:value) ? :value : :flag
+          end.freeze
+
+          descriptor.merge(
+            formats: descriptor[:formats]&.freeze,
+            options: option_names.freeze,
+            long_options:
+          ).freeze
+        end.freeze
+        private_constant :AGENTS, :BACKENDS, :OPTION_DEFINITIONS, :COMMANDS
+
+        class << self
+          def parse(arguments, command:)
+            descriptor = command_descriptor(command)
+            options = default_options
+            validate_argument_encoding!(arguments)
+            validate_exact_long_options!(arguments, descriptor:)
+            remaining = parser(options, descriptor:).permute(arguments.dup)
+
+            validate_selection!(options, remaining, command:, descriptor:)
+            options.merge(identifier: remaining.first).freeze
+          end
+
+          def hinted_format(arguments)
+            limit = arguments.index("--") || arguments.length
+            effective = :text
+            index = 0
+
+            while index < limit
+              token = arguments[index]
+
+              if token == "--format"
+                candidate = arguments[index + 1]
+                effective = candidate.to_sym if CLI::FORMATS.include?(candidate)
+                index += 2
+                next
+              end
+
+              if token.start_with?("--format=")
+                candidate = token.split("=", 2).last
+                effective = candidate.to_sym if CLI::FORMATS.include?(candidate)
+              end
+
+              index += 1
+            end
+
+            effective
+          end
+
+          def parse_no_args(arguments, command:)
+            descriptor = command_descriptor(command)
+            validate_argument_encoding!(arguments)
+            validate_exact_long_options!(arguments, descriptor:)
+            remaining = OptionParser.new.permute(arguments.dup)
+            raise OptionParser::ParseError, "unexpected arguments: #{remaining.join(" ")}" unless remaining.empty?
+          end
+
+          private
+
+          def default_options
+            {
+              current: false,
+              agent: nil,
+              format: :text,
+              using: :auto,
+              timeout: nil,
+              include_injected: false
+            }
+          end
+
+          def parser(options, descriptor:)
+            OptionParser.new do |parser|
+              descriptor.fetch(:options).each do |name|
+                OPTION_DEFINITIONS.fetch(name).fetch(:register).call(parser, options)
+              end
+            end
+          end
+
+          def validate_selection!(options, remaining, command:, descriptor:)
+            allowed_formats = descriptor.fetch(:formats)
+            unless allowed_formats.include?(options[:format])
+              raise OptionParser::ParseError, "--format #{options[:format]} is not supported for #{command}"
+            end
+
+            if options[:current] && !remaining.empty?
+              raise OptionParser::ParseError, "SESSION and --current are mutually exclusive"
+            end
+
+            if remaining.length > 1
+              raise OptionParser::ParseError, "unexpected arguments: #{remaining.drop(1).join(" ")}"
+            end
+
+            raise OptionParser::ParseError, "pass SESSION or --current" if !options[:current] && remaining.empty?
+          end
+
+          def validate_argument_encoding!(arguments)
+            arguments.each do |argument|
+              next unless argument.is_a?(String)
+
+              candidate = argument.dup
+              candidate.force_encoding(Encoding::UTF_8)
+              raise OptionParser::InvalidArgument, "arguments must be valid UTF-8" unless candidate.valid_encoding?
+            end
+          end
+
+          def validate_exact_long_options!(arguments, descriptor:)
+            allowed = descriptor.fetch(:long_options)
+            limit = arguments.index("--") || arguments.length
+            index = 0
+
+            while index < limit
+              token = arguments[index]
+              if token.start_with?("--")
+                name, value = token.split("=", 2)
+                rule = allowed[name]
+                raise OptionParser::InvalidOption, token unless rule
+                raise OptionParser::InvalidOption, token if rule == :flag && !value.nil?
+
+                if rule == :value && value.nil?
+                  index += 2
+                  next
+                end
+              end
+
+              index += 1
+            end
+          end
+
+          def command_descriptor(command)
+            COMMANDS.fetch(command.to_sym)
+          end
+
+          def parse_timeout_argument(value)
+            Integer(value, 10)
+          rescue ArgumentError, TypeError
+            return Float::NAN if value.casecmp("nan").zero?
+            return Float::INFINITY if value.casecmp("infinity").zero? || value.casecmp("inf").zero?
+            return -Float::INFINITY if value.casecmp("-infinity").zero? || value.casecmp("-inf").zero?
+
+            parsed = Float(value, exception: false)
+            return parsed unless parsed.nil?
+
+            raise OptionParser::InvalidArgument, value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agent/session_context/cli.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Agent
+  module SessionContext
+    class CLI
+      FORMATS = %w[text markdown json jsonl].freeze
+
+      def initialize(
+        argv,
+        env: ENV,
+        stdout: $stdout,
+        stderr: $stderr,
+        now: Time.now,
+        resolver: SessionResolver.new(env: env),
+        builder: Builder.new(now: now),
+        backend_factory: Summarizers,
+        config_loader: Config
+      )
+        @argv = argv.dup
+        @env = env
+        @stdout = stdout
+        @stderr = stderr
+        @resolver = resolver
+        @builder = builder
+        @backend_factory = backend_factory
+        @config_loader = config_loader
+        @current_format = :text
+      end
+
+      def run
+        case (command = @argv.shift)
+        when "show" then show
+        when "prompts" then prompts
+        # Named loop_command, not loop: Kernel#loop is an instance method
+        # available everywhere, and a method named `loop` on this CLI object
+        # would shadow it for the rest of this instance.
+        when "loop" then loop_command
+        when "summarize" then summarize
+        when "version", "--version", "-v" then version(@argv)
+        when nil then help([], @stdout, 0)
+        when "help", "--help", "-h" then help(@argv, @stdout, 0)
+        else
+          @stderr.puts "unknown command: #{safe_text(command)}"
+          1
+        end
+      rescue Agent::SessionContext::Error, OptionParser::ParseError => e
+        emit_error(e)
+        1
+      end
+
+      private
+
+      def show
+        @current_format = Options.hinted_format(@argv)
+        selection = Options.parse(@argv, command: :show)
+        session = resolve_session(selection)
+        include_injected = selection.fetch(:include_injected)
+        snapshot = @builder.show(session, include_injected:)
+        if include_injected
+          @stderr.puts "warning: exact prompts and full injected context may contain secrets; review before sharing"
+        else
+          @stderr.puts "warning: exact prompts may contain secrets; review before sharing"
+        end
+        emit_warnings(session.uid, snapshot.warnings)
+        write_output(snapshot, format: selection.fetch(:format))
+        partial_capture_status(snapshot)
+      end
+
+      def prompts
+        @current_format = Options.hinted_format(@argv)
+        selection = Options.parse(@argv, command: :prompts)
+        session = resolve_session(selection)
+        prompts_result = @builder.prompts_result(session)
+        @stderr.puts "warning: exact prompts may contain secrets; review before sharing"
+        emit_warnings(session.uid, prompts_result.reader_warnings)
+        write_output(prompts_result.prompts, format: selection.fetch(:format))
+        prompts_result.partial_capture? ? 1 : 0
+      end
+
+      # No "may contain secrets" stderr warning here, unlike show and
+      # prompts: this view prints byte sizes and tool names, never prompt or
+      # tool-result bodies (LoopView's own privacy rule), so its output is
+      # always safe to paste anywhere.
+      def loop_command
+        @current_format = Options.hinted_format(@argv)
+        selection = Options.parse(@argv, command: :loop)
+        session = resolve_session(selection)
+        loop = @builder.loop(session)
+        emit_warnings(session.uid, loop.warnings)
+        write_output(loop, format: selection.fetch(:format))
+        loop.warnings.empty? ? 0 : 1
+      end
+
+      def summarize
+        @current_format = Options.hinted_format(@argv)
+        selection = Options.parse(@argv, command: :summarize)
+        session = resolve_session(selection)
+        config = @config_loader.load(session:, env: @env, timeout: selection.fetch(:timeout))
+        backend_name = selection.fetch(:using) == :auto ? session.agent : selection.fetch(:using)
+        timeout_seconds = configured_timeout_seconds(config)
+        @stderr.puts "summarizing with #{safe_text(backend_name)} (timeout: #{format_timeout(timeout_seconds)}s)"
+        summarizer = @backend_factory.for(backend_name, timeout_seconds:)
+        snapshot = @builder.summarize(session, summarizer:)
+        emit_warnings(session.uid, snapshot.warnings)
+        write_output(snapshot, format: selection.fetch(:format))
+        partial_capture_status(snapshot)
+      end
+
+      def version(arguments)
+        Options.parse_no_args(arguments, command: :version)
+        @stdout.puts Agent::SessionContext::VERSION
+        0
+      end
+
+      def help(arguments, io, status)
+        Options.parse_no_args(arguments, command: :help)
+        io.puts <<~HELP
+          Usage: agent-session-context COMMAND [options] [SESSION]
+
+          Commands:
+            show
+            prompts
+            loop
+            summarize
+            version
+            help
+
+          Common options:
+            --current             Use environment identity, else latest on disk
+            --agent claude|codex  Narrow explicit lookup or --current disk fallback
+            --format text|markdown|json|jsonl
+
+          Show behavior:
+            Includes exact user prompts and an injected-context inventory.
+            --include-injected  Include deduplicated full injected text
+            Excludes assistant messages, thinking, tool-result bodies,
+            and raw provider envelopes.
+
+          Loop behavior:
+            Shows the session as the agent loop: prompts, model round trips,
+            tool calls paired with their results, and where it stopped.
+            Prints byte sizes and tool names, never bodies. Deterministic;
+            the ending is always labelled inferred.
+
+          Summarize options:
+            --using auto|claude|codex
+            --timeout SECONDS    Set a 1-3600s timeout for each provider call
+        HELP
+        status
+      end
+
+      def resolve_session(selection)
+        if selection.fetch(:current)
+          @resolver.current(agent: selection.fetch(:agent)) do |session|
+            @stderr.puts(
+              "warning: --current found no session environment identifier; " \
+              "using latest session on disk: #{safe_text(session.uid)}"
+            )
+          end
+        else
+          @resolver.resolve(selection.fetch(:identifier), agent: selection.fetch(:agent))
+        end
+      end
+
+      def emit_warnings(session_uid, warnings)
+        Array(warnings).each do |warning|
+          @stderr.puts "warning: #{safe_text(session_uid)}: #{safe_text(warning)}"
+        end
+      end
+
+      def write_output(value, format:)
+        rendered = renderer_for(format).call(value)
+        if human_format?(format)
+          @stdout.write(rendered)
+          @stdout.write("\n")
+        else
+          @stdout.write(rendered)
+        end
+      end
+
+      def renderer_for(format)
+        case format
+        when :text then Renderers::Text.new
+        when :markdown then Renderers::Markdown.new
+        when :json then Renderers::JSON.new
+        when :jsonl then Renderers::JSONLines.new
+        else
+          raise OptionParser::ParseError, "unsupported format #{format.inspect}"
+        end
+      end
+
+      def human_format?(format)
+        %i[text markdown].include?(format)
+      end
+
+      def emit_error(error)
+        if @current_format == :json
+          error_json = JSON.generate(
+            {
+              error: {
+                type: scrubbed_error_type(error),
+                message: Renderers::Serializer.scrub_string(normalized_error_message(error))
+              }
+            }
+          )
+          @stdout.write(error_json)
+        else
+          @stderr.puts safe_text(normalized_error_message(error))
+        end
+      end
+
+      def safe_text(value)
+        Renderers::HumanDisplay.text_inline(value)
+      end
+
+      def partial_capture_status(snapshot)
+        snapshot.summary_metadata.fetch(:reader_warning_count, 0).positive? ? 1 : 0
+      end
+
+      def configured_timeout_seconds(config)
+        value = config.timeout_seconds
+        if value.is_a?(Integer) && value >= Config::MIN_TIMEOUT_SECONDS && value <= Config::MAX_TIMEOUT_SECONDS
+          return value
+        end
+        if value.is_a?(Float) &&
+           value.finite? &&
+           value >= Config::MIN_TIMEOUT_SECONDS &&
+           value <= Config::MAX_TIMEOUT_SECONDS
+          return value
+        end
+
+        raise ConfigurationError, "Invalid configured timeout_seconds."
+      end
+
+      def format_timeout(value)
+        return value.to_i.to_s if value.is_a?(Float) && value.finite? && value == value.to_i
+
+        value.to_s
+      end
+
+      def normalized_error_message(error)
+        return error.args.first.to_s if error.instance_of?(OptionParser::ParseError)
+
+        error.message.to_s
+      end
+
+      def scrubbed_error_type(error)
+        Renderers::Serializer.scrub_string(error.class.name.to_s)
+      end
+    end
+  end
+end

data/lib/agent/session_context/config.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "psych"
+
+module Agent
+  module SessionContext
+    class Config < Data.define(:timeout_seconds)
+      DEFAULT_TIMEOUT_SECONDS = 300
+      MIN_TIMEOUT_SECONDS = 1
+      MAX_TIMEOUT_SECONDS = 3600
+      ABSENT = Object.new.freeze
+      PROJECT_CONFIG_FILENAME = ".agent-context.yml"
+      USER_CONFIG_PATH_SEGMENTS = [".config", "agent_context", "config.yml"].freeze
+      private_constant :ABSENT, :PROJECT_CONFIG_FILENAME, :USER_CONFIG_PATH_SEGMENTS
+
+      class << self
+        def load(session:, env: ENV, timeout: nil)
+          project_timeout = load_layer(project_source(session))
+          user_timeout = load_layer(user_source(env))
+
+          effective_timeout =
+            if timeout.nil?
+              if project_timeout.nil?
+                user_timeout.nil? ? DEFAULT_TIMEOUT_SECONDS : user_timeout
+              else
+                project_timeout
+              end
+            else
+              validate_timeout!(timeout, source: "timeout")
+            end
+
+          new(timeout_seconds: effective_timeout)
+        end
+
+        private
+
+        def load_layer(source)
+          return nil unless source
+
+          path = source.fetch(:path)
+          stat = stat_config_path(path, source)
+          return nil unless stat
+
+          raise_configuration_error(source, "must be a regular file") unless stat.file?
+
+          content = read_utf8(path, stat, source)
+          raw = parse_yaml(content, source)
+          timeout = extract_timeout(raw, source)
+
+          return nil if timeout.equal?(ABSENT)
+
+          validate_timeout!(timeout, source: source.fetch(:label), path:)
+        rescue ConfigurationError
+          raise
+        rescue Psych::Exception
+          raise_configuration_error(source, "contains invalid YAML")
+        rescue SystemCallError
+          raise_configuration_error(source, "could not be read")
+        rescue ArgumentError
+          raise_configuration_error(source, "contains invalid encoding")
+        end
+
+        def stat_config_path(path, source)
+          File.lstat(path)
+        rescue Errno::ENOENT, Errno::ENOTDIR
+          nil
+        rescue SystemCallError
+          raise_configuration_error(source, "could not be read")
+        end
+
+        def project_source(session)
+          project_path = normalize_absolute_path(session.project_path)
+          return nil unless project_path
+
+          {
+            label: "project configuration",
+            path: File.join(project_path, PROJECT_CONFIG_FILENAME)
+          }
+        end
+
+        def user_source(env)
+          xdg_config_home = normalize_absolute_path(env["XDG_CONFIG_HOME"])
+          if xdg_config_home
+            return {
+              label: "user configuration",
+              path: File.join(xdg_config_home, "agent_context", "config.yml")
+            }
+          end
+
+          home = normalize_absolute_path(env["HOME"])
+          return nil unless home
+
+          {
+            label: "user configuration",
+            path: File.join(home, *USER_CONFIG_PATH_SEGMENTS)
+          }
+        end
+
+        def normalize_absolute_path(value)
+          return nil unless value.respond_to?(:to_str)
+
+          path = value.to_str
+          return nil if path.empty?
+          return path if Pathname.new(path).absolute?
+
+          nil
+        end
+
+        def read_utf8(path, initial_stat, source)
+          open_config_file(path, source) do |file|
+            descriptor_stat = file.stat
+            raise_configuration_error(source, "must be a regular file") unless descriptor_stat.file?
+            ensure_same_identity!(initial_stat, descriptor_stat, source)
+
+            content = file.read
+            content = content.dup.force_encoding(Encoding::UTF_8)
+            raise_configuration_error(source, "contains invalid encoding") unless content.valid_encoding?
+
+            content
+          end
+        end
+
+        def parse_yaml(content, source)
+          return nil if content.empty?
+
+          Psych.safe_load(
+            content,
+            permitted_classes: [],
+            permitted_symbols: [],
+            aliases: false
+          )
+        rescue Psych::Exception
+          raise_configuration_error(source, "contains invalid YAML")
+        end
+
+        def extract_timeout(raw, source)
+          return ABSENT if raw.nil?
+          return ABSENT if raw == {}
+
+          raise_configuration_error(source, "must be a mapping") unless raw.is_a?(Hash)
+
+          unknown_keys = raw.keys - ["summarize"]
+          raise_configuration_error(source, "contains unsupported settings") unless unknown_keys.empty?
+
+          summarize = raw.fetch("summarize")
+          raise_configuration_error(source, "summarize must be a mapping") unless summarize.is_a?(Hash)
+          return ABSENT if summarize.empty?
+
+          unknown_summarize_keys = summarize.keys - ["timeout_seconds"]
+          unless unknown_summarize_keys.empty?
+            raise_configuration_error(source,
+                                      "contains unsupported summarize settings")
+          end
+
+          return ABSENT unless summarize.key?("timeout_seconds")
+
+          summarize.fetch("timeout_seconds")
+        end
+
+        def validate_timeout!(value, source:, path: nil)
+          unless value.is_a?(Integer) || value.is_a?(Float)
+            raise_configuration_error({ label: source, path: },
+                                      "timeout_seconds must be an Integer or Float between " \
+                                      "#{MIN_TIMEOUT_SECONDS} and #{MAX_TIMEOUT_SECONDS}")
+          end
+
+          unless value.finite? &&
+                 value >= MIN_TIMEOUT_SECONDS && value <= MAX_TIMEOUT_SECONDS
+            raise_configuration_error({ label: source, path: },
+                                      "timeout_seconds must be a finite number between " \
+                                      "#{MIN_TIMEOUT_SECONDS} and #{MAX_TIMEOUT_SECONDS}")
+          end
+
+          value
+        end
+
+        def open_config_file(path, source)
+          flags = File::RDONLY
+          flags |= File::NOFOLLOW if File.const_defined?(:NOFOLLOW)
+
+          File.open(path, flags) do |file|
+            file.binmode
+            yield file
+          end
+        rescue SystemCallError, IOError
+          raise_configuration_error(source, "could not be read")
+        end
+
+        def ensure_same_identity!(initial_stat, descriptor_stat, source)
+          return if initial_stat.dev == descriptor_stat.dev && initial_stat.ino == descriptor_stat.ino
+
+          raise_configuration_error(source, "changed while being read")
+        end
+
+        def raise_configuration_error(source, reason)
+          label = source.fetch(:label)
+          path = source[:path]
+          location = path ? " at #{path}" : ""
+
+          raise ConfigurationError, "Invalid #{label}#{location}: #{reason}."
+        end
+      end
+    end
+  end
+end

data/lib/agent/session_context/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    class Error < StandardError; end
+    class ConfigurationError < Error; end
+    class SessionNotFound < Error; end
+    class AmbiguousSession < Error; end
+    class CurrentSessionUnavailable < Error; end
+    class UnsupportedAgent < Error; end
+    class SummarizerUnavailable < Error; end
+    class SummarizerFailed < Error; end
+    class InvalidSummary < Error; end
+  end
+end