solid_loop 0.0.4

data/app/models/solid_loop/base.rb

@@ -0,0 +1,190 @@
+module SolidLoop
+  class Base
+    class << self
+      attr_accessor :llm_provider
+    end
+
+    attr_reader :loop_record, :subject
+
+    def initialize(loop_record)
+      @loop_record = loop_record
+      @subject = loop_record.subject
+    end
+
+    def self.create!(subject:, message:, system_prompt: nil, **state)
+      loop_record = SolidLoop::Loop.create!(
+        subject: subject,
+        agent_class_name: name,
+        state: state
+      )
+
+      agent_instance = new(loop_record)
+
+      system_prompt_content = system_prompt || begin
+        agent_instance.system_prompt
+      rescue NotImplementedError
+        nil
+      end
+
+      if system_prompt_content.present?
+        loop_record.messages.create!(role: "system", content: system_prompt_content)
+      end
+
+      loop_record.messages.create!(role: "user", content: message)
+
+      loop_record
+    end
+
+    def self.start!(subject:, message:, system_prompt: nil, **state)
+      loop_record = create!(subject: subject, message: message, system_prompt: system_prompt, **state)
+
+      # State advancement and dispatch commit atomically (same-database
+      # transactional job backend): no queued loop without its job.
+      loop_record.transaction do
+        loop_record.update!(status: "queued")
+        SolidLoop.enqueue!(LlmCompletionJob, loop_record.id)
+      end
+
+      loop_record
+    end
+
+    def mcps
+      []
+    end
+
+    def configure_llm_middlewares(builder)
+    end
+
+    def configure_tool_middlewares(builder)
+    end
+
+    def refresh_mcp_tools?
+      false
+    end
+
+    def streaming?
+      true # Default backwards compatibility
+    end
+
+    # When false (default), all of a turn's tool calls are enqueued at once and
+    # run in parallel across workers. When true, they run strictly one-at-a-time
+    # in model order (the next call is enqueued only after the previous result
+    # lands), and the execution-boundary guard rejects out-of-order jobs.
+    #
+    # HITL / per-tool approval gating is cleanest with `true`: a single in-flight
+    # tool at a time means an approval decision has one unambiguous step to gate.
+    def sequential_tool_calls?
+      false
+    end
+
+    def llm_adapter_name
+      :native
+    end
+
+    def llm_dialect_name
+      :open_ai
+    end
+
+    def reasoning_strategies
+      # Default to the most robust method for returning thoughts: XML wrapping
+      [ :xml ]
+    end
+
+    def mcp_principal
+      subject
+    end
+
+    def max_tokens
+      16 * 1024 # Default
+    end
+
+    def max_steps
+      100
+    end
+
+    def max_total_tokens
+      1_000_000
+    end
+
+    def max_cost
+      10.0
+    end
+
+    def max_duration
+      2.hours
+    end
+
+    def system_prompt
+      raise NotImplementedError, "You must implement #system_prompt in #{self.class.name}"
+    end
+
+    def on_message_created(message)
+      # Hook called whenever a new message is created in the loop.
+    end
+
+    def on_mcp_session_initialized(mcp_session)
+      # Hook called when an MCP session is established for the agent.
+    end
+
+    def pause!
+      # Cleanup 6 — pausing synchronously fails+hides any orphaned `processing`
+      # assistant shell (born-hidden shell protocol) inside the same transition
+      # txn, so no paused loop retains a hidden `processing` shell. The block runs
+      # under the loop lock.
+      loop_record.transition_status(
+        from: SolidLoop::Loop::ACTIVE_STATUSES,
+        to: :paused,
+        execution_token: nil,
+        lease_expires_at: nil
+      ) do
+        loop_record.messages.where(role: "assistant", status: "processing").find_each do |shell|
+          shell.update!(status: "failed", is_hidden: true)
+        end
+      end
+    end
+
+    def resume!
+      # State advancement and dispatch commit atomically inside the lock's
+      # transaction (same-database transactional job backend): a crash leaves
+      # neither a running loop without jobs nor jobs for a rolled-back resume.
+      loop_record.with_lock do
+        raise StandardError, "Unfreeze in admin UI before resuming this loop" if loop_record.admin_frozen?
+        return false unless loop_record.init? || loop_record.paused? || loop_record.failed? || loop_record.completed?
+
+        pending_tool_calls = loop_record.unresolved_tool_calls.to_a
+        if pending_tool_calls.any?
+          token = SecureRandom.uuid
+          # Tool phase: running with a token but NO LLM lease (lease NULL marks
+          # "not an in-flight LLM turn"; the reaper's case 3 guard leaves a
+          # tool-phase loop with unresolved calls untouched — the per-tool lease
+          # reclaim owns that path).
+          loop_record.update!(status: :running, error_message: nil, execution_token: token, lease_expires_at: nil)
+          # Revoke any per-tool lease left by the paused/failed generation. The
+          # fresh generation owns these calls now; without this a stale (but not
+          # yet time-expired) lease from the previous worker would make the
+          # re-enqueued job's claim CAS no-op, stranding the resumed tool. Only
+          # UNEXECUTED calls carry a live-ish lease worth clearing; executed ones
+          # already NULL it at their checkpoint. (Finding 9: resume uses a fresh
+          # generation + the stable key; the old worker's late write is already
+          # fenced out by the rotated execution_token.)
+          SolidLoop::ToolCall
+            .where(id: pending_tool_calls.map(&:id), executed_at: nil)
+            .update_all(lease_token: nil, leased_until: nil, updated_at: Time.current)
+          # Mirror the emission policy: sequential agents re-enter one call at a
+          # time (ResponseCreation chains the rest); parallel agents re-enter
+          # every unresolved call so a multi-call turn cannot stall on resume.
+          calls = sequential_tool_calls? ? pending_tool_calls.first(1) : pending_tool_calls
+          calls.each { |tool_call| SolidLoop.enqueue!(ToolExecutionJob, tool_call.id, token) }
+        else
+          # Cleanup 4 — the no-unresolved-tools branch re-queues an LLM turn; the
+          # non-`running` target (queued) must NULL lease_expires_at so the DB
+          # CHECK holds and the reaper doesn't treat it as an in-flight LLM turn.
+          loop_record.update!(status: :queued, error_message: nil, execution_token: nil, lease_expires_at: nil)
+          SolidLoop.enqueue!(LlmCompletionJob, loop_record.id)
+        end
+      end
+
+      true
+    end
+  end
+end

