omakase-agents 0.2.0 → 0.4.0

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.
+          `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:)
@@ -41,8 +49,8 @@ module Omakase
         # The seam's contract, checked here so a wrong executor cannot reach the model.
         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))
-        halt("Answer accepted.")
+        @answer = Executor::Answer.new(value: @schema.take(outcome.value), printed: outcome.printed)
+        "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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Omakase
+  # 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.
+  class Trace
+    COLOURS = {generation: 36, ruby: 33, answer: 32, error: 31, mcp: 31}.freeze
+    LIMIT = 800
+
+    def initialize(io: $stderr)
+      @io = io
+      @colour = io.respond_to?(:tty?) && io.tty?
+    end
+
+    def call(event, agent:, **payload)
+      head, body = case event
+      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
+
+      # 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
+
+    def inputs(inputs) = inputs.map { |name, value| "#{name}: #{truncate(value.inspect)}" }.join("\n")
+
+    # An Answer is `finish(value)` ending the run — with anything printed before it,
+    # which the tool result never carries because the run is over. Otherwise the
+    # outcome is already the text the model reads.
+    def outcome(outcome)
+      return truncate(outcome.to_s) unless outcome.is_a?(Executor::Answer)
+
+      truncate([outcome.printed, "finish #{outcome.value.inspect}"].reject(&:empty?).join("\n"))
+    end
+
+    def truncate(text) = (text.length > LIMIT) ? "#{text[0, LIMIT]}…" : text
+
+    def paint(event, text) = @colour ? "\e[#{COLOURS.fetch(event)}m#{text}\e[0m" : text
+  end
+end

data/lib/omakase/type.rb

@@ -20,9 +20,9 @@ module Omakase
     def code_only? = true
 
     def take(value)
-      return value if value.is_a?(@klass)
+      raise ContractError, "expected #{describe}, got #{value.class}" unless value.is_a?(@klass)
 
-      raise ContractError, "expected #{describe}, got #{value.class}"
+      well_formed(value)
     end
 
     def definition
@@ -30,5 +30,18 @@ module Omakase
     end
 
     alias_method :json, :definition
+
+    private
+
+    # An object that can say whether it is well-formed gets asked — ActiveModel,
+    # ActiveRecord, anything of that shape. The refusal reaches the model as an
+    # observation, so your own validations are what it has to satisfy, and they
+    # stay where you wrote them instead of being retyped into a prompt.
+    def well_formed(value)
+      return value unless value.respond_to?(:valid?) && value.respond_to?(:errors)
+      return value if value.valid?
+
+      raise ContractError, "#{@klass} is invalid: #{value.errors.full_messages.join("; ")}"
+    end
   end
 end

data/lib/omakase/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Omakase
-  VERSION = "0.2.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
@@ -60,6 +63,35 @@ module Omakase
 
     def embedder = @embedder ||= ->(text) { RubyLLM.embed(text).vectors }
 
+    # How an agent gets a chat when none was injected. Anything answering
+    # `call(**options)` will do — one line in test_helper.rb keeps a whole suite
+    # off the network, including the class-level calls a job makes.
+    def chat_factory=(factory)
+      @chat_factory = callable!(factory, "chat_factory")
+    end
+
+    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 —
     # a logger, a tracer, a test. Nil, the default, costs nothing.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: omakase-agents
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - eugeny
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-13 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,10 +79,12 @@ 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
 - lib/omakase/tools/ruby.rb
+- lib/omakase/trace.rb
 - lib/omakase/type.rb
 - lib/omakase/version.rb
 homepage: https://github.com/esshka/omakase