protege 0.1.0.alpha.1

data/app/services/protege/introspection_tool_call_presentation.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Protege
+  # Presents one live tool call for the console **introspection panel** — a PORO presentation helper for
+  # the console experience, not part of the engine's inference core. The panel is an event-driven feed
+  # (not a view of persisted rows): as the harness emits +tool_call.started/completed/failed+ events,
+  # +IntrospectionBroadcaster+ builds an +IntrospectionToolCallPresentation+ from the event and renders the
+  # +tool_call+ partial with it — first as a pending card, then replaced in place with the outcome.
+  # Keeping the presentation here (rather than in the partial) keeps the card markup dumb and the
+  # formatting unit-testable.
+  #
+  # Build via the state factories: +.pending+ (call just requested), +.completed+ (tool returned a
+  # successful +Result+), +.failed+ (tool returned a failed +Result+, so an error).
+  class IntrospectionToolCallPresentation
+    # Longest inline preview/args summary before it is clipped or replaced by a size count.
+    PREVIEW_LIMIT = 80
+
+    # Longest error message shown on a failed card before clipping.
+    ERROR_PREVIEW_LIMIT = 200
+
+    class << self
+      # A card for a call the model just requested, before its result is known.
+      #
+      # @param tool_call [Protege::Inference::Provider::ToolCall] the requested call
+      # @return [IntrospectionToolCallPresentation] the pending presentation
+      def pending(tool_call:)
+        new(tool_call:, status: :pending)
+      end
+
+      # A card for a call that returned successfully.
+      #
+      # @param tool_call [Protege::Inference::Provider::ToolCall] the call
+      # @param result [Protege::Result] the successful outcome (its +data+ drives the preview)
+      # @return [IntrospectionToolCallPresentation] the completed presentation
+      def completed(tool_call:, result:)
+        new(tool_call:, status: :done, result:)
+      end
+
+      # A card for a call that failed.
+      #
+      # @param tool_call [Protege::Inference::Provider::ToolCall] the call
+      # @param error [Exception] the failure (its message drives the preview)
+      # @return [IntrospectionToolCallPresentation] the failed presentation
+      def failed(tool_call:, error:)
+        new(tool_call:, status: :failed, error:)
+      end
+    end
+
+    # @return [Symbol] the card state — +:pending+, +:done+, or +:failed+
+    attr_reader :status
+
+    # @param tool_call [Protege::Inference::Provider::ToolCall] the call being presented
+    # @param status [Symbol] +:pending+, +:done+, or +:failed+
+    # @param result [Protege::Result, nil] the successful outcome, when done
+    # @param error [Exception, nil] the failure, when failed
+    def initialize(tool_call:, status:, result: nil, error: nil)
+      @tool_call = tool_call
+      @status    = status
+      @result    = result
+      @error     = error
+    end
+
+    # Stable DOM id for the card, so the pending card can be replaced in place by its outcome.
+    #
+    # @return [String] the card's DOM id
+    def card_id
+      "tool_call_#{@tool_call.id}"
+    end
+
+    # @return [String] the tool's name
+    def tool_name
+      @tool_call.name
+    end
+
+    # A one-line rendering of the call's arguments, clipped for length.
+    #
+    # @return [String, nil] the args summary, or nil when there are none
+    def arguments_summary
+      input = @tool_call.input
+      return nil if input.blank?
+
+      clip(input.map { |key, value| "#{key}: #{value.inspect}" }.join(', '), limit: PREVIEW_LIMIT)
+    end
+
+    # The response line: a short rendering of the result on success (or a size count when large), the
+    # error message on failure, and nothing while pending.
+    #
+    # @return [String, nil] the preview, or nil when pending / empty
+    def preview
+      case status
+      when :failed then clip(@error&.message.to_s, limit: ERROR_PREVIEW_LIMIT)
+      when :done   then result_preview
+      end
+    end
+
+    private
+
+    # Render the successful result's data as a short string, or its character count when too long to
+    # show inline.
+    #
+    # @return [String, nil] the response preview, or nil when there is no data
+    def result_preview
+      rendered = (@result&.data || {}).map { |key, value| "#{key}: #{preview_value(value)}" }.join(', ')
+
+      return nil if rendered.empty?
+      return rendered if rendered.length <= PREVIEW_LIMIT
+
+      "#{ActiveSupport::NumberHelper.number_to_delimited(rendered.length)} chars"
+    end
+
+    # A compact stand-in for a single result value — collections become a count, scalars their string.
+    #
+    # @param value [Object] the value to render
+    # @return [String] the compact rendering
+    def preview_value(value)
+      case value
+      when Array then "#{value.size} items"
+      when Hash  then "#{value.size} keys"
+      else value.to_s
+      end
+    end
+
+    # Clip a string to +limit+ characters, appending an ellipsis when cut.
+    #
+    # @param text [String] the text to clip
+    # @param limit [Integer] the maximum length
+    # @return [String] the original or a clipped copy
+    def clip(text, limit:)
+      return text if text.length <= limit
+
+      "#{text[0, limit]}…"
+    end
+  end
+end

