solid_loop 0.0.4

data/app/views/solid_loop/tool_calls/show.html.erb

@@ -0,0 +1,59 @@
+<div class="sl-page-header">
+  <div>
+    <h1 class="sl-page-header__title">Tool Call #<%= @tool_call.id %></h1>
+    <p class="sl-page-header__meta">Loop #<%= @tool_call.message&.loop_id %> | Function: <strong><%= @tool_call.function_name %></strong></p>
+  </div>
+  <div class="sl-page-header__actions">
+    <%= link_to "Back to Loop", loop_path(@tool_call.message.loop_id), class: "sl-btn" if @tool_call.message&.loop_id %>
+    <% if @tool_call.mcp_session_id %>
+      <%= link_to "Replay in Inspector", inspector_mcp_session_path(@tool_call.mcp_session_id, replay_tool_call_id: @tool_call.id), class: "sl-btn sl-btn--primary" %>
+    <% end %>
+  </div>
+</div>
+
+<div class="sl-layout-split">
+  <div class="sl-layout-split__main">
+    <div class="sl-card">
+      <h3>Arguments</h3>
+      <div class="sl-json sl-mt-10"><%= JSON.pretty_generate(@tool_call.arguments || {}) rescue @tool_call.arguments %></div>
+    </div>
+
+    <div class="sl-card">
+      <h3>Result</h3>
+      <div class="sl-json sl-mt-10 <%= 'sl-pre-wrap' if @tool_call.result&.include?("\n") %>"><%= @tool_call.result %></div>
+    </div>
+
+    <% if @tool_call.error_message.present? %>
+      <div class="sl-card" style="border-left: 4px solid var(--sl-error);">
+        <h3 style="color: var(--sl-error);">Error Message</h3>
+        <div class="sl-json sl-mt-10" style="color: var(--sl-error);"><%= @tool_call.error_message %></div>
+      </div>
+    <% end %>
+  </div>
+
+  <div class="sl-layout-split__sidebar">
+    <div class="sl-card">
+      <h3>Metadata</h3>
+      <div class="sl-mt-10">
+        <div class="sl-message__footer-item">
+          Status: <span class="sl-badge sl-badge--<%= @tool_call.error_message.present? ? 'error' : 'success' %>"><%= @tool_call.error_message.present? ? 'FAILED' : 'SUCCESS' %></span>
+        </div>
+        <div class="sl-message__footer-item">
+          Duration: <span class="sl-message__footer-value"><%= number_with_precision(@tool_call.duration, precision: 3) %>s</span>
+        </div>
+        <div class="sl-message__footer-item">
+          Created: <span class="sl-message__footer-value"><%= @tool_call.created_at.strftime("%Y-%m-%d %H:%M:%S") %></span>
+        </div>
+      </div>
+    </div>
+
+    <div class="sl-card">
+      <h3>Relations</h3>
+      <div class="sl-mt-10" style="display: flex; flex-direction: column; gap: 8px;">
+        <%= link_to "Parent Message", message_path(@tool_call.message_id), class: "sl-btn sl-btn--small" if @tool_call.message_id %>
+        <%= link_to "MCP Session", mcp_session_path(@tool_call.mcp_session_id), class: "sl-btn sl-btn--small" if @tool_call.mcp_session_id %>
+        <%= link_to "Loop Details", loop_path(@tool_call.message.loop_id), class: "sl-btn sl-btn--small" if @tool_call.message&.loop_id %>
+      </div>
+    </div>
+  </div>
+</div>

data/config/routes.rb

@@ -0,0 +1,27 @@
+SolidLoop::Engine.routes.draw do
+  root to: "dashboard#index", as: :dashboard
+
+  get "dashboard", to: "dashboard#index"
+  get "dashboard/stats", to: "dashboard#stats", as: :dashboard_stats
+
+  resources :loops, only: %i[index show] do
+    member do
+      patch :observe
+      patch :freeze
+      patch :unfreeze
+      patch :force_stop
+    end
+  end
+
+  resources :messages, only: %i[index show]
+  resources :tool_calls, only: %i[index show]
+  resources :mcp_sessions, only: %i[index show] do
+    member do
+      get :inspector
+      post :run_tool
+    end
+  end
+  resources :mcp_tools, only: %i[index show]
+  resources :mcp_inbound_sessions, only: %i[index show]
+  resources :events, only: %i[index show]
+end

