omakase-agents 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c14f0a611e4eacd12ed77e2944f0af6e8b5f51a908ecceff832418bb7c4f6c7e
-  data.tar.gz: 7bdeb3cef506c2eda19939a51782c24a87347158b660c83d79f2fb643720131a
+  metadata.gz: bdeb9ba4fb16ca770bcedd8b127b76cc925af49cfa73a9257d9e3d27e060de97
+  data.tar.gz: a7b72e4946ab8add9c5baac75bcd9bf5bf0419d70bfe79c54fbd843a280f78ed
 SHA512:
-  metadata.gz: 88399ffa0b1b73c20b1983d87c70fe09ef90db58ca2b9f527a7762c1294dbde90ebbac000ea3e297c6195cbb3bbf5614951b472769bfd573abb26909068f2962
-  data.tar.gz: 5089d67312535691c5d65407492e2fd046a0979bf42ad87f196b7579df515356de364b75050012f38da7e16be3c192912ac5fe101b20b699f29ea4f9819de8a4
+  metadata.gz: baa837f849d8a646edd9a9777660d236defb2c676f274cb9c2f5cade9c74e70145d8dcde3ab6c17b260f622bed61fa025489e465e8e854e45b0cf679c1099a02
+  data.tar.gz: b0dfbe030b3f6668a8ad2faea141a6c7fc0754475371bb6e3630584770b3b91e0e5e9e33e839d9de46d4dd2222b17b17ec4665b00ad7e93899c32d4cca78af08

data/CHANGELOG.md

@@ -3,6 +3,89 @@
 One entry per released version, written when the gem is pushed. Until `1.0`, a minor version may
 move the API — what breaks is listed first, so an upgrade is a decision rather than a surprise.
 
+## 0.4.0
+
+RubyLLM 2.0 underneath, and MCP waits for it. Generated code gets its inputs as locals, can crash in
+a child process instead of yours, and its answer is checked all the way down.
+
+### Breaking
+
+- RubyLLM `~> 2.0`. `ruby_llm-mcp` has no release for it yet, so `mcp` servers do not connect until
+  it does; the `mcp` declaration itself still loads.
+- Prompt caching is on for every chat Omakase builds. `model "…", caching: false` turns it off.
+- A text reply under `:code_act` gets one more turn in the same chat — "call finish" — before the
+  fallback to `:predict`. One more model call when a model forgets how to answer.
+- `finish` is held to the whole schema: nested objects, array items, enums. An answer 0.3 took can
+  now be refused, with the path of the mistake (`tags[0]: expected <string>, got 1`).
+- Chat options other than the model are the chat's own `with_*` calls — `temperature: 0.2`,
+  `thinking: {effort: :high}` — and one RubyLLM::Chat has no `with_*` for raises. 0.3 passed them
+  to `RubyLLM.chat`, which refused them anyway.
+- Generations nest ten deep at most.
+
+### Added
+
+- `Omakase::Executor::Subprocess`: generated code in a forked child, so a timeout or a crash takes
+  the child and not you. Ivars come back; the child still reaches what this process reaches.
+- Under `:code_act` the inputs are local variables in the generated code, and locals last for the
+  rest of the generation. The prompt shows only the first 500 characters of each input.
+- Every agent has `how_to_act`, a built-in skill: how to write the Ruby — `finish`, prints, `doc`,
+  locals — with examples.
+- The instructions go first and are marked as a cache boundary; `context` follows them.
+- `FakeChat.replies(a, b)`: one reply per model turn, and a turn past the last one raises.
+- A `:error` event; `Omakase::Trace` prints it and indents nested generations.
+
+### Fixed
+
+- `exit` in generated code no longer ends your process; the model is told to `finish` instead.
+- An observation past 4KB keeps its end as well as its start, so the error is not the part cut off.
+- MCP servers connect on the first instance, not at class load: an unreachable sidecar does not
+  fail boot, and a reload does not reconnect.
+- A ```ruby fence around the whole code is stripped before it runs.
+- SKILL.md is read as UTF-8, CRLF front matter is read, and front matter that is not YAML falls back
+  to plain `key: value` lines.
+
+## 0.3.0
+
+One thing changes under you: a generation may no longer call itself. The rest is additions — a real
+signature for the inputs, a trace to read a run by, a seam for the chat, and your own validations
+enforced on the way out.
+
+### Breaking
+
+- A generation may not re-enter itself. While `SupportAgent#reply` is running on an object, that
+  object's `reply` raises `Omakase::Error` instead of opening a second run. Generated code can see
+  the method and call it, and each nested call opened its own chat with its own tool budget — so the
+  budget bounded nothing. A *fresh* agent may still recurse: that is the sub-agents pattern, one
+  object per node of a tree, and the tree is the thing that ends.
+
+### Added
+
+- `takes:` names the keyword arguments, and then Ruby checks them:
+  `generates :translate, takes: %i[text language]`. A missing or misspelled argument is an
+  `ArgumentError` at the call rather than noise in a prompt, and the model reads the names instead
+  of `**inputs`. `with:` stays available for attachments. Anything that is not a plain keyword name
+  is refused where it is declared.
+- `Omakase::Trace` — the listener printed for a human: `Omakase.listener = Omakase::Trace.new`. A run
+  reads top to bottom: the call, the code the model wrote, the answer. Colour when the stream is a
+  terminal, plain when it is a log.
+- `Omakase.chat_factory` — how an agent gets a chat when none was injected. One line in
+  `test_helper.rb` keeps a whole suite off the network, including the class-level calls a job makes,
+  which have no seam to inject through. Anything answering `call(**options)` will do, and an
+  injected `chat:` still wins.
+- A `returns:` class that answers `valid?` and `errors` — which is every ActiveModel — is asked
+  before the answer is handed back, and an invalid one is refused. Under `:code_act` the refusal
+  reaches the model as `finish rejected: Post is invalid: …`, and it corrects itself inside the same
+  loop. Your validations are the contract, and they stay where you wrote them.
+- `doc(object)` takes a class as well as an instance: what an object of that type would offer, plus
+  the column names when it is a record. The model asks before it builds a type it has only been told
+  the name of.
+
+### Fixed
+
+- What generated code printed before `finish` is no longer lost — `Executor::Answer` carries it, so a
+  trace shows the working and not only the answer. `printed:` defaults, so a replacement executor
+  that knows the value alone still satisfies the seam.
+
 ## 0.2.0
 
 Nothing breaks. Four additions, each one a keyword or a seam that costs nothing when unused.

