fosm-rails 0.1.0

data/app/controllers/fosm/admin/settings_controller.rb

@@ -0,0 +1,44 @@
+module Fosm
+  module Admin
+    class SettingsController < BaseController
+      def show
+        @llm_providers = detect_llm_providers
+        @fosm_config   = summarize_fosm_config
+      end
+
+      private
+
+      LLM_PROVIDERS = [
+        { name: "Anthropic (Claude)",  env_key: "ANTHROPIC_API_KEY",   model_prefix: "anthropic/" },
+        { name: "OpenAI",              env_key: "OPENAI_API_KEY",       model_prefix: "openai/" },
+        { name: "Google (Gemini)",     env_key: "GEMINI_API_KEY",       model_prefix: "gemini/" },
+        { name: "Cohere",              env_key: "COHERE_API_KEY",       model_prefix: "cohere/" },
+        { name: "Mistral",             env_key: "MISTRAL_API_KEY",      model_prefix: "mistral/" },
+      ].freeze
+
+      def detect_llm_providers
+        LLM_PROVIDERS.map do |provider|
+          value = ENV[provider[:env_key]]
+          {
+            name:       provider[:name],
+            env_key:    provider[:env_key],
+            configured: value.present?,
+            hint:       value.present? ? "#{value.length} chars, starts with #{value[0..3]}…" : nil
+          }
+        end
+      end
+
+      def summarize_fosm_config
+        cfg = Fosm.config
+        {
+          base_controller:    cfg.base_controller,
+          admin_layout:       cfg.admin_layout,
+          app_layout:         cfg.app_layout,
+          admin_authorize:    cfg.admin_authorize.inspect,
+          app_authorize:      cfg.app_authorize.inspect,
+          current_user_method: cfg.current_user_method.inspect
+        }
+      end
+    end
+  end
+end

data/app/controllers/fosm/admin/transitions_controller.rb

@@ -0,0 +1,22 @@
+module Fosm
+  module Admin
+    class TransitionsController < BaseController
+      def index
+        @transitions = Fosm::TransitionLog.recent
+
+        @transitions = @transitions.where(record_type: params[:model]) if params[:model].present?
+        @transitions = @transitions.where(event_name: params[:event]) if params[:event].present?
+        @transitions = @transitions.where(actor_type: "symbol", actor_label: "agent") if params[:actor] == "agent"
+        @transitions = @transitions.where.not(actor_type: "symbol") if params[:actor] == "human"
+
+        @per_page = 50
+        @current_page = [params[:page].to_i, 1].max
+        @total_count = @transitions.count
+        @total_pages = (@total_count / @per_page.to_f).ceil
+        @transitions = @transitions.limit(@per_page).offset((@current_page - 1) * @per_page)
+
+        @model_names = Fosm::Registry.model_classes.map(&:name).sort
+      end
+    end
+  end
+end

data/app/controllers/fosm/admin/webhooks_controller.rb

@@ -0,0 +1,37 @@
+module Fosm
+  module Admin
+    class WebhooksController < BaseController
+      def index
+        @webhooks = Fosm::WebhookSubscription.all.order(:model_class_name, :event_name)
+        @apps = Fosm::Registry.all
+      end
+
+      def new
+        @webhook = Fosm::WebhookSubscription.new
+        @apps = Fosm::Registry.all
+      end
+
+      def create
+        @webhook = Fosm::WebhookSubscription.new(webhook_params)
+        if @webhook.save
+          redirect_to fosm.admin_webhooks_path, notice: "Webhook created successfully."
+        else
+          @apps = Fosm::Registry.all
+          render :new, status: :unprocessable_entity
+        end
+      end
+
+      def destroy
+        @webhook = Fosm::WebhookSubscription.find(params[:id])
+        @webhook.destroy
+        redirect_to fosm.admin_webhooks_path, notice: "Webhook removed."
+      end
+
+      private
+
+      def webhook_params
+        params.require(:fosm_webhook_subscription).permit(:model_class_name, :event_name, :url, :active, :secret_token)
+      end
+    end
+  end
+end

data/app/controllers/fosm/application_controller.rb