data/app/services/protege/message_search.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Protege
+  # Cross-persona email search behind the console's search page — a PORO service object (not an
+  # ActiveRecord model, and not the persona-scoped +search_emails+ agent tool).
+  #
+  # Each field narrows the +Message+ relation: +from+ scans the sender, +recipients+ spans the
+  # to/cc/bcc lists, +subject+ and +body+ (text + html) scan their columns, and +attachments+ matches
+  # by stored filename. Filled fields are ANDed onto the *same* message row, so a message only matches
+  # when it satisfies every supplied field at once. +#results+ returns the matching messages
+  # themselves (newest sent first) — the console lists the emails and links each to its thread — rather
+  # than collapsing to threads, so the result grain matches the email-grained query.
+  #
+  # Matching mirrors +search_emails+: case-insensitive +LIKE+ with +sanitize_sql_like+ so the term's
+  # own +%+/+_+ are literals — SQLite-safe, which is the dashboard's database.
+  class MessageSearch
+    # Maps each column-backed search field to the message columns it scans. Columns are a fixed
+    # allowlist, so they are safe to interpolate into the +LIKE+ clause (the term is a bound param).
+    FIELD_COLUMNS = {
+      from:       %w[from_address],
+      recipients: %w[to_addresses cc_addresses bcc_addresses],
+      subject:    %w[subject],
+      body:       %w[text_body html_body]
+    }.freeze
+
+    class << self
+      # Build a search from request params, reading the field keys it understands.
+      #
+      # @param params [ActionController::Parameters, Hash] the request params
+      # @return [Protege::MessageSearch] the configured search
+      def from_params(params)
+        new(from:        params[:from],
+            recipients:  params[:recipients],
+            subject:     params[:subject],
+            body:        params[:body],
+            attachments: params[:attachments])
+      end
+    end
+
+    # @param from [String, nil] sender term
+    # @param recipients [String, nil] term matched against to/cc/bcc
+    # @param subject [String, nil] subject term
+    # @param body [String, nil] term matched against the text and html bodies
+    # @param attachments [String, nil] attachment-filename term
+    def initialize(from: nil, recipients: nil, subject: nil, body: nil, attachments: nil)
+      @column_terms = { from:, recipients:, subject:, body: }
+      @attachments  = attachments
+    end
+
+    # Whether any field carries a term to search on.
+    #
+    # @return [Boolean]
+    def active?
+      (@column_terms.values + [@attachments]).any?(&:present?)
+    end
+
+    # The matching messages, newest sent first, each with its thread preloaded for the result row;
+    # empty when no field is filled.
+    #
+    # +preload+ (a separate query) rather than +includes+ avoids a JOIN — the search columns +subject+
+    # and +from_address+ also exist on +protege_email_threads+, so a join would make them ambiguous.
+    #
+    # @return [ActiveRecord::Relation<Protege::Message>]
+    def results
+      return Message.none unless active?
+
+      message_scope.preload(:email_thread).order(sent_at: :desc)
+    end
+
+    private
+
+    # The +Message+ relation narrowed by every filled field (each ANDed onto the same row).
+    #
+    # @return [ActiveRecord::Relation<Protege::Message>] the narrowed relation
+    def message_scope
+      scope = FIELD_COLUMNS.reduce(Message.all) do |relation, (field, columns)|
+        term = @column_terms[field]
+        next relation if term.blank?
+
+        relation.where(message_column_match_fragment(columns), term: like_term(term))
+      end
+
+      @attachments.present? ? scope.where(id: attachment_message_ids) : scope
+    end
+
+    # The SQL fragment for a single field's columns, ORed together, with a bound +:term+ param. The
+    # caller must supply the term value in the +where+ call.
+    #
+    # @param columns [Array<String>] the message columns to scan for the field
+    # @return [String] the SQL fragment, e.g. "LOWER(subject) LIKE :term OR LOWER(body) LIKE :term"
+    def message_column_match_fragment(columns)
+      columns.map { "LOWER(#{_1}) LIKE :term" }.join(' OR ')
+    end
+
+    # Message ids that own an attachment whose stored filename matches the attachments term.
+    #
+    # @return [ActiveRecord::Relation<Integer>] the matching message ids
+    def attachment_message_ids
+      ActiveStorage::Attachment
+        .where(record_type: 'Protege::Message', name: 'attachments')
+        .joins(:blob)
+        .where('LOWER(active_storage_blobs.filename) LIKE :term', term: like_term(@attachments))
+        .select(:record_id)
+    end
+
+    # Wrap a term as a case-insensitive, wildcard-escaped +LIKE+ pattern.
+    #
+    # @param value [String] the raw search term
+    # @return [String] the +%term%+ pattern, lowercased and escaped
+    def like_term(value)
+      "%#{ActiveRecord::Base.sanitize_sql_like(value.strip.downcase)}%"
+    end
+  end
+end

