omakase-agents 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0a1114c3a9af5c41d3111880844a2a74a182b23696226533c3d5076b3a3ce63
-  data.tar.gz: '049c62448ea9e6d3b96177bda1564b294cb47d08cc7aa7a514db321d0f617394'
+  metadata.gz: bdeb9ba4fb16ca770bcedd8b127b76cc925af49cfa73a9257d9e3d27e060de97
+  data.tar.gz: a7b72e4946ab8add9c5baac75bcd9bf5bf0419d70bfe79c54fbd843a280f78ed
 SHA512:
-  metadata.gz: c1fb9143de3b2b934eb183e6c396a81a06d64ac8b505f28f0a311c2411aea56c09e64207f3c5789554f88bca34bbc0a9fe7654c276775383e559769f269d4775
-  data.tar.gz: 94f16e8c77584c2a0c120e93f470acd5ba46991c7503be695d267c4dae95b8e7124360121a0186ace47c8c4dea17caf4cb147d1abc3d86d8b07e6594c4cd3321
+  metadata.gz: baa837f849d8a646edd9a9777660d236defb2c676f274cb9c2f5cade9c74e70145d8dcde3ab6c17b260f622bed61fa025489e465e8e854e45b0cf679c1099a02
+  data.tar.gz: b0dfbe030b3f6668a8ad2faea141a6c7fc0754475371bb6e3630584770b3b91e0e5e9e33e839d9de46d4dd2222b17b17ec4665b00ad7e93899c32d4cca78af08

data/CHANGELOG.md

@@ -3,6 +3,47 @@
 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

data/README.md

@@ -1,4 +1,4 @@
-# Omakase
+# Omakase Agents
 
 A light agent framework — about 800 lines of library. *Omakase* (お任せ): you name what you want,
 the rest is left to the chef.
@@ -57,6 +57,12 @@ Against **RubyLLM alone**: the tool loop, the schema plumbing, and the correctio
 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
@@ -185,7 +191,9 @@ 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`:
+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
@@ -258,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
@@ -288,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
@@ -300,13 +312,13 @@ 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.
 
-That it happens at class-definition time has a cost worth knowing: under `config.eager_load = true`
-an unreachable server fails the boot, and every reload in development reconnects. If a deploy must
-not wait on a sidecar, keep MCP agents out of the eager-loaded paths.
+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
 
@@ -331,6 +343,10 @@ reaches the model if the generated code calls `commit_style`. Anything else the
 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
@@ -440,7 +456,8 @@ 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. Generated code can start a sub-agent the
+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.
 
@@ -455,6 +472,9 @@ 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.
@@ -484,7 +504,7 @@ 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.
@@ -534,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
 ```
 
