protege 0.1.0.alpha.1

data/app/controllers/protege/responsibilities_controller.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Protege
+  # Manages scheduled responsibilities — the Loop layer's dashboard CRUD. A top-level section (like
+  # Personas or Traces): responsibilities are listed across all personas, and each one names its owning
+  # persona in the form rather than carrying it in the URL.
+  class ResponsibilitiesController < ApplicationController
+    before_action :set_responsibility, only: %i[show edit update destroy]
+
+    # List every responsibility, newest-owner-agnostic (ordered by name via the model's default scope).
+    #
+    # @return [void]
+    def index
+      @responsibilities = Responsibility.includes(:persona)
+    end
+
+    # Show a single responsibility and its recent runs.
+    #
+    # @return [void]
+    def show; end
+
+    # Render the form for creating a responsibility.
+    #
+    # @return [void]
+    def new
+      @responsibility = Responsibility.new
+    end
+
+    # Render the form for editing a responsibility.
+    #
+    # @return [void]
+    def edit; end
+
+    # Create a responsibility (its persona is chosen in the form). On failure, re-render with errors.
+    #
+    # @return [void]
+    def create
+      @responsibility = Responsibility.new(responsibility_params)
+
+      if @responsibility.save
+        redirect_to responsibility_path(@responsibility), notice: 'Responsibility created.'
+      else
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    # Update a responsibility. On failure, re-render the edit form with validation errors.
+    #
+    # @return [void]
+    def update
+      if @responsibility.update(responsibility_params)
+        redirect_to responsibility_path(@responsibility), notice: 'Responsibility updated.'
+      else
+        render :edit, status: :unprocessable_entity
+      end
+    end
+
+    # Remove a responsibility.
+    #
+    # @return [void]
+    def destroy
+      @responsibility.destroy
+      redirect_to responsibilities_path, notice: 'Responsibility deleted.'
+    end
+
+    private
+
+    # Load the responsibility named by the route into +@responsibility+ (its persona via the association).
+    #
+    # @return [Protege::Responsibility] the loaded responsibility
+    def set_responsibility
+      @responsibility = Responsibility.find(params[:id])
+    end
+
+    # Permit the editable responsibility attributes, including the +:persona_id+ the form now supplies.
+    #
+    # @return [ActionController::Parameters] the permitted attributes
+    def responsibility_params
+      params.require(:responsibility).permit(:persona_id, :name, :instructions, :schedule, :active)
+    end
+  end
+end

data/app/controllers/protege/responsibility_runs_controller.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Protege
+  # Surfaces individual runs of a responsibility — the Loop layer's run records. Creating a run is how
+  # the dashboard's "Run now" works: dispatching a responsibility immediately, modelled RESTfully as
+  # POSTing a new run rather than a custom action.
+  class ResponsibilityRunsController < ApplicationController
+    before_action :set_responsibility_run, only: [:show]
+
+    # Dispatch a responsibility now, recording a pending run and enqueuing its job. Serves
+    # +POST /responsibility_runs+.
+    #
+    # @return [void]
+    def create
+      responsibility = Responsibility.find(run_params[:responsibility_id])
+
+      @run = responsibility.dispatch!
+
+      redirect_to responsibility_run_path(@run), notice: 'Run enqueued.'
+    end
+
+    # Show one run's outcome — status, timing, and any failure detail. Serves
+    # +GET /responsibility_runs/:id+.
+    #
+    # @return [void]
+    def show
+      @responsibility = @run.responsibility
+    end
+
+    private
+
+    # Load the run record
+    #
+    # @return [Protege::ResponsibilityRun] the run to show
+    def set_responsibility_run
+      @run = ResponsibilityRun.find(params[:id])
+    end
+
+    # Permit the responsibility a "Run now" targets.
+    #
+    # @return [ActionController::Parameters] the permitted +:responsibility_id+
+    def run_params
+      params.require(:responsibility_run).permit(:responsibility_id)
+    end
+  end
+end