data/app/models/solid_loop/event.rb

@@ -0,0 +1,7 @@
+module SolidLoop
+  class Event < ApplicationRecord
+    # Optional: inbound MCP events (Mcp::Server) have no loop.
+    belongs_to :loop, class_name: "SolidLoop::Loop", inverse_of: :events, optional: true
+    belongs_to :eventable, polymorphic: true
+  end
+end

data/app/models/solid_loop/loop.rb

@@ -0,0 +1,225 @@
+module SolidLoop
+  class Loop < ApplicationRecord
+    belongs_to :subject, polymorphic: true, optional: true
+    has_many :messages, class_name: "SolidLoop::Message", foreign_key: :loop_id, dependent: :destroy, inverse_of: :loop
+    has_many :tool_calls, through: :messages, class_name: "SolidLoop::ToolCall"
+    has_many :events, class_name: "SolidLoop::Event", foreign_key: :loop_id, dependent: :destroy, inverse_of: :loop
+    has_many :mcp_sessions, class_name: "SolidLoop::McpSession", foreign_key: :loop_id, dependent: :destroy, inverse_of: :loop
+    has_many :mcp_tools, through: :mcp_sessions
+
+    def agent
+      return nil unless agent_class_name.present?
+      agent_class_name.constantize.new(self)
+    end
+
+    enum :status, {
+      init: "init",
+      queued: "queued",
+      running: "running",
+      paused: "paused",
+      completed: "completed",
+      failed: "failed"
+    }, default: :init
+
+    ACTIVE_STATUSES = %w[init queued running].freeze
+    STOPPABLE_STATUSES = (ACTIVE_STATUSES + [ "paused" ]).freeze
+
+    def admin_frozen?
+      frozen_at.present?
+    end
+
+    # CAS on status (and optionally the generation token) under the row lock.
+    # An optional block runs INSIDE the lock, after the checks pass and before
+    # the status write: use it for generation-owned side writes (message
+    # states, counters) so a losing CAS performs zero mutations.
+    def transition_status(from:, to:, expected_execution_token: :any, **attributes)
+      transitioned = false
+
+      with_lock do
+        next unless Array(from).map(&:to_s).include?(status)
+        next if expected_execution_token != :any && execution_token != expected_execution_token
+
+        yield if block_given?
+        update!(**attributes, status: to)
+        transitioned = true
+      end
+
+      transitioned
+    end
+
+    # Fence for generation-owned writes that keep the loop `running`: takes the
+    # row lock, re-validates that the caller's generation still owns the loop,
+    # and only then yields. Returns true when the block ran; on a stale token
+    # (pause/stop/resume has moved the generation on) nothing is written.
+    def with_generation(expected_execution_token)
+      owned = false
+
+      with_lock do
+        next unless running? && execution_token == expected_execution_token
+
+        yield
+        owned = true
+      end
+
+      owned
+    end
+
+    # Unresolved tool calls of the CURRENT conversation tail only. Recovery
+    # must never resurrect an obsolete tool turn, so selection starts from the
+    # newest visible user/assistant message and proceeds only when that tail is
+    # an assistant turn carrying tool calls.
+    #
+    # TODO(backlog): resolution matches tool response messages by the
+    # `tool_call_id` string; a hard FK (+ unique index) from the tool response
+    # Message to its ToolCall row would make this join-able and typo-proof.
+    def unresolved_tool_calls
+      tail = messages
+        .where(is_hidden: false, role: %i[user assistant])
+        .order(id: :desc)
+        .first
+      return SolidLoop::ToolCall.none unless tail&.assistant?
+
+      response_ids = messages
+        .where(role: :tool)
+        .where("id > ?", tail.id)
+        .pluck(:tool_call_id)
+
+      tail.tool_calls.ordered.where.not(tool_call_id: response_ids)
+    end
+
+
+
+    # ---------------------------------------------------------------------------
+    # Steering — enqueue a user message onto a live loop, delivered to the model
+    # at the NEXT turn boundary.
+    #
+    # A steering message is STAGED: `role: user, steering: true, is_hidden: true,
+    # status: pending`. Being hidden keeps it out of the in-flight turn's assembled
+    # conversation (MessageBuilding filters `is_hidden: false`); being `steering`
+    # + `pending` marks it as still-undelivered so the host app can show it as
+    # "pending" and so edit/cancel are allowed. `MessageBuilding#build_messages`
+    # materializes staged messages at the start of each turn (un-hide + mark
+    # `status: success`), which appends them AFTER the last resolved exchange and
+    # makes them immutable history. See `drain_pending_steering!`.
+    #
+    # Positioning: the live conversation orders by `COALESCE(conversation_order,
+    # id)`. An `id` alone is NOT enough — a steering message's `id` is frozen at
+    # ENQUEUE time, so a message enqueued mid-turn (after the assistant's
+    # `tool_calls` row is written but before its `tool` result rows are) sorts
+    # BETWEEN the assistant and its tool results, breaking the assistant/tool
+    # pairing invariant. Instead, delivery (see `drain_pending_steering!`) allocates
+    # a fresh, monotonic `conversation_order` value AT DELIVERY TIME, which sorts
+    # after the whole already-resolved batch. Ordinary messages leave
+    # `conversation_order` NULL and fall back to `id` unchanged.
+    STEERABLE_STATUSES = %w[init queued running paused].freeze
+
+    # Enqueue a free-text user message onto this loop. Returns the created
+    # (staged) Message, or raises if the loop is terminal.
+    def enqueue_user_message(content)
+      with_lock do
+        unless STEERABLE_STATUSES.include?(status)
+          raise SteeringError, "cannot steer a #{status} loop"
+        end
+
+        messages.create!(
+          role: "user",
+          content: content,
+          steering: true,
+          is_hidden: true,
+          status: "pending"
+        )
+      end
+    end
+
+    # Still-pending (staged, not-yet-delivered) steering messages, in enqueue order.
+    def pending_user_messages
+      messages.where(steering: true, status: "pending").order(:id)
+    end
+
+    # Edit a still-pending steering message's content. Rejected (raises) once the
+    # message has been delivered (materialized) or was cancelled. The row lock +
+    # status re-check fences against a concurrent materialize: whoever takes the
+    # lock first wins; a message mid-/post-materialize reads `status != pending`
+    # and the edit is refused.
+    def edit_pending_message(message_id, content)
+      message = messages.find(message_id)
+
+      message.with_lock do
+        unless message.steering? && message.pending?
+          raise SteeringError, "message #{message_id} is no longer pending; cannot edit"
+        end
+
+        message.update!(content: content)
+      end
+
+      message
+    end
+
+    # Cancel (delete) a still-pending steering message so it is never delivered.
+    # Rejected (raises) once delivered. Same fence as edit. Returns true.
+    def cancel_pending_message(message_id)
+      message = messages.find(message_id)
+
+      message.with_lock do
+        unless message.steering? && message.pending?
+          raise SteeringError, "message #{message_id} is no longer pending; cannot cancel"
+        end
+
+        message.destroy!
+      end
+
+      true
+    end
+
+    # Materialize the loop's staged steering messages into the live conversation.
+    # Called at the START of each turn's `build_messages` — a resolved boundary
+    # (the previous turn's tool results are all written; no half-open batch is
+    # created between here and assembly).
+    #
+    # Exactly-once / crash-safety: each message is flipped `pending -> success` and
+    # un-hidden inside its own row lock, guarded by a `pending?` re-check. A retried
+    # turn-build (or a second concurrent build) re-reads the row as `success` and
+    # skips it — never re-materializing. A concurrent edit/cancel either won the
+    # lock first (message stays pending, gets materialized next) or lost it (sees
+    # `success` and is refused): no half-applied state.
+    def drain_pending_steering!
+      # One committed, row-locked transaction. Lock the pending
+      # steering rows FOR UPDATE in ID order and materialize them, then COMMIT —
+      # all before the caller assembles the payload, so assembly reads a settled
+      # conversation. Locking-and-reloading in one query closes the pluck-then-
+      # find gap: a row cancelled/deleted between selection and lock simply is
+      # not returned by the locking SELECT (tolerated). A concurrent edit/cancel
+      # either won its own row lock first (row stays pending → materialized next
+      # turn) or blocks here and then reads `success` and is refused.
+      transaction do
+        pending = pending_user_messages.lock("FOR UPDATE").to_a
+        pending.each do |message|
+          # Re-check under the held lock (defensive; the WHERE already filters).
+          next unless message.steering? && message.pending?
+
+          # Allocate the ordering value HERE, at delivery time — not the frozen
+          # enqueue-time id — so the message sorts after every already-resolved
+          # message written between enqueue and now (e.g. the tool results of a
+          # batch the assistant opened mid-turn).
+          message.update!(is_hidden: false, status: "success", conversation_order: next_conversation_order)
+        end
+      end
+    end
+
+    after_update_commit :broadcast_status_change, if: :saved_change_to_status?
+
+    private
+
+    # A fresh, monotonic ordering value drawn from the table's EXISTING primary-key
+    # id sequence (no custom sequence — schema.rb / db:schema:load must stay clean).
+    # nextval is atomic, monotonic and gap-tolerant; occasionally consuming an id
+    # number is harmless.
+    def next_conversation_order
+      self.class.connection.select_value("SELECT nextval(pg_get_serial_sequence('solid_loop_messages', 'id'))")
+    end
+
+    def broadcast_status_change
+      ActiveSupport::Notifications.instrument("solid_loop.loop_status_changed", loop: self)
+    end
+  end
+end

