agent-session_context 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 354885a52b8cbdd91468f869bb75a09850c1cb9b065f5c05d87f2ec83d70e9cd
+  data.tar.gz: c0bdeac8d7994aa514e01b7b08b57273d843e67359ce29875447925bfe665a23
+SHA512:
+  metadata.gz: d3be9d23e7d1ae974cdc4f516a61159e586e88573a2fea32e8d28137220d298036cc4a461f87c98c29787c13a5ee51789e45e7e55df4858db22a57bde529455b
+  data.tar.gz: 2cbf65397f9bd18dda3fdfda24fc49f6633946d66f82b0589d221a5a11afb63415c1cbe222f5be58e1a6009012e700ad5189570271c030ee9b24a08e4ac745ba

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-09-01
+
+- Use the `agent-session_context` distribution, `Agent::SessionContext`
+  namespace, and `agent-session-context` executable to avoid collisions with
+  the existing `agent-context` gem and `Agent::Context` namespace.
+- Let `--current` choose the uniquely latest session metadata timestamp only
+  when no supported session environment identifier is present. Present
+  identifiers keep their validation and errors; `--agent` narrows disk
+  fallback, empty stores raise `CurrentSessionUnavailable`, the CLI warns with
+  the selected UID, and exact ties refuse with explicit-session guidance.
+- Make `show` include exact user prompts and a deduplicated injected-context
+  inventory, with explicit `--include-injected`/`include_injected: true` access
+  to full injected text and documented raw-transcript exclusions.
+- Add real Claude Code and Codex CLI JSONL fixtures for the public `show`,
+  `prompts`, and `summarize` contract.
+- Verify prompt filtering against injected environment, AGENTS, slash-command,
+  and tool-result records while keeping observed file/tool evidence grounded to
+  source refs.
+- Bound summarizer subprocess stdout/stderr streaming to independent `1 MiB`
+  caps, add per-call timeout controls across config/API/CLI, and package the
+  shared subprocess/config support.
+- Verify the Codex summarization backend against a live recorded session.
+- Document the recorded-evidence model, CLI/API surface, privacy boundaries,
+  and provider boundaries.
+- Include source, changelog, and issue-tracker links for the public GitHub
+  repository in the gem metadata.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Lucian Ghinda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,268 @@
+# Agent Session Context
+
+[![Build](https://github.com/lucianghinda/agent-session-context/actions/workflows/main.yml/badge.svg)](https://github.com/lucianghinda/agent-session-context/actions/workflows/main.yml)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-red.svg)](https://www.ruby-lang.org/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+
+Inspect and summarize recorded Claude Code and Codex sessions.
+
+## Installation
+
+Use Ruby 3.2 or newer.
+
+Add this line to your application's **Gemfile**:
+
+```ruby
+gem "agent-session_context"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+Show the latest recorded session:
+
+```bash
+agent-session-context show --current
+```
+
+## Usage
+
+### Basic Usage
+
+Show an exact session:
+
+```bash
+agent-session-context show codex:SESSION_ID
+```
+
+Disambiguate a bare identifier:
+
+```bash
+agent-session-context show SESSION_ID --agent codex
+```
+
+List exact user prompts:
+
+```bash
+agent-session-context prompts --current
+```
+
+Render prompts as JSON Lines:
+
+```bash
+agent-session-context prompts --current --format jsonl
+```
+
+### Current Sessions
+
+Use these variables for `--current`, in order:
+
+1. `AGENT_SESSION_ID` with `AGENT_NAME`
+2. `CLAUDE_CODE_SESSION_ID`
+3. `CODEX_SESSION_ID`
+4. `CODEX_THREAD_ID`
+
+Without variables, let the command select the unique newest session metadata.
+
+Pass `--agent` to restrict that disk search.
+
+Keep present identifiers authoritative.
+
+Never trigger fallback after validating a present identifier.
+
+Clear conflicting Claude and Codex identifiers before retrying.
+
+Expect missing targets, empty stores, and timestamp ties to fail.
+
+Read the selected UID from the CLI warning.
+
+Treat disk selection as recency, not live context.
+
+### Local Context
+
+Include deduplicated injected text explicitly:
+
+```bash
+agent-session-context show --current --include-injected
+```
+
+Review exact prompts and injected text before sharing them.
+
+Expect `show` to exclude assistant messages, thinking, tool-result bodies, and raw envelopes.
+
+Use `show` and `prompts` without starting a model.
+
+### Summaries
+
+Create a grounded summary:
+
+```bash
+agent-session-context summarize --current
+```
+
+Choose a backend and timeout:
+
+```bash
+agent-session-context summarize --current --using codex --timeout 45
+```
+
+Codex summarization was tested successfully against a live recorded session.
+
+Expect summaries to cite recorded source references.
+
+Expect summaries to exclude thinking, tool results, injected blocks, and raw records.
+
+Treat Codex filesystem access as read-only, not hermetic.
+
+### Ruby API
+
+Resolve and inspect a session:
+
+```ruby
+require "agent/session_context"
+
+session = Agent::SessionContext.resolve("codex:SESSION_ID")
+snapshot = Agent::SessionContext.show(session)
+```
+
+Inspect the newest recorded Codex session:
+
+```ruby
+session = Agent::SessionContext.current(agent: :codex, env: {})
+prompts = Agent::SessionContext.prompts(session)
+```
+
+Create a summary with built-in settings:
+
+```ruby
+summary = Agent::SessionContext.summarize(session, using: :codex, timeout: 45)
+```
+
+Use a custom summarizer:
+
+```ruby
+summary = Agent::SessionContext.summarize(
+  session,
+  summarizer: ->(prompt:, schema:) { call_your_model(prompt, schema) }
+)
+```
+
+Replace `call_your_model` with your adapter.
+
+Return a JSON string matching the provided schema.
+
+Pass either `summarizer:` or `timeout:`, never both.
+
+### Supported Public Ruby API
+
+`Agent::SessionContext.resolve` and `Agent::SessionContext.current` return `Agent::Sessions::Session`.
+
+`Agent::SessionContext.show` returns an `Agent::SessionContext::Snapshot` whose collections contain `Agent::SessionContext::Prompt`, `Agent::SessionContext::InjectedContext`, `Agent::SessionContext::Item`, and `Agent::SessionContext::SourceRef` values as applicable.
+
+`Agent::SessionContext.prompts` returns an array of `Agent::SessionContext::Prompt` values.
+
+`Agent::SessionContext.summarize` returns an `Agent::SessionContext::Snapshot` populated with summary `Agent::SessionContext::Item` values and summary metadata.
+
+`Agent::SessionContext::Snapshot`, `Agent::SessionContext::Prompt`, `Agent::SessionContext::InjectedContext`, `Agent::SessionContext::Item`, and `Agent::SessionContext::SourceRef` are part of the supported public data model.
+
+`Agent::SessionContext::VERSION` is public.
+
+`Agent::SessionContext::CLI::FORMATS` is the supported frozen list of CLI output format names.
+
+The public error classes listed in [Errors](#errors) are part of the compatibility contract.
+
+### Internal Architecture
+
+`resolve -> capture -> extract/collect -> optionally summarize -> build snapshot -> render`.
+
+`show` can expose injected text only when you opt into `include_injected`, while `summarize` keeps injected blocks and tool-result bodies out of the model prompt.
+
+Except for `Agent::SessionContext::CLI::FORMATS`, the CLI implementation, builders, collectors, parsers, runners, renderers, and built-in summarizer adapters are internal details without compatibility guarantees.
+
+## Options
+
+| Option | Description |
+|---|---|
+| `--current` | Use environment identity, then the newest disk metadata. |
+| `--agent claude\|codex` | Restrict explicit lookup or disk fallback. |
+| `--format FORMAT` | Choose text, Markdown, JSON, or JSON Lines when supported. |
+| `--include-injected` | Include deduplicated injected text with `show`. |
+| `--using BACKEND` | Choose `auto`, `claude`, or `codex` for summaries. |
+| `--timeout SECONDS` | Set each provider call timeout from 1 through 3600 seconds. |
+
+Run `agent-session-context help` for command details.
+
+### Configuration
+
+Expect only `summarize` to load configuration.
+
+Configuration paths retain the original `agent-context` name for compatibility.
+
+Create `.agent-context.yml` in the recorded project:
+
+```yaml
+summarize:
+  timeout_seconds: 300
+```
+
+Set user defaults in `$XDG_CONFIG_HOME/agent_context/config.yml`.
+
+Otherwise, use `$HOME/.config/agent_context/config.yml`.
+
+Use `XDG_CONFIG_HOME` exclusively when it contains an absolute path.
+
+Let project configuration override user defaults.
+
+Pass `--timeout` to override both files.
+
+Use finite numbers from `1` through `3600`.
+
+Apply the timeout to each provider call.
+
+### Output Formats
+
+| Command | Formats |
+|---|---|
+| `show` | `text`, `markdown`, `json` |
+| `prompts` | `text`, `markdown`, `json`, `jsonl` |
+| `summarize` | `text`, `markdown`, `json` |
+
+### Errors
+
+Handle these public errors:
+
+- `Agent::SessionContext::SessionNotFound`
+- `Agent::SessionContext::AmbiguousSession`
+- `Agent::SessionContext::CurrentSessionUnavailable`
+- `Agent::SessionContext::UnsupportedAgent`
+- `Agent::SessionContext::ConfigurationError`
+- `Agent::SessionContext::SummarizerUnavailable`
+- `Agent::SessionContext::SummarizerFailed`
+- `Agent::SessionContext::InvalidSummary`
+
+## Contributing
+
+Fork the repository and create a branch.
+
+Run the test suite:
+
+```bash
+bundle exec rake test
+```
+
+Open a pull request with tests and documentation.
+
+Follow [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+Report bugs through [GitHub Issues](https://github.com/lucianghinda/agent-session-context/issues).
+
+## License
+
+Use the gem under the MIT License.
+
+See [LICENSE.txt](LICENSE.txt).

data/exe/agent-session-context

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "agent/session_context"
+
+exit Agent::SessionContext::CLI.new(ARGV).run

data/lib/agent/session_context/builder.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    class Builder
+      PromptsResult = Data.define(:prompts, :reader_warnings) do
+        def partial_capture?
+          !reader_warnings.empty?
+        end
+      end
+
+      def initialize(
+        catalog: Agent::Sessions,
+        now: Time.now,
+        collector: EvidenceCollector.new,
+        prompt_extractor: PromptExtractor.new,
+        injected_context_collector: InjectedContextCollector.new
+      )
+        @catalog = catalog
+        @now = now
+        @collector = collector
+        @prompt_extractor = prompt_extractor
+        @injected_context_collector = injected_context_collector
+      end
+
+      def show(session, include_injected: false)
+        validate_include_injected!(include_injected)
+        transcript = capture(session)
+        observed = @collector.call(transcript)
+
+        build_snapshot(
+          session:,
+          transcript:,
+          observed:,
+          prompts: @prompt_extractor.call(transcript),
+          injected_context: @injected_context_collector.call(transcript, include_text: include_injected),
+          warnings: transcript.warnings,
+          summary_metadata: base_metadata(transcript)
+        )
+      end
+
+      def prompts(session)
+        prompts_result(session).prompts
+      end
+
+      def prompts_result(session)
+        transcript = capture(session)
+        PromptsResult.new(
+          prompts: @prompt_extractor.call(transcript),
+          reader_warnings: transcript.warnings
+        )
+      end
+
+      def summarize(session, summarizer:)
+        transcript = capture(session)
+        observed = @collector.call(transcript)
+        semantic = SemanticPipeline.new(backend: summarizer).call(transcript:, observed:)
+        semantic_collections, unknown_warnings = collect_semantic_items(semantic.items)
+
+        build_snapshot(
+          session: session,
+          transcript: transcript,
+          observed: observed,
+          semantic_collections: semantic_collections,
+          warnings: transcript.warnings + semantic.warnings + unknown_warnings,
+          summary_metadata: semantic.metadata.merge(base_metadata(transcript))
+        )
+      end
+
+      private
+
+      def validate_include_injected!(value)
+        return if value.equal?(true) || value.equal?(false)
+
+        raise ArgumentError, "include_injected must be true or false"
+      end
+
+      def capture(session)
+        Transcript.capture(session, reader: @catalog.read(session), now: @now)
+      end
+
+      def collect_semantic_items(items)
+        collections = empty_semantic_collections
+        warnings = []
+
+        items.each do |item|
+          field = SemanticCategories.lookup(item.kind)&.snapshot_field
+          unless field
+            warnings << "Dropped unknown semantic kind #{item.kind.inspect}"
+            next
+          end
+
+          collections[field] << item
+        end
+
+        [collections.transform_values(&:freeze).freeze, warnings.freeze]
+      end
+
+      def empty_semantic_collections
+        SemanticCategories.snapshot_fields.to_h do |field|
+          [field, []]
+        end
+      end
+
+      def build_snapshot(
+        session:,
+        transcript:,
+        observed:,
+        warnings:,
+        summary_metadata:,
+        prompts: [],
+        injected_context: [],
+        semantic_collections: empty_semantic_collections.transform_values(&:freeze).freeze
+      )
+        Snapshot.new(
+          session_uid: session.uid,
+          agent: session.agent,
+          project_path: session.project_path,
+          captured_at: transcript.captured_at,
+          message_count: transcript.entries.length,
+          prompts:,
+          injected_context:,
+          files: observed.files,
+          documents: observed.documents,
+          tool_activity: observed.tool_activity,
+          **semantic_snapshot_attributes(semantic_collections),
+          warnings: warnings,
+          summary_metadata: summary_metadata
+        )
+      end
+
+      def semantic_snapshot_attributes(semantic_collections)
+        SemanticCategories.snapshot_fields.to_h do |field|
+          [field, semantic_collections.fetch(field)]
+        end
+      end
+
+      def base_metadata(transcript)
+        metadata = { injected_parts_filtered: transcript.entries.sum { |entry| entry.parts.count(&:injected) } }
+        reader_warning_count = transcript.warnings.length
+        metadata[:reader_warning_count] = reader_warning_count if reader_warning_count.positive?
+        metadata
+      end
+    end
+  end
+end

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

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