command_tower 0.17.0 → 0.18.0

data/app/services/command_tower/messaging/inbox/reader.rb

@@ -6,6 +6,9 @@ module CommandTower
       class Reader
         DEFAULT_LIMIT = 50
         MAX_LIMIT = 100
+        WINDOW_LIMIT = 5
+        WINDOW_MAX_OLDER = 2
+        OLDEST_UNREAD = "oldest_unread"
         SCOPE_INBOX = "inbox"
         SCOPE_ARCHIVED = "archived"
         ALLOWED_SCOPES = [SCOPE_INBOX, SCOPE_ARCHIVED].freeze
@@ -17,28 +20,36 @@ module CommandTower
             offset = normalize_offset!(offset)
             scope = normalize_scope!(scope)
 
-            list_scope =
-              if scope == SCOPE_ARCHIVED
-                Messaging::InboxItem.archived_list
-              else
-                Messaging::InboxItem.default_list
-              end
-
-            scoped = Scope.for_recipient(recipient_id).merge(list_scope)
-            total_count = scoped.count
-            records =
-              scoped
-                .includes(:communication)
-                .order(Arel.sql("messaging_inbox_items.created_at DESC, messaging_inbox_items.id DESC"))
-                .limit(limit)
-                .offset(offset)
-                .to_a
+            scoped = Scope.for_recipient(recipient_id).merge(list_scope_for(scope))
+            page_rows = entry_page_rows(scoped, limit:, offset:)
+            members = page_members(scoped, page_rows)
 
             ListResult.build(
-              items: records.map { |record| ItemResult.from_record(record) },
+              items: page_rows.map { |row| build_entry(row, members) },
               limit:,
               offset:,
-              total_count:,
+              total_count: entry_count(scoped),
+            )
+          end
+
+          def conversation(recipient_id:, key:, scope: SCOPE_INBOX, around: nil, before_id: nil, after_id: nil, limit: nil)
+            recipient_id = require_recipient_id!(recipient_id)
+            raise ValidationError, "key is required" if blank?(key)
+
+            scope = normalize_scope!(scope)
+            records = members_for_key(recipient_id:, key:, scope:)
+            raise NotFoundError, "conversation not found" if records.empty?
+
+            window = conversation_window(records, around:, before_id:, after_id:, limit:)
+            latest = records.last
+            ConversationResult.build(
+              scope:,
+              subject: latest.communication.conversation_title,
+              message_count: records.size,
+              unread_count: records.count { |record| record.viewed_at.nil? },
+              inbox_item_ids: records.map(&:id),
+              message_ids: window ? window.fetch(:message_ids) : records.map(&:id),
+              window: window&.except(:message_ids),
             )
           end
 
@@ -106,6 +117,208 @@ module CommandTower
             value
           end
 
