protege 0.1.0.alpha.1

data/app/helpers/protege/messages_helper.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Protege
+  # View helpers for rendering a +Message+ within a thread — sender, timestamp,
+  # recipients, subject, and expandable raw headers. Liveness (processing/reasoning/tool use) is not
+  # shown on the message; it lives in the console's introspection panel.
+  module MessagesHelper
+    # The search-result row title: the email subject, or a placeholder when blank.
+    #
+    # @param message [Protege::Message] the matched message
+    # @return [String] the subject or "(no subject)"
+    def search_result_title(message)
+      message.subject.presence || '(no subject)'
+    end
+
+    # The search-result row's right-aligned date — the email's sent time in short +m/d/yy+ form.
+    #
+    # @param message [Protege::Message] the matched message
+    # @return [String, nil] the short date, or nil when unsent
+    def search_result_date(message)
+      message.sent_at&.strftime('%-m/%-d/%y')
+    end
+
+    # Render the sender line — persona name for outbound mail, local part of the
+    # address for inbound mail — followed by the full address.
+    #
+    # @param message [Protege::Message] the message to render the sender for
+    # @return [ActiveSupport::SafeBuffer] the bold +"name <address>"+ span
+    def message_sender(message)
+      name = if message.outbound?
+               message.persona.name
+             else
+               message.from_address.to_s.split('@').first
+             end
+
+      tag.span("#{name} <#{message.from_address}>", class: 'font-semibold')
+    end
+
+    # Render the message's send time as a +<time>+ element.
+    #
+    # @param message [Protege::Message] the message whose timestamp to render
+    # @return [ActiveSupport::SafeBuffer] a formatted +<time>+ tag
+    def message_timestamp(message)
+      tag.time(
+        message.sent_at.strftime('%b %-d, %Y %H:%M'),
+        datetime: message.sent_at.iso8601,
+        class:    'flex-shrink-0 text-xs',
+        style:    'color: var(--text-faint)'
+      )
+    end
+
+    # Render the To line, appending a Cc line only when Cc recipients exist.
+    #
+    # @param message [Protege::Message] the message whose recipients to render
+    # @return [ActiveSupport::SafeBuffer] the recipients line
+    def message_recipients(message)
+      to = tag.span("To: #{Array(message.to_addresses).join(', ')}")
+      cc = if Array(message.cc_addresses).any?
+             tag.span("Cc: #{message.cc_addresses.join(', ')}", class: 'ml-2')
+           else
+             ''.html_safe
+           end
+
+      tag.div(class: 'mt-1 text-xs', style: 'color: var(--text-muted)') { safe_join([to, cc]) }
+    end
+
+    # Render the subject line, but only when it differs from the thread subject.
+    #
+    # @param message [Protege::Message] the message whose subject to consider
+    # @return [ActiveSupport::SafeBuffer] the subject line, or an empty buffer
+    def message_subject(message)
+      if message.subject.present? && message.subject != message.email_thread.subject
+        tag.div("Subject: #{message.subject}", class: 'mt-1 text-xs font-medium')
+      else
+        ''.html_safe
+      end
+    end
+
+    # Render an expandable +<details>+ block listing the message's raw headers.
+    #
+    # @param message [Protege::Message] the message whose headers to render
+    # @return [ActiveSupport::SafeBuffer] the collapsible headers block
+    def message_headers(message)
+      tag.details(class: 'mt-1') do
+        tag.summary('Headers', class: 'cursor-pointer text-xs', style: 'color: var(--text-faint)') +
+          message_headers_list(message)
+      end
+    end
+
+    # Render a message's attachments as a row of download-link chips, or nothing when there are none.
+    #
+    # Each chip links to the blob via Active Storage's host-app route (+main_app.rails_blob_path+, since
+    # those routes live on the host, not the engine) and shows the filename and a human-readable size.
+    # +link_to+ escapes the filename, which is copied verbatim from attacker-controlled inbound headers.
+    #
+    # The link forces a download two ways: +disposition: "attachment"+ makes the service set
+    # +Content-Disposition: attachment+ (so even an +.html+ blob downloads rather than rendering), and
+    # the +download+ attribute both hints the filename and opts the anchor out of Turbo Drive — without
+    # it Turbo intercepts the click and renders an HTML attachment as a page instead of downloading it.
+    #
+    # @param message [Protege::Message] the message whose attachments to render
+    # @return [ActiveSupport::SafeBuffer] the chips row, or an empty buffer
+    def message_attachments(message)
+      return ''.html_safe unless message.attachments.attached?
+
+      chips = message.attachments.map do |attachment|
+        label = "#{attachment.filename} (#{number_to_human_size(attachment.byte_size)})"
+        link_to(label,
+                main_app.rails_blob_path(attachment, disposition: 'attachment', only_path: true),
+                download: attachment.filename.to_s,
+                class:    'inline-flex items-center gap-1 rounded px-1.5 py-0.5 text-xs font-medium hover:underline',
+                style:    'background: var(--surface-subtle); border: 1px solid var(--border)')
+      end
+
+      tag.div(class: 'mt-3 flex flex-wrap gap-2') { safe_join(chips) }
+    end
+
+    private
+
+    # Build the ordered label/value header pairs shown in the headers block.
+    #
+    # Conditional headers are included only when their value is present.
+    #
+    # @param message [Protege::Message] the message to read header values from
+    # @return [Array<Array(String, String)>] +[label, value]+ pairs in display order
+    def message_header_pairs(message)
+      pairs = [['Message-ID', message.message_id]]
+
+      pairs << ['In-Reply-To', message.in_reply_to]       if message.in_reply_to.present?
+      pairs << ['References', message.references_header]  if message.references_header.present?
+      pairs << ['Direction', message.direction]
+      pairs << ['Correlation-ID', message.correlation_id] if message.correlation_id.present?
+
+      pairs
+    end
+
+    # Render the +<dl>+ body of the headers block from the message's header pairs.
+    #
+    # @param message [Protege::Message] the message whose headers to list
+    # @return [ActiveSupport::SafeBuffer] the definition list of headers
+    def message_headers_list(message)
+      tag.dl(class: 'mt-1 space-y-0.5 text-xs', style: 'color: var(--text-muted)') do
+        safe_join(message_header_pairs(message).map do |label, value|
+          tag.div(class: 'flex gap-1') do
+            tag.dt("#{label}:", class: 'font-medium') +
+              tag.dd(value, class: 'break-all')
+          end
+        end)
+      end
+    end
+  end
+end