data/app/controllers/protege/threads_controller.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Protege
+  # Manages email threads — the inbox list, individual thread views,
+  # and composing new conversations from the dashboard console.
+  class ThreadsController < ApplicationController
+    before_action :set_thread, only: %i[show destroy]
+
+    # List the inbox threads. Serves +GET /threads+.
+    #
+    # @return [void]
+    def index
+      @threads = EmailThread.for_inbox
+    end
+
+    # Show a thread with its messages newest-first. Serves +GET /threads/:id+.
+    #
+    # Liveness (the agent's reasoning and tool use) streams into the introspection panel, so the thread
+    # view itself is static — no per-message processing indicator to compute here.
+    #
+    # @return [void]
+    def show
+      @messages = @thread.messages.order(sent_at: :desc)
+    end
+
+    # Render the compose form for a new conversation. Serves +GET /threads/new+.
+    #
+    # @return [void]
+    def new; end
+
+    # Compose and dispatch a new conversation through the +Gateway+. Serves +POST /threads+.
+    #
+    # Uses the same host-facing seam application code would — +Gateway.message+ — passing any uploaded
+    # files straight through as attachments. Redirects to the thread created for the resulting message.
+    #
+    # @return [void]
+    def create
+      persona = Persona.find(compose_params[:persona_id])
+
+      message = Gateway.message(
+        to:          persona.email_address,
+        subject:     compose_params[:subject],
+        body:        compose_params[:body],
+        attachments: compose_params[:files] || []
+      )
+
+      redirect_to thread_path(message.email_thread)
+    end
+
+    # Delete a thread and all its messages. Serves +DELETE /threads/:id+.
+    #
+    # @return [void]
+    def destroy
+      @thread.destroy!
+
+      redirect_to threads_path
+    end
+
+    private
+
+    # Load the +EmailThread+ named by +params[:id]+ into +@thread+.
+    #
+    # @return [Protege::EmailThread] the loaded thread
+    def set_thread
+      @thread = EmailThread.find(params[:id])
+    end
+
+    # Permit the compose-form attributes for a new conversation.
+    #
+    # @return [ActionController::Parameters] the permitted +:persona_id+, +:subject+, +:body+, +:files+
+    def compose_params
+      params.require(:thread).permit(:persona_id, :subject, :body, files: [])
+    end
+  end
+end

data/app/controllers/protege/traces/searches_controller.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Protege
+  module Traces
+    # Trace search — the console's cross-run finder over captured turns (see +TraceSearch+), reached from
+    # the traces sidebar's search link. Nested in the +Traces+ module because search is a view *of*
+    # traces, not a child record a trace owns (unlike a thread, which genuinely has messages).
+    class SearchesController < Protege::ApplicationController
+      # Show the search form and, in the sidebar, the traces matching the query params (see
+      # +TraceSearch+). Blank params yield no results. Serves +GET /traces/search+.
+      #
+      # @return [void]
+      def show
+        @search = TraceSearch.from_params(params)
+        @traces = @search.results
+      end
+    end
+  end
+end

data/app/controllers/protege/traces_controller.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Protege
+  # Traces — the review surface for captured inference turns (see +Protege::Trace+). +index+ lists the
+  # turns (newest first, optionally narrowed to the unlabeled review queue) in the sidebar; +show+
+  # renders one turn's request/response/settings snapshot; +update+ applies a human review label so the
+  # turn becomes usable training data. Read-and-label only — traces are written by the tracing
+  # subscriber, never edited here beyond the verdict.
+  class TracesController < ApplicationController
+    before_action :set_trace, only: %i[show update]
+
+    # List captured turns, newest first, for the sidebar (search lives on its own page — see
+    # +Traces::SearchesController+). Serves +GET /traces+.
+    #
+    # @return [void]
+    def index
+      @traces = Trace.recent
+    end
+
+    # Show one turn's snapshot and its review form. The sidebar sources its own list via the
+    # +recent_traces+ helper (like threads' +inbox_threads+), so nothing to load here. Serves
+    # +GET /traces/:id+.
+    #
+    # @return [void]
+    def show; end
+
+    # Apply a review verdict (label + optional note) to a turn. Serves +PATCH /traces/:id+.
+    #
+    # @return [void]
+    def update
+      @trace.apply_label(label: label_params[:label], annotation: label_params[:annotation])
+
+      redirect_to trace_path(@trace), notice: 'Trace labeled.'
+    end
+
+    private
+
+    # Load the trace named by +params[:id]+.
+    #
+    # @return [Protege::Trace] the loaded trace
+    def set_trace
+      @trace = Trace.find(params[:id])
+    end
+
+    # Permit the review verdict fields.
+    #
+    # @return [ActionController::Parameters] the permitted +:label+/+:annotation+
+    def label_params
+      params.require(:trace).permit(:label, :annotation)
+    end
+  end
+end