@@ -0,0 +1,23 @@
+module Fosm
+  class ApplicationController < Fosm.config.base_controller.constantize
+    protect_from_forgery with: :exception
+
+    # Call this in generated app controllers to use host app routes instead of
+    # the engine's isolated routes. FOSM apps define routes in the host app
+    # (config/routes/fosm.rb), so controllers need host app route context.
+    #
+    # `include url_helpers` triggers the module's `included` hook which calls
+    # `redefine_singleton_method(:_routes) { routes }` — this overrides the
+    # engine's _routes with the host app's routes for this controller.
+    def self.use_host_routes!
+      include ::Rails.application.routes.url_helpers
+      helper ::Rails.application.routes.url_helpers
+    end
+
+    private
+
+    def fosm_current_user
+      instance_exec(&Fosm.config.current_user_method)
+    end
+  end
+end

data/app/controllers/fosm/rails/application_controller.rb

@@ -0,0 +1,6 @@
+module Fosm
+  module Rails
+    class ApplicationController < ActionController::Base
+    end
+  end
+end

data/app/helpers/fosm/application_helper.rb

@@ -0,0 +1,19 @@
+module Fosm
+  module ApplicationHelper
+    # Returns a human-friendly label for a FOSM state, suitable for display in views.
+    def fosm_state_badge(state)
+      content_tag(:span, state.to_s.humanize,
+                  class: "text-xs font-medium px-2 py-0.5 rounded bg-gray-100 text-gray-700")
+    end
+
+    # Returns a human-friendly label for an actor stored in a TransitionLog.
+    def fosm_actor_label(transition)
+      if transition.by_agent?
+        content_tag(:span, "AI Agent",
+                    class: "text-xs font-medium text-purple-600 bg-purple-50 px-2 py-0.5 rounded")
+      else
+        transition.actor_label || transition.actor_type || "—"
+      end
+    end
+  end
+end

data/app/helpers/fosm/rails/application_helper.rb

@@ -0,0 +1,11 @@
+# Legacy helper kept for backward compatibility.
+# New code should use Fosm::ApplicationHelper directly.
+require_relative "../application_helper"
+
+module Fosm
+  module Rails
+    module ApplicationHelper
+      include Fosm::ApplicationHelper
+    end
+  end
+end

data/app/jobs/fosm/application_job.rb

@@ -0,0 +1,6 @@
+module Fosm
+  class ApplicationJob < ActiveJob::Base
+    # The FOSM engine uses the host app's ActiveJob queue adapter.
+    # Override queue_name in subclasses if needed.
+  end
+end

data/app/jobs/fosm/rails/application_job.rb

@@ -0,0 +1,6 @@
+module Fosm
+  module Rails
+    class ApplicationJob < ActiveJob::Base
+    end
+  end
+end

data/app/jobs/fosm/webhook_delivery_job.rb

