mistri 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e553e955f2a1263afed1b26889dbf04773916dbd6f33f9229e6db2b729dd655b
-  data.tar.gz: 98b95079d9f91b068580ac2708c362b1317452378eba99fe7643e301660ad89d
+  metadata.gz: de242bfa63b5f170166c93613fc2a2807971d45b792a6200eb60805c4f41c977
+  data.tar.gz: 362d523bba1848e2b552ece5906b1554c4a54820379c9f8e7a3e93430144a9c1
 SHA512:
-  metadata.gz: cb690580fe35c2226bfa0d86d23f77c9236e8dcb10ba3af0a7753a1d52b96c11e951d41ee647d0cf947dae1d3c82ca834105070099dec0c4bac728bcd296698b
-  data.tar.gz: 9e5be1a7fde00c351abc5f123ddfa82db8cb0ae34f14b0c6aa474b12338c587958c547d68e70280de7cda780ea4e674953e0f28681d33c17b37edd8ea1672d8e
+  metadata.gz: 2ac330d28d201397f03912c893a538e824c5889a999f7afff3dde4cca8fe8e3a1263f4b886623f6c65fa6b732eae02962e72d4d9c6e945215f2aa724af1d82cb
+  data.tar.gz: fa27dd203af02953b311a479992e82f87e526c8b825b6be057ec0c4bffc0a76172b19af11e57ed7c522a15d0f8e063724b74dd5c5173f11118e96736457c4453

data/CHANGELOG.md

@@ -5,6 +5,39 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-07-05
+
+- Mistri::Definition: agents as frontmatter markdown files. Config in
+  YAML, prompt in the body, {placeholders} filled at build time and
+  unfilled ones raise. Tool names and extra keys stay the host's
+  vocabulary.
+- Agent context: Mistri.agent(context: anything) rides the run and reaches
+  every tool handler and hook as context.app, untouched.
+- Content::Image.from_data_uri accepts base64 data: URIs directly.
+
+- OpenAI reasoning summaries keep their paragraph structure: a reasoning
+  item's summary parts join with a blank line, and the boundary streams as
+  a thinking delta, so live views match the finished text.
+
+## [0.3.0] - 2026-07-05
+
+- Sessions heal at replay: a run killed mid-tool (deploy, crash) leaves
+  tool calls without results, which providers reject on every later turn.
+  Unsettled calls now replay with a synthesized interrupted result; calls
+  parked for human approval stay open for resume. The stored log is never
+  rewritten, and context assembly now reads the store exactly once.
+- Empty completions retry: a turn that answers with no text, thinking, or
+  tool calls (an intermittent provider behavior) now retries under the
+  standard policy instead of ending the run in silence.
+- Gemini: consecutive user turns are no longer merged. Mixing a text part
+  into a functionResponse turn makes Gemini answer an empty candidate, so
+  steers and resumed prompts stay their own turns; Gemini accepts this.
+- The spawn tool takes an optional `name`: the model labels each worker,
+  and the label rides origin tags and the transcript link, so fan-out
+  streams read as `pricing-scout#a41f` instead of `spawn#a41f`.
+- The spawn tool's `model` parameter names the default child model in its
+  description, so the model's choice (or non-choice) is informed.
+
 ## [0.2.1] - 2026-07-05
 
 - The gem homepage and documentation links now point at

data/README.md

@@ -7,10 +7,12 @@
 
 <p align="center"><strong>mistri</strong>, the agent harness for Ruby applications.</p>
 
+<p align="center"><a href="https://mistri.sh">mistri.sh</a> · <a href="https://mistri.sh/docs/getting-started/">docs</a></p>
+
 <p align="center">
   <a href="https://rubygems.org/gems/mistri"><img alt="Gem Version" src="https://img.shields.io/gem/v/mistri"></a>
   <a href="https://github.com/mcheemaa/mistri/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/mcheemaa/mistri/actions/workflows/ci.yml/badge.svg"></a>