data/app/helpers/protege/application_helper.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Protege
+  # The single aggregator of every engine helper module. The engine registers only this module on the
+  # view context (+helper Protege::ApplicationHelper+ in ApplicationController), so including every
+  # helper here is what makes their methods available in all render contexts — request views, partials,
+  # and Turbo broadcast renders alike. Two groups: the reusable, model-agnostic UI toolkit under
+  # +Protege::Components::+ — pulled in as a whole via its own aggregator, +Components::ComponentsHelper+,
+  # which includes the rest of the group (typography, tables, badges, buttons, cards, dialogs, menus,
+  # forms, layout, sidebar, pagination, the introspection panel) — and the model-named helpers at the
+  # top level (threads, personas, email
+  # domains, messages, responsibilities, traces). Any cross-helper call resolves through the view, which
+  # has them all via this module.
+  module ApplicationHelper
+    include Components::ComponentsHelper
+    include EmailDomainsHelper
+    include MessagesHelper
+    include PersonasHelper
+    include ResponsibilitiesHelper
+    include ThreadsHelper
+    include TraceHelper
+
+    # List of JS files to be added to the console layout
+    #
+    # @return [Array<string>] javascript asset file paths.
+    def js_files
+      %w[protege/theme protege/resize protege/forms protege/copy protege/keys protege/attachment_picker]
+    end
+  end
+end

data/app/helpers/protege/components/badges_helper.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Protege
+  module Components
+    # Compact status indicators: the pill +badge+ and the labelled +status_dot+. Both take a semantic
+    # color and resolve it through the +badge_colors+ / +dot_colors+ maps defined alongside them, so the
+    # palette lives with the components that use it.
+    module BadgesHelper
+      # Render a small pill badge tinted by semantic color.
+      #
+      # @param text [String] the badge label
+      # @param color [Symbol] the semantic color (see +badge_colors+)
+      # @return [ActiveSupport::SafeBuffer] the badge markup
+      def badge(text, color = :gray)
+        _, fg = badge_colors(color)
+        tag.span(text, class: "inline-flex items-center rounded px-1.5 py-0.5 text-xs font-medium #{fg}",
+                       style: 'background: var(--surface-subtle); border: 1px solid var(--border)')
+      end
+
+      # Map a semantic badge color to its +[background, foreground]+ classes.
+      #
+      # @param color [Symbol] the semantic color
+      # @return [Array(nil, String)] the background and foreground class pair
+      def badge_colors(color)
+        case color
+        when :green  then [nil, 'text-green-600']
+        when :red    then [nil, 'text-red-600']
+        when :yellow then [nil, 'text-yellow-600']
+        else              [nil, '']
+        end
+      end
+
+      # Render a colored status dot followed by its label.
+      #
+      # @param text [String] the status label
+      # @param color [Symbol] the semantic color (see +dot_colors+)
+      # @return [ActiveSupport::SafeBuffer] the status-dot markup
+      def status_dot(text, color = :gray)
+        dot_color = dot_colors(color)
+        tag.span(class: 'inline-flex items-center gap-1.5 text-xs', style: 'color: var(--text-muted)') do
+          tag.span('', class: "h-1.5 w-1.5 rounded-full #{dot_color}") + text
+        end
+      end
+
+      # Map a semantic status color to its dot background class.
+      #
+      # @param color [Symbol] the semantic color
+      # @return [String] the Tailwind background class for the dot
+      def dot_colors(color)
+        case color
+        when :green  then 'bg-green-600'
+        when :red    then 'bg-red-600'
+        when :yellow then 'bg-yellow-600'
+        else              'bg-gray-500'
+        end
+      end
+    end
+  end
+end