data/app/services/protege/trace_search.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Protege
+  # Console-side search over captured inference traces (see +Protege::Trace+) — a PORO service, the trace
+  # analog of +MessageSearch+.
+  #
+  # Each free-text field narrows the +Trace+ relation with a case-insensitive +LIKE+; +label+ filters by
+  # the review verdict. Filled fields are ANDed onto the *same* row, so a trace matches only when it
+  # satisfies every supplied field at once. +request+/+response+ are JSON-text columns, so those terms
+  # match against the serialized JSON of the turn (the prompt/tool catalog and the produced output),
+  # not structured fields.
+  #
+  # Matching mirrors +MessageSearch+: case-insensitive +LIKE+ with +sanitize_sql_like+ so the term's own
+  # +%+/+_+ are literals — SQLite-safe, the dashboard's database.
+  class TraceSearch
+    # Maps each free-text search field to the trace columns it scans. Columns are a fixed allowlist, so
+    # they are safe to interpolate into the +LIKE+ clause (the term is always a bound param).
+    FIELD_COLUMNS = {
+      correlation_id: %w[correlation_id],
+      model:          %w[model],
+      request:        %w[request],
+      response:       %w[response],
+      annotation:     %w[annotation]
+    }.freeze
+
+    class << self
+      # Build a search from request params, reading the field keys it understands.
+      #
+      # @param params [ActionController::Parameters, Hash] the request params
+      # @return [Protege::TraceSearch] the configured search
+      def from_params(params)
+        new(correlation_id: params[:correlation_id],
+            model:          params[:model],
+            request:        params[:request],
+            response:       params[:response],
+            annotation:     params[:annotation],
+            label:          params[:label])
+      end
+    end
+
+    # @param correlation_id [String, nil] run-id term
+    # @param model [String, nil] model term
+    # @param request [String, nil] term matched against the serialized request JSON
+    # @param response [String, nil] term matched against the serialized response JSON
+    # @param annotation [String, nil] reviewer-note term
+    # @param label [String, nil] a review verdict to filter by (ignored unless a real +Trace+ label)
+    def initialize(correlation_id: nil, model: nil, request: nil, response: nil, annotation: nil, label: nil)
+      @column_terms = { correlation_id:, model:, request:, response:, annotation: }
+      @label        = label if Trace.labels.key?(label)
+    end
+
+    # Whether any field carries something to search on — a text term or a valid label.
+    #
+    # @return [Boolean]
+    def active?
+      @column_terms.values.any?(&:present?) || @label.present?
+    end
+
+    # The matching traces, newest captured first; empty when nothing is filled.
+    #
+    # @return [ActiveRecord::Relation<Protege::Trace>]
+    def results
+      return Trace.none unless active?
+
+      trace_scope.order(created_at: :desc)
+    end
+
+    private
+
+    # The +Trace+ relation narrowed by every filled text field (each ANDed onto the same row), then by
+    # the label verdict when one is set.
+    #
+    # @return [ActiveRecord::Relation<Protege::Trace>] the narrowed relation
+    def trace_scope
+      scope = FIELD_COLUMNS.reduce(Trace.all) do |relation, (field, columns)|
+        term = @column_terms[field]
+        next relation if term.blank?
+
+        relation.where(column_match_fragment(columns), term: like_term(term))
+      end
+
+      @label.present? ? scope.where(label: @label) : scope
+    end
+
+    # The SQL fragment for a field's columns, ORed together, with a bound +:term+ param. The caller
+    # supplies the term value in the +where+ call.
+    #
+    # @param columns [Array<String>] the trace columns to scan for the field
+    # @return [String] the SQL fragment, e.g. "LOWER(request) LIKE :term"
+    def column_match_fragment(columns)
+      columns.map { "LOWER(#{_1}) LIKE :term" }.join(' OR ')
+    end
+
+    # Wrap a term as a case-insensitive, wildcard-escaped +LIKE+ pattern.
+    #
+    # @param value [String] the raw search term
+    # @return [String] the +%term%+ pattern, lowercased and escaped
+    def like_term(value)
+      "%#{ActiveRecord::Base.sanitize_sql_like(value.strip.downcase)}%"
+    end
+  end
+end