+          def list_scope_for(scope)
+            if scope == SCOPE_ARCHIVED
+              Messaging::InboxItem.archived_list
+            else
+              Messaging::InboxItem.default_list
+            end
+          end
+
+          def entry_page_rows(scoped, limit:, offset:)
+            sql = <<~SQL.squish
+              SELECT conversation_key, inbox_item_id AS latest_id, item_created_at AS activity_at
+              FROM (
+                SELECT
+                  members.*,
+                  ROW_NUMBER() OVER (
+                    PARTITION BY entry_group
+                    ORDER BY item_created_at DESC, inbox_item_id DESC
+                  ) AS recency_rank
+                FROM (#{member_groups_sql(scoped)}) members
+              ) ranked
+              WHERE recency_rank = 1
+              ORDER BY activity_at DESC, latest_id DESC
+              LIMIT #{limit} OFFSET #{offset}
+            SQL
+
+            Messaging::InboxItem.connection.select_all(sql).to_a
+          end
+
+          def entry_count(scoped)
+            sql = <<~SQL.squish
+              SELECT COUNT(*) FROM (
+                SELECT entry_group
+                FROM (#{member_groups_sql(scoped)}) members
+                GROUP BY entry_group
+              ) entry_groups
+            SQL
+
+            Messaging::InboxItem.connection.select_value(sql).to_i
+          end
+
+          def member_groups_sql(scoped)
+            scoped.select(Arel.sql(<<~SQL.squish)).to_sql
+              messaging_inbox_items.id AS inbox_item_id,
+              messaging_inbox_items.created_at AS item_created_at,
+              messaging_communications.conversation_key AS conversation_key,
+              CASE
+                WHEN messaging_communications.conversation_key IS NULL
+                  THEN CONCAT('m:', messaging_inbox_items.id)
+                ELSE CONCAT('c:', messaging_communications.conversation_key)
+              END AS entry_group
+            SQL
+          end
+
+          def page_members(scoped, page_rows)
+            keys = page_rows.filter_map { |row| row_value(row, "conversation_key").presence }
+            standalone_ids = page_rows.filter_map do |row|
+              next if row_value(row, "conversation_key").present?
+
+              Integer(row_value(row, "latest_id"))
+            end
+            ids = standalone_ids.dup
+            if keys.any?
+              ids.concat(
+                scoped.where(messaging_communications: { conversation_key: keys }).pluck("messaging_inbox_items.id"),
+              )
+            end
+            return [] if ids.empty?
+
+            scoped.where(messaging_inbox_items: { id: ids }).includes(:communication).to_a
+          end
+
+          def build_entry(row, members)
+            latest_id = Integer(row_value(row, "latest_id"))
+            key = row_value(row, "conversation_key").presence
+            group =
+              if key
+                members.select { |member| member.communication.conversation_key == key }
+              else
+                members.select { |member| member.id == latest_id }
+              end
+            group = group.sort_by { |member| [member.created_at, member.id] }
+            latest = group.find { |member| member.id == latest_id }
+            raise InvariantError, "latest inbox member missing" if latest.nil?
+
+            conversation = key.present?
+            EntryResult.build(
+              kind: conversation ? "conversation" : "message",
+              id: conversation ? key : latest.id,
+              title: conversation ? latest.communication.conversation_title : latest.communication.title,
+              preview: conversation ? latest.communication.title : nil,
+              activity_at: latest.created_at,
+              message_count: group.size,
+              unread_count: group.count { |member| member.viewed_at.nil? },
+              inbox_item_ids: group.map(&:id),
+            )
+          end
+
+          def conversation_window(records, around:, before_id:, after_id:, limit:)
+            windowed = !around.nil? || !before_id.nil? || !after_id.nil?
+            unless windowed
+              raise ValidationError, "invalid_limit" unless limit.nil?
+
+              return
+            end
+
+            modes = [around, before_id, after_id].count { |value| !value.nil? }
+            raise ValidationError, "invalid_window" unless modes == 1
+
+            page_limit = normalize_window_limit!(limit)
+            cursor = nil
+            anchor = nil
+            slice =
+              if !around.nil?
+                anchor = resolve_anchor(records, around)
+                around_slice(records, anchor, page_limit)
+              elsif !before_id.nil?
+                cursor = find_member!(records, before_id)
+                records.select { |record| before_record?(record, cursor) }.last(page_limit)
+              else
+                cursor = find_member!(records, after_id)
+                records.select { |record| before_record?(cursor, record) }.first(page_limit)
+              end
+
+            flags = window_flags(records, slice, cursor)
+            {
+              message_ids: slice.map(&:id),
+              anchor_inbox_item_id: anchor&.id,
+              has_before: flags.fetch(:has_before),
+              has_after: flags.fetch(:has_after),
+              before_cursor: flags.fetch(:before_cursor),
+              after_cursor: flags.fetch(:after_cursor),
+            }
+          end
+
+          def resolve_anchor(records, around)
+            return records.find { |record| record.viewed_at.nil? } || records.last if around.to_s == OLDEST_UNREAD
+
+            find_member!(records, around)
+          end
+
+          def around_slice(records, anchor, limit)
+            index = records.index(anchor)
+            before_count = [WINDOW_MAX_OLDER, index, limit - 1].min
+            after_count = [limit - 1 - before_count, records.length - 1 - index].min
+            records[(index - before_count)..(index + after_count)]
+          end
+
+          def find_member!(records, inbox_item_id)
+            id = Integer(inbox_item_id)
+            records.find { |record| record.id == id } || raise(ValidationError, "invalid_cursor")
+          rescue ArgumentError, TypeError
+            raise ValidationError, "invalid_cursor"
+          end
+
+          def window_flags(records, slice, cursor)
+            if slice.any?
+              first = slice.first
+              last = slice.last
+              {
+                has_before: records.any? { |record| before_record?(record, first) },
+                has_after: records.any? { |record| before_record?(last, record) },
+                before_cursor: first.id,
+                after_cursor: last.id,
+              }
+            else
+              {
+                has_before: !cursor.nil? && records.any? { |record| before_record?(record, cursor) },
+                has_after: !cursor.nil? && records.any? { |record| before_record?(cursor, record) },
+                before_cursor: nil,
+                after_cursor: nil,
+              }
+            end
+          end
+
+          def before_record?(candidate, boundary)
+            return candidate.id < boundary.id if candidate.created_at == boundary.created_at
+
+            candidate.created_at < boundary.created_at
+          end
+
+          def normalize_window_limit!(limit)
+            value = limit.nil? ? WINDOW_LIMIT : Integer(limit)
+            raise ValidationError, "invalid_limit" if value < 1 || value > WINDOW_LIMIT
+
+            value
+          rescue ArgumentError, TypeError
+            raise ValidationError, "invalid_limit"
+          end
+
+          def members_for_key(recipient_id:, key:, scope:)
+            Scope.for_recipient(recipient_id)
+              .merge(list_scope_for(scope))
+              .includes(:communication)
+              .where(messaging_communications: { conversation_key: key })
+              .order(Arel.sql("messaging_inbox_items.created_at ASC, messaging_inbox_items.id ASC"))
+              .to_a
+          end
+
+          def row_value(row, key)
+            row[key] || row[key.to_sym]
+          end
+
           def blank?(value)
             value.nil? || (value.respond_to?(:empty?) && value.empty?) ||
               (value.is_a?(String) && value.strip.empty?)

data/app/services/command_tower/messaging/inbox.rb

@@ -13,6 +13,10 @@ module CommandTower
         Reader.show(recipient_id:, inbox_item_id:)
       end
 
+      def conversation(recipient_id:, key:, scope: Reader::SCOPE_INBOX, around: nil, before_id: nil, after_id: nil, limit: nil)
+        Reader.conversation(recipient_id:, key:, scope:, around:, before_id:, after_id:, limit:)
+      end
+
       def unread_count(recipient_id:)
         Reader.unread_count(recipient_id:)
       end

data/app/services/command_tower/messaging/rendering/inbox_document_renderer.rb

@@ -36,6 +36,12 @@ module CommandTower
       # fail open and then let a second node still execute composer domain
       # I/O.
       #
+      # A stored `inbox_presentation_snapshot` replaces that live resolution.
+      # Null means there is no retained presentation (legacy rows, or a
+      # document with no presentation node) and the live composer still runs.
+      # An omitted snapshot drops the presentation node and does not call
+      # the composer. A stored payload is rendered as-is.
+      #
       # The composer's raw result is always projected down to the
       # registration's declared `output_keys` before it reaches
       # `content.blocks[].data` (corrective slice — presentation
@@ -50,6 +56,10 @@ module CommandTower
           new(communication:, recipient_id:).render
         end
 
+        def self.compose_shell(communication)
+          new(communication:, recipient_id: nil).compose_shell
+        end
+
         def initialize(communication:, recipient_id:)
           @communication = communication
           @recipient_id = recipient_id
@@ -57,9 +67,16 @@ module CommandTower
         end
 
         def render
-          document = build_from_type_composer || build_generic
+          document = compose_shell
+          snapshot = stored_presentation_snapshot
+          return resolve_presentation_blocks(document) if snapshot.nil?
+          return drop_presentation_blocks(document) if InboxPresentationSnapshot.omitted?(snapshot)
+
+          apply_stored_presentation(document, snapshot)
+        end
 
-          resolve_presentation_blocks(document)
+        def compose_shell
+          build_from_type_composer || build_generic
         end
 
         private
@@ -107,42 +124,42 @@ module CommandTower
           return nil if @presentation_attempted
 
           @presentation_attempted = true
-          key = block[:key]
-          variant = block[:variant]
-
-          definition = CommandTower.config.registry.inbox_presentations.fetch(key)
-          composer_result = definition.composer_class.constantize.call(communication:, recipient_id:)
-
-          # Duck-typed: a registered composer may be a plain class returning a
-          # Hash directly, or a `CommandTower::Services::ApplicationService`
-          # (whose `.call` always returns a `ServiceResult`) — either way the
-          # unwrapped result below is a plain Hash (Rich Messaging Presentation
-          # Authority's composer contract).
-          if composer_result.respond_to?(:success?)
-            return nil unless composer_result.success?
-
-            raw_data = composer_result.data
-          else
-            raw_data = composer_result
+          InboxPresentationResolver.resolve(communication:, recipient_id:, block:)
+        end
+
+        def stored_presentation_snapshot
+          raw = communication.inbox_presentation_snapshot
+          return nil if raw.blank?
+          return nil unless raw.respond_to?(:stringify_keys)
+
+          raw.stringify_keys
+        end
+
+        def drop_presentation_blocks(document)
+          InboxDocument.build(blocks: document.blocks.reject { |block| block[:type] == "presentation" })
+        end
+
+        def apply_stored_presentation(document, snapshot)
+          applied = false
+          blocks = document.blocks.filter_map do |block|
+            next block unless block[:type] == "presentation"
+            next nil if applied
+
+            applied = true
+            stored_presentation_block(snapshot)
           end
 
-          # Explicit output projection (corrective slice — presentation
-          # ServiceResult/context leak fix): only the keys the presentation's
-          # own registration declares in `output_keys` ever reach
-          # `content.blocks[].data`. This is a declared allow-list owned by
-          # the registration, not an inference from `ApplicationService`
-          # argument metadata — composer inputs (e.g. `communication`,
-          # `recipient_id` on an `ApplicationService`-shaped composer),
-          # incidental intermediate context/result keys, and anything else
-          # are dropped unconditionally here, independent of composer shape.
-          { type: "presentation", key:, variant:, data: raw_data.to_h.slice(*definition.output_keys) }.freeze
-        rescue StandardError
-          # Fail-open: unregistered capability, unresolvable composer class,
-          # or a raising/failing composer must never surface as a 500 on the
-          # Inbox read path, and must never allow a subsequent presentation
-          # block in the same document to still attempt composition (the
-          # budget above is consumed regardless of this outcome).
-          nil
+          InboxDocument.build(blocks:)
+        end
+
+        def stored_presentation_block(snapshot)
+          data = snapshot["data"].respond_to?(:to_h) ? snapshot["data"].to_h.deep_symbolize_keys : {}
+          {
+            type: "presentation",
+            key: snapshot["key"].to_s,
+            variant: snapshot["variant"],
+            data:,
+          }.freeze
         end
 
         def paragraph_block(text)

data/app/services/command_tower/messaging/rendering/inbox_presentation_resolver.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Rendering
+      # Resolves one presentation block through the inbox presentation registry.
+      # Returns the projected block, or nil when the capability is missing,
+      # the composer fails, or the composer raises. Does not persist and does
+      # not perform network I/O. Callers own the one-presentation budget.
+      class InboxPresentationResolver
+        def self.resolve(communication:, recipient_id:, block:)
+          new(communication:, recipient_id:, block:).resolve
+        end
+
+        def initialize(communication:, recipient_id:, block:)
+          @communication = communication
+          @recipient_id = recipient_id
+          @block = block
+        end
+
+        def resolve
+          definition = CommandTower.config.registry.inbox_presentations.fetch(block[:key])
+          raw_data = unwrap(definition.composer_class.constantize.call(communication:, recipient_id:))
+          return nil if raw_data.nil?
+
+          {
+            type: "presentation",
+            key: block[:key],
+            variant: block[:variant],
+            data: raw_data.to_h.slice(*definition.output_keys),
+          }.freeze
+        rescue StandardError
+          nil
+        end
+
+        private
+
+        attr_reader :communication, :recipient_id, :block
+
+        def unwrap(composer_result)
+          if composer_result.respond_to?(:success?)
+            return nil unless composer_result.success?
+
+            composer_result.data
+          else
+            composer_result
+          end
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging/rendering/inbox_presentation_snapshot.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module CommandTower
+  module Messaging
+    module Rendering
+      # Captures the first presentation node's projected data at Accept time.
+      # Returns nil when the document has no presentation node. Returns an
+      # omitted marker when a presentation node was seen and capture failed.
+      # Never persists and never performs network I/O.
+      class InboxPresentationSnapshot
+        VERSION = 1
+
+        def self.capture(communication:, recipient_id:)
+          new(communication:, recipient_id:).capture
+        end
+
+        def self.omitted?(snapshot)
+          snapshot.is_a?(Hash) && snapshot.stringify_keys["omitted"] == true
+        end
+
+        def initialize(communication:, recipient_id:)
+          @communication = communication
+          @recipient_id = recipient_id
+        end
+
+        def capture
+          block = first_presentation_block
+          return nil if block.nil?
+
+          capture_seen_block(block)
+        end
+
+        private
+
+        attr_reader :communication, :recipient_id
+
+        def capture_seen_block(block)
+          resolved = InboxPresentationResolver.resolve(communication:, recipient_id:, block:)
+          resolved.nil? ? omitted_marker : payload(resolved)
+        rescue StandardError
+          omitted_marker
+        end
+
+        def first_presentation_block
+          document = InboxDocumentRenderer.compose_shell(communication)
+          document.blocks.find { |block| block[:type] == "presentation" }
+        end
+
+        def payload(resolved)
+          {
+            "v" => VERSION,
+            "key" => resolved[:key].to_s,
+            "variant" => resolved[:variant],
+            "data" => resolved[:data].deep_stringify_keys,
+          }
+        end
+
+        def omitted_marker
+          { "v" => VERSION, "omitted" => true }
+        end
+      end
+    end
+  end
+end

data/app/services/command_tower/messaging.rb

@@ -13,7 +13,9 @@ module CommandTower
       metadata: nil,
       preference_state: nil,
       platform_enabled_channels:,
-      message_overrides: nil
+      message_overrides: nil,
+      conversation_key: nil,
+      conversation_title: nil
     )
       Accept::Coordinator.call(
         recipient_id:,
@@ -25,6 +27,8 @@ module CommandTower
         preference_state:,
         platform_enabled_channels:,
         message_overrides:,
+        conversation_key:,
+        conversation_title:,
       )
     end
 

data/app/services/command_tower/services/messaging/communications/produce.rb

@@ -15,6 +15,8 @@ module CommandTower
           validate :body, is_a: String, required: true
           validate :metadata, is_a: Hash, required: false
           validate :platform_enabled_channels, is_a: Array, required: true
+          validate :conversation_key, is_a: String, required: false
+          validate :conversation_title, is_a: String, required: false
 
           def call
             recipient_result = CommandTower::Services::Messaging::Recipients.call(user: user)
@@ -33,6 +35,8 @@ module CommandTower
               preference_state: nil,
               platform_enabled_channels:,
               message_overrides: nil,
+              conversation_key:,
+              conversation_title:,
             )
 
             # Use communication_status — ServiceResult strips Interactor reserved :status.