data/app/helpers/protege/components/buttons_helper.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Protege
+  module Components
+    # Clickable actions: the primary/danger +button+, the solid form-submitting +action_button+ (its
+    # +button_to+ counterpart, sharing the same look via +button_class+), the amber text +ui_link+, and
+    # the two link-styled form buttons (+inline_button+, +destructive_link+) for subtler POST/DELETE
+    # actions. Variant styling is resolved by +button_variant_style+, defined alongside them here.
+    module ButtonsHelper
+      # Render a styled button. The +:danger+ variant uses the danger hover style.
+      #
+      # @param text [String] the button label
+      # @param variant [Symbol] the visual variant (see +button_variant_style+)
+      # @param attrs [Hash] extra HTML attributes forwarded to the button
+      # @return [ActiveSupport::SafeBuffer] the button markup
+      def button(text, variant: :primary, **attrs)
+        tag.button(text,
+                   class: button_class(variant, attrs.delete(:class)),
+                   style: button_variant_style(variant),
+                   **attrs)
+      end
+
+      # Render a solid, button-styled action that submits a form — a +button_to+ (so it POSTs, unlike the
+      # formless {#button}) wearing the same styling as {#button}. Use this for actions that mutate state
+      # from a plain click (e.g. "Sync now"); the link-styled {#inline_button}/{#destructive_link} are the
+      # subtler variants.
+      #
+      # @param text [String] the button label
+      # @param href [String] the form action target
+      # @param method [Symbol] the HTTP verb the button submits (default +:post+)
+      # @param variant [Symbol] the visual variant (see +button_variant_style+)
+      # @param attrs [Hash] extra HTML attributes forwarded to the button
+      # @return [ActiveSupport::SafeBuffer] the button-to markup
+      def action_button(text, href, method: :post, variant: :primary, **attrs)
+        button_to text, href,
+                  method:,
+                  class:  button_class(variant, attrs.delete(:class)),
+                  style:  button_variant_style(variant),
+                  form:   { class: 'inline' },
+                  **attrs
+      end
+
+      # Render a form button as a link-styled element, for use in inline
+      # forms (e.g. +button_to+ with +form: { class: "inline" }).
+      #
+      # @param text [String] the button text
+      # @param href [String] the form action target
+      # @param method [Symbol] the HTTP verb the button submits
+      # @param attrs [Hash] extra HTML attributes forwarded to the button
+      # @return [ActiveSupport::SafeBuffer] the button markup
+      def inline_button(text, href, method: :post, **attrs)
+        classes = 'text-sm text-amber-600 hover:text-amber-700 cursor-pointer ' \
+                  "bg-transparent border-0 p-0 #{attrs.delete(:class)}"
+
+        button_to text, href,
+                  method:,
+                  class:  classes,
+                  form:   { class: 'inline' },
+                  **attrs
+      end
+
+      # Render an amber text link, dimmed when +muted+.
+      #
+      # @param text [String] the link text
+      # @param href [String] the link target
+      # @param muted [Boolean] whether to render the dimmed variant
+      # @param attrs [Hash] extra HTML attributes forwarded to the link
+      # @return [ActiveSupport::SafeBuffer] the link markup
+      def ui_link(text, href, muted: false, **attrs)
+        classes = if muted
+                    'text-sm text-amber-400 hover:text-amber-600'
+                  else
+                    'text-sm text-amber-600 hover:text-amber-700'
+                  end
+
+        link_to(text, href, class: "#{classes} #{attrs.delete(:class)}", **attrs)
+      end
+
+      # Render a destructive action as an inline form button with optional confirm.
+      #
+      # @param text [String] the link text
+      # @param href [String] the action target
+      # @param confirm [String, nil] optional Turbo confirmation prompt
+      # @param method [Symbol] the HTTP verb the button submits
+      # @return [ActiveSupport::SafeBuffer] the button-to markup
+      # @param [Hash{Symbol => Object}] attrs
+      def destructive_link(text, href, confirm: nil, method: :delete, **attrs)
+        classes = 'text-sm text-red-500 hover:text-red-700 cursor-pointer ' \
+                  "bg-transparent border-0 p-0 #{attrs.delete(:class)}"
+
+        button_to text, href,
+                  method:,
+                  class:  classes,
+                  form:   { class: 'inline' },
+                  data:   confirm ? { turbo_confirm: confirm } : {},
+                  **attrs
+      end
+
+      # Render an icon-only button — a muted glyph that brightens on hover (e.g. a composer's attach
+      # control). +label+ is both the tooltip and the accessible name, since there is no visible text.
+      #
+      # @param name [Symbol] the icon to render (see {IconsHelper#icon})
+      # @param label [String] the tooltip / accessible label
+      # @param attrs [Hash] extra HTML attributes forwarded to the button (e.g. +data:+)
+      # @return [ActiveSupport::SafeBuffer] the icon-button markup
+      def icon_button(name, label:, **attrs)
+        tag.button(icon(name),
+                   type:         'button',
+                   title:        label,
+                   'aria-label': label,
+                   class:        'rounded p-1.5 opacity-70 transition-opacity hover:opacity-100 cursor-pointer',
+                   style:        'color: var(--text-muted)',
+                   **attrs)
+      end
+
+      # The shared class list for the solid button look, worn by both {#button} and {#action_button}.
+      #
+      # @param variant [Symbol] the button variant (only +:danger+ changes the hover treatment)
+      # @param extra [String, nil] caller-supplied extra classes
+      # @return [String] the combined class string
+      def button_class(variant, extra = nil)
+        hover_class = variant == :danger ? 'btn-danger' : 'btn-outline'
+        base_class  = 'inline-flex items-center justify-center rounded-sm px-2.5 py-1 text-xs ' \
+                      'font-semibold uppercase tracking-wide transition-colors cursor-pointer'
+        class_names(hover_class, base_class, extra)
+      end
+
+      # Map a button variant to its inline style string.
+      #
+      # @param variant [Symbol] the button variant
+      # @return [String] the variant's CSS style string
+      def button_variant_style(variant)
+        case variant
+        when :secondary then 'background: transparent; border: 1px solid var(--border); color: var(--text-muted)'
+        when :danger    then 'background: transparent; border: 1px solid #ef4444; color: #ef4444'
+        else                 'background: transparent; border: 1px solid var(--border); color: var(--text)'
+        end
+      end
+    end
+  end
+end