data/db/migrate/20260408000100_solid_loop_init.rb

@@ -0,0 +1,136 @@
+class SolidLoopInit < ActiveRecord::Migration[7.1]
+  def change
+    create_table :solid_loop_loops do |t|
+      t.references :subject, polymorphic: true
+
+      t.string :title
+      t.string :agent_class_name
+      t.string :status, default: "init", null: false
+      t.boolean :observe_enabled, default: false, null: false
+      t.datetime :frozen_at
+
+      t.jsonb :state, default: {}, null: false
+      t.jsonb :metadata, default: {}, null: false
+
+      t.integer :step_count, default: 0, null: false
+      t.integer :tokens_prompt, default: 0, null: false
+      t.integer :tokens_completion, default: 0, null: false
+      t.integer :tokens_total, default: 0, null: false
+      t.integer :tokens_prompt_cached, default: 0, null: false
+
+      t.float :duration_parsing, default: 0.0, null: false
+      t.float :duration_generation, default: 0.0, null: false
+      t.float :duration_tools, default: 0.0, null: false
+      t.float :duration_total, default: 0.0, null: false
+
+      t.decimal :cost, precision: 15, scale: 10, default: 0.0, null: false
+
+      t.text :error_message
+
+      t.timestamps
+    end
+    add_index :solid_loop_loops, :status
+
+    create_table :solid_loop_mcp_sessions do |t|
+      t.references :loop, null: false, foreign_key: { to_table: :solid_loop_loops }
+
+      t.string :mcp_name, null: false
+      t.string :session_id, null: false
+      t.string :transport_kind, default: "http", null: false
+
+      t.jsonb :metadata, default: {}, null: false
+
+      t.timestamps
+    end
+    add_index :solid_loop_mcp_sessions, [ :loop_id, :mcp_name ], unique: true
+
+    create_table :solid_loop_mcp_tools do |t|
+      t.references :mcp_session, null: false, foreign_key: { to_table: :solid_loop_mcp_sessions }
+
+      t.string :name, null: false
+      t.jsonb :input_schema, default: {}, null: false
+      t.text :description
+
+      t.timestamps
+    end
+    add_index :solid_loop_mcp_tools, [ :mcp_session_id, :name ], unique: true
+
+    create_table :solid_loop_messages do |t|
+      t.references :loop, null: false, foreign_key: { to_table: :solid_loop_loops }
+
+      t.string :role, null: false
+      t.string :status, null: false
+      t.string :tool_call_id
+
+      t.jsonb :tool_calls_raw, default: [], null: false
+      t.jsonb :metadata, default: {}, null: false
+
+      t.integer :tokens_prompt, default: 0, null: false
+      t.integer :tokens_completion, default: 0, null: false
+      t.integer :tokens_total, default: 0, null: false
+      t.integer :tokens_prompt_cached, default: 0, null: false
+
+      t.float :tps, default: 0.0, null: false
+      t.float :ttft, default: 0.0, null: false
+      t.float :duration_thinking, default: 0.0, null: false
+      t.float :duration_generation, default: 0.0, null: false
+
+      t.decimal :cost, precision: 15, scale: 10, default: 0.0, null: false
+
+      t.boolean :is_hidden, default: false, null: false
+
+      t.text :content
+      t.text :reasoning_content
+      t.text :error_message
+
+      t.timestamps
+    end
+    add_index :solid_loop_messages, :tool_call_id
+    add_index :solid_loop_messages, :role
+    add_index :solid_loop_messages, [ :loop_id, :is_hidden ]
+
+    create_table :solid_loop_tool_calls do |t|
+      t.references :message, null: false, foreign_key: { to_table: :solid_loop_messages }
+      t.references :mcp_session, foreign_key: { to_table: :solid_loop_mcp_sessions }
+
+      t.string :tool_call_id, null: false
+      t.string :function_name, null: false
+
+      t.jsonb :arguments, default: {}, null: false
+      t.jsonb :metadata, default: {}, null: false
+
+      t.float :duration, default: 0.0, null: false
+      t.boolean :is_success
+
+      t.text :result
+      t.text :error_message
+
+      t.timestamps
+    end
+    add_index :solid_loop_tool_calls, [ :message_id, :tool_call_id ], unique: true
+    add_index :solid_loop_tool_calls, :metadata, using: :gin, opclass: :jsonb_path_ops
+
+    create_table :solid_loop_events do |t|
+      t.references :eventable, polymorphic: true, null: false
+      t.references :loop
+      t.references :message
+
+      t.string :name, null: false
+      t.string :http_method, null: false
+      t.string :tool_call_id
+      t.string :url
+
+      # Nullable on purpose: a planned wire-log storage change will stop
+      # persisting these payloads inline.
+      t.jsonb :request_data, default: {}
+      t.jsonb :response_data, default: {}
+      t.jsonb :headers, default: {}, null: false
+
+      t.float :duration, default: 0.0, null: false
+      t.text :log
+
+      t.timestamps
+    end
+    add_index :solid_loop_events, :tool_call_id
+  end
+end

