agent-session_context 0.1.0

data/lib/agent/session_context/renderers/human_display.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    module Renderers
+      module HumanDisplay
+        module_function
+
+        def text_inline(value)
+          sanitize_string(value, preserve_newlines: false)
+        end
+
+        def text_block(value)
+          sanitize_string(value, preserve_newlines: true).split("\n", -1).map { |line| "| #{line}" }.join("\n")
+        end
+
+        def markdown_text(value)
+          escape_markdown(text_inline(value))
+        end
+
+        def markdown_literal(value)
+          literal = text_inline(value)
+          return "<code></code>" if literal.empty?
+          return "<code>#{literal}</code>" if literal.match?(/\A +\z/)
+
+          fence = "`" * [longest_backtick_run(literal) + 1, 1].max
+          "#{fence}#{code_span_content(literal)}#{fence}"
+        end
+
+        def markdown_block(value)
+          content = sanitize_string(value, preserve_newlines: true)
+          fence = "`" * [longest_backtick_run(content) + 1, 3].max
+
+          ["#{fence}text", content, fence].join("\n")
+        end
+
+        def timestamp(value)
+          serialized = Serializer.serialize_timestamp(value)
+          return if serialized.nil?
+
+          serialized.to_s
+        end
+
+        def refs(source_refs)
+          Array(source_refs).map { |ref| "#{ref.message_index}:#{ref.part_index}" }.join(", ")
+        end
+
+        def attributes(hash, inline_formatter:)
+          Serializer.normalized_hash_entries(hash).map do |key, value|
+            "#{inline_formatter.call(key)}=#{attribute_value(value, inline_formatter)}"
+          end.join(", ")
+        end
+
+        def attribute_value(value, inline_formatter)
+          return "{#{attributes(value, inline_formatter:)}}" if value.is_a?(Hash)
+          return value.map { |entry| attribute_value(entry, inline_formatter) }.join(",") if value.is_a?(Array)
+
+          inline_formatter.call(Serializer.serialize(value).to_s)
+        end
+
+        def sanitize_string(value, preserve_newlines:)
+          scrubbed = Serializer.scrub_string(value.to_s)
+          buffer = String.new(encoding: Encoding::UTF_8)
+
+          scrubbed.each_codepoint do |codepoint|
+            if preserve_newlines && codepoint == 0x0A
+              buffer << "\n"
+              next
+            end
+
+            visible = visible_control_escape(codepoint)
+            buffer << (visible || codepoint)
+          end
+
+          buffer
+        end
+
+        def escape_markdown(value)
+          escaped = value.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+          escaped = escaped.gsub(/([\\`*\[\]#])/, "\\\\\\1")
+          escaped = escaped.gsub(/(^|[^[:alnum:]])_([^_]+)_([^[:alnum:]]|$)/, '\1\\_\2\\_\3')
+          escaped.gsub("-", "\\-")
+        end
+
+        def code_span_content(literal)
+          return " #{literal} " if literal.start_with?("`") || literal.end_with?("`")
+          return " #{literal} " if literal.start_with?(" ") && literal.end_with?(" ")
+
+          literal
+        end
+
+        def longest_backtick_run(value)
+          value.scan(/`+/).map(&:length).max || 0
+        end
+
+        def visible_control_escape(codepoint)
+          case codepoint
+          when 0x09
+            "\\t"
+          when 0x0A
+            "\\n"
+          when 0x0D
+            "\\r"
+          when 0x1B
+            "\\e"
+          when 0x00..0x08, 0x0B..0x0C, 0x0E..0x1A, 0x1C..0x1F, 0x7F, 0x80..0x9F
+            format("\\u%04X", codepoint)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agent/session_context/renderers/json.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    module Renderers
+      class JSON
+        def call(value)
+          ::JSON.generate(Serializer.serialize(value))
+        end
+      end
+    end
+  end
+end

data/lib/agent/session_context/renderers/json_lines.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    module Renderers
+      class JSONLines
+        def call(prompts)
+          Array(prompts).map { |prompt| ::JSON.generate(Serializer.serialize(prompt)) }.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/agent/session_context/renderers/markdown.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    module Renderers
+      class Markdown
+        SECTION_ORDER = [
+          ["Goal", :goals],
+          ["Files", :files],
+          ["Documents", :documents],
+          ["Tool activity", :tool_activity],
+          ["Decisions", :decisions],
+          ["Terminology", :terms],
+          ["Constraints", :constraints],
+          ["Open questions", :open_questions],
+          ["Next actions", :next_actions],
+          ["Warnings", :warnings]
+        ].freeze
+        private_constant :SECTION_ORDER
+
+        def call(value)
+          if value.is_a?(Snapshot)
+            render_snapshot(value)
+          else
+            render_prompts(Array(value))
+          end
+        end
+
+        private
+
+        def render_snapshot(snapshot)
+          sections = [render_session(snapshot)]
+          sections << render_snapshot_prompts(snapshot.prompts) if snapshot.prompts.any?
+          sections << render_injected_context(snapshot.injected_context) if snapshot.injected_context.any?
+
+          SECTION_ORDER.each do |title, field|
+            section = render_section(title, snapshot.public_send(field))
+            sections << section if section
+          end
+
+          sections.join("\n\n")
+        end
+
+        def render_prompts(prompts, heading_level: 2)
+          heading = "#" * heading_level
+          prompts.map do |prompt|
+            lines = ["#{heading} Prompt #{prompt.index}"]
+            prompt_at = HumanDisplay.timestamp(prompt.at)
+            lines << "- At: #{HumanDisplay.markdown_literal(prompt_at)}" if prompt_at
+            lines << "- Refs: #{HumanDisplay.markdown_literal(HumanDisplay.refs(prompt.source_refs))}"
+            lines << ""
+            lines << HumanDisplay.markdown_block(prompt.text)
+            lines.join("\n")
+          end.join("\n\n")
+        end
+
+        def render_snapshot_prompts(prompts)
+          ["## User prompts", render_prompts(prompts, heading_level: 3)].join("\n\n")
+        end
+
+        def render_injected_context(contexts)
+          entries = contexts.map do |context|
+            lines = [
+              "### Injected #{HumanDisplay.markdown_literal(context.kind)}",
+              "- Bytes: #{HumanDisplay.markdown_literal(context.bytes)}",
+              "- Occurrences: #{HumanDisplay.markdown_literal(context.occurrences)}",
+              "- Refs: #{HumanDisplay.markdown_literal(HumanDisplay.refs(context.source_refs))}"
+            ]
+            if context.text
+              lines << ""
+              lines << HumanDisplay.markdown_block(context.text)
+            end
+            lines.join("\n")
+          end
+
+          ["## Injected context", entries.join("\n\n")].join("\n\n")
+        end
+
+        def render_session(snapshot)
+          lines = [
+            "## Session",
+            "- UID: #{HumanDisplay.markdown_literal(snapshot.session_uid)}",
+            "- Agent: #{HumanDisplay.markdown_literal(snapshot.agent)}"
+          ]
+          lines << "- Project path: #{HumanDisplay.markdown_literal(snapshot.project_path)}" if snapshot.project_path
+          captured_at = HumanDisplay.timestamp(snapshot.captured_at)
+          lines << "- Captured at: #{HumanDisplay.markdown_literal(captured_at)}" if captured_at
+          lines << "- Message count: #{HumanDisplay.markdown_literal(snapshot.message_count)}"
+          if snapshot.summary_metadata.any?
+            lines << "- Summary metadata: #{HumanDisplay.markdown_literal(attributes(snapshot.summary_metadata))}"
+          end
+          lines.join("\n")
+        end
+
+        def render_section(title, items)
+          return if items.empty?
+
+          if title == "Warnings"
+            return (["## #{title}"] + items.map { |warning| "- #{HumanDisplay.markdown_text(warning)}" }).join("\n")
+          end
+
+          (["## #{title}"] + items.map { |item| "- #{item_line(item)}" }).join("\n")
+        end
+
+        def item_line(item)
+          fragments = [base_item_text(item)]
+          attrs = attributes(item.attributes)
+          fragments << "(#{HumanDisplay.markdown_literal(attrs)})" unless attrs.empty?
+          fragments << HumanDisplay.markdown_literal("[#{item.evidence}]")
+          fragments << "refs #{HumanDisplay.markdown_literal(HumanDisplay.refs(item.source_refs))}"
+          fragments.join(" ")
+        end
+
+        def base_item_text(item)
+          return "#{HumanDisplay.markdown_text(item.label)}: #{HumanDisplay.markdown_text(item.detail)}" if item.detail
+
+          HumanDisplay.markdown_text(item.label)
+        end
+
+        def attributes(hash)
+          HumanDisplay.attributes(hash, inline_formatter: HumanDisplay.method(:text_inline))
+        end
+      end
+    end
+  end
+end

data/lib/agent/session_context/renderers/serializer.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    module Renderers
+      module Serializer
+        module_function
+
+        def serialize(value)
+          case value
+          when nil, true, false, Integer
+            value
+          when Float
+            serialize_float(value)
+          when String
+            scrub_string(value)
+          when Symbol
+            scrub_string(value.to_s)
+          when Time
+            value.iso8601
+          when Array
+            value.map { |entry| serialize(entry) }
+          when Hash
+            serialize_hash(value)
+          else
+            return serialize_data(value) if data_object?(value)
+
+            scrub_string(value.to_s)
+          end
+        end
+
+        def scrub_string(value)
+          value.encode("UTF-8", invalid: :replace, undef: :replace)
+        end
+
+        def data_object?(value)
+          defined?(Data) && value.is_a?(Data)
+        end
+
+        def serialize_data(value)
+          value.members.to_h do |member|
+            [member.to_s, serialize_member(member, value.public_send(member))]
+          end
+        end
+
+        def serialize_hash(value)
+          normalized_hash_entries(value).each_with_object({}) do |(key, nested_value), serialized|
+            serialized[key] = serialize(nested_value)
+          end
+        end
+
+        def normalized_hash_entries(value)
+          entries = value.each_with_object([]) do |(key, nested_value), collected|
+            collected << [normalized_key(key), nested_value]
+          end
+          detect_duplicate_keys!(entries)
+          entries.sort_by(&:first)
+        end
+
+        def detect_duplicate_keys!(entries)
+          entries.group_by(&:first).sort_by(&:first).each do |key, grouped_entries|
+            next unless grouped_entries.length > 1
+
+            raise ArgumentError, "duplicate serialized key: #{safe_dump(key)}"
+          end
+        end
+
+        def serialize_member(member, value)
+          return serialize_timestamp(value) if %i[at captured_at].include?(member.to_sym)
+
+          serialize(value)
+        end
+
+        def serialize_timestamp(value)
+          case value
+          when nil
+            nil
+          when Time
+            value.iso8601
+          when String
+            scrub_string(value)
+          else
+            raise ArgumentError, "unsupported timestamp value: #{unsupported_value_label(value)}"
+          end
+        end
+
+        def serialize_float(value)
+          raise ArgumentError, "unsupported numeric value: #{unsupported_value_label(value)}" unless value.finite?
+
+          value
+        end
+
+        def normalized_key(key)
+          scrub_string(key.to_s)
+        end
+
+        def safe_dump(value)
+          case value
+          when String
+            scrub_string(value).dump
+          when Symbol
+            scrub_string(value.to_s).dump
+          when Float
+            return "NaN" if value.nan?
+            return "Infinity" if value.infinite? == 1
+            return "-Infinity" if value.infinite? == -1
+
+            value.to_s
+          else
+            scrub_string(value.inspect)
+          end
+        end
+
+        def unsupported_value_label(value)
+          klass = value.class
+          name = klass.name
+          return "(anonymous class)" if name.nil? || name.empty?
+
+          scrub_string(name)
+        end
+      end
+    end
+  end
+end

data/lib/agent/session_context/renderers/text.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    module Renderers
+      class Text
+        SECTION_ORDER = [
+          ["Goal", :goals],
+          ["Files", :files],
+          ["Documents", :documents],
+          ["Tool activity", :tool_activity],
+          ["Decisions", :decisions],
+          ["Terminology", :terms],
+          ["Constraints", :constraints],
+          ["Open questions", :open_questions],
+          ["Next actions", :next_actions],
+          ["Warnings", :warnings]
+        ].freeze
+        private_constant :SECTION_ORDER
+
+        def call(value)
+          if value.is_a?(Snapshot)
+            render_snapshot(value)
+          else
+            render_prompts(Array(value))
+          end
+        end
+
+        private
+
+        def render_snapshot(snapshot)
+          sections = [render_session(snapshot)]
+          sections << render_snapshot_prompts(snapshot.prompts) if snapshot.prompts.any?
+          sections << render_injected_context(snapshot.injected_context) if snapshot.injected_context.any?
+
+          SECTION_ORDER.each do |title, field|
+            section = render_section(title, snapshot.public_send(field))
+            sections << section if section
+          end
+
+          sections.join("\n\n")
+        end
+
+        def render_snapshot_prompts(prompts)
+          ["User prompts", render_prompts(prompts)].join("\n\n")
+        end
+
+        def render_injected_context(contexts)
+          entries = contexts.map do |context|
+            lines = [
+              "Injected #{HumanDisplay.text_inline(context.kind)}",
+              "- Bytes: #{context.bytes}",
+              "- Occurrences: #{context.occurrences}",
+              "- Refs: #{HumanDisplay.refs(context.source_refs)}"
+            ]
+            if context.text
+              lines << "- Text:"
+              lines << HumanDisplay.text_block(context.text)
+            end
+            lines.join("\n")
+          end
+
+          ["Injected context", entries.join("\n\n")].join("\n\n")
+        end
+
+        def render_prompts(prompts)
+          prompts.map do |prompt|
+            lines = ["Prompt #{prompt.index}"]
+            prompt_at = HumanDisplay.timestamp(prompt.at)
+            lines << "- At: #{HumanDisplay.text_inline(prompt_at)}" if prompt_at
+            lines << "- Refs: #{HumanDisplay.refs(prompt.source_refs)}"
+            lines << HumanDisplay.text_block(prompt.text)
+            lines.join("\n")
+          end.join("\n\n")
+        end
+
+        def render_session(snapshot)
+          lines = [
+            "Session",
+            "- UID: #{HumanDisplay.text_inline(snapshot.session_uid)}",
+            "- Agent: #{HumanDisplay.text_inline(snapshot.agent)}"
+          ]
+          lines << "- Project path: #{HumanDisplay.text_inline(snapshot.project_path)}" if snapshot.project_path
+          captured_at = HumanDisplay.timestamp(snapshot.captured_at)
+          lines << "- Captured at: #{HumanDisplay.text_inline(captured_at)}" if captured_at
+          lines << "- Message count: #{snapshot.message_count}"
+          lines << "- Summary metadata: #{attributes(snapshot.summary_metadata)}" if snapshot.summary_metadata.any?
+          lines.join("\n")
+        end
+
+        def render_section(title, items)
+          return if items.empty?
+
+          if title == "Warnings"
+            return ([title] + items.map { |warning| "- #{HumanDisplay.text_inline(warning)}" }).join("\n")
+          end
+
+          ([title] + items.map { |item| "- #{item_line(item)}" }).join("\n")
+        end
+
+        def item_line(item)
+          fragments = [base_item_text(item)]
+          attrs = attributes(item.attributes)
+          fragments << "(#{attrs})" unless attrs.empty?
+          fragments << "[#{item.evidence}]"
+          fragments << "refs #{HumanDisplay.refs(item.source_refs)}"
+          fragments.join(" ")
+        end
+
+        def base_item_text(item)
+          return "#{HumanDisplay.text_inline(item.label)}: #{HumanDisplay.text_inline(item.detail)}" if item.detail
+
+          HumanDisplay.text_inline(item.label)
+        end
+
+        def attributes(hash)
+          HumanDisplay.attributes(hash, inline_formatter: HumanDisplay.method(:text_inline))
+        end
+      end
+    end
+  end
+end

data/lib/agent/session_context/semantic_categories.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Agent
+  module SessionContext
+    class SemanticCategories
+      Category = Data.define(
+        :external_key,
+        :internal_kind,
+        :snapshot_field,
+        :prompt_description,
+        :item_shape
+      )
+
+      ALL = [
+        Category.new(
+          external_key: "goals",
+          internal_kind: :goal,
+          snapshot_field: :goals,
+          prompt_description: "stated goals or desired outcomes from the conversation",
+          item_shape: :text
+        ),
+        Category.new(
+          external_key: "decisions",
+          internal_kind: :decision,
+          snapshot_field: :decisions,
+          prompt_description: "decisions the participants have already made",
+          item_shape: :text
+        ),
+        Category.new(
+          external_key: "terms",
+          internal_kind: :term,
+          snapshot_field: :terms,
+          prompt_description: "project-specific terms with their definitions",
+          item_shape: :term
+        ),
+        Category.new(
+          external_key: "constraints",
+          internal_kind: :constraint,
+          snapshot_field: :constraints,
+          prompt_description: "limits, requirements, or non-negotiables",
+          item_shape: :text
+        ),
+        Category.new(
+          external_key: "open_questions",
+          internal_kind: :open_question,
+          snapshot_field: :open_questions,
+          prompt_description: "questions that are still unresolved",
+          item_shape: :text
+        ),
+        Category.new(
+          external_key: "next_actions",
+          internal_kind: :next_action,
+          snapshot_field: :next_actions,
+          prompt_description: "concrete follow-up actions that someone should take",
+          item_shape: :text
+        )
+      ].freeze
+      EXTERNAL_KEYS = ALL.map(&:external_key).freeze
+      SNAPSHOT_FIELDS = ALL.map(&:snapshot_field).uniq.freeze
+      EXTERNAL_INDEX = ALL.to_h { |category| [category.external_key, category] }.freeze
+      INTERNAL_INDEX = ALL.to_h { |category| [category.internal_kind, category] }.freeze
+
+      private_constant :EXTERNAL_KEYS, :SNAPSHOT_FIELDS, :EXTERNAL_INDEX, :INTERNAL_INDEX
+
+      class << self
+        def all
+          ALL
+        end
+
+        def external_keys
+          EXTERNAL_KEYS
+        end
+
+        def snapshot_fields
+          SNAPSHOT_FIELDS
+        end
+
+        def lookup(identifier)
+          case identifier
+          when String
+            EXTERNAL_INDEX[identifier]
+          when Symbol
+            INTERNAL_INDEX[identifier]
+          end
+        end
+      end
+    end
+  end
+end