fosm-rails 0.1.0

data/README.md

@@ -0,0 +1,322 @@
+# fosm-rails
+
+**Finite Object State Machine for Rails** — declarative lifecycles for business objects, with an AI agent interface that enforces bounded autonomy.
+
+```ruby
+class Invoice < ApplicationRecord
+  include Fosm::Lifecycle
+
+  lifecycle do
+    state :draft,     initial: true
+    state :sent
+    state :paid,      terminal: true
+    state :cancelled, terminal: true
+
+    event :send_invoice, from: :draft,  to: :sent
+    event :pay,          from: :sent,   to: :paid
+    event :cancel,       from: [:draft, :sent], to: :cancelled
+
+    guard :has_line_items, on: :send_invoice do |invoice|
+      invoice.amount > 0
+    end
+
+    side_effect :notify_client, on: :send_invoice do |invoice, transition|
+      InvoiceMailer.send_to_client(invoice).deliver_later
+    end
+  end
+end
+```
+
+That block is the complete lifecycle specification. There is no path from `draft` to `paid`. There is no path out of `paid` — it's terminal. A guard blocks sending an empty invoice. A side effect fires the notification email. The machine enforces all of it.
+
+---
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "fosm-rails"
+```
+
+`gemlings` (the AI agent framework) is a **required dependency** — it is declared in `fosm-rails.gemspec` and installed automatically. You do not need to add it separately. Set the API key for your LLM provider (e.g. `ANTHROPIC_API_KEY`) and the agent is ready to use with no extra configuration.
+
+Run:
+
+```bash
+bundle install
+rails fosm:install:migrations
+rails db:migrate
+```
+
+Mount the engine in `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount Fosm::Engine => "/fosm"
+  draw :fosm  # draws config/routes/fosm.rb (auto-created by generators)
+end
+```
+
+Configure auth in `config/initializers/fosm.rb`:
+
+```ruby
+Fosm.configure do |config|
+  # The base controller the FOSM engine inherits from
+  config.base_controller = "ApplicationController"
+
+  # Who can access /fosm/admin — should be superadmin only
+  config.admin_authorize = -> { redirect_to root_path unless current_user&.superadmin? }
+
+  # How to authorize individual FOSM apps
+  config.app_authorize = ->(_level) { authenticate_user! }
+
+  # How to get the current user (for transition log actor tracking)
+  config.current_user_method = -> { current_user }
+
+  # Layouts
+  config.admin_layout = "admin"    # your admin layout
+  config.app_layout   = "application"
+end
+```
+
+---
+
+## Quickstart: create a new FOSM app
+
+```bash
+rails generate fosm:app invoice \
+  --fields name:string amount:decimal client_name:string due_date:date \
+  --states draft,sent,paid,overdue,cancelled \
+  --access authenticate_user!
+```
+
+This generates:
+
+```
+app/models/fosm/invoice.rb          # Model with lifecycle DSL stub
+app/controllers/fosm/invoice_controller.rb
+app/views/fosm/invoice/             # index, show, new, _form
+app/agents/fosm/invoice_agent.rb    # Gemlings AI agent
+db/migrate/..._create_fosm_invoices.rb
+config/routes/fosm.rb               # Route registration
+```
+
+Then run `rails db:migrate` and visit `/fosm/apps/invoices`.
+
+> **One lifecycle definition → three things for free**
+>
+> When you run `rails generate fosm:app invoice`, FOSM generates a model with a lifecycle stub, a CRUD controller, HTML views, database migration, and a Gemlings AI agent — all wired together. Define the states, events, guards, and side effects once. The CRUD UI enforces them. The AI agent is bounded by them. The admin dashboard visualises them.
+
+---
+
+## Defining lifecycles
+
+### States
+
+```ruby
+lifecycle do
+  state :draft,  initial: true   # starting state (exactly one allowed)
+  state :active
+  state :closed, terminal: true  # no transitions out of terminal states
+end
+```
+
+### Events
+
+```ruby
+event :activate,  from: :draft,             to: :active
+event :close,     from: [:draft, :active],  to: :closed
+```
+
+### Guards
+
+Guards are **pure functions** — they block a transition if they return false. No side effects inside guards.
+
+```ruby
+guard :has_required_fields, on: :activate do |record|
+  record.name.present? && record.amount.positive?
+end
+```
+
+### Side effects
+
+Side effects run **after** the state persists, within the same database transaction.
+
+```ruby
+side_effect :send_notification, on: :activate do |record, transition|
+  # transition contains: { from:, to:, event:, actor: }
+  NotificationMailer.activated(record).deliver_later
+end
+```
+
+---
+
+## Firing events
+
+```ruby
+# Dynamic bang method (generated per event)
+invoice.send_invoice!(actor: current_user)
+invoice.pay!(actor: current_user)
+invoice.cancel!(actor: current_user, metadata: { reason: "client request" })
+
+# Or via the generic fire! method
+invoice.fire!(:send_invoice, actor: current_user)
+
+# Check before firing
+invoice.can_send_invoice?     # => true/false
+invoice.available_events      # => [:pay, :cancel]
+invoice.draft?                # => false (state predicate)
+invoice.sent?                 # => true
+```
+
+When a transition is invalid, `fire!` raises a `Fosm::InvalidTransition` error. When a guard fails, it raises `Fosm::GuardFailed`. There is no silent state corruption.
+
+---
+
+## AI Agents (powered by Gemlings)
+
+**Every FOSM app automatically has a fully-configured AI agent.** You don't write any agent code to get started — the tools are derived directly from the lifecycle definition at runtime. The agent is bounded by the same rules as the human UI: it can only fire events that exist, it cannot bypass guards, and every action is written to the immutable transition log.
+
+Each FOSM app auto-generates standard Gemlings tools from the lifecycle definition. The agent can only fire events that exist in the machine.
+
+```ruby
+# app/agents/fosm/invoice_agent.rb
+class Fosm::InvoiceAgent < Fosm::Agent
+  model_class Fosm::Invoice
+  default_model "anthropic/claude-sonnet-4-20250514"
+
+  # Optional: add custom tools
+  fosm_tool :find_overdue,
+            description: "Find sent invoices past their due date",
+            inputs: {} do
+    Fosm::Invoice.where(state: "sent")
+                 .where("due_date < ?", Date.today)
+                 .map { |inv| { id: inv.id, due_date: inv.due_date.to_s } }
+  end
+end
+
+# Use it
+agent = Fosm::InvoiceAgent.build_agent
+agent.run("Mark all sent invoices older than 30 days as overdue")
+
+# Or use a different model
+agent = Fosm::InvoiceAgent.build_agent(model: "openai/gpt-4o")
+agent.run("Pay invoice #42 if it's in the correct state")
+```
+
+**Standard tools auto-generated for every FOSM app:**
+
+| Tool | Description |
+|---|---|
+| `list_invoices` | List records, optionally filtered by state |
+| `get_invoice` | Get a record by ID with state + available events |
+| `available_events_for_invoice` | What events can fire from current state |
+| `transition_history_for_invoice` | Full audit trail for a record |
+| `send_invoice_invoice` | Fire the `send_invoice` event (one per lifecycle event) |
+| `pay_invoice` | Fire the `pay` event |
+| `cancel_invoice` | Fire the `cancel` event |
+
+The agent cannot fire an event that doesn't exist in the lifecycle. Invalid transitions return `{ success: false }` — the machine refuses, not the LLM.
+
+---
+
+## Admin UI
+
+The engine mounts an admin interface at `/fosm/admin` (access controlled by `config.admin_authorize`):
+
+- **Dashboard** — all FOSM apps with state distribution
+- **App detail** — lifecycle definition table, state distribution chart, stuck record detection
+- **Agent explorer** (`/fosm/admin/apps/:slug/agent`) — the auto-generated tool catalog for the app's AI agent, a direct tool tester (no LLM required), and the system prompt injected into agents
+- **Agent chat** (`/fosm/admin/apps/:slug/agent/chat`) — live multi-turn chat with the agent; see tool calls, thoughts, and state changes in real time
+- **Transition log** — complete audit trail, filterable by app / event / actor (human vs AI agent)
+- **Webhooks** — configure HTTP callbacks for any FOSM event (with HMAC-SHA256 signing)
+- **Settings** — LLM provider key status, engine configuration overview
+
+---
+
+## Webhooks
+
+Configure via the admin UI at `/fosm/admin/webhooks` or programmatically:
+
+```ruby
+Fosm::WebhookSubscription.create!(
+  model_class_name: "Fosm::Invoice",
+  event_name: "send_invoice",
+  url: "https://your-app.com/webhooks/fosm",
+  secret_token: "your_signing_secret",
+  active: true
+)
+```
+
+FOSM POSTs a JSON payload to your URL with headers:
+- `X-FOSM-Event`: the event name
+- `X-FOSM-Record-Type`: the model class name
+- `X-FOSM-Signature`: `sha256=HMAC-SHA256(secret_token, payload)` (if secret token set)
+
+---
+
+## Transition log
+
+Every state change is written to `fosm_transition_logs` — an immutable, append-only table. Records cannot be updated or deleted.
+
+```ruby
+Fosm::TransitionLog.for_record("Fosm::Invoice", 42).recent
+# => [{ event: "send_invoice", from: "draft", to: "sent", actor: "user@example.com", at: "..." }]
+
+Fosm::TransitionLog.for_app(Fosm::Invoice).by_event("pay").count
+# => 17
+```
+
+---
+
+## Architecture
+
+```
+your_rails_app/
+  app/
+    models/fosm/          ← Your FOSM models (generated)
+      invoice.rb
+    controllers/fosm/     ← Your FOSM controllers (generated)
+      invoice_controller.rb
+    views/fosm/           ← Your FOSM views (generated, customizable)
+      invoice/
+    agents/fosm/          ← Your Gemlings AI agents (generated)
+      invoice_agent.rb
+  config/
+    routes/fosm.rb        ← Route registration (auto-updated by generator)
+    initializers/fosm.rb  ← Engine configuration
+
+# Engine provides (from gem):
+  app/models/fosm/
+    transition_log.rb     ← Shared audit trail
+    webhook_subscription.rb
+  app/controllers/fosm/admin/
+    dashboard_controller.rb
+    ...
+  lib/fosm/
+    lifecycle.rb          ← The DSL concern
+    agent.rb              ← Gemlings base agent
+    engine.rb
+```
+
+---
+
+## Requirements
+
+- Ruby >= 3.1
+- Rails >= 8.1
+- Any SQL database supported by Rails (SQLite, PostgreSQL, MySQL)
+- `ANTHROPIC_API_KEY` (or another provider key) to use the AI agent chat — see `/fosm/admin/settings` for status
+
+`gemlings` is bundled automatically as a required dependency. No separate configuration needed unless you want to choose a different LLM provider.
+
+---
+
+## Contributing
+
+FOSM is open source and welcomes contributions. See [AGENTS.md](AGENTS.md) for a deep explanation of the design philosophy and how to extend the engine thoughtfully.
+
+## License
+
+FSL-1.1-Apache-2.0 — Copyright 2026 [Abhishek Parolkar](https://parolkar.com) and INLOOP.STUDIO PTE LTD. See [LICENSE](LICENSE) for details.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"

data/app/assets/stylesheets/fosm/rails/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

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

@@ -0,0 +1,242 @@
+module Fosm
+  module Admin
+    class AgentsController < BaseController
+      before_action :load_app
+
+      def show
+        @tools = derive_tool_definitions
+        @system_prompt = derive_system_prompt
+        @agent_class = begin
+          "Fosm::#{@model_class.name.demodulize}Agent".constantize
+        rescue NameError
+          nil
+        end
+      end
+
+      # ── Chat ──────────────────────────────────────────────────────────────────
+
+      def chat
+        @history = chat_history
+      end
+
+      def chat_send
+        message = params[:message].to_s.strip
+        return render json: { error: "Message cannot be blank" }, status: :bad_request if message.blank?
+
+        agent = fetch_or_build_agent
+
+        # reset: true starts fresh each turn (avoids trailing-whitespace issues with
+        # multi-turn context). Visual history is maintained in the session.
+        result = agent.run(message, reset: true, return_full_result: true)
+
+        # Persist agent instance so next message continues the same conversation
+        store_agent(agent)
+
+        steps = Array(result.steps).map { |s|
+          h = s.to_h
+          # Ensure tool_calls are plain hashes for JSON serialization
+          if h[:tool_calls]
+            h[:tool_calls] = h[:tool_calls].map { |tc|
+              { name: tc.function.name, args: tc.function.arguments }
+            } rescue h[:tool_calls].map(&:to_s)
+          end
+          h
+        }
+
+        output = result.output.to_s
+
+        # Store chat history in Rails.cache (not session cookie) to avoid
+        # ActionDispatch::Cookies::CookieOverflow — agent responses can be large.
+        history = chat_history
+        history << { role: "user",  content: message }
+        history << { role: "agent", content: output, timing: result.timing.round(2) }
+        save_chat_history(history.last(10))
+
+        render json: { output: output, steps: steps,
+                       token_usage: result.token_usage.to_h,
+                       timing: result.timing.round(2) }
+      rescue => e
+        render json: { error: "#{e.class}: #{e.message}" }, status: :unprocessable_entity
+      end
+
+      def chat_reset
+        ::Rails.cache.delete(chat_history_key)
+        ::Rails.cache.delete(agent_cache_key)
+        render json: { ok: true }
+      end
+
+      def agent_invoke
+        tool   = params[:tool].to_s
+        id     = params[:record_id].presence
+        filter = params[:filter].presence
+
+        result = invoke_tool(tool, id, filter)
+        render json: result
+      rescue => e
+        render json: { error: e.message }, status: :unprocessable_entity
+      end
+
+      private
+
+      def load_app
+        @slug = params[:slug]
+        @model_class = Fosm::Registry.find(@slug)
+        render plain: "FOSM app '#{@slug}' not found", status: :not_found unless @model_class
+        @lifecycle = @model_class.fosm_lifecycle
+        @mn = @model_class.name.demodulize.underscore
+      end
+
+      # Derives tool metadata from the lifecycle — no Gemlings required.
+      def derive_tool_definitions
+        plural = @mn.pluralize
+        tools = [
+          {
+            name: "list_#{plural}",
+            description: "List #{plural} with their current state. Pass state= to filter.",
+            params: { state: "Optional: filter by state name (e.g. 'draft')" },
+            requires_id: false,
+            category: :read
+          },
+          {
+            name: "get_#{@mn}",
+            description: "Get a #{@mn} by ID with current state and available events.",
+            params: { id: "Record ID" },
+            requires_id: true,
+            category: :read
+          },
+          {
+            name: "available_events_for_#{@mn}",
+            description: "Check which lifecycle events can fire from the current state. Always call before firing.",
+            params: { id: "Record ID" },
+            requires_id: true,
+            category: :read
+          },
+          {
+            name: "transition_history_for_#{@mn}",
+            description: "Full immutable audit trail of every state transition for this record.",
+            params: { id: "Record ID" },
+            requires_id: true,
+            category: :read
+          }
+        ]
+
+        @lifecycle.events.each do |event|
+          guard_note = event.guards.any? ? " Guards: #{event.guards.map(&:name).join(', ')}." : ""
+          side_note  = event.side_effects.any? ? " Side-effects: #{event.side_effects.map(&:name).join(', ')}." : ""
+          tools << {
+            name: "#{event.name}_#{@mn}",
+            description: "Fire '#{event.name}'. Valid from [#{event.from_states.join(' | ')}] → #{event.to_state}.#{guard_note}#{side_note}",
+            params: { id: "Record ID" },
+            requires_id: true,
+            event: event.name,
+            category: :mutate
+          }
+        end
+
+        tools
+      end
+
+      def derive_system_prompt
+        state_names    = @lifecycle.state_names.join(", ")
+        terminal       = @lifecycle.states.select(&:terminal?).map(&:name).join(", ")
+        event_names    = @lifecycle.event_names.join(", ")
+
+        <<~PROMPT.strip
+          You are a FOSM AI agent managing #{@model_class.name.demodulize.pluralize.humanize}.
+
+          ARCHITECTURE CONSTRAINTS:
+          1. State changes happen ONLY via lifecycle event tools. Never use direct updates.
+          2. Valid states: #{state_names}
+          3. Terminal states (irreversible): #{terminal.presence || "none"}
+          4. Available lifecycle events: #{event_names}
+          5. ALWAYS call available_events_for_#{@mn}(id:) before firing any event.
+          6. If a tool returns { success: false }, DO NOT retry — report the error.
+          7. Records in a terminal state cannot transition further — accept this.
+        PROMPT
+      end
+
+      def invoke_tool(tool, id, filter)
+        plural = @mn.pluralize
+        klass  = @model_class
+
+        case tool
+        when "list_#{plural}"
+          records = filter.present? ? klass.where(state: filter) : klass.order(created_at: :desc).limit(20)
+          { result: records.map { |r| safe_attrs(r) } }
+
+        when "get_#{@mn}"
+          record = klass.find(id)
+          { result: safe_attrs(record).merge(available_events: record.available_events) }
+
+        when "available_events_for_#{@mn}"
+          record = klass.find(id)
+          { result: { id: record.id, current_state: record.state, available_events: record.available_events } }
+
+        when "transition_history_for_#{@mn}"
+          logs = Fosm::TransitionLog.for_record(klass.name, id).recent
+          { result: logs.map { |t|
+            { event: t.event_name, from: t.from_state, to: t.to_state,
+              actor: t.actor_label || t.actor_type, at: t.created_at.iso8601 }
+          } }
+
+        else
+          # fire event: tool name pattern is "event_name_#{mn}"
+          event_name = tool.delete_suffix("_#{@mn}").to_sym
+          record = klass.find(id)
+          record.fire!(event_name, actor: :agent)
+          { result: { success: true, id: record.id, new_state: record.reload.state } }
+        end
+      rescue ActiveRecord::RecordNotFound
+        { error: "Record ##{id} not found" }
+      rescue Fosm::Error => e
+        { error: e.message, success: false }
+      end
+
+      def agent_cache_key
+        "fosm_agent_#{session.id}_#{@slug}"
+      end
+
+      def chat_history_key
+        "fosm_chat_#{session.id}_#{@slug}"
+      end
+
+      def chat_history
+        ::Rails.cache.read(chat_history_key) || []
+      end
+
+      def save_chat_history(history)
+        ::Rails.cache.write(chat_history_key, history, expires_in: 4.hours)
+      end
+
+      def fetch_or_build_agent
+        ::Rails.cache.read(agent_cache_key) || build_fosm_agent
+      end
+
+      def store_agent(agent)
+        ::Rails.cache.write(agent_cache_key, agent, expires_in: 2.hours)
+      rescue
+        # Marshal serialization may fail for complex objects — that's OK,
+        # next message will start a fresh agent with no prior memory
+      end
+
+      def build_fosm_agent
+        klass = begin
+          "Fosm::#{@model_class.name.demodulize}Agent".constantize
+        rescue NameError
+          # Build an ad-hoc anonymous agent class for this model
+          anon = Class.new(Fosm::Agent)
+          anon.model_class(@model_class)
+          anon
+        end
+        klass.build_agent
+      end
+
+      def safe_attrs(record)
+        record.attributes.except("created_by_id").tap do |h|
+          h["created_at"] = h["created_at"]&.iso8601
+          h["updated_at"] = h["updated_at"]&.iso8601
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+module Fosm
+  module Admin
+    class AppsController < BaseController
+      def index
+        redirect_to fosm.admin_root_path
+      end
+
+      def show
+        @slug = params[:slug]
+        @model_class = Fosm::Registry.find(@slug)
+        return render plain: "FOSM app '#{@slug}' not found", status: :not_found unless @model_class
+
+        @lifecycle = @model_class.fosm_lifecycle
+        @diagram_data = @lifecycle.to_diagram_data
+
+        @state_counts = @lifecycle.state_names.index_with { |s| @model_class.where(state: s).count }
+        @recent_transitions = Fosm::TransitionLog.for_app(@model_class).recent.limit(20)
+        @total = @model_class.count
+
+        # Stuck records: in a non-terminal state, no transition in 7 days
+        non_terminal_states = @lifecycle.states.reject(&:terminal?).map { |s| s.name.to_s }
+        # Load record_ids as array and cast to match the model's PK type (record_id
+        # is stored as varchar in transition_logs but the model PK may be bigint).
+        pk_type = @model_class.columns_hash[@model_class.primary_key]&.sql_type_metadata&.type
+        stuck_ids = Fosm::TransitionLog.for_app(@model_class)
+                                        .where("created_at < ?", 7.days.ago)
+                                        .distinct
+                                        .pluck(:record_id)
+        stuck_ids = stuck_ids.map(&:to_i) if pk_type == :integer
+        @stuck_count = @model_class.where(state: non_terminal_states).where.not(id: stuck_ids).count
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+module Fosm
+  module Admin
+    class BaseController < Fosm::ApplicationController
+      layout -> { Fosm.config.admin_layout }
+
+      before_action :fosm_authorize_admin
+
+      private
+
+      def fosm_authorize_admin
+        instance_exec(&Fosm.config.admin_authorize)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module Fosm
+  module Admin
+    class DashboardController < BaseController
+      def index
+        @apps = Fosm::Registry.all.map do |slug, model_class|
+          lifecycle = model_class.fosm_lifecycle
+          state_counts = lifecycle.state_names.index_with { |state_name|
+            model_class.where(state: state_name).count
+          }
+          {
+            slug: slug,
+            model_class: model_class,
+            name: model_class.name.demodulize.humanize,
+            state_counts: state_counts,
+            total: model_class.count,
+            recent_transitions: Fosm::TransitionLog.for_app(model_class).recent.limit(3)
+          }
+        end
+
+        @total_transitions = Fosm::TransitionLog.count
+        @recent_transitions = Fosm::TransitionLog.recent.limit(10)
+      end
+    end
+  end
+end