solid_loop 0.0.4

data/docs/decisions/durable_attempt_lease.md

@@ -0,0 +1,364 @@
+# Durable lease + reaper
+
+Status: accepted design.
+
+This document describes the durable-lease design that makes SolidLoop's LLM turns
+and tool invocations crash/restart-safe: how a worker claims a unit of work, how
+its lease is kept alive while it runs, how a periodic reaper recovers work whose
+worker died, and the guarantees (and their limits) that result.
+
+## Context
+
+- **Breaking DB changes are acceptable.** A consumer can reset its dev DB and
+  hand-fix records, so there is **no online migration, no backfill, no quiesced
+  rollout, no recovery task** — the rollout story is "drop, recreate, reset."
+- Durable, crash/restart-safe resumes are a release requirement: without them,
+  the claim "durable, crash/restart resumes" is false.
+- Bar: **correct + as simple to build and maintain as possible**, not
+  zero-downtime migration of a live fleet.
+
+## What the existing code already provides
+
+- `LlmCompletionJob.perform(loop_id)` **already CAS-claims**:
+  `UPDATE ... SET status=running, execution_token=uuid WHERE status=queued`.
+- `solid_loop_tool_calls.executed_at` is **already the tool checkpoint**;
+  `ToolExecutionJob(tool_call_id, execution_token)` already carries the fence.
+- The stable ToolCall idempotency key already propagates via `CallContext` /
+  MCP `_meta`.
+- The streaming shell is a plain message row (`status: "processing"`,
+  `is_hidden` default false); `MessageBuilding` assembles `where(is_hidden:false)`,
+  so hiding a mid-stream partial needs **zero new message columns**.
+
+## Design
+
+**Schema: 3 new columns, 2 CHECKs, 2 indexes. No new tables or models.**
+
+```sql
+ALTER TABLE solid_loop_loops
+  ADD COLUMN lease_expires_at timestamptz;   -- non-NULL iff an LLM turn is in flight
+ALTER TABLE solid_loop_loops
+  ADD CONSTRAINT running_requires_token
+  CHECK (status <> 'running' OR execution_token IS NOT NULL);
+ALTER TABLE solid_loop_loops
+  ADD CONSTRAINT lease_running_only
+  CHECK (lease_expires_at IS NULL OR status = 'running');
+
+ALTER TABLE solid_loop_tool_calls
+  ADD COLUMN lease_token  varchar,
+  ADD COLUMN leased_until timestamptz;
+ALTER TABLE solid_loop_tool_calls
+  ADD CONSTRAINT tool_lease_pair
+  CHECK ((lease_token IS NULL) = (leased_until IS NULL));
+
+-- messages: NO new columns (status 'processing' + is_hidden = the shell protocol)
+-- indexes: loops(status, lease_expires_at); tool_calls(leased_until) WHERE executed_at IS NULL
+```
+
+### State model
+
+- **Loop** (existing statuses): `queued` = durable LLM work intent; `running` +
+  `lease_expires_at` set = LLM HTTP turn in flight; `running` + `lease_expires_at`
+  NULL = tool phase (the LLM commit clears it when emitting tools).
+  `execution_token` is BOTH the generation fence AND the LLM lease token —
+  rotated at every claim/resume, cleared at pause/stop/reclaim.
+- **ToolCall**: `executed_at IS NULL` = durable intent; live lease = `lease_token`
+  set and `leased_until > now`; `executed_at` set = terminal (the existing CAS
+  `WHERE executed_at IS NULL` stays the exactly-once-in-DB guard). Two tokens
+  exist ONLY because reclaiming one dead parallel tool must not fence healthy
+  siblings — the one place a second token is load-bearing (parallel tools are the
+  shipped default: `Base#sequential_tool_calls? => false`).
+- **Shell message** (born-hidden protocol): created `status:"processing",
+  is_hidden:true`; the ONLY path that flips it visible is the canonical LLM commit
+  txn (which also fence-checks); reclaim/pause/stop/error mark any `processing`
+  shell for the loop `failed` and leave it hidden (partial content kept for
+  admin/audit). `MessageBuilding`'s existing `is_hidden:false` filter already
+  excludes it. Force-stop must not mark partial output `success`.
+
+### Claim
+
+LLM: today's CAS plus `lease_expires_at = now + ttl`. Tool:
+`UPDATE tool_calls SET lease_token=uuid, leased_until=now+ttl
+ WHERE id=? AND executed_at IS NULL AND (lease_token IS NULL OR leased_until < now)`
+after verifying `loop.execution_token` matches the job arg; 0 rows ⇒ no-op.
+
+**The lease is derived PER CLAIM so `lease > client timeout + margin` holds BY
+CONSTRUCTION** for both LLM and tool — a live worker can never hold an expired
+lease *for the duration of a single inactivity window* (its HTTP/tool client
+raises first). LLM: `read_timeout (600s default) + lease_margin`, from the agent's
+own provider. Tool: `max(default_tool_timeout, slowest resolved HTTP MCP client
+timeout) + lease_margin` — the HTTP timeout (`mcp_config[:timeout] || 60`,
+operator-settable well above the default) MUST be folded in, or a *healthy*
+long-running HTTP tool could be reclaimed → duplicate invocation on a live call.
+Residual (documented in `Configuration`): an in-process/custom tool exposes no
+client timeout to derive from, so `default_tool_timeout` is its ceiling; one that
+legitimately runs longer MAY be reclaimed (a duplicate invocation — harmless: the
+both-token fence yields exactly one canonical result and tools carry the stable
+`solid_loop:tool_call:#{id}` idempotency key), so operators must set
+`default_tool_timeout` above their slowest in-process tool.
+
+### Host resume contract — revoke the tool lease before re-enqueue
+
+Any host-side `paused→running` (or `failed→running`) transition that re-enqueues a
+`ToolExecutionJob` for an unexecuted tool_call MUST FIRST revoke that call's live
+per-tool lease (`lease_token`/`leased_until` → NULL), or the re-enqueued job's
+self-claim CAS (the `lease_token IS NULL OR leased_until < now` predicate above)
+matches zero rows and no-ops SILENTLY — the loop then strands until the stale
+lease's TTL expires and the reaper (case 2) repairs it (up to `tool_lease_duration
++ reaper interval`). `SolidLoop::Base#resume!` is the canonical example: it rotates
+a fresh `execution_token` AND `UPDATE tool_calls SET lease_token=NULL,
+leased_until=NULL WHERE id IN (...) AND executed_at IS NULL` in the same locked
+txn BEFORE enqueuing (`app/models/solid_loop/base.rb`, the pending-tool-calls
+branch). Hosts that hand-roll their own resume must mirror BOTH steps.
+Observability: the claim no-op logs a `Rails.logger.warn` (`ToolExecutionJob:
+tool lease claim lost …`) with the tool_call/loop ids and the surviving
+lease_token/leased_until, so the otherwise-invisible strand is diagnosable.
+
+### LLM heartbeat
+
+The claim-time lease derivation above is NOT sufficient on its own for the LLM
+path. `read_timeout` is an **inactivity** timeout (the silence between two
+consecutive socket reads), NOT a bound on total request duration. A healthy model
+can stream for tens of minutes with **every inter-chunk gap** well under
+`read_timeout`, so a static `read_timeout + margin` lease would expire on a LIVE
+worker mid-stream and the reaper (case 1) would reclaim a live turn — a duplicate
+provider call plus a discarded result. Pre-call **MCP session initialization**
+(before the first chunk) is likewise unbounded by `read_timeout`.
+
+So `LeaseHeartbeat` (`lib/solid_loop/lease_heartbeat.rb`) renews
+`lease_expires_at` for the ENTIRE claimed LLM job — MCP init + the whole stream
+(incl. a silent prefill) + finalization — on a DEDICATED pooled DB connection
+through the Rails executor, at ~`ttl/4` cadence. Every renew is a CONDITIONAL
+`UPDATE ... WHERE id=loop_id AND status='running' AND execution_token=<ours>`, so
+it can NEVER renew a lease it no longer owns; a 0-row renew sets a thread-safe
+LOST-LEASE flag. The main path calls `heartbeat.check!` (raising
+`SolidLoop::LostLease`) BEFORE any canonical write/checkpoint (in
+`ResponseParsing`), so a worker whose lease was lost commits nothing; the job
+swallows `LostLease` (recovery belongs to whoever now owns the generation). The
+heartbeat stops in an `ensure` before the canonical completion, joining its thread
+and returning its connection (no pool leak, no thread left running in tests).
+Correctness still ultimately rests on the commit-time fence check under the row
+lock; the heartbeat's job is only to keep a HEALTHY turn from being falsely
+reclaimed. The tool path keeps the static per-claim lease (a tool invocation is a
+single bounded client call, so its lease derivation IS sufficient — no tool
+heartbeat).
+
+### The process-wide lease renewer
+
+The heartbeat is a thin registration handle over a SINGLE process-wide
+`SolidLoop::LeaseRenewer` (`lib/solid_loop/lease_renewer.rb`), not one thread per
+turn. Each in-flight `LlmCompletionJob` registers its
+`(loop_id, execution_token, lease_duration, max_duration)` on start and
+deregisters when the turn ends; the renewer renews ALL registered leases from ONE
+long-lived connection checked out once, so renewal is **O(1) in connections, not
+O(concurrency)**. A per-turn renewer thread each checking out its own connection
+per tick would livelock at full worker-pool occupancy (pool == concurrency, the
+standard shape): all N connections held by busy workers, so every heartbeat blocks
+in `with_connection`, treats `checkout_timeout` as a lost lease, yields its turn
+uncommitted, and the reaper requeues into the same saturated pool. The single
+renewer avoids this entirely. Deployment requirement: size the DB pool as
+`worker_concurrency + 1` (documented in the README).
+
+`LeaseHeartbeat` keeps the public surface (`run`/`start`/`stop`/`lost?`/`check!`)
+and the ownership contract (conditional renew keyed on loop+token,
+`lease_expires_at IS NOT NULL` guard, per-registration lost flag,
+stop-before-commit). The renewer is created via a class-level constant mutex
+(`LeaseRenewer::MUTEX`) wrapping BOTH `@instance ||= new` and the reset-to-nil
+swap, so concurrent first-turns can't each construct a distinct renewer (which
+would each start a thread contending for the one process-lifetime connection —
+a livelock). The blocking `stop!` (thread join) runs OUTSIDE the lock so a
+concurrent `instance` never waits on a join.
+
+**Leak ceiling.** Leak safety does not depend on the job's `ensure` ever running.
+A registration that never deregisters (a job that skipped its `ensure`) would
+otherwise be renewed forever, so the reaper's case-1 reclaim could never fire.
+Each registration carries a hard ceiling tied to the **owning agent's own legal
+turn bound** — `max_duration + config.lease_leak_grace` (default `2h + 5min`).
+A turn longer than `max_duration` is illegitimate by the agent's own contract, so
+a legitimate turn always finishes before the ceiling (never dropped), while a
+genuine leak self-expires shortly after `max_duration` → its lease lapses → the
+reaper reclaims it. `max_duration` is registered alongside the other fields (the
+`LlmCompletionJob` already resolves the agent; a fallback
+`config.default_max_duration` covers out-of-band callers). A ceiling tied to
+`lease_duration × K` instead would be wrong: a healthy turn stays registered for
+its whole life, so any legitimate stream longer than K lease-widths (e.g. a small
+`read_timeout` with steady chunks, 30 min vs a ~20-min K=20 ceiling) would be
+dropped → its lease would lapse → the reaper would reclaim a live turn → the
+replacement would hit the same ceiling → no long turn could ever complete.
+
+The renewer intentionally runs for the whole process lifetime; its single
+connection is released at process exit (no shutdown hook needed — nothing to
+drain between turns). Each registration's `lost` flag is a
+`Concurrent::AtomicBoolean` so the renewer-thread write and main-path read carry a
+memory barrier on every Ruby engine, not only MRI+GVL.
+
+### Reclaim
+
+One idempotent `SolidLoop.reap!` service on a host-installed recurrence (30–60s).
+Each case is a short row-locked txn that re-checks expiry under lock (two racing
+reapers ⇒ one wins):
+
+1. `running`, `lease_expires_at < now` → dead LLM turn: fail+hide the processing
+   shell, rotate the token away, loop → `queued`, re-enqueue
+   `LlmCompletionJob(loop_id)`. If the loop is paused/terminal/frozen, just clean
+   the shell.
+2. `running`, lease NULL, an unresolved tool_call with expired/absent lease →
+   re-enqueue `ToolExecutionJob(id, current execution_token)` (claim CAS dedupes;
+   healthy siblings untouched).
+3. `running`, lease NULL, zero unresolved tools → dropped-enqueue repair: loop →
+   `queued`, enqueue the next turn.
+4. `queued` older than a threshold → re-enqueue (repairs a lost queue row).
+
+A backstop sweep (`reap_orphaned_shells`) over paused/terminal loops fails+hides
+any orphaned `processing` shell (cases 1–4 only scan `running`). A gem-side health
+check reports the last successful reap.
+
+### Failure reconciliation
+
+Both jobs wrap EVERYTHING — agent `constantize`, provider resolution, MCP init,
+payload build, parse, callbacks — in `rescue StandardError`; if the fence still
+matches under lock: shell → failed+hidden, loop → failed (or paused by error
+class), token + lease cleared. A PRE-lease error takes a no-lease,
+generation-fenced failure path (the loop → failed under the token, no tool_call
+write). Hard kills fall through to the reaper. A renamed/missing agent class or a
+raising config hook now fails the loop VISIBLY instead of stranding it. The two
+job reconcilers share a `ToolFailureReconciler` so their semantics cannot drift.
+
+### Steering
+
+First act of an LLM turn after claim, in one committed row-locked txn: lock
+pending steering rows `FOR UPDATE` in ID order; flip to delivered with
+delivery-time `conversation_order`; commit. Payload builds from canonical history
+afterward. Cancel locks the same row — no pluck/find gap. A retried turn re-reads
+history (already-delivered steering included) and may drain newly-arrived
+steering; both are fine WITHOUT exact-bytes retry. The loop-completion txn checks
+pending steering and goes `queued` instead of `completed`.
+
+### Canonical writes under the row lock
+
+The tool canonical writes are LOOP-ROW-LOCKED, not `reload`-fenced. Lock order is
+**loop row → tool_call → message** (deterministic ascending id). `ToolExecution`
+holds the loop lock across both-token validation AND the
+`executed_at`/result/`duration_tools` write; `ResponseCreation` holds the SAME
+loop lock across validation, the tool response `message.create!`, the
+completion-gate transition, and the successor enqueue. A `reload` is NOT a fence;
+the row lock freezes `loop.execution_token` + `tool_call.lease_token` between
+validation and mutation, so a stale/revoked worker writes NOTHING. The tool BODY
+runs OUTSIDE the loop lock (a long tool must never serialize pause/stop/resume
+behind the loop lock). `mcp_session_id` is noncanonical telemetry folded into the
+FENCED canonical write (no separate unfenced update), so a stale worker cannot
+overwrite it.
+
+## Load-bearing — must NOT be dropped
+
+- The single **canonical-commit transaction** with a fence check under row locks
+  (all durable writes happen here or nowhere).
+- **CAS claim** (duplicate job delivery must no-op).
+- **Transactional enqueue with verified `perform_later`** + reaper repair of lost
+  queue rows (the "queued forever" failure mode). `SolidLoop.enqueue!` provides
+  the verified-enqueue half.
+- **Per-`tool_call` lease columns** (parallel is the shipped default).
+- The **job-level reconciliation wrapper** (~30 lines).
+- **Steering drain as a committed, row-locked txn before payload build** with
+  delivery-time `conversation_order`.
+
+## Delivery contract (README)
+
+Exactly-once (in SolidLoop's DB): canonical assistant message + loop counters per
+logical LLM turn; canonical tool response + ToolCall checkpoint per ToolCall.
+At-least-once: pending job delivery (claim CAS makes duplicates harmless); LLM
+provider request; tool invocation/effect (unless the handler dedupes the stable
+ToolCall key atomically with its effect). Best-effort: streaming UI chunks.
+
+## Guarantees and their limits
+
+1. Wider duplicate-call window: any death between provider-send and canonical
+   commit re-sends the whole request (possible duplicate side effect). This window
+   is narrowed, not closed.
+2. Reclaim latency up to `ttl + reaper interval` (~13 min worst case at a 600s
+   read timeout) instead of heartbeat-scale. "Permanently stranded" is fully
+   closed.
+3. No exact-request-bytes retry ⇒ no provider idempotency keys offered (near-
+   useless anyway).
+4. No per-acquisition audit rows (logs + an optional `reclaim_count`).
+5. Mid-stream partial text hidden by default (hosts opt into showing processing
+   shells — a one-line host change).
+6. Migration is **additive**, not destructive: the new columns are nullable, so
+   old terminal loops sit at `NULL` (correct — they are not in flight). The only
+   cleanup is any dangling `running` loop with no `execution_token` (would trip
+   the CHECK) — mark it `failed`, and the reaper heals such rows anyway. A
+   consumer's own domain tables are untouched. "Breaking" here means we do not
+   write careful online-rollout code and the release notes declare incompatibility
+   with the prior release — not that data is destroyed.
+7. Reaper case 2's "exactly one re-enqueue" holds for the UNEXECUTED sub-case
+   (the CAS-claimed lease fences the losing reaper). The dropped-CONTINUATION
+   sub-case (a call `executed_at` set but its canonical response/successor never
+   committed) carries no lease to CAS, so two racing reapers may both re-enqueue
+   it — harmless: `ResponseCreation`'s `response_message` idempotency check plus
+   the completion-gate `transition_status` fence make the duplicate a no-op and
+   the next LLM turn still fires exactly once. (At-least-once job delivery,
+   claim-CAS-dedupes, per the delivery contract.)
+
+   "Two racing reapers ⇒ one acts" is LITERALLY true for cases 1, 2-unexecuted, 3,
+   AND 4. Cases 1 / 2-unexecuted / 3 resolve to one winner under the row lock
+   (expiry re-check / CAS-claimed lease / under-lock re-confirmation). Case 4
+   (`queued` past threshold) BUMPS `updated_at` inside the same row-locked txn
+   BEFORE the enqueue, so the losing reaper re-reads `updated_at < threshold` as
+   false and does not re-enqueue. The ONE remaining duplicate-but-harmless case is
+   **case-2-CONTINUATION** (above): it carries no lease/marker to CAS, so a
+   duplicate `ToolExecutionJob` delivery is possible but idempotent (CAS-deduped
+   at ResponseCreation).
+
+## Known limitations
+
+- Continuation failure after a tool checkpoint surfaces late (the reaper
+  redelivers the checkpointed call; the tool body is not repeated).
+- At-least-once external tool effects for slow in-process/custom tools reclaimed
+  past `default_tool_timeout` (the canonical DB result is still exactly one).
+- Tool-lease derivation bounds configured HTTP MCP calls only; opaque custom
+  transports and cumulative setup can exceed the derived lease.
+- `SolidLoop.last_reaped_at` is process-local, not fleet-wide.
+- Mixed old/new workers across the lease upgrade are unsupported (drain or deploy
+  atomically).
+- Lease timestamps are Rails UTC `:datetime`.
+- Reaper scans/indexes are adequate but not scale-tuned.
+- Middleware that REPLACES (rather than wraps) a canonical finalizer forfeits the
+  durability guarantees unless it reproduces the fences itself.
+
+## Configuration / tunables
+
+```ruby
+SolidLoop.configure do |c|
+  c.config.lease_margin          # slack (s) added on top of a client timeout when deriving a lease
+  c.config.default_read_timeout  # fallback read_timeout when an agent's provider omits one; single source for the derived LLM lease and the HTTP client fallback
+  c.config.default_tool_timeout  # ceiling for an in-process/custom tool's lease
+  c.config.lease_leak_grace      # grace (s) on top of an agent's max_duration → the renewer's leak ceiling; > 0
+  c.config.default_max_duration  # fallback max_duration (s) sizing the leak ceiling when a registration omits one
+end
+```
+
+The invariant `lease_margin > 0` guarantees `lease > read_timeout` (LLM) and
+`lease > tool timeout` (tools) per claim; the heartbeat then keeps a healthy LLM
+turn's lease alive for its full duration. `Adapters::Native`'s fallback read
+timeout reads `default_read_timeout` (the SAME value the LLM lease derives from),
+so the derived lease can never be shorter than the client timeout. `ReaperJob`
+uses the `solid_loop_maintenance` queue; hosts allowlisting queues must consume
+the COMPLETE set (`solid_loop_llm`, `solid_loop_tool`, `solid_loop_maintenance`).
+`Reaper::Result` is a diagnostic return value, not a precise stable API;
+`cleaned_shell_loops` counts LOOPS, not shell rows.
+
+## Test focus
+
+The suite is a set of deterministic scenarios using a failpoint +
+`SimulatedHardCrash < Exception`, on real Postgres, non-transactional where locks
+must contend: kill after LLM claim; kill mid-stream (shell failed+hidden, absent
+from retry payload, assert TWO HTTP calls = the documented at-least-once
+boundary); redelivery after commit no-ops; renamed agent / provider
+`NoMethodError` → loop failed + token cleared; pause mid-stream → late commit
+fenced, resume clean; pause during long tool → late tool write fenced; tool kill
+after side effect pre-`executed_at` → reinvoked once, one canonical result (stable
+key); two parallel tools, one dies → sibling unaffected; cancel-vs-drain on two
+connections; two reapers race one expired lease; tool-phase loop (lease NULL)
+never falsely reclaimed + case-3 gap repair; steering delivered exactly once
+across a retried turn; heartbeat renewal under full pool saturation; renewer
+singleton creation race; the leak ceiling keeps a healthy long turn alive but
+drops a leaked one.

data/docs/decisions/mcp-only-tooling.md

@@ -0,0 +1,135 @@
+# Decision: MCP-Only Tooling (removal of native Ruby tools)
+
+> **Status: implemented in 0.0.3.**
+
+**Date:** 2026-07-08
+**Companion:** [mcp_transports.md](../guides/mcp_transports.md) — reference documentation for the new entities.
+
+## Decision
+
+SolidLoop drops the native Ruby tool path entirely. **Every tool is an MCP tool.**
+MCP becomes the single tool *interface*; transports are pluggable *implementations*
+behind a small port (`SolidLoop::Mcp::Transport`):
+
+| Transport | What it is | Ships with the gem |
+|---|---|---|
+| `Mcp::HttpTransport` | Streamable-HTTP MCP (today's `McpClient` Faraday path) | yes (reference adapter) |
+| `Mcp::Toolset` | In-process MCP server over the host app's service layer — the new home for what used to be native Ruby tools | yes (base class + DSL) |
+| `Mcp::StdioTransport` | Ephemeral child-process MCP server, spawn-per-call | yes, with a restricted contract |
+| custom | Anything implementing the port | user-provided |
+
+Users group their tools into domain toolsets ("search", "weather", "files" …) —
+each toolset is a logical MCP server. Transports can be mixed per agent: one domain
+external over HTTP, another in-process, another stdio.
+
+## Why
+
+1. **One execution path.** Today `ToolExecution` middleware has two resolution
+   branches (Ruby class match by `FUNCTION_NAME`/class name, then `mcp_tools`
+   lookup), `MessageBuilding` merges two schema sources, and the unknown-tool
+   message unions both lists. All of that collapses to one path: `loop.mcp_tools`.
+2. **Uniform observability.** Every tool call becomes a JSON-RPC envelope with a
+   wire log and an admin event — native calls today bypass the MCP logging.
+3. **Uniform discovery.** Schemas always come from `tools/list`; no more
+   hand-written `to_tool_spec` on ad-hoc classes.
+4. **Ports & adapters.** The transport port makes "local MCP" a first-class
+   concept instead of a special case, and lets users bring their own transport.
+5. **Timing.** At decision time, 0.0.1 and 0.0.2 were internal milestones;
+   0.0.3 became the first public release. The native-tool API could therefore
+   be removed cleanly, with no deprecation cycle and no external users to
+   migrate.
+
+## What is removed / changed (blast radius)
+
+Removed:
+- `SolidLoop::Base#tools` (`attr_accessor :tools`, `app/models/solid_loop/base.rb`).
+- The "Try Ruby Tool" branch in `ToolMiddlewares::ToolExecution#call`
+  (constantize + `FUNCTION_NAME`/class-name matching) and the native half of
+  `build_unknown_tool_message`.
+- The native merge in `Middlewares::MessageBuilding`
+  (`env.agent.tools.map { .to_tool_spec }`); payload tools become
+  `env.loop.mcp_tools.ordered.map(&:to_tool_spec)` only.
+- The `to_tool_spec` / `FUNCTION_NAME` conventions for user tool classes
+  (dummy app `CheckTaskTool`, `RaisingTool` are rewritten as a test toolset).
+
+Changed:
+- `McpClient` delegates all I/O to a `Transport` (see companion doc); the current
+  Faraday code moves verbatim into `Mcp::HttpTransport`.
+- `McpSessionInitializer` / `McpToolExecutionService` stop reading Faraday
+  internals (`resp&.env&.method`, response objects) and consume the
+  transport-agnostic `Mcp::Result` instead. Wire logs keep working for every
+  transport — this preserves the observability requirement from
+  `docs/decisions/ruby_llm_rejected.md`.
+- `Base#mcps` config accepts new entry forms (`toolset:`, `transport:`, `prefix:`)
+  alongside today's `url:` form. See companion doc.
+- `McpSession` gains `transport_kind` (`http` / `local` / `stdio` / `custom`).
+  Nothing is published yet, so the column goes directly into the init
+  migration (`20260408000100_solid_loop_init.rb`).
+- Unknown-tool feedback message lists `loop.mcp_tools.pluck(:name)` only.
+
+Unchanged:
+- `McpSession` / `McpTool` persistence, per-loop session rows, the admin UI,
+  the MCP Inspector, `tools:` whitelists and `required_tools` validation,
+  the `mcp://<server>/<tool>` metadata URL — all apply uniformly to every
+  transport.
+
+## Migration guide (native tool → toolset)
+
+Before (0.0.2):
+
+```ruby
+class CheckTaskTool
+  FUNCTION_NAME = "check_task"
+  def self.to_tool_spec = { type: "function", function: { name: "check_task", ... } }
+  def call(tool_call) = "Task verified: #{tool_call.arguments["path"]}"
+end
+
+class MyAgent < SolidLoop::Base
+  def tools = [CheckTaskTool]
+end
+```
+
+After:
+
+```ruby
+class TaskTools < SolidLoop::Mcp::Toolset
+  server_name "tasks"
+
+  tool "check_task",
+       description: "Verifies the task completed successfully",
+       input_schema: { type: "object",
+                       properties: { path: { type: "string" } } } do |args, ctx|
+    "Task verified: #{args["path"]}"
+  end
+end
+
+class MyAgent < SolidLoop::Base
+  def mcps = [ { name: :tasks, toolset: TaskTools } ]
+end
+```
+
+## Known trade-offs
+
+- **Ergonomics tax.** The 80% case "expose one Ruby method as a tool" gets a
+  toolset + explicit JSON schema instead of a bare class. The toolset DSL is the
+  make-or-break piece; it must stay one-screen simple. Mitigation: schema
+  helpers and a generator are on the table if the raw DSL feels heavy.
+- **stdio does not fit the durable-async core cleanly.** A stdio server's
+  session state lives in a child process owned by whichever worker spawned it;
+  the next tool call runs in a different job, possibly on a different machine.
+  `StdioTransport` therefore has a restricted contract: spawn-per-call,
+  stateless servers only, no cross-round server memory. Stateful stdio servers
+  (running shells, browser sessions, REPLs) are explicitly unsupported.
+- **Tool-name collisions** become likely with several servers per agent; solved
+  with per-entry `prefix:` + hard validation at session init (companion doc).
+
+## Out of scope (future work, deliberately not designed here)
+
+- Per-tool execution policy (`auto` / `requires_approval`) for HITL gating —
+  orthogonal layer on top of `ToolExecution`; the toolset/port design leaves
+  room for it but does not define it.
+- Server-initiated MCP notifications / streaming `tools/call` over local and
+  stdio transports; first iteration is synchronous request/response only.
+
+Serving toolsets over HTTP and consuming MCP resources/prompts were subsequently
+implemented in 0.0.4; see [mcp-server.md](mcp-server.md) for the settled design.