data/db/migrate/20260709000100_solid_loop_create_mcp_inbound_sessions.rb

@@ -0,0 +1,16 @@
+class SolidLoopCreateMcpInboundSessions < ActiveRecord::Migration[7.1]
+  def change
+    create_table :solid_loop_mcp_inbound_sessions do |t|
+      t.string :server_name, null: false, index: true
+      t.string :session_id, null: false, index: { unique: true }
+      # Human-readable label of the authorizer's principal, for the admin UI.
+      t.string :principal
+      t.datetime :last_used_at
+      # DELETE terminates the session instead of destroying the row: a client
+      # must not be able to erase its own audit trail (events hang off this row).
+      t.datetime :terminated_at
+
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260713000100_solid_loop_add_execution_guards.rb

@@ -0,0 +1,6 @@
+class SolidLoopAddExecutionGuards < ActiveRecord::Migration[7.1]
+  def change
+    add_column :solid_loop_loops, :execution_token, :string
+    add_column :solid_loop_tool_calls, :executed_at, :datetime
+  end
+end

data/db/migrate/20260714000100_solid_loop_add_message_steering.rb

@@ -0,0 +1,17 @@
+class SolidLoopAddMessageSteering < ActiveRecord::Migration[7.1]
+  def change
+    # Marks a user message that was enqueued as a "steering" instruction onto a
+    # live loop: staged (hidden) and editable/cancellable while `status: pending`,
+    # then materialized into the conversation (un-hidden, `status: success`) at the
+    # next turn boundary. The flag lets the host app surface still-pending steering
+    # messages distinctly from ordinary conversation and from permanently-hidden
+    # rows (e.g. compaction notes).
+    add_column :solid_loop_messages, :steering, :boolean, default: false, null: false
+
+    # Partial index to make "the loop's still-pending steering messages" cheap.
+    add_index :solid_loop_messages,
+      [ :loop_id, :id ],
+      where: "steering AND status = 'pending'",
+      name: "index_solid_loop_messages_on_pending_steering"
+  end
+end

data/db/migrate/20260714000200_solid_loop_add_message_conversation_order.rb

@@ -0,0 +1,14 @@
+class SolidLoopAddMessageConversationOrder < ActiveRecord::Migration[7.1]
+  def change
+    # Explicit conversation position for a message, decoupled from its primary-key
+    # `id`. NULL for ordinary messages (they order by `id` as before); populated
+    # only for DELIVERED steering messages, where `id` (frozen at enqueue time) can
+    # fall between a half-open assistant(tool_calls) batch and its tool results. The
+    # live conversation orders by `COALESCE(conversation_order, id)`, and delivery
+    # allocates a fresh, monotonic value so a steering message always sorts after
+    # the whole resolved batch. See Loop#drain_pending_steering!.
+    add_column :solid_loop_messages, :conversation_order, :bigint
+
+    add_index :solid_loop_messages, [ :loop_id, :conversation_order ]
+  end
+end