data/app/services/command_tower/services/messaging/communications/produce_many.rb

@@ -18,6 +18,8 @@ module CommandTower
           validate :body, is_a: String, required: true
           validate :platform_enabled_channels, is_a: Array, required: true
           validate :metadata, is_a: Hash, required: false
+          validate :conversation_key, is_a: String, required: false
+          validate :conversation_title, is_a: String, required: false
           validate :execution_mode, is_one: EXECUTION_MODES, required: false, default: :async
 
           def call
@@ -128,6 +130,8 @@ module CommandTower
               body:,
               metadata:,
               platform_enabled_channels:,
+              conversation_key:,
+              conversation_title:,
             )
           end
 
@@ -139,6 +143,8 @@ module CommandTower
               "body" => body,
               "platform_enabled_channels" => platform_enabled_channels,
               "metadata" => metadata,
+              "conversation_key" => conversation_key,
+              "conversation_title" => conversation_title,
             }
           end
 

data/app/services/command_tower/services/messaging/inbox.rb

@@ -34,7 +34,7 @@ module CommandTower
           def call
             with_recipient do |recipient_id|
               result = CommandTower::Messaging::Inbox.list(recipient_id:, limit:, offset:, scope:)
-              context.items = result.items.map { |item| Inbox.item(item) }
+              context.items = result.items.map { |entry| Inbox.entry(entry) }
               context.pagination = { limit: result.limit, offset: result.offset, total_count: result.total_count }
             end
           end