data/app/helpers/protege/personas_helper.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Protege
+  # View helpers for persona pages — selectors, labels, status, and resolver display.
+  module PersonasHelper
+    # List the loaded +Persona+ subclasses for the new-persona type selector.
+    #
+    # @return [Array<Class>] the +Persona+ descendant classes
+    def available_persona_types
+      Persona.descendants
+    end
+
+    # List active email domains for the persona form's domain selector.
+    #
+    # @return [ActiveRecord::Relation<Protege::EmailDomain>] domains eligible for selection
+    def available_email_domains
+      EmailDomain.all
+    end
+
+    # Fetch every +Persona+ ordered by name for sidebar listing.
+    #
+    # @return [ActiveRecord::Relation<Protege::Persona>] personas ordered alphabetically
+    def all_personas
+      Persona.order(:name)
+    end
+
+    # Format a persona's name together with its type for display.
+    #
+    #   persona_label(persona) # => "Bob <Agent>"
+    #
+    # @param persona [Protege::Persona] the persona to label
+    # @return [String] the +"name <Type>"+ label
+    def persona_label(persona)
+      "#{persona.name} <#{persona.class.display_name}>"
+    end
+
+    # Render a status dot reflecting whether a persona is available.
+    #
+    # @param persona [Protege::Persona] the persona whose availability to show
+    # @return [ActiveSupport::SafeBuffer] a green dot when active, red otherwise
+    def persona_status(persona)
+      if persona.active?
+        status_dot('Available', :green)
+      else
+        status_dot('Unavailable', :red)
+      end
+    end
+
+    # Format a persona's resolver chain as a hash suitable for +info_card+ (rendered full-width, since
+    # the resolver class names are long). Each entry maps the resolver's short class name to a summary
+    # of its positional args, keyword args, and whether it was given a block.
+    #
+    # @param persona [Protege::Persona] the persona whose reply (+message_resolvers+) chain to format
+    # @return [Hash{String => String}] resolver-name => configuration summary
+    def resolver_pairs(persona)
+      pairs = persona.message_resolvers.entries.each_with_object({}) do |(klass, args, kwargs, block), accumulator|
+        accumulator[klass.name.demodulize] = resolver_config(args, kwargs, block)
+      end
+
+      pairs.any? ? pairs : { 'Resolvers' => 'None configured' }
+    end
+
+    # The tool classes a persona's operator may toggle — the checkbox universe on the persona form.
+    #
+    # This is the persona's *grant* (its code-declared ceiling), or every registered tool when no grant
+    # was declared. It is deliberately the grant rather than the effective set: the operator toggles
+    # within what the code allows, so a tool disabled in the DB still appears (unchecked) and can be
+    # switched back on, while a tool outside the grant is never offered.
+    #
+    # @param persona [Protege::Persona] the persona being edited
+    # @return [Array<Class>] the toggleable tool classes
+    def persona_tool_options(persona)
+      grant = persona.class.tool_grant
+
+      grant ? ToolMixin.registered.select { grant.include?(_1.id) } : ToolMixin.registered
+    end
+
+    private
+
+    # Summarize a resolver entry's positional args, keyword args, and whether it was given a block.
+    #
+    # @return [String] a comma-joined summary, or "" when the resolver takes no configuration
+    def resolver_config(args, kwargs, block)
+      parts  = args.map(&:inspect)
+      parts += kwargs.map { |key, value| "#{key}: #{value.inspect}" }
+      parts << '{ … }' if block
+      parts.join(', ')
+    end
+  end
+end