data/db/migrate/20260715000100_solid_loop_add_mcp_inbound_session_principal_key.rb

@@ -0,0 +1,43 @@
+class SolidLoopAddMcpInboundSessionPrincipalKey < ActiveRecord::Migration[7.1]
+  def change
+    # Stable identity of the authenticated principal (NOT the display label in
+    # `principal`): every in-session POST/DELETE is scoped to it so principal B
+    # cannot ride principal A's session_id. Nullable + backfilled to the old
+    # label for rows minted before this column existed (see Mcp::Server).
+    # NOTE: the backfill is best-effort. For a bare-String authorizer the new key
+    # equals the old `#to_s`, so those sessions survive the migration. For an
+    # ActiveRecord-principal authorizer the new key is a GlobalID (stable), which
+    # will NOT match the backfilled `#to_s`, so legacy AR-principal sessions
+    # fail-closed (404) and simply re-initialize. Acceptable: inbound sessions are
+    # short-lived and re-init is transparent. No security exposure either way.
+    add_column :solid_loop_mcp_inbound_sessions, :principal_key, :string
+
+    # Stable per-mount/endpoint identity. `server_name` comes from the toolset
+    # CLASS, so two mounts of the same class shared one namespace; the mount key
+    # (defaults to server_name) separates them. Session lookup scopes to it.
+    add_column :solid_loop_mcp_inbound_sessions, :mount_key, :string
+
+    # Records the acting principal on each inbound event, so an audit row shows
+    # who actually invoked (not just who initialized the session).
+    add_column :solid_loop_events, :principal_key, :string
+
+    reversible do |dir|
+      dir.up do
+        execute <<~SQL.squish
+          UPDATE solid_loop_mcp_inbound_sessions
+          SET principal_key = principal
+          WHERE principal_key IS NULL
+        SQL
+        execute <<~SQL.squish
+          UPDATE solid_loop_mcp_inbound_sessions
+          SET mount_key = server_name
+          WHERE mount_key IS NULL
+        SQL
+      end
+    end
+
+    add_index :solid_loop_mcp_inbound_sessions,
+              [ :mount_key, :session_id ],
+              name: "index_solid_loop_mcp_inbound_sessions_on_mount_and_session"
+  end
+end

data/db/migrate/20260715000200_solid_loop_add_llm_lease.rb

@@ -0,0 +1,40 @@
+class SolidLoopAddLlmLease < ActiveRecord::Migration[7.1]
+  # The LLM lease for the durable lease + reaper design
+  # (docs/decisions/durable_attempt_lease.md). LLM path only; the per-tool_call
+  # lease columns (leased_until / lease_token) are deliberately NOT added here —
+  # a separate migration adds them.
+  def up
+    # Non-NULL iff an LLM HTTP turn is in flight. The reaper reads
+    # (status, lease_expires_at) to find dead turns; NULL means "not in an LLM
+    # turn" (tool phase, or terminal). Nullable so pre-existing terminal loops
+    # correctly sit at NULL.
+    add_column :solid_loop_loops, :lease_expires_at, :datetime
+
+    add_index :solid_loop_loops, [ :status, :lease_expires_at ],
+      name: "index_solid_loop_loops_on_status_and_lease"
+
+    # A `running` loop that carries no execution_token cannot be fenced or
+    # reclaimed correctly (the token IS the LLM lease/generation fence). Heal any
+    # legacy such rows before adding the invariant so the constraint can be added
+    # VALID (single-consumer dev DB — no online rollout; see the ADR).
+    execute(<<~SQL)
+      UPDATE solid_loop_loops
+      SET status = 'failed',
+          error_message = COALESCE(error_message, 'reconciled: running without execution_token at lease migration'),
+          lease_expires_at = NULL
+      WHERE status = 'running' AND execution_token IS NULL
+    SQL
+
+    execute(<<~SQL)
+      ALTER TABLE solid_loop_loops
+      ADD CONSTRAINT running_requires_token
+      CHECK (status <> 'running' OR execution_token IS NOT NULL)
+    SQL
+  end
+
+  def down
+    execute("ALTER TABLE solid_loop_loops DROP CONSTRAINT IF EXISTS running_requires_token")
+    remove_index :solid_loop_loops, name: "index_solid_loop_loops_on_status_and_lease"
+    remove_column :solid_loop_loops, :lease_expires_at
+  end
+end