data/README.md

@@ -1,6 +1,6 @@
-# Omakase
+# Omakase Agents
 
-A light agent framework — about 700 lines of library. *Omakase* (お任せ): you name what you want,
+A light agent framework — about 800 lines of library. *Omakase* (お任せ): you name what you want,
 the rest is left to the chef.
 
 **[esshka.github.io/omakase](https://esshka.github.io/omakase/)** · [rubygems](https://rubygems.org/gems/omakase-agents) · [changelog](CHANGELOG.md) ![gem](https://img.shields.io/gem/v/omakase-agents?color=c8452e&label=)
@@ -54,9 +54,15 @@ method; deleting one is deleting a method.
 ## Why this
 
 Against **RubyLLM alone**: the tool loop, the schema plumbing, and the correction turn after a bad
-answer are what these 700 lines are. Everything else — providers, keys, models, streaming, tracing —
+answer are what these 800 lines are. Everything else — providers, keys, models, streaming, tracing —
 is still RubyLLM's, and stays reachable.
 
+Against **`RubyLLM::Agent`**: that is a chat preset — model, tools, instructions and a schema kept
+on a class, handing back a `RubyLLM::Chat`, with Rails persistence of the conversation. Reach for it
+when the product is the chat. Here the product is a method: `generates` defines one the model
+implements, the agent's own methods and fields are its tools and state, and the call returns a typed
+value. Both sit on RubyLLM and do not overlap.
+
 Against **a framework with a tool registry**: there is nothing to register and nothing to keep in
 sync. The model gets one tool, `ruby`, and reaches the rest through the object. A tool's description
 is `describe`, a line above the method, instead of a JSON schema that drifts from the code it
@@ -79,6 +85,53 @@ gem "omakase-agents"     # the library is `Omakase`
 gem install omakase-agents
 ```
 
+## Quickstart
+
+One file, one working agent. Five minutes.
+
+**1.** Install the gem and set a key:
+
+```bash
+gem install omakase-agents
+export OPENROUTER_API_KEY=sk-or-...
+```
+
+**2.** Save this as `triage.rb`:
+
+```ruby
+require "omakase"
+
+Omakase.configure_from_env
+
+class TriageAgent < Omakase::Agent
+  model "meta/muse-glimmer-30b", provider: :openrouter
+  instructions "You triage customer support messages."
+  strategy :predict
+
+  generates :triage do
+    string :severity, enum: %w[low medium high]
+    string :summary
+  end
+end
+
+pp TriageAgent.triage(message: "The app crashes every time I open my invoices")
+```
+
+**3.** Run it:
+
+```bash
+ruby triage.rb
+```
+
+A Ruby Hash comes back, matching the schema you declared:
+
+```ruby
+{severity: "high", summary: "App crashes on opening invoices"}
+```
+
+You wrote no JSON parsing and registered no tool. Next: [Usage](#usage) for the rest of the
+API, or [How it works](#how-it-works) for why it is built this way.
+
 ## Usage
 
 The whole API, in one class:
@@ -136,6 +189,20 @@ FeedbackAgent.analyze(text: "Great product, but shipping was slow")
 FeedbackAgent.new.analyze(text: "…")
 ```
 
+By default they take whatever you pass. Name them with `takes:` and they become a real Ruby
+signature, so a missing or misspelled argument is an `ArgumentError` at the call rather than noise
+in a prompt — and the model reads the names instead of `**inputs`. Under `:code_act` the inputs are
+also local variables in the generated code, so a long list or a record is used, not retyped; the
+prompt shows only the first 500 characters of each:
+
+```ruby
+generates :decide, "Decide this refund.", takes: %i[email complaint], returns: Refund
+
+RefundAgent.decide(email: "ada@example.com")                 # => ArgumentError: missing keyword: :complaint
+RefundAgent.decide(emial: "…", complaint: "…")               # => ArgumentError: unknown keyword: :emial
+```
+
+`with:` stays available on a named signature, since attachments are not part of the prompt.
 `describe` above an ordinary method is the docstring Ruby does not have — it is what the model reads
 when it decides what to call.
 
@@ -167,7 +234,9 @@ generates :count_items, returns: :integer      # :string (default), :integer, :n
 
 Both forms are the same mechanism: a schema whose only property is `result` unwraps to that value.
 A Ruby class works too — `returns: Ticket` — and then the method hands back the object rather than
-data; see [`:code_act`](#strategies) for what that requires.
+data; see [`:code_act`](#strategies) for what that requires. If that object can say whether it is
+well-formed — anything answering `valid?` and `errors`, which is every ActiveModel — it is asked, and
+an invalid one is refused.
 
 ### Attachments
 
@@ -197,7 +266,10 @@ class ApplicationAgent < Omakase::Agent
 end
 ```
 
-Naming a provider implies `assume_model_exists: true`; any other RubyLLM chat option passes through.
+Naming a provider implies `assume_model_exists: true`. Any other option is the chat's own `with_*`
+call — `temperature: 0.2`, `thinking: {effort: :high}`, `max_output_tokens: 2_000` — and an option
+RubyLLM::Chat has no `with_*` for raises. Prompt caching is on unless you say `caching: false`: the
+tool loop resends the whole chat on every step, and the instructions come first so they cache.
 Subclasses inherit the setting and can override it, so one `ApplicationAgent` configures the lot.
 
 A generation method can name its own model — a cheap one for classification beside a strong one
@@ -227,7 +299,8 @@ end
 
 An MCP server's tools become methods on the agent, listed among its capabilities like any other —
 so generated code calls a remote tool and the agent's own methods in the same expression. Add the
-`ruby_llm-mcp` gem; options are passed to it verbatim.
+`ruby_llm-mcp` gem; options are passed to it verbatim. Its 1.0 release still pins RubyLLM 1.x, so
+this waits on a `ruby_llm-mcp` that supports RubyLLM 2.
 
 ```ruby
 class DocsAgent < ApplicationAgent
@@ -239,10 +312,14 @@ class DocsAgent < ApplicationAgent
 end
 ```
 
-The connection opens when the class is defined and the tools are read from the server then, so a
+The connection opens on the first instance and the tools are read from the server then, so a
 tool's arguments reach the model as documentation. A failed call raises, which the model sees and
 can correct. Only text comes back: an image or audio result is dropped.
 
+Class load does not talk to the server, so an unreachable sidecar does not fail boot, and a reload
+does not reconnect. The first instance pays that cost; if the server is down, its tools are absent
+and the generate still runs. The next instance tries that server again.
+
 ### Skills
 
 A skill is a directory with a `SKILL.md` — the same YAML front matter Claude Code and friends use.
@@ -257,11 +334,19 @@ class CommitAgent < ApplicationAgent
 end
 ```
 
+The path is expanded against the working directory, which is `Rails.root` until something — a job
+runner, a systemd unit — decides otherwise, so `Rails.root.join("app/agents/skills/commit_style")`
+is the spelling that keeps working.
+
 That is the whole of “loaded on demand”: the one-line description is in the prompt, the body only
 reaches the model if the generated code calls `commit_style`. Anything else the skill ships —
 scripts, templates — sits in the same directory, and the body ends with its path, so generated Ruby
 can read or run it.
 
+Every agent already has one: `how_to_act`. It is how to write the Ruby that implements a
+generation — `finish`, prints, `doc`, ivars — with examples. The description sits in the capability
+list; the body arrives when the model calls it.
+
 ### Remembering
 
 The chat is fresh on every call — two threads calling one agent must not share a mutable
@@ -338,6 +423,44 @@ things one agent learns about its work; past that it is your database's job —
 reimplement against it. And for a few dozen facts, `@notes.grep(/shipping/)` beats every word of
 this.
 
+### Sub-agents
+
+Some work is a tree, and the tree is usually already in your database — a comment thread, a category
+tree, a bill of materials. One agent per node folds it from the leaves up, and the recursion belongs
+to the data: a node with no children is the base case, so nothing has to invent how deep to go.
+
+```ruby
+class ThreadAgent < ApplicationAgent
+  instructions "You sum up a discussion for someone who has not read it."
+  strategy :predict
+
+  def initialize(comment, **options)
+    super(**options)
+    @comment = comment
+  end
+
+  def roll_up
+    return said if @comment.replies.empty?
+
+    summarise(comment: said, replies: @comment.replies.map { |reply| self.class.new(reply).roll_up })
+  end
+
+  generates :summarise, "Sum up this comment together with the replies it drew.", returns: :string
+
+  private
+
+  def said = "#{@comment.author}: #{@comment.body}"
+end
+```
+
+A leaf is its own summary, so the model is asked only where there is something to fold. A fresh
+agent per branch is not ceremony either: siblings then share no state, and one object may not
+re-enter a generation it is already inside. That is refused, because a nested run opens its own chat
+with its own tool budget — nothing would bound the spend. For the same reason generations nest ten
+deep at most. Generated code can start a sub-agent the
+same way. [`examples/recursive_agent.rb`](examples/recursive_agent.rb) is the runnable version: four
+comments, two of them leaves, two generations.
+
 ### Testing
 
 `Omakase::Agent.new(chat:)` takes any object that quacks like a `RubyLLM::Chat`, and one ships with
@@ -349,10 +472,28 @@ assert_equal "high", SupportAgent.new(chat:).triage(message: "broken")[:severity
 
 # drive the tool the way a model would
 chat = Omakase::FakeChat.new { |fake| fake.run("finish(stock_of(:apple))") }
+
+# one reply per model turn, in order; one turn too many raises
+chat = Omakase::FakeChat.replies("prose, not JSON", {"severity" => "high", "summary" => "…"})
 ```
 
 It records `instructions`, `schema`, `tools` and `tasks`, so the prompt is assertable too.
 
+Injecting a chat covers the agent you are testing. A suite covers everything else, including the
+class-level calls a job makes — `SupportAgent.triage(message:)` builds its own agent and has no seam
+to inject through. `Omakase.chat_factory` is that seam, and one line in `test_helper.rb` puts the
+whole suite off the network:
+
+```ruby
+# test/test_helper.rb
+Omakase.chat_factory = ->(**) { Omakase::FakeChat.new { raise "an agent asked for a model" } }
+```
+
+Make it raise, and any generation you forgot to stub fails loudly instead of quietly calling a
+provider from CI. An injected `chat:` still wins, so the tests that mean to run an agent keep
+working. Anything answering `call(**options)` will do; the options are the class's chat options, so
+a factory can assert the model too.
+
 ### Listening in
 
 One callback hears every step as it happens: a generation starting, model-written code running,
@@ -363,7 +504,32 @@ Omakase.listener = ->(event, **payload) { Rails.logger.info("#{event} #{payload.
 ```
 
 `:generation` carries `agent:, name:, inputs:` · `:ruby` carries `agent:, code:, outcome:` ·
-`:answer` carries `agent:, name:, value:`.
+`:answer` carries `agent:, name:, value:` · `:error` carries `agent:, name:, error:`.
+
+One listener is included, for reading a run rather than storing it: it prints each step to stderr,
+in colour when stderr is a terminal.
+
+```ruby
+Omakase.listener = Omakase::Trace.new
+
+# → SupportAgent#triage
+#     message: "my mug arrived cracked"
+# · ruby
+#     order = order_db.find(1)
+#     puts "eligible: #{refund_eligible?(order)}"
+#     finish(Ticket.new("A-1", :high))
+#     eligible: true
+#     finish #<struct Ticket id="A-1", severity=:high>
+# ← SupportAgent#triage
+#     #<struct Ticket id="A-1", severity=:high>
+```
+
+In Rails there is already a bus for this, and one line puts the events on it — subscribers and your
+APM pick them up with nothing further:
+
+```ruby
+Omakase.listener = ->(event, **payload) { ActiveSupport::Notifications.instrument("#{event}.omakase", payload) }
+```
 
 ## Rails
 
@@ -388,7 +554,7 @@ logs and APM without any code of ours:
 
 ```ruby
 ActiveSupport::Notifications.subscribe("chat.ruby_llm") do |*, payload|
-  Rails.logger.info(model: payload[:model], input: payload[:input_tokens], output: payload[:output_tokens])
+  Rails.logger.info(model: payload[:model], input: payload[:tokens].input, output: payload[:tokens].output)
 end
 ```
 
@@ -404,17 +570,43 @@ Jobs move data, not objects: arguments and results have to serialize, so a `retu
 answer — a live Ruby object — does not survive the trip. [`examples/support_job.rb`](examples/support_job.rb)
 is the runnable version, three tickets triaged concurrently by the async adapter.
 
+**Validations are the contract.** A `returns:` class that answers `valid?` and `errors` gets asked
+before the answer is handed back, so a generation cannot return a record your own validations
+reject:
+
+```ruby
+class Post < ApplicationRecord
+  validates :slug, format: {with: /\A[a-z0-9-]+\z/}, length: {maximum: 12}
+end
+
+class BlogAgent < ApplicationAgent
+  generates :write, "Write a post about the topic.", returns: Post
+end
+```
+
+Nothing about the slug is in the prompt. Under `:code_act` the refusal goes back to the model as
+`finish rejected: Post is invalid: Slug is too long (maximum is 12 characters)`, and it corrects
+itself inside the same loop, within its call budget. Your rules stay in the model, where the rest of
+the application already reads them.
+
 **Threads.** Puma is multi-threaded and so is this: printing from generated code goes to a
 per-thread buffer, and each call gets its own chat and its own agent instance. Concurrent calls are
-just threads:
+threads — wrapped in the Rails executor, which is what returns the connection to the pool and makes
+autoloading safe off the request thread:
 
 ```ruby
-ids.map { |id| Thread.new { WarehouseAgent.appraise(item_id: id) } }.map(&:value)
+ids.map do |id|
+  Thread.new { Rails.application.executor.wrap { WarehouseAgent.appraise(item_id: id) } }
+end.map(&:value)
 ```
 
 Sharing one agent instance across threads is your business as usual — its state is yours. Do not
 turn on RubyLLM's `tool_concurrency`: that runs generated code against the same agent in parallel.
 
+**The pool.** A generation holds its thread for the whole run, and the moment generated code touches
+`ActiveRecord` it holds a database connection with it — through every provider round-trip of a
+`:code_act` loop, not just the queries. Size `pool:` by concurrent agent runs, not by request rate.
+
 **Multi-turn, many pods.** Identity is a row, state is your tables, and the agent is a value —
 rebuilt from them for one turn and thrown away. The chat is fresh per call anyway, so nothing
 sticks to a process: any pod serves any turn, and multi-turn is nothing more than `context`
@@ -446,18 +638,39 @@ class SupportAgent < ApplicationAgent
 end
 
 class TurnJob < ApplicationJob
+  limits_concurrency key: ->(conversation) { conversation }   # one turn per conversation at a time
+
   def perform(conversation)
-    conversation.with_lock do                         # turns on one conversation stay serial
-      reply = SupportAgent.new(conversation).reply
-      conversation.messages.create!(role: "assistant", content: reply)
-    end
+    reply = SupportAgent.new(conversation).reply              # no transaction open across this
+    conversation.messages.create!(role: "assistant", content: reply)
   end
 end
 ```
 
+`limits_concurrency` is Solid Queue's; Sidekiq and GoodJob have their own. What matters is that the
+lock lives in the queue: `with_lock` around a generation would hold a transaction open for the whole
+provider round-trip — a pinned connection, a long-running transaction, and every other turn on that
+row waiting behind it.
+
+[`examples/conversation_agent.rb`](examples/conversation_agent.rb) is all of this running: two turns
+of one conversation, each crossing the queue, with nothing but an id and a String travelling between
+them. The second turn answers from the first because the history is a table, not a process.
+
 Marshal-into-a-column is the escape hatch for resuming a run mid-flight, not the default: rows can
 be queried and migrated, blobs cannot.
 
+**The console.** An agent is a plain object, so `rails console` is already the harness:
+
+```ruby
+agent = SupportAgent.new(Conversation.find(42))
+agent.context    # exactly what the model will read
+agent.reply      # one real generation, right here
+```
+
+The same value the job builds, built by hand — and every tool is an ordinary method, so
+`agent.refund!(order_id, 20)` runs with no model in the room. Nothing to boot, nothing to mock: the
+console session that debugs your models debugs your agents.
+
 **Errors.** Everything raised at the boundary is an `Omakase::Error`:
 
 | | |
@@ -497,8 +710,10 @@ turn naming what was wrong. No code runs. Right for classification, extraction,
 is `instance_eval`d on the agent, so the agent’s methods and state are the API; anything printed and
 the value of the last expression come back as the observation, and the loop repeats until the model
 calls `finish(value)`. `Capabilities` lists the agent’s own methods (with their `describe` text) in
-the system prompt, minus the method being written, so it cannot recurse into itself. A failure comes
-back with the line that raised, `doc(object)` prints what an object of an unfamiliar type offers, and
+the system prompt, minus the method being written. Leaving it out is not enough on its own, since
+generated code can still find the method, so a generation already running refuses to start again — a
+nested one would open its own chat with its own budget, and nothing would bound the spend. A failure
+comes back with the line that raised, `doc(object)` prints what an object — or a class — offers, and
 an answer that misses the contract is rejected into the same loop — the model corrects itself without
 another request. Nothing in the provider bounds a tool loop, so the tool does: ten calls, then a turn
 to answer with what it has.
@@ -544,12 +759,13 @@ generates :plan, strategy: CriticStrategy
     lib/omakase/type.rb            return types that are a Ruby class
     lib/omakase/capabilities.rb    the agent’s own methods, listed for the model
     lib/omakase/doc.rb             what an unfamiliar object offers, for generated code
-    lib/omakase/executor.rb        runs generated Ruby against the agent
+    lib/omakase/executor.rb        in-process; Executor::Subprocess isolates a crash
     lib/omakase/tools/ruby.rb      that executor, as a RubyLLM tool, with a call budget
     lib/omakase/mcp.rb             an MCP server’s tools, as methods on the agent
     lib/omakase/skills.rb          a SKILL.md directory, as one described method
     lib/omakase/memory.rb          remember and recall, by meaning
     lib/omakase/fake_chat.rb       the stand-in chat for tests
+    lib/omakase/trace.rb           those events, printed for a human
     lib/omakase/strategies/        code_act, predict
 
 ## Examples
@@ -565,10 +781,13 @@ Copy `.env.example` to `.env` and fill in a key; `MODEL` and `PROVIDER` there pi
 | [`support_agent.rb`](examples/support_agent.rb) | plain Ruby orchestrating generated methods |
 | [`support_job.rb`](examples/support_job.rb) | generation off the request thread, via ActiveJob |
 | [`rails_app.rb`](examples/rails_app.rb) | a whole Rails app in one file: initializer, agent, controller |
+| [`conversation_agent.rb`](examples/conversation_agent.rb) | multi-turn over ActiveRecord, one turn per job, no process state |
 | [`mcp_agent.rb`](examples/mcp_agent.rb) | an MCP server's tools as methods on the agent |
 | [`skill_agent.rb`](examples/skill_agent.rb) | a SKILL.md directory the model loads when it needs it |
 | [`interview_agent.rb`](examples/interview_agent.rb) | remembering across calls, without a shared chat |
 | [`memory_agent.rb`](examples/memory_agent.rb) | recall by meaning, kept across a marshalled run |
+| [`recursive_agent.rb`](examples/recursive_agent.rb) | a comment thread folded from the leaves up, one agent per node |
+| [`subprocess_agent.rb`](examples/subprocess_agent.rb) | generated code in a child process: a crash there is an observation here |
 
 ```bash
 bundle exec rake                     # tests and Standard, no network
@@ -586,12 +805,21 @@ too. Two rules follow:
 - **A marshalled agent is your data, never user input.** `Marshal.load` on bytes someone else can
   write is remote code execution, resumed run or not.
 
-What is bounded: ten tool calls per generation, a 30-second timeout per execution, and 4KB of
-observation. What is not: what the code can reach. For real isolation, swap the executor —
-anything answering `call(agent, code, timeout:)` will do:
+What is bounded: ten tool calls per generation, one run of a generation at a time, a 30-second
+timeout per execution, and 4KB of observation — its start and its end, where the error is. `exit` in
+generated code is refused rather than ending your process; `exit!` cannot be caught, so only
+Subprocess survives it. The default executor uses Ruby's `Timeout` in this
+process — inside a database driver it can leave the connection unusable.
+`Omakase::Executor::Subprocess` is the reference swap: the same `instance_eval`, in a child process,
+so a timeout or a crash takes the child and not you. Ivars come back one at a time, so one Proc
+does not drop the rest; methods the model defined on the object die with the child. The child is a
+copy of this process, so it can still reach ActiveRecord, ENV, and the disk — that is isolation of
+fate, not of capability. Untrusted input still belongs to `:predict`. Do not use it from a threaded
+server; run the generation in a job. Do not call MCP tools under it: the child would share the
+parent's stdio client.
 
 ```ruby
-Omakase.executor = MySubprocessExecutor    # returns an observation String or Executor::Answer
+Omakase.executor = Omakase::Executor::Subprocess
 ```
 
 ## Not here, on purpose
@@ -600,7 +828,8 @@ Omakase.executor = MySubprocessExecutor    # returns an observation String or Ex
   RubyLLM, and making it resumable would be a different library.
 - **Reflection and forgetting in memory.** No decay, no consolidation pass: `Memory` grows until you
   prune it, and past a few hundred entries the answer is pgvector, not more code here.
-- **A sandbox.** `instance_eval` runs in your process. Real isolation is a swapped executor, above.
+- **A sandbox.** The child can still reach what this process can. Subprocess isolates a crash and a
+  timeout, not `File` or ActiveRecord.
 - **Multi-agent orchestration.** An agent is an object, so one agent calling another is a method
   call. There is nothing to add.
 - **Streaming.** A generation method returns a value, not tokens. RubyLLM streams if you need that.