-  <a href="https://codecov.io/gh/mcheemaa/mistri"><img alt="Coverage" src="https://codecov.io/gh/mcheemaa/mistri/graph/badge.svg"></a>
+  <a href="https://codecov.io/gh/mcheemaa/mistri"><img alt="Coverage" src="https://img.shields.io/codecov/c/github/mcheemaa/mistri"></a>
   <a href="mistri.gemspec"><img alt="Ruby >= 3.2" src="https://img.shields.io/badge/ruby-%3E%3D%203.2-CC342D"></a>
   <a href="Gemfile"><img alt="Runtime dependencies: zero" src="https://img.shields.io/badge/runtime_deps-0-brightgreen"></a>
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
@@ -100,6 +102,20 @@ Mistri::Tool.define("edit_page", "Applies a page edit.") do |args|
 end
 ```
 
+Handlers and hooks can take the run's context as a second argument, and
+`context.app` carries whatever object you pass as `Mistri.agent(context:)`
+— the acting user, a tenant, a request — so tools stay authorization-aware
+without closure gymnastics:
+
+```ruby
+agent = Mistri.agent("claude-opus-4-8", tools: tools,
+                     context: { traveler: current_traveler })
+
+Mistri::Tool.define("book_hotel", "Books the chosen hotel.") do |args, context|
+  Bookings.create!(args, traveler: context.app[:traveler])
+end
+```
+
 ## Human approval
 
 Mark a tool `needs_approval: true` (or a predicate on its arguments) and the
@@ -108,12 +124,12 @@ The decision is a one-line session write from any process, any time later;
 `resume` settles it and carries on.
 
 ```ruby
-send_gift = Mistri::Tool.define("send_gift", "Sends a real gift.",
-                                needs_approval: ->(args) { args["amount"].to_i > 100 }) do |args|
-  Gifts.send!(args)
+book_hotel = Mistri::Tool.define("book_hotel", "Books the chosen hotel.",
+                                 needs_approval: ->(args) { args["total_usd"].to_i > 500 }) do |args|
+  Bookings.create!(args)
 end
 
-result = agent.run("Send Ana a $200 gift")
+result = agent.run("Book the corner suite for the Lisbon trip")
 result.awaiting_approval?   # => true; nothing executed
 
 # Days later, in a controller:
@@ -213,6 +229,20 @@ A skill is a `SKILL.md` (or flat `.md`) with `name:`/`description:`
 frontmatter, or built from database rows with
 `Mistri::Skill.new(name:, description:, body:)`.
 
+## Definitions
+
+An agent as a markdown file: YAML frontmatter for config, the body as the
+prompt, `{placeholders}` filled at build time (unfilled ones raise). Tool
+names and any extra keys stay your vocabulary; the gem only reads the
+file.
+
+```ruby
+definition = Mistri::Definition.load("app/agents/trip_planner.md")
+agent = Mistri.agent(definition.model,
+                     system: definition.render(first_name: traveler.first_name),
+                     tools: registry.build(definition.tools, traveler))
+```
+
 ## Sub-agents
 
 Delegate to a child agent with a clean context: exploration fills the
@@ -230,8 +260,9 @@ agent = Mistri.agent("claude-opus-4-8", tools: [researcher.tool])
 ```
 
 Or hand the model an open spawn tool and let it compose its own workers:
-instructions, a tool subset, and a host-allowlisted model per child.
-Several spawns in one turn fan out in parallel:
+a name for the event stream, instructions, a tool subset, and a
+host-allowlisted model per child. Several spawns in one turn fan out in
+parallel:
 
 ```ruby
 spawn = Mistri::SubAgent.spawner(provider: provider, tools: [fetch_page, search])
@@ -342,6 +373,7 @@ policy = Mistri::RetryPolicy.new(attempts: 3)
 
 ```ruby
 photo = Mistri::Content::Image.from_bytes(File.binread("chart.png"), mime_type: "image/png")
+photo = Mistri::Content::Image.from_data_uri(params[:image])   # canvases and uploads
 agent.run("What trend does this chart show?", images: [photo])
 
 Mistri.agent("gpt-5.5", provider_options: { reasoning: { effort: "high" } })
@@ -351,18 +383,21 @@ Mistri.agent("claude-opus-4-8", provider_options: { cache: false })
 ## Testing
 
 `rake test` is hermetic and fast. `rake integration` runs every feature end
-to end against real provider APIs, once per model in the matrix. Scenarios
-assert that coined codenames (a ghost of a word like `Wraithowyn` exists in
-no training data) flowed through tool results, summaries, and child agents:
-proof of information flow, not model knowledge.
+to end against real provider APIs, once per model in the matrix: an
+Anthropic, an OpenAI, and a Gemini model by default. Scenarios assert that
+coined codenames (a ghost of a word like `Wraithowyn` exists in no training
+data) flowed through tool results, summaries, and child agents: proof of
+information flow, not model knowledge.
 
 ```console