data/app/helpers/protege/components/cards_helper.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Protege
+  module Components
+    # Surface-card UI elements shared across engine views. One helper among the +Components+ peers pulled
+    # together by +ComponentsHelper+; +info_card+ calls +heading_2+ (+TypographyHelper+), resolved through
+    # the view, which has every helper.
+    #
+    # Colors use CSS custom properties (--surface, --border, --text-faint) defined
+    # in tailwind/application.css so dark mode works via a single .dark class toggle.
+    module CardsHelper
+      # Render a surface card, padded unless +padding+ is false.
+      #
+      # @param padding [Boolean] whether to apply interior padding
+      # @yield the card body content
+      # @return [ActiveSupport::SafeBuffer] the card markup
+      def card(padding: true, &)
+        tag.div(class: "rounded-xl #{'p-6' if padding}",
+                style: 'background: var(--surface); border: 1px solid var(--border)', &)
+      end
+
+      # Render a titled card of label/value pairs in a monospace value column.
+      #
+      # By default the label sits in a fixed-width column beside the value — right for short labels like
+      # "Address". Pass +full_width: true+ to let the label take its natural width so the value uses the
+      # full row, for longer labels (e.g. resolver class names) that would overflow the fixed column.
+      #
+      # @param title [String] the card title
+      # @param pairs [Hash{String => String}] the label => value rows
+      # @param full_width [Boolean] let the label size to its content instead of a fixed column
+      # @return [ActiveSupport::SafeBuffer] the info-card markup
+      def info_card(title, pairs = {}, full_width: false)
+        tag.div(class: 'rounded-xl p-5',
+                style: 'background: var(--surface); border: 1px solid var(--border)') do
+          tag.div(class: 'mb-3') { heading_2(title) } +
+            tag.div(class: 'space-y-1 text-sm') do
+              safe_join(pairs.map do |label, value|
+                tag.div(class: 'flex gap-8') do
+                  tag.span(label, class: (full_width ? 'shrink-0' : 'w-20'), style: 'color: var(--text-faint)') +
+                    tag.code(value, class: 'font-mono break-all')
+                end
+              end)
+            end
+        end
+      end
+    end
+  end
+end