data/app/helpers/protege/responsibilities_helper.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Protege
+  # View helpers for responsibility pages — status display and run-history formatting.
+  module ResponsibilitiesHelper
+    # Fetch every +Responsibility+ (persona eager-loaded) for the global sidebar listing. The model's
+    # default scope already orders by name.
+    #
+    # @return [ActiveRecord::Relation<Protege::Responsibility>] all responsibilities
+    def all_responsibilities
+      Responsibility.includes(:persona)
+    end
+
+    # Render a status dot reflecting whether a responsibility is active.
+    #
+    # @param responsibility [Protege::Responsibility] the responsibility whose state to show
+    # @return [ActiveSupport::SafeBuffer] a green dot when active, grey when paused
+    def responsibility_status(responsibility)
+      if responsibility.active?
+        status_dot('Active', :green)
+      else
+        status_dot('Paused', :gray)
+      end
+    end
+
+    # Render a run's status as a colour-coded badge.
+    #
+    # @param run [Protege::ResponsibilityRun] the run whose status to badge
+    # @return [ActiveSupport::SafeBuffer] the badge markup
+    def run_status_badge(run)
+      colors = { 'completed' => :green, 'failed' => :red, 'running' => :gray, 'pending' => :gray }
+      badge(run.status, colors.fetch(run.status, :gray))
+    end
+
+    # Build the responsibility Show page's recent-runs table — its headers and one
+    # +[status badge, when, detail link]+ row per run, newest first (capped at ten).
+    #
+    # @param responsibility [Protege::Responsibility] the responsibility whose runs to format
+    # @return [Protege::Components::TablesHelper::Table] the headers + rows for +table+
+    def responsibility_runs_table(responsibility)
+      rows = responsibility.responsibility_runs.order(created_at: :desc).limit(10).map do |run|
+        [
+          run_status_badge(run),
+          run.correlation_id,
+          run_time(run),
+          ui_link('Details', responsibility_run_path(run))
+        ]
+      end
+
+      Components::TablesHelper::Table.new(headers: ['Status', 'Correlation ID', 'When', ''], rows:)
+    end
+
+    private
+
+    # The most relevant timestamp for a run: when it started, falling back to when it was enqueued.
+    #
+    # @param run [Protege::ResponsibilityRun]
+    # @return [String] a formatted timestamp
+    def run_time(run)
+      (run.started_at || run.created_at).strftime('%Y-%m-%d %H:%M')
+    end
+  end
+end