data/app/models/solid_loop/mcp_inbound_session.rb

@@ -0,0 +1,25 @@
+module SolidLoop
+  # A session issued by Mcp::Server to an external MCP client — the inbound
+  # mirror of McpSession (which is shaped around the loop and does not apply
+  # here). One row per client connection; inbound Events hang off it.
+  # See docs/decisions/mcp-server.md.
+  class McpInboundSession < ApplicationRecord
+    self.table_name = "solid_loop_mcp_inbound_sessions"
+
+    has_many :events, class_name: "SolidLoop::Event", as: :eventable, dependent: :destroy
+
+    validates :server_name, presence: true
+    validates :session_id, presence: true, uniqueness: true
+
+    scope :active, -> { where(terminated_at: nil) }
+
+    # Sessions are bound to the authenticated principal's stable key AND the
+    # mount identity; in-session lookup scopes to both so a different valid
+    # principal cannot ride another caller's session_id. `principal` stays the
+    # human-readable label; `principal_key` is the identity. See Mcp::Server.
+
+    def terminated?
+      terminated_at.present?
+    end
+  end
+end

data/app/models/solid_loop/mcp_session.rb

@@ -0,0 +1,12 @@
+module SolidLoop
+  class McpSession < ApplicationRecord
+    self.table_name = "solid_loop_mcp_sessions"
+
+    belongs_to :loop, class_name: "SolidLoop::Loop", inverse_of: :mcp_sessions
+    has_many :mcp_tools, class_name: "SolidLoop::McpTool", foreign_key: :mcp_session_id, dependent: :destroy, inverse_of: :mcp_session
+    has_many :tool_calls, class_name: "SolidLoop::ToolCall", foreign_key: :mcp_session_id, dependent: :nullify, inverse_of: :mcp_session
+
+    validates :mcp_name, presence: true, uniqueness: { scope: :loop_id }
+    validates :session_id, presence: true
+  end
+end