@@ -0,0 +1,52 @@
+module Fosm
+  # Delivers webhook payloads to configured endpoints when FOSM events fire.
+  # Runs asynchronously after the transition completes.
+  class WebhookDeliveryJob < ApplicationJob
+    queue_as :default
+    retry_on StandardError, wait: :polynomially_longer, attempts: 5
+
+    def perform(record_type:, record_id:, event_name:, from_state:, to_state:, metadata: {})
+      subscriptions = Fosm::WebhookSubscription.for_event(record_type, event_name)
+      return if subscriptions.none?
+
+      payload = {
+        event: event_name,
+        record_type: record_type,
+        record_id: record_id,
+        from_state: from_state,
+        to_state: to_state,
+        fired_at: Time.current.iso8601,
+        metadata: metadata
+      }
+
+      subscriptions.each do |subscription|
+        deliver(subscription, payload)
+      end
+    end
+
+    private
+
+    def deliver(subscription, payload)
+      uri = URI.parse(subscription.url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = 5
+      http.read_timeout = 10
+
+      request = Net::HTTP::Post.new(uri.request_uri, {
+        "Content-Type" => "application/json",
+        "X-FOSM-Event" => payload[:event],
+        "X-FOSM-Record-Type" => payload[:record_type],
+        "User-Agent" => "fosm-rails/#{Fosm::VERSION}"
+      })
+
+      if subscription.secret_token.present?
+        signature = OpenSSL::HMAC.hexdigest("SHA256", subscription.secret_token, payload.to_json)
+        request["X-FOSM-Signature"] = "sha256=#{signature}"
+      end
+
+      request.body = payload.to_json
+      http.request(request)
+    end
+  end
+end

data/app/models/fosm/application_record.rb

@@ -0,0 +1,6 @@
+module Fosm
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+    connects_to database: { writing: :primary } if ActiveRecord::Base.configurations.find_db_config("primary")
+  end
+end

data/app/models/fosm/rails/application_record.rb

@@ -0,0 +1,7 @@
+module Fosm
+  module Rails
+    class ApplicationRecord < ActiveRecord::Base
+      self.abstract_class = true
+    end
+  end
+end

data/app/models/fosm/transition_log.rb

@@ -0,0 +1,27 @@
+module Fosm
+  # Immutable audit trail of every FOSM state transition.
+  # Records are never updated or deleted — this is an append-only log.
+  class TransitionLog < ApplicationRecord
+    self.table_name = "fosm_transition_logs"
+
+    # Immutability: prevent any updates or deletions
+    before_update { raise ActiveRecord::ReadOnlyRecord, "Fosm::TransitionLog is immutable" }
+    before_destroy { raise ActiveRecord::ReadOnlyRecord, "Fosm::TransitionLog records cannot be deleted" }
+
+    validates :record_type, :record_id, :event_name, :from_state, :to_state, presence: true
+
+    scope :recent, -> { order(created_at: :desc) }
+    scope :for_record, ->(type, id) { where(record_type: type, record_id: id.to_s) }
+    scope :for_app, ->(model_class) { where(record_type: model_class.name) }
+    scope :by_event, ->(event) { where(event_name: event.to_s) }
+    scope :by_actor_type, ->(type) { where(actor_type: type) }
+
+    def by_agent?
+      actor_type == "symbol" && actor_label == "agent"
+    end
+
+    def by_human?
+      !by_agent? && actor_id.present?
+    end
+  end
+end

data/app/models/fosm/webhook_subscription.rb

@@ -0,0 +1,15 @@
+module Fosm
+  # Admin-configured webhooks that fire on specific FOSM transitions.
+  class WebhookSubscription < ApplicationRecord
+    self.table_name = "fosm_webhook_subscriptions"
+
+    validates :model_class_name, presence: true
+    validates :event_name, presence: true
+    validates :url, presence: true, format: { with: URI::DEFAULT_PARSER.make_regexp(%w[http https]) }
+
+    scope :active, -> { where(active: true) }
+    scope :for_event, ->(model_class, event) {
+      where(model_class_name: model_class.to_s, event_name: event.to_s).active
+    }
+  end
+end

data/app/views/fosm/admin/agents/chat.html.erb

@@ -0,0 +1,242 @@
+<div class="flex flex-col h-screen max-h-screen">
+
+  <!-- Header -->
+  <div class="flex items-center justify-between px-5 py-3 bg-white border-b border-gray-200 shrink-0">
+    <div class="flex items-center gap-3">
+      <%= link_to "←", fosm.agent_admin_app_path(@slug), class: "text-gray-400 hover:text-gray-700 text-lg" %>
+      <div>
+        <span class="font-semibold text-gray-900 text-sm"><%= @model_class.name.demodulize.humanize %> Agent Chat</span>
+        <span class="text-xs text-gray-400 ml-2">FOSM bounded autonomy · tools only</span>
+      </div>
+    </div>
+    <button id="new-chat-btn"
+            onclick="resetChat()"
+            class="text-xs border border-gray-200 text-gray-500 px-3 py-1.5 rounded hover:bg-gray-50">
+      New conversation
+    </button>
+  </div>
+
+  <!-- Messages -->
+  <div id="messages" class="flex-1 overflow-y-auto px-5 py-4 space-y-4 bg-gray-50">
+
+    <% if @history.empty? %>
+      <div id="empty-state" class="flex flex-col items-center justify-center h-full text-center text-gray-400 space-y-2 py-20">
+        <div class="text-4xl">🤖</div>
+        <p class="text-sm font-medium text-gray-600">Chat with <%= @model_class.name.demodulize.humanize %> Agent</p>
+        <p class="text-xs max-w-sm">
+          The agent can only act via the lifecycle tools — it cannot bypass guards or jump to terminal states directly.
+        </p>
+        <div class="mt-4 space-y-2 text-left">
+          <p class="text-xs text-gray-400 font-medium">Try asking:</p>
+          <% example_prompts = [
+               "List all #{@mn.pluralize} in draft state",
+               "What events are available for #{@mn} #1?",
+               "Cancel #{@mn} #2"
+          ] %>
+          <% example_prompts.each do |prompt| %>
+            <button onclick="sendMessage(<%= prompt.to_json %>)"
+                    class="block w-full text-left text-xs bg-white border border-gray-200 rounded-lg px-3 py-2 hover:border-gray-300 hover:bg-gray-50 text-gray-600">
+              <%= prompt %>
+            </button>
+          <% end %>
+        </div>
+      </div>
+    <% end %>
+
+    <% @history.each do |msg| %>
+      <% if msg[:role] == "user" || msg["role"] == "user" %>
+        <div class="flex justify-end">
+          <div class="bg-gray-800 text-white text-sm rounded-2xl rounded-tr-sm px-4 py-2.5 max-w-lg">
+            <%= (msg[:content] || msg["content"]) %>
+          </div>
+        </div>
+      <% else %>
+        <% content = msg[:content] || msg["content"] %>
+        <% steps = msg[:steps] || msg["steps"] || [] %>
+        <div class="flex flex-col gap-1 max-w-2xl">
+          <div class="bg-white border border-gray-200 rounded-2xl rounded-tl-sm px-4 py-3 text-sm text-gray-800 whitespace-pre-wrap"><%= content %></div>
+          <% if steps.any? %>
+            <details class="text-xs text-gray-400 cursor-pointer select-none ml-1">
+              <summary class="hover:text-gray-600"><%= steps.size %> step<%= steps.size == 1 ? "" : "s" %> · expand reasoning</summary>
+              <div class="mt-1 space-y-1 ml-2 border-l-2 border-gray-100 pl-3">
+                <% steps.each do |step| %>
+                  <% step = step.transform_keys(&:to_s) %>
+                  <div class="py-1">
+                    <% if step["thought"].present? %>
+                      <p class="text-gray-500 italic"><%= step["thought"].to_s.truncate(200) %></p>
+                    <% end %>
+                    <% if step["tool_calls"].present? %>
+                      <% Array(step["tool_calls"]).each do |tc| %>
+                        <% tc = tc.is_a?(Hash) ? tc.transform_keys(&:to_s) : {} %>
+                        <p class="font-mono text-purple-600">
+                          🔧 <%= tc["name"] %><% if tc["args"].present? %>(<%= tc["args"].map { |k,v| "#{k}: #{v.inspect}" }.join(", ") %><% end %>)
+                        </p>
+                      <% end %>
+                    <% end %>
+                    <% if step["observation"].present? %>
+                      <p class="text-green-600 font-mono text-[10px] truncate"><%= step["observation"].to_s.truncate(150) %></p>
+                    <% end %>
+                  </div>
+                <% end %>
+              </div>
+            </details>
+          <% end %>
+        </div>
+      <% end %>
+    <% end %>
+
+    <div id="thinking" class="hidden flex gap-2 items-center text-sm text-gray-400">
+      <div class="flex gap-1">
+        <span class="animate-bounce" style="animation-delay:0ms">●</span>
+        <span class="animate-bounce" style="animation-delay:150ms">●</span>
+        <span class="animate-bounce" style="animation-delay:300ms">●</span>
+      </div>
+      <span>Agent is thinking…</span>
+    </div>
+  </div>
+
+  <!-- Input -->
+  <div class="shrink-0 bg-white border-t border-gray-200 px-4 py-3">
+    <div class="flex gap-2 items-end">
+      <textarea id="chat-input"
+                rows="1"
+                placeholder="Ask the agent something… (Enter to send, Shift+Enter for newline)"
+                class="flex-1 resize-none text-sm border border-gray-200 rounded-xl px-3 py-2.5 focus:outline-none focus:border-gray-400 max-h-32 overflow-y-auto"
+                onkeydown="handleKey(event)"
+                oninput="autoResize(this)"></textarea>
+      <button id="send-btn"
+              onclick="sendFromInput()"
+              class="text-sm bg-gray-900 text-white px-4 py-2.5 rounded-xl hover:bg-gray-700 shrink-0">
+        Send
+      </button>
+    </div>
+    <p class="text-[10px] text-gray-300 mt-1 ml-1">
+      Agent has access to: list, get, available_events, transition_history, and fire-event tools.
+    </p>
+  </div>
+</div>
+
+<script>
+const CHAT_SEND_URL  = '<%= fosm.agent_chat_send_admin_app_path(@slug) %>';
+const CHAT_RESET_URL = '<%= fosm.agent_chat_reset_admin_app_path(@slug) %>';
+const CSRF_TOKEN     = document.querySelector('meta[name="csrf-token"]')?.content || '';
+
+function scrollBottom() {
+  const el = document.getElementById('messages');
+  el.scrollTop = el.scrollHeight;
+}
+
+function appendMessage(role, content, steps) {
+  const wrap = document.getElementById('messages');
+  const empty = document.getElementById('empty-state');
+  if (empty) empty.remove();
+
+  const div = document.createElement('div');
+
+  if (role === 'user') {
+    div.className = 'flex justify-end';
+    div.innerHTML = `<div class="bg-gray-800 text-white text-sm rounded-2xl rounded-tr-sm px-4 py-2.5 max-w-lg">${escapeHtml(content)}</div>`;
+  } else {
+    div.className = 'flex flex-col gap-1 max-w-2xl';
+    let stepsHtml = '';
+    if (steps && steps.length > 0) {
+      const stepItems = steps.map(s => {
+        let parts = [];
+        if (s.thought) parts.push(`<p class="text-gray-500 italic">${escapeHtml(s.thought.substring(0, 200))}</p>`);
+        if (s.tool_calls) {
+          s.tool_calls.forEach(tc => {
+            const args = tc.args ? Object.entries(tc.args).map(([k,v]) => `${k}: ${JSON.stringify(v)}`).join(', ') : '';
+            parts.push(`<p class="font-mono text-purple-600">🔧 ${escapeHtml(tc.name)}(${escapeHtml(args)})</p>`);
+          });
+        }
+        if (s.observation) parts.push(`<p class="text-green-600 font-mono text-[10px] truncate">${escapeHtml(String(s.observation).substring(0, 150))}</p>`);
+        return `<div class="py-1">${parts.join('')}</div>`;
+      }).join('');
+      stepsHtml = `<details class="text-xs text-gray-400 cursor-pointer select-none ml-1">
+        <summary class="hover:text-gray-600">${steps.length} step${steps.length === 1 ? '' : 's'} · expand reasoning</summary>
+        <div class="mt-1 space-y-1 ml-2 border-l-2 border-gray-100 pl-3">${stepItems}</div>
+      </details>`;
+    }
+    div.innerHTML = `<div class="bg-white border border-gray-200 rounded-2xl rounded-tl-sm px-4 py-3 text-sm text-gray-800 whitespace-pre-wrap">${escapeHtml(content)}</div>${stepsHtml}`;
+  }
+
+  wrap.insertBefore(div, document.getElementById('thinking'));
+  scrollBottom();
+}
+
+async function sendMessage(text) {
+  if (!text.trim()) return;
+  appendMessage('user', text);
+
+  const thinking = document.getElementById('thinking');
+  thinking.classList.remove('hidden');
+  document.getElementById('send-btn').disabled = true;
+  scrollBottom();
+
+  try {
+    const resp = await fetch(CHAT_SEND_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': CSRF_TOKEN },
+      body: JSON.stringify({ message: text })
+    });
+    const data = await resp.json();
+    if (data.error) {
+      // Translate technical LLM errors into friendly messages
+      let friendly = data.error;
+      if (data.error.includes('trailing whitespace')) {
+        friendly = "I had trouble continuing from the previous message. I've reset my context — please try again.";
+      } else if (data.error.includes('anthropic_api_key') || data.error.includes('Missing configuration')) {
+        friendly = "No API key configured. Set ANTHROPIC_API_KEY (or another provider) and restart the server.";
+      } else if (data.error.includes('LLM API error')) {
+        friendly = "The LLM returned an error: " + data.error.replace(/.*LLM API error:\s*/, '');
+      }
+      appendMessage('agent', '⚠ ' + friendly, []);
+    } else {
+      appendMessage('agent', data.output || '(no response)', data.steps || []);
+    }
+  } catch(e) {
+    appendMessage('agent', '⚠ Something went wrong. Please try again.', []);
+  } finally {
+    thinking.classList.add('hidden');
+    document.getElementById('send-btn').disabled = false;
+  }
+}
+
+function sendFromInput() {
+  const input = document.getElementById('chat-input');
+  const text = input.value.trim();
+  if (!text) return;
+  input.value = '';
+  autoResize(input);
+  sendMessage(text);
+}
+
+async function resetChat() {
+  if (!confirm('Start a new conversation? This will clear the current context.')) return;
+  await fetch(CHAT_RESET_URL, {
+    method: 'DELETE',
+    headers: { 'X-CSRF-Token': CSRF_TOKEN }
+  });
+  window.location.reload();
+}
+
+function handleKey(e) {
+  if (e.key === 'Enter' && !e.shiftKey) {
+    e.preventDefault();
+    sendFromInput();
+  }
+}
+
+function autoResize(el) {
+  el.style.height = 'auto';
+  el.style.height = Math.min(el.scrollHeight, 128) + 'px';
+}
+
+function escapeHtml(str) {
+  return String(str)
+    .replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;')
+    .replace(/"/g,'&quot;').replace(/'/g,'&#39;');
+}
+
+document.addEventListener('DOMContentLoaded', scrollBottom);
+</script>