data/app/helpers/protege/threads_helper.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Protege
+  # View helpers for thread pages — the inbox list, compose selectors, sidebar
+  # display, and the thread detail header.
+  module ThreadsHelper
+    # Fetch every +EmailThread+ ordered by most recent activity.
+    #
+    # @return [ActiveRecord::Relation<Protege::EmailThread>] threads newest-activity first
+    def inbox_threads
+      EmailThread.order(last_message_at: :desc)
+    end
+
+    # List the active personas eligible for the compose form.
+    #
+    # @return [ActiveRecord::Relation<Protege::Persona>] personas eligible for selection
+    def available_personas
+      Persona.active
+    end
+
+    # Format the available personas as +[label, id]+ pairs for a select dropdown.
+    #
+    # @return [Array<Array(String, Integer)>] option label/value pairs
+    def available_persona_options
+      available_personas.map { |persona| ["#{persona.name} <#{persona.email_address}>", persona.id] }
+    end
+
+    # Format a thread subject with its message count for sidebar display.
+    # Truncation is handled by the +sidebar_item+ helper.
+    #
+    #   thread_title(thread) # => "Hello (3)"
+    #
+    # @param thread [Protege::EmailThread] the thread to title
+    # @return [String] the subject, suffixed with the count when it exceeds one
+    def thread_title(thread)
+      subject = thread.subject.presence || '(no subject)'
+      thread.message_count > 1 ? "#{thread.persona.name} - #{subject} (#{thread.message_count})" : subject
+    end
+
+    # Format the thread's last-activity date for sidebar display.
+    #
+    # @param thread [Protege::EmailThread] the thread to date
+    # @return [String, nil] the short +m/d/yy+ date, or nil when no activity
+    def thread_date(thread)
+      thread.last_message_at&.strftime('%-m/%-d/%y')
+    end
+
+    # Build a one-line preview from the first line of the latest message.
+    #
+    # @param thread [Protege::EmailThread] the thread to preview
+    # @return [String] the trimmed first line, or an em dash when empty
+    def thread_preview(thread)
+      thread.latest_message&.text_body.to_s.lines.first.to_s.strip.presence || '—'
+    end
+
+    # Render the thread detail header — subject, persona, message count, last
+    # activity, and thread ID. An optional block renders actions beside the title.
+    #
+    # @param thread [Protege::EmailThread] the thread whose header to render
+    # @yield optional content rendered to the right of the subject
+    # @return [ActiveSupport::SafeBuffer] the header markup
+    def thread_header(thread, &block)
+      tag.div(class: 'flex-shrink-0 px-5 py-3') do
+        thread_header_title(thread, &block) +
+          thread_header_meta(thread) +
+          thread_header_id(thread)
+      end
+    end
+
+    private
+
+    # Render the title row — the subject and any caller-supplied actions block.
+    #
+    # @param thread [Protege::EmailThread] the thread whose subject to render
+    # @yield optional content rendered to the right of the subject
+    # @return [ActiveSupport::SafeBuffer] the title row markup
+    def thread_header_title(thread, &block)
+      tag.div(class: 'flex items-center justify-between') do
+        heading_3(thread.subject.presence || '(no subject)') +
+          (block ? capture(&block) : ''.html_safe)
+      end
+    end
+
+    # Render the metadata row — persona, message count, and last activity.
+    #
+    # @param thread [Protege::EmailThread] the thread whose metadata to render
+    # @return [ActiveSupport::SafeBuffer] the metadata row markup
+    def thread_header_meta(thread)
+      tag.div(class: 'mt-1 flex items-center gap-3 text-xs', style: 'color: var(--text-muted)') do
+        tag.span do
+          'Persona: '.html_safe + tag.span(thread.persona.name, class: 'font-medium')
+        end +
+          tag.span(pluralize(thread.message_count, 'message')) +
+          thread_header_last_activity(thread)
+      end
+    end
+
+    # Render the last-activity span, or an empty buffer when there is none.
+    #
+    # @param thread [Protege::EmailThread] the thread whose last activity to render
+    # @return [ActiveSupport::SafeBuffer] the last-activity span, or an empty buffer
+    def thread_header_last_activity(thread)
+      return ''.html_safe unless thread.last_message_at
+
+      tag.span("Last activity: #{thread.last_message_at.strftime('%b %-d, %Y %H:%M')}")
+    end
+
+    # Render the thread ID row.
+    #
+    # @param thread [Protege::EmailThread] the thread whose ID to render
+    # @return [ActiveSupport::SafeBuffer] the thread ID row markup
+    def thread_header_id(thread)
+      tag.div(class: 'mt-1 text-xs', style: 'color: var(--text-faint)') do
+        "Thread ID: #{thread.thread_id}"
+      end
+    end
+  end
+end

data/app/helpers/protege/trace_helper.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Protege
+  # View helpers for the tracing dashboard — the one place the trace views ask about tracing state, so
+  # the +config.tracing+ hash shape stays out of the templates.
+  module TraceHelper
+    # Fetch captured turns newest first — the sidebar list. A helper (like +inbox_threads+) so the +show+
+    # page's sidebar sources its own list without the controller re-deriving it into an ivar.
+    #
+    # @return [ActiveRecord::Relation<Protege::Trace>] traces newest first
+    def recent_traces
+      Trace.recent
+    end
+
+    # Whether inference tracing is currently capturing turns — the +config.tracing+ master switch.
+    #
+    # @return [Boolean] true when tracing is enabled
+    def tracing_enabled?
+      Protege.configuration.tracing[:enabled] ? true : false
+    end
+  end
+end