data/db/migrate/20260715000300_solid_loop_add_tool_lease.rb

@@ -0,0 +1,33 @@
+class SolidLoopAddToolLease < ActiveRecord::Migration[7.1]
+  # The per-tool_call lease for the durable lease + reaper design
+  # (docs/decisions/durable_attempt_lease.md): a SECOND
+  # fence token that lets the reaper reclaim ONE dead parallel tool without
+  # fencing its healthy siblings (parallel tools are the shipped default:
+  # Base#sequential_tool_calls? => false).
+  #
+  # Additive, per the ADR: both columns are nullable. `executed_at` stays the
+  # terminal exactly-once-in-DB checkpoint; the lease is only load-bearing while
+  # a tool call is unresolved (executed_at IS NULL).
+  def up
+    # lease_token  — the per-tool second fence token (a fresh uuid per claim).
+    # leased_until — when the lease expires; a healthy tool's client raises before
+    #                this (duration derived to strictly outlive the tool timeout),
+    #                so a live worker never holds an expired lease.
+    add_column :solid_loop_tool_calls, :lease_token, :string
+    add_column :solid_loop_tool_calls, :leased_until, :datetime
+
+    # The reaper (case 2) scans unresolved tool calls whose lease is expired or
+    # absent. The partial index keeps the scan cheap and excludes terminal
+    # (executed_at set) rows — they are never reclaimed.
+    add_index :solid_loop_tool_calls, :leased_until,
+      where: "executed_at IS NULL",
+      name: "index_solid_loop_tool_calls_on_leased_until_unresolved"
+  end
+
+  def down
+    remove_index :solid_loop_tool_calls,
+      name: "index_solid_loop_tool_calls_on_leased_until_unresolved"
+    remove_column :solid_loop_tool_calls, :leased_until
+    remove_column :solid_loop_tool_calls, :lease_token
+  end
+end

data/db/migrate/20260715000400_solid_loop_add_lease_running_check.rb

@@ -0,0 +1,32 @@
+class SolidLoopAddLeaseRunningCheck < ActiveRecord::Migration[7.1]
+  # The lease-running CHECK (docs/decisions/durable_attempt_lease.md).
+  #
+  # `lease_expires_at` is non-NULL ONLY while an LLM HTTP turn is in flight — i.e.
+  # only while the loop is `running`. Every non-`running` transition (pause, stop,
+  # freeze, fail, complete, requeue, tool phase) is supposed to clear it. This
+  # additive CHECK makes that invariant enforced by construction, so a missed
+  # clear-site becomes a hard failure instead of a silently stuck lease the reaper
+  # re-selects forever.
+  #
+  # Additive per the ADR: heal any offending rows first (single-consumer dev DB —
+  # no online rollout), then add the constraint VALID.
+  def up
+    # Heal: any non-`running` loop still carrying a lease is stale — NULL it. (A
+    # terminal/paused loop is never in an LLM turn, so the lease is meaningless.)
+    execute(<<~SQL)
+      UPDATE solid_loop_loops
+      SET lease_expires_at = NULL
+      WHERE lease_expires_at IS NOT NULL AND status <> 'running'
+    SQL
+
+    execute(<<~SQL)
+      ALTER TABLE solid_loop_loops
+      ADD CONSTRAINT lease_requires_running
+      CHECK (lease_expires_at IS NULL OR status = 'running')
+    SQL
+  end
+
+  def down
+    execute("ALTER TABLE solid_loop_loops DROP CONSTRAINT IF EXISTS lease_requires_running")
+  end
+end

data/db/migrate/20260715000500_solid_loop_add_tool_lease_pair_check.rb