data/app/subscribers/protege/introspection_broadcaster.rb

@@ -0,0 +1,324 @@
+# frozen_string_literal: true
+
+module Protege
+  # Drives the console's **introspection panel** from inference events — an app-level subscriber for the
+  # console experience, not part of the engine's inference core. A peer of +Subscribers::HookDispatcher+
+  # and +Subscribers::Tracing+, installed once at boot.
+  #
+  # It subscribes to Protege events and translates streaming + tool-call notifications into Turbo Stream
+  # broadcasts, building the panel's live activity feed: one chronological stream where the model's
+  # reasoning tokens and its tool calls are interleaved in the order they happen. Installed via the
+  # +install!+ contract (see the engine initializer) and holds process-local state for the lifetime of
+  # the process; +reset!+ detaches its subscriptions and clears that state.
+  #
+  # What each event does (all broadcast to the thread's Turbo channel, target +dom_id(thread, :activity)+
+  # — the feed container in +_introspection.html.slim+):
+  #
+  # * +InferenceChunkEvent+ — stream the token into the run's current reasoning block, opening a fresh block
+  #   after each tool call so reasoning is grouped into spaced paragraphs. Interleaving is automatic:
+  #   every append lands at the feed's end, so reasoning blocks and cards stay in chronological order.
+  # * +ToolCallStartedEvent+ — append a pending tool card the instant the model requests the call.
+  # * +ToolCallCompletedEvent+ / +ToolCallFailedEvent+ — replace that card in place with the outcome
+  #   (a response preview, or the error message).
+  #
+  # **Routing.** Only +InferenceChunkEvent+ carries the thread; the tool-call events carry just the
+  # +correlation_id+ that +Protege::Event.emit+ injects into every event. So the broadcaster keeps a
+  # +correlation_id → thread+ map, populated from +InferenceStartedEvent+ (which carries the message, hence
+  # its thread) and cleared on +InferenceCompletedEvent+/+InferenceFailedEvent+. This is the single stream-
+  # routing convention — no +emit_*+ signature carries the thread just for the panel. +@mutex+ guards
+  # the map because callbacks may run concurrently across threads. Runs with no thread (scheduled
+  # +ResponsibilityRun+s) never populate the map, so their tool events broadcast nothing.
+  #
+  # The feed is live-only by design: it is not rehydrated from persistence, so a page reload shows an
+  # empty feed until the next run streams in.
+  module IntrospectionBroadcaster
+    # Maps a run's +correlation_id+ to the +EmailThread+ its events broadcast to. Populated on
+    # +InferenceStartedEvent+, cleared on completion/failure.
+    @threads = {}
+
+    # Maps a run's +correlation_id+ to its currently open reasoning block's DOM id (tokens append into
+    # it), or nil when none is open — a tool call closes the block so the next token opens a fresh one.
+    @reasoning = {}
+
+    # Maps a run's +correlation_id+ to a counter that makes each reasoning block's DOM id unique.
+    @reasoning_seq = {}
+
+    # Live event-bus subscription handles, retained so {reset!} can detach them.
+    @handles = []
+
+    # Guards concurrent access to the maps from callbacks running on multiple threads.
+    @mutex = Mutex.new
+
+    extend self
+
+    # Wire the event listeners — the subscriber's +install!+ contract. Idempotent: retains the
+    # subscription handles and no-ops until {reset!} runs, so a repeat call never double-subscribes.
+    # Called once at boot from the engine's +after_initialize+.
+    #
+    # @return [void]
+    def install!
+      return unless @handles.empty?
+
+      @handles = [
+        install_start_listener,
+        install_chunk_listener,
+        *install_tool_listeners,
+        *install_completion_listeners
+      ]
+    end
+
+    # Detach every subscription and drop all per-run state — the subscriber's +reset!+ contract, for
+    # boot re-wiring and tests.
+    #
+    # @return [void]
+    def reset!
+      @handles.each { |handle| ActiveSupport::Notifications.unsubscribe(handle) }
+      @handles = []
+      @mutex.synchronize do
+        @threads.clear
+        @reasoning.clear
+        @reasoning_seq.clear
+      end
+    end
+
+    private
+
+    # Remember which thread a run's later (thread-less) events belong to, and open the run in the feed
+    # with a pulsing "Processing…" marker.
+    #
+    # @return [Object] the subscription handle
+    def install_start_listener
+      InferenceStartedEvent.subscribe do |event|
+        thread = event.message&.email_thread
+        next unless thread
+
+        # The correlation_id is the run's stable DOM id, so we can key the reasoning block and the marker on it.
+        remember(correlation_id: event.correlation_id, thread:)
+
+        broadcast_run_marker(thread:,
+                             correlation_id: event.correlation_id,
+                             status:         :processing,
+                             action:         :append)
+      end
+    end
+
+    # Append each streamed reasoning token to the run's current reasoning block. Chunks carry the thread
+    # directly; empty content and thread-less payloads are dropped.
+    #
+    # @return [Object] the subscription handle
+    def install_chunk_listener
+      InferenceChunkEvent.subscribe do |event|
+        thread  = event.thread
+        content = event.chunk_content
+        next if thread.nil? || content.nil? || content.empty?
+
+        append_reasoning(thread:,
+                         correlation_id: event.correlation_id,
+                         content:)
+      end
+    end
+
+    # Stream the tool-call lifecycle into the feed: a pending card on start, then the outcome in place.
+    # Starting a call also closes the run's open reasoning block, so post-tool reasoning opens a new one.
+    #
+    # @return [Array<Object>] the subscription handles
+    def install_tool_listeners
+      started = ToolCallStartedEvent.subscribe do |event|
+        close_reasoning(event.correlation_id)
+        presenter = IntrospectionToolCallPresentation.pending(tool_call: event.tool_call)
+        broadcast_card(event, presenter, :append)
+      end
+
+      completed = ToolCallCompletedEvent.subscribe do |event|
+        presenter = IntrospectionToolCallPresentation.completed(tool_call: event.tool_call,
+                                                                result:    event.result)
+        broadcast_card(event, presenter, :replace)
+      end
+
+      failed = ToolCallFailedEvent.subscribe do |event|
+        presenter = IntrospectionToolCallPresentation.failed(tool_call: event.tool_call, error: event.error)
+        broadcast_card(event, presenter, :replace)
+      end
+
+      [started, completed, failed]
+    end
+
+    # Close the run in the feed — remove its marker on success, replace it with a red error on failure
+    # — and forget its thread.
+    #
+    # @return [Array<Object>] the subscription handles
+    def install_completion_listeners
+      completed = InferenceCompletedEvent.subscribe do |event|
+        finish_run(correlation_id: event.correlation_id)
+      end
+
+      failed = InferenceFailedEvent.subscribe do |event|
+        finish_run(correlation_id: event.correlation_id, error: event.error)
+      end
+
+      [completed, failed]
+    end
+
+    # Resolve the run's marker (remove it when the run succeeded, replace it with the error when it
+    # failed), then drop its thread mapping.
+    #
+    # @param correlation_id [String, nil] the run's id
+    # @param error [Exception, nil] the failure, or nil on success
+    # @return [void]
+    def finish_run(correlation_id:, error: nil)
+      thread = thread_for(correlation_id)
+
+      if thread && error
+        broadcast_run_marker(thread:,
+                             correlation_id:,
+                             status:         :failed,
+                             detail:         error.message,
+                             action:         :replace)
+      elsif thread
+        Turbo::StreamsChannel.broadcast_remove_to(thread, target: run_marker_id(correlation_id))
+      end
+
+      forget(correlation_id:)
+    end
+
+    # Append (on start) or replace (on finish) a run's lifecycle marker in the feed.
+    #
+    # @param thread [EmailThread] the run's thread
+    # @param correlation_id [String] the run's id (its marker's stable DOM id)
+    # @param status [Symbol] +:processing+ or +:failed+
+    # @param action [Symbol] +:append+ (start) or +:replace+ (finish)
+    # @param detail [String, nil] the error message, for +:failed+
+    # @return [void]
+    def broadcast_run_marker(thread:, correlation_id:, status:, action:, detail: nil)
+      id      = run_marker_id(correlation_id)
+      locals  = { id:, status:, detail: }
+      partial = 'protege/threads/run_marker'
+
+      if action == :append
+        Turbo::StreamsChannel.broadcast_append_to(thread, target: activity_target(thread), partial:, locals:)
+      else
+        Turbo::StreamsChannel.broadcast_replace_to(thread, target: id, partial:, locals:)
+      end
+    end
+
+    # Stream a reasoning token: open a fresh reasoning block in the feed if none is open for this run
+    # (carrying the first token), otherwise append the token into the open block.
+    #
+    # @param thread [EmailThread] the thread whose feed to update
+    # @param correlation_id [String] the run's id (keys its open reasoning block)
+    # @param content [String] the raw token text
+    # @return [void]
+    def append_reasoning(thread:, correlation_id:, content:)
+      block_id, opened = reasoning_block(correlation_id)
+
+      if opened
+        Turbo::StreamsChannel.broadcast_append_to(thread,
+                                                  target:  activity_target(thread),
+                                                  partial: 'protege/threads/reasoning',
+                                                  locals:  { id: block_id, content: })
+      else
+        html = ERB::Util.html_escape(content)
+        Turbo::StreamsChannel.broadcast_append_to(thread, target: block_id, html:)
+      end
+    end
+
+    # The next sequence number for a run's reasoning blocks, so each block's DOM id is unique within the run.
+    #
+    # @param correlation_id [String] the run's id
+    # @return [Integer] the next sequence number
+    def reasoning_block_id(correlation_id)
+      (@reasoning_seq[correlation_id] || 0) + 1
+    end
+
+    # The run's open reasoning block, opening a new one when none is active.
+    #
+    # @param correlation_id [String] the run's id
+    # @return [Array(String, Boolean)] the block's DOM id and whether it was just opened
+    def reasoning_block(correlation_id)
+      @mutex.synchronize do
+        existing = @reasoning[correlation_id]
+        next [existing, false] if existing
+
+        reasoning_block_id(correlation_id).tap do |seq|
+          @reasoning_seq[correlation_id] = seq
+          @reasoning[correlation_id]     = "reasoning_#{correlation_id}_#{seq}"
+        end
+
+        [@reasoning[correlation_id], true]
+      end
+    end
+
+    # Close the run's open reasoning block, so the next token opens a fresh one.
+    #
+    # @param correlation_id [String] the run's id
+    # @return [void]
+    def close_reasoning(correlation_id)
+      @mutex.synchronize { @reasoning.delete(correlation_id) }
+    end
+
+    # Broadcast a tool card, appending it (pending) or replacing it in place (outcome). No-op when the
+    # event's run has no mapped thread.
+    #
+    # @param event [Protege::Event] the tool-call event
+    # @param card [IntrospectionToolCallPresentation] the card to render
+    # @param action [Symbol] +:append+ (pending) or +:replace+ (outcome)
+    # @return [void]
+    def broadcast_card(event, card, action)
+      thread = thread_for(event.correlation_id)
+      return unless thread
+
+      locals  = { presentation: card }
+      partial = 'protege/threads/tool_call'
+
+      if action == :append
+        Turbo::StreamsChannel.broadcast_append_to(thread,
+                                                  target: activity_target(thread),
+                                                  partial:, locals:)
+      else
+        Turbo::StreamsChannel.broadcast_replace_to(thread,
+                                                   target:  card.card_id,
+                                                   partial:,
+                                                   locals:)
+      end
+    end
+
+    # The feed container's DOM id for a thread (matches +_introspection.html.slim+).
+    #
+    # @param thread [EmailThread] the thread
+    # @return [String] the activity feed target id
+    def activity_target(thread)
+      ActionView::RecordIdentifier.dom_id(thread, :activity)
+    end
+
+    # The stable DOM id for a run's lifecycle marker.
+    #
+    # @param correlation_id [String] the run's id
+    # @return [String] the marker's DOM id
+    def run_marker_id(correlation_id)
+      "run_#{correlation_id}"
+    end
+
+    # @param correlation_id [String] the run's id
+    # @param thread [EmailThread] the run's thread
+    # @return [void]
+    def remember(correlation_id:, thread:)
+      @mutex.synchronize { @threads[correlation_id] = thread }
+    end
+
+    # @param correlation_id [String, nil] the run's id
+    # @return [EmailThread, nil] the mapped thread, or nil when the run has none
+    def thread_for(correlation_id)
+      @mutex.synchronize { @threads[correlation_id] }
+    end
+
+    # @param correlation_id [String, nil] the run's id
+    # @return [void]
+    def forget(correlation_id:)
+      @mutex.synchronize do
+        @threads.delete(correlation_id)
+        @reasoning.delete(correlation_id)
+        @reasoning_seq.delete(correlation_id)
+      end
+    end
+  end
+end