@@ -80,6 +80,37 @@ module CommandTower
           end
         end
 
+        class Conversation < CommandTower::Services::ApplicationService
+          include FailureMapping
+          validate :user, is_a: User, required: true
+          validate :key, is_a: String, required: true
+          validate :scope, is_a: String, required: false, default: "inbox"
+          validate :around, is_a: [String, Integer], required: false
+          validate :before_id, is_a: Integer, required: false
+          validate :after_id, is_a: Integer, required: false
+          validate :limit, is_a: Integer, required: false
+
+          def call
+            with_recipient do |recipient_id|
+              found = CommandTower::Messaging::Inbox.conversation(
+                recipient_id:, key:, scope:, around:, before_id:, after_id:, limit:,
+              )
+              messages = found.message_ids.map do |inbox_item_id|
+                Inbox.detail(recipient_id:, inbox_item_id:)
+              end
+              context.conversation = {
+                scope: found.scope,
+                subject: found.subject,
+                message_count: found.message_count,
+                unread_count: found.unread_count,
+                inbox_item_ids: found.inbox_item_ids,
+                messages:,
+                window: found.window,
+              }
+            end
+          end
+        end
+
         class UnreadCount < CommandTower::Services::ApplicationService
           include FailureMapping
           validate :user, is_a: User, required: true