@@ -0,0 +1,35 @@
+class SolidLoopAddToolLeasePairCheck < ActiveRecord::Migration[7.1]
+  # The tool-lease-pair CHECK (docs/decisions/durable_attempt_lease.md).
+  #
+  # `solid_loop_tool_calls.lease_token` and `.leased_until` are the two halves of
+  # ONE per-tool lease, but they were independently nullable. A malformed
+  # unresolved row with `lease_token` SET but `leased_until` NULL is never
+  # reclaimable: the reaper's `lease_token IS NULL OR leased_until < now` predicate
+  # is false (token present) OR NULL (NULL comparison) — never true — so the row
+  # can never be re-claimed, and `lease_held_by?` (requires `leased_until.present?`)
+  # rejects it too. The pair must be atomically both-set or both-NULL.
+  #
+  # Additive per the ADR (single-consumer dev DB — no online rollout): HEAL any
+  # mismatched UNRESOLVED row (clear BOTH halves so the reaper can reclaim it) then
+  # add the invariant VALID. Resolved rows (executed_at set) are left untouched —
+  # the lease is not load-bearing once a call is terminal, and a legacy resolved
+  # row carrying a half-lease is harmless — but the CHECK below still covers them,
+  # so heal any mismatched row regardless to keep the constraint addable.
+  def up
+    execute(<<~SQL)
+      UPDATE solid_loop_tool_calls
+      SET lease_token = NULL, leased_until = NULL
+      WHERE (lease_token IS NULL) <> (leased_until IS NULL)
+    SQL
+
+    execute(<<~SQL)
+      ALTER TABLE solid_loop_tool_calls
+      ADD CONSTRAINT tool_lease_pair_both_or_neither
+      CHECK ((lease_token IS NULL) = (leased_until IS NULL))
+    SQL
+  end
+
+  def down
+    execute("ALTER TABLE solid_loop_tool_calls DROP CONSTRAINT IF EXISTS tool_lease_pair_both_or_neither")
+  end
+end

data/docs/contributing/coverage.md

@@ -0,0 +1,64 @@
+# Contributor Coverage Workflow
+
+Use the coverage rake task to verify changed-line coverage after changing application code.
+
+## Contributor Rule
+
+Uncovered changed lines means the task is not complete. Add tests before closing the task.
+
+## Run Tests First
+
+If `coverage/coverage.json` is missing, run the relevant test suite first.
+
+Common commands from `README.md`:
+
+```bash
+bundle exec rspec
+bundle exec appraisal rails-7-1 rspec
+bundle exec appraisal rails-7-2 rspec
+bundle exec appraisal rails-8-1 rspec
+bundle exec appraisal rspec
+```
+
+For the full local CI flow, use:
+
+```bash
+make ci
+```
+
+`make ci` does the following:
+- removes `coverage/.resultset.json`
+- runs the default RSpec suite with `COVERAGE_NAME=gem`
+- runs the Rails 7.1 appraisal suite with `COVERAGE_NAME=rails-7-1`
+- runs the Rails 7.2 appraisal suite with `COVERAGE_NAME=rails-7-2`
+- runs the Rails 8.1 appraisal suite with `COVERAGE_NAME=rails-8-1`
+- prints the merged coverage summary with `bundle exec rake 'coverage:report[sort]'`
+
+Use `make ci` when you want the closest local approximation of the full gem validation workflow across supported Rails versions.
+
+## Changed-Line Coverage
+
+```bash
+# staged changes only
+rails 'coverage:report[worst,,staged]'
+
+# all branch changes since main
+rails 'coverage:report[worst,,branch]'
+
+# last commit
+rails 'coverage:report[worst,,head]'
+```
+
+## Explore Weak Spots
+
+```bash
+rails 'coverage:report[partial]'
+rails 'coverage:report[partial,service]'
+rails 'coverage:report[worst,controller]'
+rails coverage:report
+```
+
+## Source Of Truth
+
+- Task implementation: `lib/tasks/coverage.rake`
+- Coverage artifact: `coverage/coverage.json`