data/app/models/solid_loop/mcp_tool.rb

@@ -0,0 +1,26 @@
+module SolidLoop
+  class McpTool < ApplicationRecord
+    self.table_name = "solid_loop_mcp_tools"
+
+    belongs_to :mcp_session, class_name: "SolidLoop::McpSession", inverse_of: :mcp_tools
+
+    scope :ordered, -> { order(:mcp_session_id, :id) }
+
+    validates :name, presence: true, uniqueness: { scope: :mcp_session_id }
+
+    def to_tool_spec
+      {
+        type: "function",
+        function: {
+          name: name,
+          description: description,
+          parameters: input_schema
+        }
+      }
+    end
+
+    def call(agent:, arguments:, tool_call: nil)
+      SolidLoop::McpToolExecutionService.new(self, agent, tool_call: tool_call).call(arguments)
+    end
+  end
+end

data/app/models/solid_loop/message.rb

@@ -0,0 +1,69 @@
+module SolidLoop
+  class Message < ApplicationRecord
+    belongs_to :loop, inverse_of: :messages
+    has_many :tool_calls, class_name: "SolidLoop::ToolCall", dependent: :destroy, inverse_of: :message
+    has_many :events, as: :eventable, class_name: "SolidLoop::Event", dependent: :destroy, inverse_of: :eventable
+    enum :status, {
+      pending: "pending",
+      processing: "processing",
+      success: "success",
+      failed: "failed"
+    }, default: :pending
+
+    enum :role, {
+      system: "system",
+      user: "user",
+      assistant: "assistant",
+      tool: "tool"
+    }
+
+    def tps
+      return 0.0 unless tokens_completion.to_i > 0
+
+      # Generation time starts from first token until the end
+      # total_duration is duration_generation
+      actual_gen_time = duration_generation.to_f - ttft.to_f
+
+      return 0.0 if actual_gen_time <= 0
+
+      (tokens_completion.to_f / actual_gen_time).round(2)
+    end
+
+    def cumulative_duration
+      # Sum of generation durations and tool durations for all messages in the loop up to (and including) this one
+      previous_messages = loop.messages.where("created_at <= ?", created_at)
+
+      gen_dur = previous_messages.sum(:duration_generation)
+
+      # Sum tool durations from tool calls associated with these messages
+      tool_dur = SolidLoop::ToolCall.where(message_id: previous_messages.map(&:id)).sum(:duration)
+
+      (gen_dur + tool_dur).round(3)
+    end
+
+    after_create_commit :broadcast_creation
+
+    def trigger_content_append(new_content, new_reasoning = nil, tool_calls_raw = [], ttft: 0.0, duration_thinking: 0.0, duration_generation: 0.0, tokens_completion: 0)
+      update_columns(
+        content: new_content,
+        reasoning_content: new_reasoning,
+        tool_calls_raw: tool_calls_raw,
+        ttft: ttft,
+        duration_thinking: duration_thinking,
+        duration_generation: duration_generation,
+        tokens_completion: tokens_completion
+      )
+      broadcast_update
+    end
+
+    def broadcast_update
+      ActiveSupport::Notifications.instrument("solid_loop.message_updated", message: self)
+    end
+
+    private
+
+    def broadcast_creation
+      ActiveSupport::Notifications.instrument("solid_loop.message_created", message: self)
+    end
+  end
+end

