agent-session_context 0.1.0

data/lib/agent/session_context/cli.rb

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

data/lib/agent/session_context/evidence_collector.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    class EvidenceCollector
+      DOCUMENT_BASENAMES = %w[agents.md claude.md readme readme.md].freeze
+      DOCUMENT_EXTENSIONS = %w[.md .markdown .txt .pdf .doc .docx .odt .rtf].freeze
+      PATH_KEYS = %w[path file_path filename source destination target].freeze
+      # rubocop:disable-next Layout/LineLength -- splitting this regexp would obscure its URL grammar
+      SCHEMELESS_URL_PATTERN = %r{(?<![A-Za-z0-9_./-])(?:[A-Za-z0-9-]+\.)+[A-Za-z]{2,}(?::\d+)?(?:/[^\s"'<>?#]+)+(?:\?[^\s"'<>#]*)?(?:#[^\s"'<>]*)?}i
+      SCHEME_URL_PATTERN = %r{[A-Za-z][A-Za-z0-9+\-.]*://[^\s"'<>]+}
+      TOOL_ACTIONS = {
+        "Read" => :read,
+        "read_file" => :read,
+        "view_image" => :read,
+        "Write" => :modified,
+        "Edit" => :modified,
+        "MultiEdit" => :modified,
+        "apply_patch" => :modified,
+        "move_file" => :modified
+      }.freeze
+      PATH_SCAN_PATTERN = %r{(?:\.\.?/|/)?[A-Za-z0-9._-]+(?:/[A-Za-z0-9._-]+)+}
+
+      Result = Data.define(:files, :tool_activity) do
+        def documents
+          files.select { |item| EvidenceCollector.document_item?(item) }.freeze
+        end
+      end
+
+      class << self
+        def document_item?(item)
+          item.kind == :file && document_path?(item.label)
+        end
+
+        def document_path?(path)
+          basename = File.basename(path).downcase
+          extension = File.extname(path).downcase
+
+          DOCUMENT_BASENAMES.include?(basename) || DOCUMENT_EXTENSIONS.include?(extension)
+        end
+      end
+
+      def call(transcript)
+        tool_activity = []
+        files = {}
+
+        transcript.entries.each do |entry|
+          entry.parts.each do |part|
+            next unless part.type == :tool_use
+
+            parsed_input = parse_input(part.text)
+            tool_activity << build_tool_item(part, parsed_input)
+
+            extract_paths(part.text, parsed_input).each do |path|
+              add_item(files, kind: :file, path: path, action: action_for(part.name), source_ref: part.source_ref)
+            end
+          end
+        end
+
+        file_items = files.values.freeze
+
+        Result.new(files: file_items, tool_activity: tool_activity.freeze)
+      end
+
+      private
+
+      def build_tool_item(part, parsed_input)
+        Item.new(
+          kind: :tool,
+          label: part.name || "(unknown)",
+          evidence: :observed,
+          source_refs: [part.source_ref],
+          attributes: tool_attributes(part.call_id, parsed_input)
+        )
+      end
+
+      def tool_attributes(call_id, parsed_input)
+        attributes = { call_id: call_id }
+        return attributes unless parsed_input.is_a?(Hash)
+
+        attributes[:input_keys] = parsed_input.keys.map { |key| String.new(key.to_s).freeze }.sort.freeze
+        attributes
+      end
+
+      def parse_input(raw_input)
+        return unless raw_input.is_a?(String)
+
+        JSON.parse(raw_input)
+      rescue JSON::ParserError, TypeError
+        nil
+      end
+
+      def extract_paths(raw_input, parsed_input)
+        keyed_paths = extract_keyed_paths(parsed_input)
+        return keyed_paths unless keyed_paths.empty?
+
+        scan_plain_text(raw_input)
+      end
+
+      def extract_keyed_paths(parsed_input)
+        return [] unless parsed_input.is_a?(Array) || parsed_input.is_a?(Hash)
+
+        seen = {}
+        collected = []
+        collect_keyed_paths(parsed_input, seen, collected, under_path_key: false)
+        collected.freeze
+      end
+
+      def collect_keyed_paths(value, seen, collected, under_path_key:)
+        case value
+        when Hash
+          value.each do |key, child|
+            collect_keyed_paths(child, seen, collected, under_path_key: under_path_key || PATH_KEYS.include?(key.to_s))
+          end
+        when Array
+          value.each do |child|
+            collect_keyed_paths(child, seen, collected, under_path_key: under_path_key)
+          end
+        when String
+          append_unique_path(collected, seen, value) if valid_keyed_path?(value) && under_path_key
+        end
+      end
+
+      def scan_plain_text(raw_input)
+        return [].freeze unless raw_input.is_a?(String)
+
+        spans = url_spans(raw_input)
+        span_index = 0
+        seen = {}
+
+        raw_input.to_enum(:scan, PATH_SCAN_PATTERN).each_with_object([]) do |_ignored, collected|
+          match = Regexp.last_match
+          span_index = advance_span_index(spans, span_index, match.begin(0))
+          next if overlap?(spans, span_index, match.begin(0), match.end(0))
+
+          append_unique_path(collected, seen, match[0])
+        end.freeze
+      end
+
+      def valid_keyed_path?(value)
+        !value.empty? && !value.include?("\0") && !url_like?(value)
+      end
+
+      def url_like?(value)
+        value.match?(/\A#{SCHEME_URL_PATTERN}\z/o) || value.match?(/\A#{SCHEMELESS_URL_PATTERN}\z/o)
+      end
+
+      def url_spans(raw_input)
+        spans = []
+
+        [SCHEME_URL_PATTERN, SCHEMELESS_URL_PATTERN].each do |pattern|
+          raw_input.to_enum(:scan, pattern).each do
+            match = Regexp.last_match
+            spans << [match.begin(0), match.end(0)]
+          end
+        end
+
+        merge_spans(spans)
+      end
+
+      def merge_spans(spans)
+        return [].freeze if spans.empty?
+
+        sorted_spans = spans.sort_by { |start_index, end_index| [start_index, end_index] }
+        merged = [sorted_spans.first.dup]
+
+        sorted_spans.drop(1).each do |start_index, end_index|
+          current_span = merged.last
+
+          if start_index <= current_span[1]
+            current_span[1] = [current_span[1], end_index].max
+          else
+            merged << [start_index, end_index]
+          end
+        end
+
+        merged.freeze
+      end
+
+      def advance_span_index(spans, span_index, match_start)
+        span_index += 1 while span_index < spans.length && spans[span_index][1] <= match_start
+        span_index
+      end
+
+      def overlap?(spans, span_index, _match_start, match_end)
+        span_index < spans.length && spans[span_index][0] < match_end
+      end
+
+      def append_unique_path(collected, seen, path)
+        return if seen.key?(path)
+
+        seen[path] = true
+        collected << path
+      end
+
+      def action_for(tool_name)
+        TOOL_ACTIONS.fetch(tool_name.to_s, :referenced)
+      end
+
+      def add_item(collection, kind:, path:, action:, source_ref:)
+        key = [kind, path, action]
+        existing = collection[key]
+
+        if existing
+          return if existing.source_refs.include?(source_ref)
+
+          collection[key] = Item.new(
+            kind: kind,
+            label: path,
+            evidence: :observed,
+            source_refs: existing.source_refs + [source_ref],
+            attributes: existing.attributes
+          )
+          return
+        end
+
+        collection[key] = Item.new(
+          kind: kind,
+          label: path,
+          evidence: :observed,
+          source_refs: [source_ref],
+          attributes: { action: action }
+        )
+      end
+    end
+  end
+end