data/app/hooks/protege/event_logger_hook.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Protege
+  # Built-in event logger hook. Subscribes to the full lifecycle of Protege events and writes
+  # human-readable log lines to the configured +Protege.configuration.logger+, giving operators a
+  # trace of each agent run.
+  #
+  # Subclassing +Protege::Hook+ means the engine wires these handlers onto the event bus once
+  # at boot; each +on+ block receives a typed +Protege::Event+ and runs isolated, so a logging
+  # error can never break inference. As a built-in it is always active.
+  class EventLoggerHook < Protege::Hook
+    # Log the start of an inference run for a persona.
+    on InferenceStartedEvent do |event|
+      log "[#{ts}] #{cid(event)} INF START persona=#{event.persona&.name}"
+    end
+
+    # Log the completion of an inference run for a persona.
+    on InferenceCompletedEvent do |event|
+      log "[#{ts}] #{cid(event)} INF DONE persona=#{event.persona&.name}"
+    end
+
+    # Log the set of tool calls the model requested in a single turn.
+    on ToolCallsReceivedEvent do |event|
+      names = event.tool_calls&.map(&:name)&.join(', ')
+      log "[#{ts}] #{cid(event)} TOOLS RECV [#{names}]"
+    end
+
+    # Log the start of a single tool invocation.
+    on ToolCallStartedEvent do |event|
+      tc = event.tool_call
+      log "[#{ts}] #{cid(event)} TOOL START #{tc&.name} id=#{tc&.id}"
+    end
+
+    # Log a successful tool invocation and its result data.
+    on ToolCallCompletedEvent do |event|
+      tc = event.tool_call
+      log "[#{ts}] #{cid(event)} TOOL OK #{tc&.name} id=#{tc&.id} data=#{event.result&.data}"
+    end
+
+    # Log a failed tool invocation with its error class, message, and a short backtrace.
+    on ToolCallFailedEvent do |event|
+      tc = event.tool_call
+      log "[#{ts}] #{cid(event)} TOOL FAIL #{tc&.name} id=#{tc&.id} " \
+          "#{event.error&.class}: #{event.error&.message}\n    #{error_backtrace(event.error)}"
+    end
+
+    # Log the agent loop hitting its turn cap with tool calls still pending.
+    on InferenceMaxTurnsReachedEvent do |event|
+      names = event.tool_calls&.map(&:name)&.join(', ')
+      log "[#{ts}] #{cid(event)} MAX TURNS turn=#{event.turn} pending=[#{names}]"
+    end
+
+    # Log a scheduled responsibility run being enqueued — pending, awaiting a worker (the Loop layer).
+    on LoopRunEnqueuedEvent do |event|
+      log "[#{ts}] #{cid(event)} LOOP PENDING #{event.name} persona=#{event.persona_name}"
+    end
+
+    # Log the start of a scheduled responsibility run (the Loop layer).
+    on LoopRunStartedEvent do |event|
+      log "[#{ts}] #{cid(event)} LOOP START #{event.name} persona=#{event.persona_name}"
+    end
+
+    # Log the successful completion of a scheduled responsibility run.
+    on LoopRunCompletedEvent do |event|
+      log "[#{ts}] #{cid(event)} LOOP DONE #{event.name} persona=#{event.persona_name}"
+    end
+
+    # Log a failed scheduled responsibility run with its error class, message, and short backtrace.
+    on LoopRunFailedEvent do |event|
+      log "[#{ts}] #{cid(event)} LOOP FAIL #{event.name} persona=#{event.persona_name} " \
+          "#{event.error&.class}: #{event.error&.message}\n    #{error_backtrace(event.error)}"
+    end
+
+    private
+
+    # Render the first few backtrace frames of an error for compact logging.
+    #
+    # @param error [Exception, nil] the captured error, or +nil+
+    # @return [String, nil] up to three indented backtrace frames, or +nil+ when unavailable
+    def error_backtrace(error)
+      return nil unless error
+
+      error.backtrace&.first(3)&.join("\n    ")
+    end
+
+    # The correlation id for log line prefixes, falling back to a placeholder.
+    #
+    # @param event [Protege::Event] the event being logged
+    # @return [String] the correlation id, or +'--------'+ when absent
+    def cid(event)
+      event.correlation_id || '--------'
+    end
+
+    # Write a single line to the configured Protege logger at info level.
+    #
+    # @param line [String] the formatted log line
+    # @return [void]
+    def log(line)
+      Protege.configuration.logger.info(line)
+    end
+
+    # Produce a UTC ISO-8601 timestamp for log line prefixes.
+    #
+    # @return [String] the current time in ISO-8601 UTC
+    def ts
+      Time.now.utc.iso8601
+    end
+  end
+end

