agent_session_context 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e25d4c855e914bc804c30b9505d6983513b7465c37832eca6af1aec37cdafb63
+  data.tar.gz: '079e33a4af4f74b9cb23d6aaa07c8c5e8193da29aca3e12c9ea542c52a497c6c'
+SHA512:
+  metadata.gz: c73b78d0a6ff85c7ff84e088e5b68308d4175628c56e9ea201eeffe9ff9a47aad8fd75004537659860922f864dff11fb5aa3eaad8e21b1891345821387ae1e04
+  data.tar.gz: 2647f8a4aad1fa59d5689c7fdfa5af5692af993a33ae00a3474601045a7add3c34453e2587382bf02255a294970fcb7a63fa6f187871241ab21c3afe796d7528

data/CHANGELOG.md

@@ -0,0 +1,43 @@
+## [Unreleased]
+
+## [1.0.0] - 2026-09-10
+
+- Require `agent_sessions` 0.4, which adds the round-trip grouping the `loop` command is built on.
+- **BREAKING**: the gem is now distributed as `agent_session_context`. The
+  namespace, require path, and executable are unchanged; users change only
+  the Gemfile line.
+- Add the `loop` command and `Agent::SessionContext.loop`, showing a session
+  as the agent loop: prompts, model round trips, tool calls paired with
+  their results, and where it stopped. Moved from `agent_sessions` before it
+  shipped there, since this gem interprets what a store recorded rather than
+  normalizing it. Prints byte sizes and tool names, never prompt or
+  tool-result bodies; renders the same session the same way regardless of
+  machine or time zone; and always labels the ending inferred, since no
+  on-disk transcript records why a session stopped.
+
+## [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,298 @@
+# 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.
+
+### Agent Loop
+
+Show a session as the agent loop:
+
+```bash
+agent-session-context loop --current
+```
+
+Print prompts, model round trips, tool calls paired with their results, and where the session stopped.
+
+Print byte sizes and tool names only, never prompt or tool-result bodies.
+
+Expect the ending to always read as inferred: no store on disk records why a session stopped.
+
+Expect deterministic output: render the same session the same way regardless of machine or time zone.
+
+Render `loop` as text, Markdown, JSON, or JSON Lines with `--format`.
+
+### 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)
+```
+
+Read a session as the agent loop:
+
+```ruby
+loop = Agent::SessionContext.loop(session)
+loop.ending #=> :answered, :stopped_in_the_loop, :not_a_model_record, or :empty
+```
+
+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.loop` returns an `Agent::SessionContext::Loop`.
+
+`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::Loop` and `Agent::SessionContext::ToolCall` are part of the supported public data model. `Agent::SessionContext::LoopView` is internal.
+
+`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` |
+| `loop` | `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,150 @@
+# 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 loop(session)
+        Loop.for(@catalog.read(session))
+      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