data/app/models/solid_loop/tool_call.rb

@@ -0,0 +1,42 @@
+module SolidLoop
+  class ToolCall < ApplicationRecord
+    belongs_to :message, inverse_of: :tool_calls
+    belongs_to :mcp_session, class_name: "SolidLoop::McpSession", optional: true, inverse_of: :tool_calls
+
+    scope :ordered, -> { order(:id) }
+
+    # Stable per-invocation idempotency key. `executed_at` prevents SolidLoop
+    # from re-invoking a checkpointed tool, but a crash between a remote side
+    # effect and the checkpoint commit can still double-invoke: handlers of
+    # irreversible tools should dedupe on this key (delivered via
+    # `CallContext#idempotency_key` in-process and MCP `_meta` on the wire).
+    def idempotency_key
+      "solid_loop:tool_call:#{id}"
+    end
+
+    # The per-tool_call lease (docs/decisions/durable_attempt_lease.md).
+    # A live lease means THIS worker's `lease_token` is stamped and the lease has
+    # not expired. The canonical completion write re-checks this under the row
+    # lock (alongside the loop's execution_token) so a stale worker whose lease
+    # was revoked by pause/reclaim writes nothing canonical.
+    #
+    # `now` is passed explicitly so a single fenced transaction evaluates expiry
+    # against one consistent clock.
+    def lease_held_by?(token, now: Time.current)
+      token.present? &&
+        lease_token == token &&
+        leased_until.present? &&
+        leased_until > now
+    end
+
+    def response_message
+      message.loop.messages
+        .where(role: :tool, tool_call_id: tool_call_id)
+        .where("id > ?", message_id)
+        .order(:id)
+        .first
+    end
+
+    after_commit { message.broadcast_update }
+  end
+end

data/app/queries/solid_loop/admin/base_query.rb

@@ -0,0 +1,23 @@
+module SolidLoop
+  module Admin
+    class BaseQuery
+      attr_reader :params, :scope
+
+      def initialize(params, scope:)
+        @params = params
+        @scope = scope
+      end
+
+      def call
+        scope
+      end
+
+      private
+
+      def present_param(key)
+        value = params[key]
+        value.is_a?(String) ? value.strip.presence : value.presence
+      end
+    end
+  end
+end

data/app/queries/solid_loop/admin/events_query.rb

@@ -0,0 +1,31 @@
+module SolidLoop
+  module Admin
+    class EventsQuery < BaseQuery
+      def initialize(params, scope: SolidLoop::Event.order(created_at: :desc))
+        super
+      end
+
+      def call
+        filtered = scope
+        filtered = filtered.where(loop_id: loop_id) if loop_id
+        filtered = filtered.where(name: name) if name
+        filtered = filtered.where(eventable_type: eventable_type) if eventable_type
+        filtered
+      end
+
+      private
+
+      def loop_id
+        present_param(:loop_id)
+      end
+
+      def name
+        present_param(:name)
+      end
+
+      def eventable_type
+        present_param(:eventable_type)
+      end
+    end
+  end
+end