-$ MISTRI_INTEGRATION_MODELS=claude-opus-4-8,gpt-5.5 bundle exec rake integration
+$ bundle exec rake integration
+$ MISTRI_INTEGRATION_MODELS=claude-opus-4-8 bundle exec rake integration
 ```
 
 ## Roadmap
 
-`0.2.0`: an MCP client bridge, so any MCP server's tools plug into an agent.
+Next up: strict tool schemas, provider-native MCP passthrough, and the
+hardening that falls out of the first production applications.
 
 ## Credits
 

data/lib/mistri/agent.rb

@@ -30,7 +30,8 @@ module Mistri
     # return a replacement result, or nil to keep the original.
     def initialize(provider:, session: nil, system: nil, tools: [], budget: nil,
                    max_concurrency: 4, transform_context: nil, compaction: Compaction.new,
-                   retries: RetryPolicy.new, skills: [], before_tool: nil, after_tool: nil)
+                   retries: RetryPolicy.new, skills: [], before_tool: nil, after_tool: nil,
+                   context: nil)
       @provider = provider
       @session = session || Session.new(store: Stores::Memory.new)
       skills = skills.is_a?(String) ? Skills.load(skills) : Array(skills)
@@ -46,10 +47,17 @@ module Mistri
       @retries = retries || nil
       @before_tool = before_tool
       @after_tool = after_tool
+      @context = context
     end
 
     attr_reader :session
 
+    # What retries see when a completion answers nothing at all.
+    EMPTY_COMPLETION_ERROR = {
+      "type" => "EmptyCompletion",
+      "message" => "the provider returned an empty completion"
+    }.freeze
+
     # Run one exchange: append the user turn, then loop until the model
     # answers without tools, a gated tool suspends the run, the run aborts,
     # or a budget stops it.
@@ -212,9 +220,10 @@ module Mistri
                                    tools: @tools.map(&:spec), signal: signal,
                                    output_schema: output_schema, &emit)
         attempt += 1
-        if retry_turn?(message, attempt, signal)
-          pause = @retries.delay(attempt, message.error&.dig("retry_after"))
-          record_retry(message, attempt, pause, &emit)
+        error = turn_error(message)
+        if retry_turn?(error, attempt, signal)
+          pause = @retries.delay(attempt, error["retry_after"])
+          record_retry(message, error, attempt, pause, &emit)
           wait(pause, signal)
           next unless signal&.aborted?
         end
@@ -223,15 +232,29 @@ module Mistri
       end
     end
 
-    def retry_turn?(message, attempt, signal)
-      return false unless @retries && message.stop_reason == StopReason::ERROR
+    # The provider's own error when the turn failed, or a synthesized one
+    # for a completion that answers nothing: providers intermittently stop
+    # with an empty candidate, and a retry usually clears it.
+    def turn_error(message)
+      return message.error if message.stop_reason == StopReason::ERROR
+
+      EMPTY_COMPLETION_ERROR if empty_completion?(message)
+    end
+
+    def empty_completion?(message)
+      message.stop_reason == StopReason::STOP &&
+        message.content.all? { |block| block.is_a?(Content::Text) && block.text.to_s.strip.empty? }
+    end
+
+    def retry_turn?(error, attempt, signal)
+      return false unless @retries && error
       return false if signal&.aborted?
 
-      @retries.retry?(message.error, attempt)
+      @retries.retry?(error, attempt)
     end
 
-    def record_retry(message, attempt, pause, &emit)
-      @session.append("retry", "attempt" => attempt, "error" => message.error,
+    def record_retry(message, error, attempt, pause, &emit)
+      @session.append("retry", "attempt" => attempt, "error" => error,
                                "delay" => pause.round(2))
       note = format("attempt %<attempt>d failed; retrying in %<pause>.1fs",
                     attempt: attempt, pause: pause)
@@ -281,7 +304,8 @@ module Mistri
 
       results = ToolExecutor.call(calls, @tools_by_name, signal: signal,
                                                          max_concurrency: @max_concurrency,
-                                                         session: @session, emit: emit)
+                                                         session: @session, emit: emit,
+                                                         app: @context)
       context = hook_context(signal, emit)
       results.each do |call, result, seconds|
         result = rewrite(call, result, context) if @after_tool
@@ -316,7 +340,7 @@ module Mistri
     end
 
     def hook_context(signal, emit)
-      ToolContext.new(session: @session, signal: signal, emit: emit)
+      ToolContext.new(session: @session, signal: signal, emit: emit, app: @context)
     end
 
     # The tool message carries both channels; the :tool_result event exposes

data/lib/mistri/content.rb

@@ -50,6 +50,15 @@ module Mistri
       # second copy of what can be a multi-megabyte payload.
       def self.from_bytes(bytes, mime_type:) = new(data: [bytes.b].pack("m0").freeze, mime_type:)
 
+      # Browsers, canvases, and upload pipelines hand images around as
+      # data: URIs; accept them directly.
+      def self.from_data_uri(uri)
+        match = /\Adata:(?<mime>[^;,]+);base64,(?<data>.+)\z/m.match(uri.to_s)
+        raise ArgumentError, "not a base64 data: URI" unless match
+
+        new(data: match[:data].delete("\n").freeze, mime_type: match[:mime])
+      end
+
       def initialize(data:, mime_type:)
         super(data: Content.freeze_string(data), mime_type: Content.freeze_string(mime_type))
       end

data/lib/mistri/definition.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Mistri
+  # An agent definition: a markdown file whose YAML frontmatter carries the
+  # config and whose body is the prompt. Prompts stay editable prose in
+  # files a reviewer can diff; code stays out of them.
+  #
+  #   ---
+  #   role: Trip Planner
+  #   model: claude-opus-4-8
+  #   tools:
+  #     - search_flights
+  #     - book_hotel
+  #   ---
+  #   You plan trips end to end. Address the traveler as {first_name}.
+  #
+  #   definition = Mistri::Definition.load("app/agents/trip_planner.md")
+  #   agent = Mistri.agent(definition.model,
+  #                        system: definition.render(first_name: traveler.first_name),
+  #                        tools: registry.build(definition.tools, traveler))
+  #
+  # The gem reads the file; what tool names mean, and what any extra
+  # frontmatter keys mean, stays the host's vocabulary via #config.
+  class Definition
+    FRONTMATTER = /\A---\s*\n(?<yaml>.*?)\n---\s*\n(?<body>.*)\z/m
+
+    attr_reader :name, :body, :config
+
+    def self.load(path)
+      match = FRONTMATTER.match(File.read(path))
+      raise ConfigurationError, "#{path} has no frontmatter" unless match
+
+      config = YAML.safe_load(match[:yaml]) || {}
+      raise ConfigurationError, "#{path} frontmatter is not a mapping" unless config.is_a?(Hash)
+
+      new(name: File.basename(path.to_s, ".md"), config: config, body: match[:body].strip)
+    end
+
+    def initialize(name:, config:, body:)
+      @name = name.to_s
+      @config = config.freeze
+      @body = body
+      freeze
+    end
+
+    def model = config["model"]
+
+    def role = config["role"]
+
+    # Tool declarations as a name => options map. A bare list means no
+    # options; a map form carries per-tool options in the host's
+    # vocabulary (gates, caching, whatever the host honors).
+    def tools
+      raw = config["tools"]
+      entries = case raw
+                when Hash then raw.transform_values { |options| options || {} }
+                when Array then raw.to_h { |tool| [tool, {}] }
+                else {}
+                end
+      entries.transform_keys(&:to_s)
+    end
+
+    def tool_names = tools.keys
+
+    # The body with {placeholders} filled in. An unfilled placeholder
+    # raises: a prompt silently addressing "{first_name}" is worse than an
+    # error. A value of nil renders as empty, which lets optional context
+    # collapse cleanly.
+    def render(vars = {})
+      vars = vars.transform_keys(&:to_s)
+      body.gsub(/\{(\w+)\}/) do
+        vars.fetch(Regexp.last_match(1)) do |key|
+          raise ConfigurationError, "no value for {#{key}} in the #{name} definition"
+        end
+      end
+    end
+  end
+end

data/lib/mistri/providers/gemini/serializer.rb

@@ -10,26 +10,17 @@ module Mistri
       # thought signatures echo back verbatim on the exact part they arrived
       # with, but only for messages this provider produced; a foreign
       # signature would be rejected. Thinking summaries are output-only and
-      # never replay.
+      # never replay. Consecutive user turns stay separate: Gemini accepts
+      # them, and mixing a text part into a functionResponse turn makes it
+      # answer an empty candidate.
       module Serializer
         module_function
 
         def contents(history)
           groups = history.reject(&:system?).chunk_while { |a, b| a.tool? && b.tool? }
-          turns = groups.filter_map do |group|
+          groups.filter_map do |group|
             group.first.tool? ? tool_turn(group) : turn(group.first)
           end
-          merge_user_runs(turns)
-        end
-
-        # A steered run puts a user message right behind tool results, and
-        # both serialize as user turns. Gemini expects turns to alternate, so
-        # consecutive user turns merge into one.
-        def merge_user_runs(turns)
-          turns.chunk_while { |a, b| a[:role] == "user" && b[:role] == "user" }
-               .map do |run|
-            run.length == 1 ? run.first : { role: "user", parts: run.flat_map { |t| t[:parts] } }
-          end
         end
 
         def system_instruction(system)

data/lib/mistri/providers/openai/assembler.rb

@@ -25,7 +25,8 @@ module Mistri
           case record["type"]
           when "response.output_item.added" then start_item(record["item"], &)
           when "response.output_text.delta" then text_delta(record["delta"], &)
-          when "response.reasoning_summary_text.delta" then thinking_delta(record["delta"], &)
+          when "response.reasoning_summary_text.delta"
+            thinking_delta(record["delta"], record["summary_index"], &)
           when "response.function_call_arguments.delta" then arguments_delta(record["delta"], &)
           when "response.output_item.done" then finish_item(record["item"], &)
           when "response.completed", "response.incomplete", "response.failed"
@@ -83,6 +84,7 @@ module Mistri
           return unless kind
 
           @current = Builder.new(kind, @blocks.size, +"", +"")
+          @summary_part = nil
           emit_event(:"#{kind}_start", content_index: @current.index, &)
         end
 
@@ -93,9 +95,17 @@ module Mistri
           emit_event(:text_delta, content_index: @current.index, delta: delta, &)
         end
 
-        def thinking_delta(delta, &)
+        # A reasoning item carries one or more summary parts, each its own
+        # paragraph; the boundary streams as a delta so live views keep the
+        # break the finished text will have.
+        def thinking_delta(delta, part, &)
           return unless @current
 
+          if @summary_part && part && part != @summary_part
+            @current.text << "\n\n"
+            emit_event(:thinking_delta, content_index: @current.index, delta: "\n\n", &)
+          end
+          @summary_part = part if part
           @current.text << delta.to_s
           emit_event(:thinking_delta, content_index: @current.index, delta: delta, &)
         end
@@ -131,7 +141,7 @@ module Mistri
             text = Array(item["content"]).filter_map { |part| part["text"] }.join
             Content::Text.new(text: text, signature: item["id"])
           when :thinking
-            summary = Array(item["summary"]).filter_map { |part| part["text"] }.join
+            summary = Array(item["summary"]).filter_map { |part| part["text"] }.join("\n\n")
             Content::Thinking.new(thinking: summary, signature: JSON.generate(item))
           when :toolcall
             ToolCall.new(id: item["call_id"], name: item["name"],

data/lib/mistri/retry_policy.rb

@@ -11,7 +11,7 @@ module Mistri
   class RetryPolicy
     RETRYABLE_STATUSES = [408, 429, 500, 502, 503, 504, 529].freeze
     RETRYABLE_TYPES = %w[ProviderError RateLimitError OverloadedError ServerError
-                         TruncatedStream].freeze
+                         TruncatedStream EmptyCompletion].freeze
 
     attr_reader :attempts, :base, :max_delay
 

data/lib/mistri/session.rb

@@ -40,16 +40,25 @@ module Mistri
     # The conversation as the model replays it.
     def messages = replay.map(&:first)
 
+    # What a run killed mid-tool answers in place of the result it never got.
+    INTERRUPTED_RESULT = "[interrupted: the run stopped before this tool returned]"
+
     # Replay messages paired with the entry index each came from, starting at
     # the latest compaction boundary. The synthetic summary message carries a
     # nil index. Compaction places its cuts by these indexes; the full entry
-    # log stays in the store for transcript views.
+    # log stays in the store for transcript views. One store read builds the
+    # whole context, healed: a crash that left tool calls unanswered would
+    # brick every later turn with a provider rejection, so unsettled calls
+    # get a synthesized interrupted result. Calls parked for human approval
+    # stay open; resume owns those.
     def replay
-      compaction = last_compaction
+      log = entries
+      compaction = log.reverse_each.find { |entry| entry["type"] == "compaction" }
       from = compaction ? compaction["kept_from"] : 0
-      pairs = entries.each_with_index.filter_map do |entry, index|
+      pairs = log.each_with_index.filter_map do |entry, index|
         [Message.from_h(entry["message"]), index] if index >= from && entry["type"] == "message"
       end
+      pairs = heal(pairs, parked_call_ids(log))
       compaction ? [[summary_message(compaction["summary"]), nil], *pairs] : pairs
     end
 
@@ -102,6 +111,28 @@ module Mistri
 
     private
 
+    def heal(pairs, parked)
+      answered = pairs.map(&:first).select(&:tool?).to_set(&:tool_call_id)
+      pairs.flat_map do |message, index|
+        dangling = if message.assistant?
+                     message.tool_calls.reject do |call|
+                       answered.include?(call.id) || parked.include?(call.id)
+                     end
+                   else
+                     []
+                   end
+        [[message, index]] + dangling.map do |call|
+          [Message.tool(content: INTERRUPTED_RESULT, tool_call_id: call.id,
+                        tool_name: call.name), nil]
+        end
+      end
+    end
+
+    def parked_call_ids(log)
+      log.filter_map { |entry| entry.dig("call", "id") if entry["type"] == "approval_request" }
+         .to_set
+    end
+
     def summary_message(summary)
       Message.user("#{Compaction::SUMMARY_PREFACE}\n\n#{summary}")
     end

data/lib/mistri/sub_agent.rb

@@ -18,8 +18,8 @@ module Mistri
   #   )
   #   agent = Mistri::Agent.new(provider:, tools: [researcher.tool])
   #
-  # and the open spawn tool, where the model writes the child's
-  # instructions, picks a tool subset, and may name a model:
+  # and the open spawn tool, where the model composes each worker: names
+  # it, writes its instructions, picks a tool subset, and may pick a model:
   #
   #   spawn = Mistri::SubAgent.spawner(provider:, tools: [fetch_page, search])
   #
@@ -84,9 +84,10 @@ module Mistri
 
     class << self
       # The open spawn tool over a pool of tools the host allows children to
-      # use. The model may grant a tool subset by name; models: is the
-      # host's allowlist of child model ids — without one, no model choice
-      # is offered at all, so a hallucinated id can never construct a
+      # use. The model may name the worker (a display label riding origins
+      # and the transcript link) and grant a tool subset by name; models: is
+      # the host's allowlist of child model ids — without one, no model
+      # choice is offered at all, so a hallucinated id can never construct a
       # provider or land children on an expensive model.
       def spawner(provider:, tools: [], models: [], needs_approval: false, **agent_options)
         forbid_gated!(tools)
@@ -94,10 +95,11 @@ module Mistri
           raise ConfigurationError, "the spawn tool never goes in its own pool"
         end
 
+        schema = spawner_schema(tools, models, default_model(provider))
         Tool.define("spawn_agent", SPAWNER_DESCRIPTION,
-                    needs_approval: needs_approval,
-                    schema: spawner_schema(tools, models)) do |args, context|
-          run_child(label: "spawn", provider: child_provider(provider, args["model"], models),
+                    needs_approval: needs_approval, schema: schema) do |args, context|
+          run_child(label: child_label(args["name"]),
+                    provider: child_provider(provider, args["model"], models),
                     system: args.fetch("instructions"),
                     tools: pick(tools, args["tools"]),
                     task: args.fetch("task"), context: context, **agent_options)
@@ -173,22 +175,33 @@ module Mistri
         end
       end
 
-      def spawner_schema(pool, models)
+      def spawner_schema(pool, models, default)
         tool_names = pool.map(&:name)
+        fallback = default ? " (default: #{default})" : ""
         lambda do
+          string :name, "A short name for this worker, shown wherever its events appear"
           string :task, "The child's complete task", required: true
           string :instructions, "The child's system prompt", required: true
           if tool_names.any?
             array :tools, "Subset of tools to grant (default: all)",
                   items: { type: "string", enum: tool_names }
           end
-          if models.any?
-            string :model, "Model for the child (default: the configured one)",
-                   enum: models
-          end
+          string :model, "Model for the child#{fallback}", enum: models if models.any?
         end
       end
 
+      def default_model(provider)
+        provider.model if provider.respond_to?(:model)
+      end
+
+      # The label rides origins as "label#id" and joins nesting with ">",
+      # so those separators squeeze to hyphens along with whitespace.
+      def child_label(raw)
+        label = raw.to_s.gsub(/[#>\s]+/, "-").squeeze("-")[0, 32]
+        label = label.delete_prefix("-").delete_suffix("-")
+        label.empty? ? "spawn" : label
+      end
+
       def child_provider(default, requested, models)
         return default if requested.nil? || requested.to_s.empty?
         unless models.include?(requested)

data/lib/mistri/tool_context.rb

@@ -2,13 +2,24 @@
 
 module Mistri
   # What a tool handler may know about the run it executes inside: the
-  # caller's session, the abort signal, and the event stream. Handlers take
-  # it as an optional second argument — a proc ignores it invisibly, a
-  # lambda opts in by accepting two parameters. Sub-agents are built on it;
-  # any tool that spawns work, links records to the session, or streams
-  # progress can use it the same way.
-  ToolContext = Data.define(:session, :signal, :emit) do
-    def initialize(session: nil, signal: nil, emit: nil)
+  # caller's session, the abort signal, the event stream, and the host's
+  # own context object. Handlers take it as an optional second argument — a
+  # proc ignores it invisibly, a lambda opts in by accepting two
+  # parameters. Sub-agents are built on it; any tool that spawns work,
+  # links records to the session, or streams progress can use it the same
+  # way.
+  #
+  # app carries whatever the host passes as Agent.new(context:) — the
+  # acting user, a tenant, a request — untouched. The gem provides the
+  # slot, never the vocabulary:
+  #
+  #   agent = Mistri.agent("claude-opus-4-8", tools: tools,
+  #                        context: { traveler: current_traveler })
+  #   Mistri::Tool.define("book_hotel", "Books the chosen hotel.") do |args, context|
+  #     Bookings.create(args, traveler: context.app[:traveler])
+  #   end
+  ToolContext = Data.define(:session, :signal, :emit, :app) do
+    def initialize(session: nil, signal: nil, emit: nil, app: nil)
       super
     end
   end

data/lib/mistri/tool_executor.rb

@@ -16,10 +16,12 @@ module Mistri
 
     module_function
 
-    def call(calls, tools_by_name, signal: nil, max_concurrency: 4, session: nil, emit: nil)
+    def call(calls, tools_by_name, signal: nil, max_concurrency: 4, session: nil, emit: nil,
+             app: nil)
       return [] if calls.empty?
 
-      context = ToolContext.new(session: session, signal: signal, emit: thread_safe(emit))
+      context = ToolContext.new(session: session, signal: signal, emit: thread_safe(emit),
+                                app: app)
       results = Array.new(calls.length)
       queue = Queue.new
       calls.each_with_index { |call, index| queue << [call, index] }

data/lib/mistri/version.rb

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

data/lib/mistri.rb

@@ -23,6 +23,7 @@ require_relative "mistri/workspace/directory"
 require_relative "mistri/workspace/single"
 require_relative "mistri/memory"
 require_relative "mistri/tools"
+require_relative "mistri/definition"
 require_relative "mistri/skill"
 require_relative "mistri/skills"
 require_relative "mistri/tool_executor"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mistri
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Muhammad Ahmed Cheema
@@ -34,6 +34,7 @@ files:
 - lib/mistri/compaction.rb
 - lib/mistri/compactor.rb
 - lib/mistri/content.rb
+- lib/mistri/definition.rb
 - lib/mistri/edit.rb
 - lib/mistri/errors.rb
 - lib/mistri/event.rb