data/app/helpers/protege/components/components_helper.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Protege
+  module Components
+    # The aggregator for the +Protege::Components::+ UI toolkit. It holds no methods of its own — every
+    # component lives in a focused, self-describing helper (typography, tables, badges, buttons, dialogs,
+    # menus, cards, forms, layout, sidebar, pagination, introspection) — and this module includes them
+    # all, so +Protege::ApplicationHelper+ pulls the whole toolkit into the view with a single
+    # +include Components::ComponentsHelper+. Because they land on the view together, any component can
+    # freely call another (e.g. +info_card+ renders a +heading_2+) through the view.
+    #
+    # Colors throughout use CSS custom properties (--surface, --border, --text, --text-muted,
+    # --text-faint) defined in tailwind/application.css so dark mode works via a single .dark class toggle.
+    module ComponentsHelper
+      include BadgesHelper
+      include ButtonsHelper
+      include CardsHelper
+      include DialogsHelper
+      include FormsHelper
+      include HotkeysHelper
+      include IntrospectionHelper
+      include LayoutHelper
+      include MenusHelper
+      include PaginationHelper
+      include SidebarHelper
+      include TablesHelper
+      include TypographyHelper
+    end
+  end
+end

data/app/helpers/protege/components/dialogs_helper.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Protege
+  module Components
+    # Native modal +<dialog>+ elements: +dialog+ renders one (closing on backdrop click), and +show_dialog+
+    # builds the +showModal()+ snippet a trigger fires to open it by id.
+    module DialogsHelper
+      # Build the JS snippet that opens a +<dialog>+ by element id.
+      #
+      # @param element_id [String] the DOM id of the target dialog
+      # @return [String] the +showModal()+ invocation
+      def show_dialog(element_id)
+        "document.getElementById('#{element_id}').showModal()"
+      end
+
+      # Render a modal +<dialog>+ that closes on backdrop click.
+      #
+      # @param element_id [String] the DOM id assigned to the dialog
+      # @yield the dialog body content
+      # @return [ActiveSupport::SafeBuffer] the dialog markup
+      # @param [Hash{Symbol => Object}] attrs
+      def dialog(element_id, **attrs, &)
+        tag.dialog(
+          id:      element_id,
+          # focus:outline-none — showModal() focuses the dialog itself when it has no focusable child
+          # (e.g. the hotkey-help overlay), which would otherwise draw the UA focus ring on the whole box.
+          class:   'rounded-xl p-6 shadow-lg backdrop:bg-gray-900/50 max-w-md w-full m-auto focus:outline-none',
+          style:   'background: var(--surface); border: 1px solid var(--border); color: var(--text)',
+          onclick: 'event.target === this && this.close()',
+          **attrs,
+          &
+        )
+      end
+    end
+  end
+end