@@ -115,6 +146,21 @@ module CommandTower
             { id: item.id, title: item.title, status: item.status, viewed_at: item.viewed_at, created_at: item.created_at, updated_at: item.updated_at }
           end
 
+          def entry(entry)
+            {
+              kind: entry.kind,
+              id: entry.id,
+              title: entry.title,
+              preview: entry.preview,
+              activity_at: entry.activity_at,
+              created_at: entry.created_at,
+              message_count: entry.message_count,
+              unread_count: entry.unread_count,
+              read: entry.read,
+              inbox_item_ids: entry.inbox_item_ids,
+            }
+          end
+
           def detail(recipient_id:, inbox_item_id:)
             item = CommandTower::Messaging::Inbox.show(recipient_id:, inbox_item_id:)
             communication = CommandTower::Messaging::Contract::Communications.find(

data/app/workflows/command_tower/workflows/messaging/communications/produce_recipient_workflow.rb

@@ -15,7 +15,9 @@ module CommandTower
             title:,
             body:,
             platform_enabled_channels:,
-            metadata: nil
+            metadata: nil,
+            conversation_key: nil,
+            conversation_title: nil
           )
             user = User.find_by(id: user_id)
             unless user
@@ -34,6 +36,8 @@ module CommandTower
               body:,
               metadata:,
               platform_enabled_channels:,
+              conversation_key:,
+              conversation_title:,
             )
 
             unless result.success?