@@ -739,7 +759,7 @@ 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
@@ -767,6 +787,7 @@ Copy `.env.example` to `.env` and fill in a key; `MODEL` and `PROVIDER` there pi
 | [`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
@@ -785,14 +806,20 @@ too. Two rules follow:
   write is remote code execution, resumed run or not.
 
 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. That timeout is Ruby's `Timeout`, which raises
-wherever the code has got to — inside a database driver it can leave the connection unusable — one
-more reason anything long-running belongs in an executor of your own. What is not bounded: what the
-code can reach. For real isolation, swap the executor — anything answering `call(agent, code,
-timeout:)` will do:
+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
@@ -801,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.

data/lib/omakase/agent.rb

@@ -6,6 +6,9 @@ module Omakase
   class Agent
     # The generations this thread is inside, so one cannot re-enter itself.
     RUNNING = :omakase_running
+    # Each level opens a chat with a fresh tool budget, so depth is what bounds the cost.
+    # ponytail: a constant; a setting when a real tree needs more.
+    MAX_DEPTH = 10
     class << self
       # The model and any RubyLLM chat option. Naming a provider takes the model
       # id on trust, since providers like OpenRouter or Ollama serve ids that are
@@ -31,9 +34,14 @@ module Omakase
 
       # An MCP server's tools, as methods on the agent. Options are passed to
       # `ruby_llm-mcp` verbatim: `mcp :files, transport_type: :stdio, config: {command: "npx", …}`.
-      def mcp(name, **options)
-        require "ruby_llm/mcp"
-        MCP.attach(self, RubyLLM::MCP.add_client(name: name.to_s, **options))
+      # The server opens on the first instance, not at class load.
+      def mcp(name, **options) = MCP.defer(self, name, options)
+
+      # Here rather than in `initialize`, which a subclass may override and
+      # never call super from — and then generate with none of its tools.
+      def new(...)
+        MCP.ensure(self)
+        super
       end
 
       # A skill directory — a SKILL.md with YAML front matter. Its description
@@ -124,6 +132,7 @@ module Omakase
         subclass.strategy(@strategy) if @strategy
         subclass.generations.merge!(generations)
         subclass.descriptions.merge!(descriptions)
+        Skills.attach_core(subclass)
       end
     end
 
@@ -177,19 +186,43 @@ module Omakase
 
       # Generated code can see this method and call it. Each nested call opens its
       # own chat with its own tool budget, so the budget would bound nothing.
-      raise Error, "#{self.class}##{name} is already running — it cannot call itself" if running.include?(key)
+      raise Error, "#{self.class}##{name} is already running — it cannot call itself" if running.any? { |frame| frame[:key] == key }
+      raise Error, "#{self.class}##{name}: generations nest deeper than #{MAX_DEPTH}" if running.size >= MAX_DEPTH
 
-      running.push(key)
+      frame = {key:, inputs:}
+      running.push(frame)
       begin
         Omakase.emit(:generation, agent: self, name:, inputs:)
         value = generation.strategy.call(Request.new(agent: self, generation:, inputs:))
         Omakase.emit(:answer, agent: self, name:, value:)
         value
       rescue RubyLLM::Error, RubyLLM::ConfigurationError, RubyLLM::ModelNotFoundError => e
-        raise ProviderError, "#{self.class}##{name}: #{e.message}"
+        error = ProviderError.new("#{self.class}##{name}: #{e.message}")
+        Omakase.emit(:error, agent: self, name:, error:)
+        raise error
+      rescue => e
+        Omakase.emit(:error, agent: self, name:, error: e)
+        raise
       ensure
-        running.delete(key)
+        running.delete(frame)
+      end
+    end
+
+    # Where generated code runs during a generation: self is the agent and the
+    # inputs are locals, which then last for the rest of that generation.
+    def omakase_scope
+      frame = Thread.current[RUNNING]&.reverse_each&.find { |entry| entry[:key].first == object_id }
+      return unless frame
+
+      frame[:scope] ||= omakase_blank_binding.tap do |scope|
+        frame[:inputs].except(:with).each do |name, value|
+          scope.local_variable_set(name, value) if /\A[a-z_]\w*\z/.match?(name.to_s)
+        end
       end
     end
+
+    # A string instance_eval, so a `def` in generated code lands on this object
+    # alone — and no local of the caller leaks in.
+    def omakase_blank_binding = instance_eval("binding", __FILE__, __LINE__)
   end
 end

data/lib/omakase/capabilities.rb

@@ -18,10 +18,15 @@ module Omakase
     end
 
     def entry(agent_class, name)
-      signature = "#{name}(#{parameters(agent_class.instance_method(name))})"
+      method = agent_class.instance_method(name)
+      signature = "#{name}(#{parameters(method)})"
       # A prompt written as a block needs an instance to read; `describe` it instead.
       prompt = agent_class.generations[name]&.prompt
-      description = agent_class.descriptions[name] || (prompt unless prompt.is_a?(Proc))
+      # Look up on the method's owner so a late attach on a parent still
+      # documents the tool for subclasses created before that generate.
+      owner = method.owner
+      description = (owner.descriptions[name] if owner.respond_to?(:descriptions)) ||
+        (prompt unless prompt.is_a?(Proc))
       description ? "#{signature} — #{description}" : signature
     end
 

data/lib/omakase/executor.rb

@@ -2,7 +2,7 @@
 
 module Omakase
   # Runs model-written Ruby in the agent's own context.
-  # ponytail: instance_eval is not a sandbox — see Omakase.executor to swap it.
+  # ponytail: instance_eval is not a sandbox — Subprocess isolates a crash, not File.
   module Executor
     SOURCE = "(generated)"
     RESULT = :omakase_result
@@ -23,25 +23,40 @@ module Omakase
     def call(agent, code, timeout: TIMEOUT)
       printed = StringIO.new
       answer = catch(RESULT) do
-        value = capturing(printed) { Timeout.timeout(timeout) { agent.instance_eval(code, SOURCE, 1) } }
+        value = capturing(printed) { Timeout.timeout(timeout) { evaluate(agent, code) } }
         return observation([printed.string.chomp, "=> #{value.inspect}"])
       end
       Answer.new(value: answer, printed: printed.string.chomp)
     rescue ScriptError, StandardError => e
       observation([printed.string.chomp, failure(e, code)])
+    rescue SystemExit
+      # In process, exit would end the host. exit! cannot be caught: Subprocess covers that.
+      observation([printed.string.chomp, "exit is not allowed — answer with finish(value)"])
     end
 
-    # The model can only fix what it can locate, so point at the line.
+    # Inside a generation the inputs are locals; outside one, plain instance_eval.
+    def evaluate(agent, code)
+      scope = agent.respond_to?(:omakase_scope, true) && agent.send(:omakase_scope)
+      scope ? scope.eval(code, SOURCE, 1) : agent.instance_eval(code, SOURCE, 1)
+    end
+
+    # The model can only fix what it can locate, so point at the line. A
+    # SyntaxError has no generated frame to point from.
     def failure(error, code)
-      line = error.backtrace&.grep(TRACE)&.first&.slice(/:(\d+)/, 1)&.to_i
-      source = code.lines[line - 1]&.strip if line&.positive?
-      ["#{error.class}: #{error.message}", ("line #{line}: #{source}" if source)].compact.join("\n")
+      message = "#{error.class}: #{error.message}"
+      line = error.backtrace.grep(TRACE).first&.slice(/:(\d+)/, 1)&.to_i
+      return message unless line
+
+      "#{message}\nline #{line}: #{code.lines[line - 1].to_s.strip}"
     end
 
+    # Head and tail: the error or the value comes last, and it is what the model needs next.
     def observation(parts)
       text = parts.reject(&:empty?).join("\n")
-      text = "#{text[0, MAX_OUTPUT]}\n… (truncated)" if text.length > MAX_OUTPUT
-      text.empty? ? "(no output)" : text
+      return text if text.length <= MAX_OUTPUT
+
+      half = MAX_OUTPUT / 2
+      "#{text[0, half]}\n… (#{text.length - MAX_OUTPUT} characters truncated)\n#{text[-half..]}"
     end
 
     # Thread-local, so concurrent agents never share a buffer. Agent#puts reads it.
@@ -52,5 +67,127 @@ module Omakase
     ensure
       Thread.current[OUTPUT] = previous
     end
+
+    # Generated code runs in a child process so a timeout, a crash, or a
+    # runaway loop cannot take the parent with it. The child is a copy of
+    # this process — it can still reach ActiveRecord, ENV, and the disk.
+    # That is isolation of fate, not of capability. Untrusted input still
+    # belongs to :predict.
+    #
+    # Ivars written in the child are marshalled back one at a time, so a
+    # generation's second tool call sees what the first one set. Methods
+    # the model defined on the object die with the child.
+    module Subprocess
+      module_function
+
+      def call(agent, code, timeout: TIMEOUT)
+        IO.pipe(binmode: true) do |reader, writer|
+          pid = fork do
+            reader.close
+            # Own process group, so a timeout can kill grandchildren too.
+            Process.setsid
+            # Parent owns the deadline; Timeout here would race it.
+            payload = pack(agent, Executor.call(agent, code, timeout: nil))
+            writer.write([payload.bytesize].pack("N"), payload)
+          ensure
+            exit! 0
+          end
+          writer.close
+          collect(reader, agent, pid, clock + timeout)
+        end
+      end
+
+      def collect(reader, agent, pid, deadline)
+        payload = read_packet(reader, deadline)
+        stop(pid) if payload == :timeout
+        status = reap(pid)
+        case payload
+        when :timeout then "execution timed out"
+        when :eof then "child process #{fate(status)}"
+        else unpack(agent, payload)
+        end
+      end
+
+      def pack(agent, result)
+        kept, dropped = agent.marshal_dump.partition { |_, value| marshalable?(value) }
+        result = note_dropped(result, dropped.map(&:first))
+        Marshal.dump({result: carry(result), state: kept.to_h})
+      end
+
+      def marshalable?(value)
+        Marshal.dump(value)
+        true
+      rescue TypeError
+        false
+      end
+
+      # A dropped ivar turns the answer into an observation: silent state loss
+      # would leave the next tool call reasoning about a value that is gone.
+      def note_dropped(result, dropped)
+        return result if dropped.empty?
+
+        prior = result.is_a?(Answer) ? [result.printed, "finish #{result.value.inspect}"].reject(&:empty?).join("\n") : result
+        Executor.observation([prior, "cannot keep #{dropped.join(", ")} across the process boundary"])
+      end
+
+      # Only an Answer can fail here — an observation is a String.
+      def carry(result)
+        return result if marshalable?(result)
+
+        "cannot return #{result.value.class} across the process boundary"
+      end
+
+      def unpack(agent, payload)
+        packet = Marshal.load(payload)
+        agent.marshal_load(packet[:state])
+        packet[:result]
+      rescue ArgumentError, TypeError => e
+        "#{e.message}: a class defined in generated code does not survive the process boundary"
+      end
+
+      # Length-prefixed, so a leftover write-end cannot hang the parent.
+      def read_packet(io, deadline)
+        header = read_exactly(io, 4, deadline)
+        return header if header.is_a?(Symbol)
+
+        read_exactly(io, header.unpack1("N"), deadline)
+      end
+
+      # select is exact for a pipe, so readpartial cannot block past the deadline.
+      def read_exactly(io, n, deadline)
+        buf = "".b
+        while buf.bytesize < n
+          return :timeout unless IO.select([io], nil, nil, [deadline - clock, 0].max)
+
+          buf << io.readpartial(n - buf.bytesize)
+        end
+        buf
+      rescue EOFError
+        :eof
+      end
+
+      def clock = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      def fate(status)
+        return "was killed" if status.nil? || status.signaled?
+        return "ended without an answer" if status.success?
+
+        "exited #{status.exitstatus}"
+      end
+
+      # The child led its own group unless the deadline beat it to setsid.
+      def stop(pid)
+        Process.kill("KILL", (Process.getpgid(pid) == pid) ? -pid : pid)
+      rescue Errno::ESRCH
+        nil
+      end
+
+      # ECHILD: the host reaps children itself, with a CHLD trap.
+      def reap(pid)
+        Process.wait2(pid).last
+      rescue Errno::ECHILD
+        nil
+      end
+    end
   end
 end

data/lib/omakase/fake_chat.rb

@@ -9,9 +9,22 @@ module Omakase
   # The script receives the chat, so it can drive the tool the way a model would:
   #
   #   Omakase::FakeChat.new { |chat| chat.run("finish(42)") }
+  #
+  # Or one reply per model turn, in order; a turn past the last one raises:
+  #
+  #   Omakase::FakeChat.replies("prose, not JSON", {"result" => 42})
   class FakeChat
     Response = Struct.new(:content)
 
+    def self.replies(*replies)
+      new do |chat|
+        raise Error, "FakeChat: no scripted reply left for turn #{chat.tasks.size}" if replies.empty?
+
+        reply = replies.shift
+        reply.respond_to?(:call) ? reply.call(chat) : reply
+      end
+    end
+
     attr_reader :instructions, :schema, :tools, :tasks, :attachments
 
     def initialize(&script)
@@ -20,20 +33,32 @@ module Omakase
       @tools = []
       @tasks = []
       @attachments = []
+      @complete = true
     end
 
-    def with_instructions(text) = tap { @instructions << text }
+    # A log of every call — the real chat replaces unless `append:`.
+    def with_instructions(text, **) = tap { @instructions << text }
 
     def with_schema(schema) = tap { @schema = schema }
 
-    def with_tool(tool, **) = tap { @tools << tool }
+    def with_tools(*tools) = tap { @tools.concat(tools) }
 
-    def ask(task, with: nil)
+    def ask(task, with: nil) = ask_later(task, with:).step
+
+    def ask_later(task, with: nil)
       @tasks << task
       @attachments << with if with
+      tap { @complete = false }
+    end
+
+    # The whole script is one step: it answers, so the chat is then complete.
+    def step
+      @complete = true
       Response.new(@script.call(self))
     end
 
+    def complete? = @complete
+
     # Run code the way the model would, through the agent's one tool.
     def run(code) = tools.fetch(0).call(code:)
   end

data/lib/omakase/mcp.rb

@@ -4,19 +4,91 @@ module Omakase
   # An MCP server's tools, as methods on the agent — so generated code calls a
   # remote tool the same way it calls anything else the agent exposes.
   module MCP
+    LOCKS = Mutex.new
+    # A tool name landing on a method is your bug, not a sidecar being down —
+    # and both arrive as an Error out of the same call.
+    Clash = Class.new(Error)
+
+    class << self
+      def client_factory=(factory)
+        unless factory.nil? || factory.respond_to?(:call)
+          raise Error, "client_factory must answer call, got #{factory.class}"
+        end
+
+        @client_factory = factory
+      end
+
+      def client_factory
+        @client_factory || ->(name, **options) {
+          require "ruby_llm/mcp"
+          RubyLLM::MCP.add_client(name: name.to_s, **options)
+        }
+      end
+    end
+
     module_function
 
+    def defer(agent_class, name, options)
+      servers(agent_class)[name.to_sym] = options
+    end
+
+    def ensure(agent_class)
+      return unless pending?(agent_class)
+
+      agent_class.ancestors.take_while { |mod| mod != Agent }.reverse_each do |klass|
+        next unless klass.is_a?(Class)
+
+        mutex_for(klass).synchronize { attach_pending(klass) }
+      end
+    end
+
+    def pending?(agent_class)
+      agent_class.ancestors.take_while { |mod| mod != Agent }.any? do |mod|
+        mod.is_a?(Class) && (servers(mod).keys - attached(mod)).any?
+      end
+    end
+
+    def attach_pending(klass)
+      servers(klass).each do |name, options|
+        next if attached(klass).include?(name)
+
+        # A down sidecar stays unattached — connecting and listing its tools are
+        # the same trip. The generate still runs. Next ensure retries. A name
+        # clash is not the sidecar being down, it is your bug, so it raises.
+        begin
+          attach(klass, client_factory.call(name, **options))
+        rescue Clash
+          raise
+        rescue => e
+          Omakase.emit(:mcp, agent: klass, name:, error: e)
+          next
+        end
+        attached(klass) << name
+      end
+    end
+
     def attach(agent_class, client)
+      defined = []
       client.tools.each do |tool|
         name = method_name(tool)
         # A remote tool list must not quietly shadow a capability the agent already has.
-        raise Error, "#{agent_class} already has ##{name}" if Capabilities.names(agent_class).include?(name)
+        raise Clash, "#{agent_class} already has ##{name}" if Capabilities.names(agent_class).include?(name)
 
         agent_class.describe(description(tool))
         # nil is how a model leaves an argument out; MCP servers reject it.
         agent_class.define_method(name) { |**arguments| MCP.result(tool.execute(**arguments.compact)) }
+        defined << name
       end
       client
+    rescue
+      # Else the next ensure dies on "already has #name".
+      defined.each do |name|
+        agent_class.send(:remove_method, name)
+        agent_class.descriptions.delete(name)
+      end
+      agent_class.instance_variable_set(:@pending_description, nil)
+      client.close if client.respond_to?(:close)
+      raise
     end
 
     # Tool names may hold characters a Ruby method name cannot.
@@ -39,5 +111,22 @@ module Omakase
       text = tool.description.to_s.gsub(/\s+/, " ").strip
       [text, ("Arguments — #{arguments.join(", ")}" if arguments.any?)].compact.join(" ")
     end
+
+    def mutex_for(klass)
+      mutex = klass.instance_variable_get(:@mcp_mutex)
+      return mutex if mutex
+
+      LOCKS.synchronize do
+        klass.instance_variable_get(:@mcp_mutex) || klass.instance_variable_set(:@mcp_mutex, Mutex.new)
+      end
+    end
+
+    def servers(klass)
+      klass.instance_variable_get(:@mcp_servers) || klass.instance_variable_set(:@mcp_servers, {})
+    end
+
+    def attached(klass)
+      klass.instance_variable_get(:@mcp_attached) || klass.instance_variable_set(:@mcp_attached, [])
+    end
   end
 end

data/lib/omakase/request.rb

@@ -7,17 +7,21 @@ module Omakase
 
     def schema = generation.schema
 
-    def instructions = [agent.class.instructions, agent.context].reject { |text| text.to_s.empty? }.join("\n\n")
+    def instructions = agent.class.instructions
+
+    # Rebuilt on every call, so it goes after what a provider can cache.
+    def context = agent.context.to_s
 
     # `with:` is reserved: files for the model to look at, passed through to
     # RubyLLM's `ask(with:)` as attachments rather than rendered into the text.
     def attachments = inputs[:with]
 
-    def task
+    # With `preview:`, the model's code holds the inputs, so the prompt only shows them.
+    def task(preview: false)
       arguments = inputs.except(:with)
       return prompt if arguments.empty?
 
-      lines = arguments.map { |name, value| "- #{name}: #{value.inspect}" }
+      lines = arguments.map { |name, value| "- #{name}: #{preview ? shorten(value.inspect) : value.inspect}" }
       "#{prompt}\n\nInputs:\n#{lines.join("\n")}"
     end
 
@@ -27,5 +31,13 @@ module Omakase
       text = generation.prompt
       text.is_a?(Proc) ? agent.instance_exec(&text) : text
     end
+
+    # Past the limit, code_act shows the start of an input: the whole value is a local.
+    # ponytail: inspects the whole value, then cuts; a bounded printer if a huge input shows up in a profile.
+    def shorten(text, limit = 500)
+      return text if text.length <= limit
+
+      "#{text[0, limit]}… (#{text.length} characters — the whole value is in the local)"
+    end
   end
 end

data/lib/omakase/schema.rb

@@ -43,9 +43,10 @@ module Omakase
 
     # From the provider's JSON: unwrap first, then hold it to the contract.
     def cast(content)
+      content = parse(content) if content.is_a?(String)
       raise ContractError, "expected JSON matching #{JSON.generate(json)}, got #{content.inspect}" unless content.is_a?(Hash)
 
-      data = RubyLLM::Utils.deep_symbolize_keys(content)
+      data = symbolize(content)
       take(wrapped? ? data.fetch(RESULT) { raise ContractError, %(missing "result" in #{data.inspect}) } : data)
     end
 
@@ -54,9 +55,9 @@ module Omakase
       return demand(value, properties.fetch("result")["type"]) if wrapped?
       raise ContractError, "expected #{describe}, got #{value.inspect}" unless value.is_a?(Hash)
 
-      data = RubyLLM::Utils.deep_symbolize_keys(value)
-      missing = json.fetch("required").map(&:to_sym) - data.keys
-      raise ContractError, "missing #{missing.join(", ")} — expected #{describe}" if missing.any?
+      data = symbolize(value)
+      problem = object_mismatch(data, json, nil)
+      raise ContractError, "#{problem} — expected #{describe}" if problem
 
       data
     end
@@ -67,11 +68,60 @@ module Omakase
 
     def properties = json.fetch("properties")
 
+    # RubyLLM 2 hands structured output back as a JSON string. Not JSON stays a
+    # String, so cast reports what the model actually said.
+    def parse(content)
+      JSON.parse(content)
+    rescue JSON::ParserError
+      content
+    end
+
+    def symbolize(value)
+      case value
+      when Hash then value.to_h { |key, item| [key.respond_to?(:to_sym) ? key.to_sym : key, symbolize(item)] }
+      when Array then value.map { |item| symbolize(item) }
+      else value
+      end
+    end
+
     def demand(value, type)
-      matched = (type == "boolean") ? [true, false].include?(value) : value.is_a?(RUBY_TYPES.fetch(type))
-      raise ContractError, "expected <#{type}>, got #{value.inspect}" unless matched
+      raise ContractError, "expected <#{type}>, got #{value.inspect}" unless type?(value, type)
 
       value
     end
+
+    def type?(value, type)
+      case type
+      when "boolean" then [true, false].include?(value)
+      when "null" then value.nil?
+      when Array then type.any? { |each| type?(value, each) }
+      else value.is_a?(RUBY_TYPES.fetch(type, BasicObject))
+      end
+    end
+
+    # The first place a nested value breaks its schema, as a path the model can fix.
+    def mismatch(value, spec, path)
+      return "#{path}: expected <#{Array(spec["type"]).join("|")}>, got #{value.inspect}" if spec["type"] && !type?(value, spec["type"])
+      return "#{path}: expected one of #{spec["enum"].inspect}, got #{value.inspect}" if spec["enum"] && !spec["enum"].include?(value)
+
+      case value
+      when Array then value.each_with_index.filter_map { |item, i| mismatch(item, spec["items"], "#{path}[#{i}]") if spec["items"] }.first
+      when Hash then object_mismatch(value, spec, path)
+      end
+    end
+
+    # An optional field left nil is a field left out, which is allowed.
+    def object_mismatch(value, spec, path)
+      required = Array(spec["required"])
+      missing = required.map(&:to_sym) - value.keys
+      return [path, "missing #{missing.join(", ")}"].compact.join(": ") if missing.any?
+
+      Hash(spec["properties"]).filter_map do |name, child|
+        field = value[name.to_sym]
+        next if field.nil? && !required.include?(name)
+
+        mismatch(field, child, [path, name].compact.join(".")) if value.key?(name.to_sym)
+      end.first
+    end
   end
 end

data/lib/omakase/skills/how_to_act/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: how-to-act
+description: How to write the Ruby that implements a generation — finish, prints, doc, ivars. Call once before you act.
+---
+
+You write Ruby. It runs on the agent: its methods and ivars are yours, on self.
+
+Call a method. Print what you need to see. `finish` with the answer — the value, not a sentence about it.
+
+```ruby
+orders = orders_for("ada@example.com")
+orders.each { |o| puts "total: #{o.total}" }
+puts policy_on(:damage)
+finish(Refund.new(order_id: 1, amount: 39.9, reason: "cracked mug, policy :damage"))
+```
+
+Without `finish`, the last expression comes back as `=> …` and you keep going.
+
+```ruby
+stock_of("apple") + stock_of("pear")
+# => 7
+```
+
+The inputs are local variables. Locals and ivars last for the rest of this generation:
+
+```ruby
+n = items.sum { |item| stock_of(item) }
+# later:
+finish(n + 1)
+```
+
+An object you do not know:
+
+```ruby
+doc(orders.first)   # a class works too
+```
+
+For meaning — classify, judge, summarize — call a generation method, not a regex. Never type out large data by hand: compute it or take it from an input.
+
+Prints come back to you, not to the process. If `finish` is refused, the message says why — fix it in the next call. Do not retype a value you already computed. Work in as few calls as you can.

data/lib/omakase/skills.rb

@@ -6,11 +6,18 @@ module Omakase
   # capabilities; the body only arrives when the model calls the method — which
   # is all "loaded on demand" has to mean.
   module Skills
+    CORE = File.expand_path("skills/how_to_act", __dir__)
+
     module_function
 
+    # Every agent gets the how-to. Skip when a parent already defined it.
+    def attach_core(agent_class)
+      attach(agent_class, CORE) unless Capabilities.names(agent_class).include?(:how_to_act)
+    end
+
     def attach(agent_class, path)
       directory = File.expand_path(path)
-      front_matter, body = parse(File.read(File.join(directory, "SKILL.md")))
+      front_matter, body = parse(File.read(File.join(directory, "SKILL.md"), encoding: "UTF-8"))
       name = (front_matter["name"] || File.basename(directory)).tr("-", "_").to_sym
       raise Error, "#{agent_class} already has ##{name}" if Capabilities.names(agent_class).include?(name)
 
@@ -19,12 +26,19 @@ module Omakase
       name
     end
 
-    # The front matter every SKILL.md in the wild is written with.
+    # The front matter every SKILL.md in the wild is written with — CRLF too.
     def parse(text)
-      match = text.match(/\A---\n(.*?)\n---\n(.*)\z/m)
+      match = text.match(/\A---\r?\n(.*?)\r?\n---\r?\n(.*)\z/m)
       return [{}, text.strip] unless match
 
-      [YAML.safe_load(match[1]), match[2].strip]
+      [front_matter(match[1]), match[2].strip]
+    end
+
+    # Claude Code style hints like `argument-hint: "<x>" [-p]` are not YAML; read those line by line.
+    def front_matter(text)
+      YAML.safe_load(text)
+    rescue Psych::SyntaxError
+      text.scan(/^([\w-]+):[ \t]*(.*?)\r?$/).to_h
     end
   end
 end

data/lib/omakase/strategies/code_act.rb

@@ -9,14 +9,16 @@ module Omakase
 
       def call(request)
         tool = Tools::Ruby.new(request.agent, request.schema)
-        notes = request.chat
-          .with_instructions(instructions(request))
-          .with_tool(tool)
-          .ask(request.task, with: request.attachments)
-          .content
-
+        chat = Predict.instruct(request.chat, instructions(request), request.context)
+          .with_tools(tool)
+          .ask_later(request.task(preview: true), with: request.attachments)
+        response = run(chat, tool)
+        # A text reply is usually a model that forgot how to answer, not one that is done.
+        response = run(chat.ask_later(nudge(request)), tool) unless tool.done?
         return tool.answer.value if tool.answer
 
+        notes = response&.content
+
         # It never called finish. A JSON answer can still be given in a tool-free turn.
         return Predict.call(request, task: "#{request.task}\n\nWork done:\n#{notes}") unless request.schema.code_only?
 
@@ -24,18 +26,33 @@ module Omakase
         raise ContractError, "#{request.generation.name}: the model never called finish(#{request.schema.describe})"
       end
 
+      def run(chat, tool)
+        response = nil
+        response = chat.step until chat.complete? || tool.done?
+        response
+      end
+
+      def nudge(request)
+        "Your reply was text with no tool call, so the task is not done. " \
+          "Call the `ruby` tool and end with finish(#{request.schema.describe})."
+      end
+
+      # Nothing here changes between calls of one generation, so providers can cache it.
       def instructions(request)
         <<~TEXT
           #{request.instructions}
 
           You act by writing Ruby: call the `ruby` tool with code that is evaluated on the
-          agent object, so its methods and state are available on self.
+          agent object, so its methods and state are available on self. The inputs are
+          local variables in that code — use them, do not retype them.
 
           #{capabilities(request).join("\n")}
 
           `doc(object)` prints what an object of an unfamiliar type offers; a class works too.
+          `how_to_act` is the rest, with examples — call it once before you write code.
 
-          Return the answer from inside the code, never as a message — the last thing you run is:
+          Run the task; do not define a method for it. Return the answer from inside the
+          code, never as a message — the last thing you run is:
 
               finish(#{request.schema.describe})
 

data/lib/omakase/strategies/predict.rb

@@ -9,8 +9,7 @@ module Omakase
       module_function
 
       def call(request, task: request.task)
-        chat = request.chat
-          .with_instructions(instructions(request))
+        chat = instruct(request.chat, instructions(request), request.context)
           .with_schema(request.schema.definition)
 
         request.schema.cast(chat.ask(task, with: request.attachments).content)
@@ -19,6 +18,13 @@ module Omakase
         request.schema.cast(chat.ask("#{e.message}\n\n#{CORRECTION}").content)
       end
 
+      # The stable text first and marked for the cache; the context, which
+      # changes from call to call, after it.
+      def instruct(chat, stable, context)
+        chat = chat.with_instructions(stable, cache_until_here: true)
+        context.empty? ? chat : chat.with_instructions(context, append: true)
+      end
+
       # Weaker providers treat the schema as a hint, so it goes in the prompt too.
       def instructions(request)
         "#{request.instructions}\n\nAnswer as JSON matching this schema:\n#{JSON.generate(request.schema.json)}"

data/lib/omakase/tools/ruby.rb

@@ -6,6 +6,8 @@ module Omakase
     # through it, so the model composes calls in code instead of one per turn.
     class Ruby < RubyLLM::Tool
       BUDGET = 10
+      # Only a fence around the whole code: one inside it is part of a string.
+      FENCE = /\A```(?:ruby|rb)?[ \t]*\r?\n(.*?)\r?\n?```\z/m
 
       description <<~TEXT
         Evaluate Ruby in the context of the agent object: its methods and state are
@@ -13,7 +15,7 @@ module Omakase
         expression, is returned to you. Call finish(value) to answer.
       TEXT
 
-      param :code, desc: "Ruby source to evaluate."
+      parameter :code, description: "Ruby source to evaluate."
 
       attr_reader :answer
 
@@ -29,11 +31,17 @@ module Omakase
 
       def name = "ruby"
 
+      # RubyLLM 2 tools cannot end the loop, so the strategy asks this between steps.
+      def done? = !@answer.nil? || @calls > @budget + 1
+
       def execute(code:)
+        code = code.strip[FENCE, 1] || code
         # Nothing bounds the provider's tool loop, so the budget does.
         @calls += 1
         return "No tool calls left — answer with what you have." if @calls == @budget + 1
-        return halt("Tool budget spent.") if @calls > @budget + 1
+        return "Tool budget spent." if @calls > @budget + 1
+        # A later call in the same round must not act on an agent that has answered.
+        return "Answer already accepted." if @answer
 
         outcome = @executor.call(@agent, code, timeout: @timeout)
         Omakase.emit(:ruby, agent: @agent, code:, outcome:)
@@ -42,7 +50,7 @@ module Omakase
         raise Error, "executor must return a String or Executor::Answer, got #{outcome.class}" unless outcome.is_a?(Executor::Answer)
 
         @answer = Executor::Answer.new(value: @schema.take(outcome.value), printed: outcome.printed)
-        halt("Answer accepted.")
+        "Answer accepted."
       rescue ContractError => e
         # Off-contract answers are corrected inside the same loop, not by another request.
         # Anything else — a broken executor, a bad configuration — is not the model's to fix.

data/lib/omakase/trace.rb

@@ -5,7 +5,7 @@ module Omakase
   # 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.
   class Trace
-    COLOURS = {generation: 36, ruby: 33, answer: 32}.freeze
+    COLOURS = {generation: 36, ruby: 33, answer: 32, error: 31, mcp: 31}.freeze
     LIMIT = 800
 
     def initialize(io: $stderr)
@@ -18,11 +18,16 @@ module Omakase
       when :generation then ["→ #{agent.class}##{payload[:name]}", inputs(payload[:inputs])]
       when :ruby then ["· ruby", "#{payload[:code].strip}\n#{outcome(payload[:outcome])}"]
       when :answer then ["← #{agent.class}##{payload[:name]}", truncate(payload[:value].inspect)]
+      when :error then ["✗ #{agent.class}##{payload[:name]}", truncate("#{payload[:error].class}: #{payload[:error].message}")]
+      # A down sidecar is not an error the run raises, so nothing else would say it.
+      when :mcp then ["! #{agent} mcp #{payload[:name]}", truncate(payload[:error].message)]
       else return # a listener that raises takes the run down with it
       end
 
-      @io.puts(paint(event, head))
-      @io.puts(body.gsub(/^/, "    ")) unless body.empty?
+      # A generation called from generated code sits inside its caller's.
+      indent = "    " * [(Thread.current[Agent::RUNNING]&.size || 1) - 1, 0].max
+      @io.puts(indent + paint(event, head))
+      @io.puts(body.gsub(/^/, "#{indent}    ")) unless body.empty?
     end
 
     private

data/lib/omakase/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Omakase
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/omakase.rb

@@ -21,6 +21,8 @@ module Omakase
   ContractError = Class.new(Error)
   # The model or its provider failed. RubyLLM has already retried what it retries.
   ProviderError = Class.new(Error)
+  # What RubyLLM.chat itself takes; every other option is a `with_*` call on the chat.
+  CHAT_ARGUMENTS = %i[model provider protocol assume_model_exists context].freeze
 
   class << self
     # Providers, keys, default model, timeouts, logging — all of it is RubyLLM's.
@@ -45,7 +47,8 @@ module Omakase
     end
 
     # Where generated code runs. Anything answering `call(agent, code, timeout:)`
-    # will do — swap in a subprocess or a container to get real isolation.
+    # will do — Executor::Subprocess is the reference: a child process, so a
+    # timeout cannot take this one with it.
     def executor=(executor)
       @executor = callable!(executor, "executor")
     end
@@ -67,7 +70,27 @@ module Omakase
       @chat_factory = callable!(factory, "chat_factory")
     end
 
-    def chat_factory = @chat_factory ||= ->(**options) { RubyLLM.chat(**options) }
+    def chat_factory = @chat_factory ||= method(:build_chat)
+
+    # `caching: true`, `thinking: {effort: :high}`, `temperature: 0.2` become the
+    # chat's own with_* calls. Caching is on unless you say `caching: false`: the
+    # tool loop resends the whole chat on every step.
+    def build_chat(**options)
+      chat = RubyLLM.chat(**options.slice(*CHAT_ARGUMENTS))
+      {caching: true, **options.except(*CHAT_ARGUMENTS)}.each do |name, value|
+        setter = :"with_#{name}"
+        raise Error, "unknown chat option #{name}: RubyLLM::Chat has no ##{setter}" unless chat.respond_to?(setter)
+
+        keywords = chat.method(setter).parameters.any? { |kind, _| kind == :keyrest }
+        case value
+        when true then chat.public_send(setter)
+        when Array then chat.public_send(setter, *value)
+        when Hash then keywords ? chat.public_send(setter, **value) : chat.public_send(setter, value)
+        else chat.public_send(setter, value)
+        end
+      end
+      chat
+    end
 
     # Every step, as it happens: a generation starts, model-written code runs,
     # an answer lands. Anything answering `call(event, **payload)` will do —

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omakase-agents
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - eugeny
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-16 00:00:00.000000000 Z
+date: 2026-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: schematist
   requirement: !ruby/object:Gem::Requirement
@@ -79,6 +79,7 @@ files:
 - lib/omakase/request.rb
 - lib/omakase/schema.rb
 - lib/omakase/skills.rb
+- lib/omakase/skills/how_to_act/SKILL.md
 - lib/omakase/strategies.rb
 - lib/omakase/strategies/code_act.rb
 - lib/omakase/strategies/predict.rb