data/app/jobs/protege/application_job.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Protege
+  # Abstract base class for every Active Job in the Protege engine.
+  #
+  # Both +InferenceJob+ and +ConsoleInferenceJob+ inherit from this class rather than
+  # +ActiveJob::Base+ directly, matching the host-app convention of an +ApplicationJob+ base. It
+  # provides a single place to configure cross-cutting job behaviour — retry policy, queue adapter
+  # selection, and around-perform callbacks — so individual jobs stay focused on their own work.
+  #
+  # == Failure policy
+  #
+  # Inference can fail for two very different reasons, and they are handled differently:
+  #
+  # * +Protege::Error::TRANSIENT+ are provider hiccups that a later attempt may clear (rate
+  #   limits, timeouts, outages). These are retried with polynomial backoff.
+  # * +Protege::Error::PERMANENT+ cannot be fixed by retrying — a malformed request, bad
+  #   credentials, an unknown model/capability, an unparseable response (plus a vanished record).
+  #   Retrying only wastes work, so these are discarded after the job has recorded the failure.
+  #
+  # Any other error falls through to the queue adapter's default handling (no retry), still recorded
+  # on the message by each job's own +rescue+.
+  class ApplicationJob < ActiveJob::Base
+    # Failures where retrying cannot help; discarded after the failure is recorded.
+    discard_on(ActiveRecord::RecordNotFound, *Protege::Error::PERMANENT)
+    # Provider failures a later attempt may clear.
+    retry_on(*Protege::Error::TRANSIENT, attempts: 3, wait: :polynomially_longer)
+
+    private
+
+    # Restore the per-run correlation ID so this job's events share the originating trace token. Every
+    # Protege job sets this at the top of +perform+, keeping events correlated from ingress (or the
+    # scheduler tick) through inference.
+    #
+    # @param correlation_id [String] the trace token to thread through this job's events
+    # @return [void]
+    def restore_correlation_id(correlation_id)
+      Protege::Current.correlation_id = correlation_id
+    end
+  end
+end

data/app/jobs/protege/console_inference_job.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Protege
+  # Runs a dashboard-originated message through the inference pipeline.
+  #
+  # The console counterpart to +InferenceJob+: enqueued by +Gateway.accept_console_message+ when a
+  # developer sends a message from the HQ console. Because console messages bypass SMTP entirely,
+  # this job operates on a +Message+ that has already been persisted, rather than on an
+  # +ActionMailbox::InboundEmail+ it must ingest first. The remainder of the flow — correlation-ID
+  # restoration, running the Orchestrator's +Harness+, and recording the outcome — mirrors
+  # +InferenceJob+.
+  #
+  # == Lifecycle
+  #
+  # 1. Restore the correlation ID for event tracing.
+  # 2. Find the +Message+ and +Persona+ from their IDs.
+  # 3. Transition the message to +processing+.
+  # 4. Run the inference loop (+Harness+).
+  # 5. Mark the message +processed+ on success, +failed+ on error.
+  class ConsoleInferenceJob < ApplicationJob
+    queue_as :default
+
+    # Process one pre-persisted console message end to end.
+    #
+    # @param message_id [Integer] primary key of the pre-persisted +Message+ record
+    # @param persona_id [Integer] primary key of the +Persona+; STI loads the correct subclass
+    # @param correlation_id [String] trace token forwarded from the console request
+    # @return [void]
+    # @raise [StandardError] re-raised after being recorded on the message, to trigger retries
+    def perform(message_id:, persona_id:, correlation_id:)
+      restore_correlation_id(correlation_id)
+
+      message = Message.find(message_id)
+      persona = Persona.find(persona_id)
+
+      process(message:, persona:)
+    rescue StandardError => e
+      message&.mark_failed!(e)
+      raise
+    end
+
+    private
+
+    # Run the message through the inference loop and record success.
+    #
+    # @param message [Protege::Message] the message to process
+    # @param persona [Protege::Persona] the persona handling it
+    # @return [void]
+    def process(message:, persona:)
+      message.start_processing!
+
+      Orchestrator.reply(persona:, message:)
+
+      message.mark_processed!
+    end
+  end
+end