mistri 0.4.1 → 0.5.0

data/lib/mistri/sub_agent.rb

@@ -3,7 +3,7 @@
 module Mistri
   # Delegation with a clean context: a child agent runs on its own session
   # (the caller's store, linked in the caller's transcript), and only its
-  # final answer returns to the parent — exploration never fills the
+  # final answer returns to the parent; exploration never fills the
   # parent's window. Compaction rescues a full context after the fact;
   # spawning avoids filling it in the first place. A child session is its
   # own single-provider session, so delegating to a cheaper model is the
@@ -24,7 +24,7 @@ module Mistri
   #   spawn = Mistri::SubAgent.spawner(provider:, tools: [fetch_page, search])
   #
   # Children never receive a spawn tool: delegation is one level deep by
-  # construction. Parallel fan-out costs nothing — several spawn calls in
+  # construction. Parallel fan-out costs nothing: several spawn calls in
   # one turn run concurrently on the executor pool.
   #
   # Child events forward into the parent's stream tagged with origin
@@ -45,7 +45,7 @@ module Mistri
     attr_reader :name, :description
 
     # schema: makes the specialist answer in validated JSON (task mode
-    # underneath) — fan-out children then return a uniform shape the parent
+    # underneath), so fan-out children return a uniform shape the parent
     # synthesizes instead of five styles of prose.
     def initialize(name:, description:, provider:, system: nil, tools: [], schema: nil,
                    **agent_options)
@@ -62,7 +62,9 @@ module Mistri
 
     # The delegate tool: each call runs a fresh child and answers with its
     # final text, plus {agent, session_id} on the ui channel so a host can
-    # link the child's transcript.
+    # link the child's transcript. The model may name each run, so two
+    # parallel researchers read as "Corgi" and "Beagle" in lanes and lists
+    # instead of "researcher" twice.
     def tool
       sub = self
       blurb = "#{@description} Runs as a focused sub-agent with a clean " \
@@ -71,39 +73,41 @@ module Mistri
                                 schema: lambda {
                                   string :task, "Complete instructions for the sub-agent",
                                          required: true
+                                  string :name, "A short name for this run, shown wherever " \
+                                                "its events appear (default: the tool's name)"
                                 }) do |args, context|
-        sub.run_child(args.fetch("task"), context)
+        sub.run_child(args.fetch("task"), context, name: args["name"])
       end
     end
 
-    def run_child(task, context)
-      SubAgent.run_child(label: @name, provider: @provider, system: @system,
+    def run_child(task, context, name: nil)
+      SubAgent.run_child(label: SubAgent.sanitize_label(name, fallback: @name),
+                         provider: @provider, system: @system,
                          tools: @tools, task: task, context: context, schema: @schema,
                          **@agent_options)
     end
 
     class << self
-      # The open spawn tool over a pool of tools the host allows children to
-      # 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)
-        if tools.any? { |tool| tool.name == "spawn_agent" }
-          raise ConfigurationError, "the spawn tool never goes in its own pool"
-        end
+      # The open spawn tool: the model names each worker, grants it a tool
+      # subset from the host's pool, and may pick a type, a model, and a
+      # mode. All policy lives on Spawner; this is the front door.
+      def spawner(provider:, **)
+        Spawner.new(provider: provider, **).tool
+      end
 
-        schema = spawner_schema(tools, models, default_model(provider))
-        Tool.define("spawn_agent", SPAWNER_DESCRIPTION,
-                    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)
-        end
+      # The whole kit in one call: the spawn tool plus the management
+      # console, so a host hands its agent everything workers need.
+      def pack(provider:, console: {}, **spawner_options)
+        [spawner(provider: provider, **spawner_options), *Console.tools(**console)]
+      end
+
+      # A worker's display name, made safe for origins: the label rides
+      # them as "label#id" and nesting joins with ">", so those separators
+      # squeeze to hyphens along with whitespace. Blank falls back.
+      def sanitize_label(text, fallback:)
+        label = text.to_s.gsub(/[#>\s]+/, "-").squeeze("-")[0, 32]
+        label = label.delete_prefix("-").delete_suffix("-")
+        label.empty? ? fallback : label
       end
 
       def run_child(label:, provider:, system:, tools:, task:, context:, schema: nil,
@@ -111,16 +115,103 @@ module Mistri
         store = context.session ? context.session.store : Stores::Memory.new
         child = Session.new(store: store)
         context.session&.append("subagent", "name" => label, "session_id" => child.id)
-        agent = Agent.new(provider: provider, session: child, system: system,
-                          tools: tools, **agent_options)
-        origin = "#{label}##{child.id[0, 8]}"
-        emit = ->(event) { forward(event, origin, context) }
-        result = if schema
-                   agent.task(task, schema: schema, signal: context.signal, &emit)
-                 else
-                   agent.run(task, signal: context.signal, &emit)
-                 end
-        answer(result, label, child)
+        # An inline child runs on a signal derived from the parent's: the
+        # parent's abort cascades down through the handle, while stopping
+        # the child alone leaves the parent running.
+        signal, cascade = context.signal ? context.signal.derive : [AbortSignal.new, nil]
+        result = begin
+          execute_child(child: child, label: label, provider: provider, system: system,
+                        tools: tools, task: task, schema: schema, signal: signal,
+                        emit: context.emit, **agent_options)
+        ensure
+          context.signal&.remove_callback(cascade) if cascade
+        end
+        outcome = answer(result, label, child)
+        child.append(Child::TERMINAL, terminal(result))
+        outcome
+      end
+
+      # The host job's way back in: reconstruct provider, system, and tools
+      # from the spec through host registries, then hand them here. Reopens
+      # the child session the spawn created, runs it exactly like an inline
+      # child (started entry, lease, stop watching, terminals), streams
+      # origin-tagged events to the emit the job supplies, and reports the
+      # outcome back to the parent (see report_back). A background child
+      # runs on its own signal: the parent's turn is long over, so only
+      # stop_agent and the stop flag end it early.
+      #
+      # The child's lease is the exactly-once fence, so it is taken before
+      # anything else: refused means another process is running this child
+      # right now (a queue redelivered a live job), so leave its owner alone.
+      # Holding it, a terminal decides: present means the child was
+      # cancelled while queued or the queue retried a finished job, so
+      # there is nothing to run; absent means run, and that includes the
+      # child a crashed process left mid-run, which is exactly what queue
+      # retries are for. Either kind of no-op returns nil.
+      def run_dispatched(spec, provider:, system:, tools:, store:, emit: nil, schema: nil,
+                         **agent_options)
+        child = Session.new(store: store, id: spec.fetch("session_id"))
+        signal = AbortSignal.new
+        lease = Locks.hold(Child.lease_key(child.id),
+                           stop_key: Child.stop_key(child.id), signal: signal)
+        return nil if Mistri.locks && lease.nil?
+
+        if Child.new(name: spec.fetch("name"), session_id: child.id, store: store).finished?
+          lease&.release
+          return nil
+        end
+
+        result = execute_child(child: child, label: spec.fetch("name"), provider: provider,
+                               system: system, tools: tools, task: spec.fetch("task"),
+                               schema: schema, signal: signal, emit: emit, lease: lease,
+                               **agent_options)
+        deny_pending(result, child)
+        child.append(Child::TERMINAL, terminal(result))
+        result
+      rescue StandardError => e
+        # Completion is a contract even when the runner dies in the
+        # preamble: without this, a raise before the started entry (a lock
+        # backend down, say) would leave the child reading :queued forever,
+        # with nothing to report and nothing for a retry to heal.
+        if child && !Child.new(name: spec.fetch("name"), session_id: child.id,
+                               store: store).finished?
+          child.append(Child::TERMINAL,
+                       "status" => "failed", "error" => "#{e.class}: #{e.message}")
+        end
+        lease&.release
+        raise
+      ensure
+        report_back(spec, store, emit) if child
+      end
+
+      # A child cannot wait for a human, whichever door it entered by: any
+      # calls parked for approval are denied AND settled with the denial as
+      # their tool result, so no approval request stays open on a finished
+      # child and its transcript replays without repair.
+      def deny_pending(result, child)
+        return unless result.awaiting_approval?
+
+        result.pending.each do |call|
+          child.deny(call.id, note: "sub-agents cannot pause for human approval")
+          child.append_message(Message.tool(
+                                 content: "Denied: sub-agents cannot pause for human approval.",
+                                 tool_call_id: call.id, tool_name: call.name
+                               ))
+        end
+      end
+
+      # Every child ends by writing its own terminal entry: completion is a
+      # contract, and status stays readable from the store forever.
+      def terminal(result)
+        case result.status
+        when :completed then { "status" => "done", "report" => result.text.to_s }
+        when :aborted then { "status" => "stopped" }
+        when :awaiting_approval
+          { "status" => "failed",
+            "error" => "needed human approval, which sub-agents cannot wait for" }
+        else
+          { "status" => "failed", "error" => (result.error_message || result.status).to_s }
+        end
       end
 
       def forbid_gated!(tools)
@@ -134,11 +225,69 @@ module Mistri
 
       private
 
-      def forward(event, origin, context)
-        return unless context.emit
+      # The one hardened execution path every child goes through, whichever
+      # door it entered by. From the started entry on, every exit writes a
+      # terminal, setup failures included, or the child would read as
+      # running forever. The lease says "alive right now" to other
+      # processes and its thread watches the child's stop flag; a
+      # dispatched run hands in the lease it already holds (its run-or-not
+      # decision happened under the fence), an inline child acquires its
+      # own here. Either way, this path releases it.
+      def execute_child(child:, label:, provider:, system:, tools:, task:, schema:,
+                        signal:, emit:, lease: nil, **agent_options)
+        child.append(Child::STARTED, {})
+        lease ||= Locks.hold(Child.lease_key(child.id),
+                             stop_key: Child.stop_key(child.id), signal: signal)
+        begin
+          agent = Agent.new(provider: provider, session: child, system: system,
+                            tools: tools, **agent_options)
+          origin = "#{label}##{child.id[0, 8]}"
+          tagged = ->(event) { forward(event, origin, emit) }
+          if schema
+            agent.task(task, schema: schema, signal: signal, &tagged)
+          else
+            agent.run(task, signal: signal, &tagged)
+          end
+        rescue StandardError => e
+          child.append(Child::TERMINAL, "status" => "failed", "error" => "#{e.class}: #{e.message}")
+          raise
+        ensure
+          lease&.release
+          Mistri.locks&.clear_flag(Child.stop_key(child.id))
+        end
+      end
+
+      def forward(event, origin, emit)
+        return unless emit
 
         tagged = event.origin ? "#{origin}>#{event.origin}" : origin
-        context.emit.call(event.with(origin: tagged))
+        emit.call(event.with(origin: tagged))
+      end
+
+      # Every terminal outcome reports back, exactly once. The report joins
+      # the parent's inbox (a typed entry that folds at its next turn
+      # boundary, exactly like a steer) and a :subagent_report event
+      # closes the child's lane in whatever UI watched the spawn. A child
+      # that never ran has nothing to say, and the parent session drops a
+      # duplicate delivery, so a redelivered job cannot repeat one.
+      def report_back(spec, store, emit)
+        facade = Child.new(name: spec.fetch("name"), session_id: spec.fetch("session_id"),
+                           store: store)
+        return unless facade.finished?
+
+        status = facade.status
+        text = status == :failed ? facade.error : facade.report
+        delivered = if (parent_id = spec["parent_session_id"])
+                      Session.new(store: store, id: parent_id)
+                             .deliver_report(name: facade.name, session_id: facade.session_id,
+                                             status: status.to_s, text: text)
+                    else
+                      true
+                    end
+        return unless delivered
+
+        emit&.call(Event.new(type: :subagent_report, agent: facade.name,
+                             session_id: facade.session_id, status: status, content: text))
       end
 
       # The parent always gets an in-band answer it can react to. A child
@@ -150,68 +299,17 @@ module Mistri
         when :completed
           ToolResult.new(content: result.text.to_s, ui: link)
         when :awaiting_approval
-          result.pending.each do |call|
-            child.deny(call.id, note: "sub-agents cannot pause for human approval")
-          end
+          deny_pending(result, child)
           ToolResult.new(content: "The #{label} sub-agent stopped: it needed human " \
                                   "approval, which sub-agents cannot wait for.", ui: link)
         when :aborted
-          ToolResult.new(content: "[the #{label} sub-agent was aborted]", ui: link)
+          ToolResult.new(content: "[the #{label} sub-agent was stopped]", ui: link)
         else
           reason = result.error_message || result.status
           ToolResult.new(content: "The #{label} sub-agent failed: #{reason}", ui: link)
         end
       end
 
-      def pick(pool, names)
-        return pool if names.nil? || names.empty?
-
-        by_name = pool.to_h { |tool| [tool.name, tool] }
-        names.map do |name|
-          by_name.fetch(name) do
-            raise ArgumentError,
-                  "unknown tool #{name.inspect}; available: #{by_name.keys.join(", ")}"
-          end
-        end
-      end
-
-      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
-          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)
-          raise ArgumentError,
-                "model #{requested.inspect} is not allowed; available: #{models.join(", ")}"
-        end
-
-        Mistri.provider(requested)
-      end
-
       # A predicate gate cannot be judged statically; the runtime denial in
       # answer covers it.
       def statically_gated?(tool)

data/lib/mistri/task_output.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  # The text side of task mode: how a schema is asked for, how the answer
+  # parses, and how a violation is sent back for a fix. Pure functions over
+  # strings and schemas; Agent#task owns the loop that drives them.
+  module TaskOutput
+    # Distinguishable from a parsed nil: JSON "null" is a valid value.
+    PARSE_FAILED = Object.new.freeze
+
+    module_function
+
+    def prompt(input, schema)
+      "#{input}\n\nAnswer with ONLY a JSON value matching this schema:\n" \
+        "#{JSON.generate(Schema.strict(schema))}"
+    end
+
+    def parse(text)
+      body = text.to_s.strip
+      body = body[/\A```(?:json)?\s*(.*?)```\z/m, 1] || body
+      JSON.parse(body)
+    rescue JSON::ParserError
+      PARSE_FAILED
+    end
+
+    def errors(value, schema)
+      return ["the answer is not valid JSON"] if value.equal?(PARSE_FAILED)
+
+      Schema.violations(value, schema)
+    end
+
+    def fix_prompt(errors)
+      lines = errors.map { |error| "- #{error}" }.join("\n")
+      "Your answer did not satisfy the required output schema. Problems:\n" \
+        "#{lines}\nReply with ONLY the corrected JSON."
+    end
+  end
+end

data/lib/mistri/tool.rb

@@ -28,7 +28,7 @@ module Mistri
     end
 
     def initialize(name:, description:, input_schema: EMPTY_SCHEMA, eager_input_streaming: false,
-                   needs_approval: false, timeout: nil, &handler)
+                   needs_approval: false, ends_turn: false, timeout: nil, &handler)
       raise ArgumentError, "tool #{name.inspect} needs a handler block" unless handler
 
       @name = name.to_s
@@ -36,6 +36,7 @@ module Mistri
       @input_schema = input_schema
       @eager_input_streaming = eager_input_streaming
       @needs_approval = needs_approval
+      @ends_turn = ends_turn
       @timeout = timeout
       @handler = handler
     end
@@ -61,6 +62,14 @@ module Mistri
       @needs_approval.respond_to?(:call) ? @needs_approval.call(arguments) : @needs_approval
     end
 
+    # A tool that is the last word of its turn: once it executes, the loop
+    # ends the run instead of prompting the model again. This is how a tool
+    # like ask_user hands the floor to a human structurally, with no prompt
+    # discipline required; the answer arrives as the next run's input.
+    def ends_turn?
+      @ends_turn
+    end
+
     # The provider-facing definition; every serializer accepts this shape.
     def spec
       definition = { name: @name, description: @description, input_schema: @input_schema }

data/lib/mistri/tool_context.rb

@@ -3,14 +3,14 @@
 module Mistri
   # What a tool handler may know about the run it executes inside: the
   # 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
+  # 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
+  # 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,

data/lib/mistri/version.rb

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

data/lib/mistri.rb

@@ -14,6 +14,7 @@ require_relative "mistri/sse"
 require_relative "mistri/partial_json"
 require_relative "mistri/transport"
 require_relative "mistri/schema"
+require_relative "mistri/task_output"
 require_relative "mistri/edit"
 require_relative "mistri/tool_context"
 require_relative "mistri/tool_result"
@@ -34,10 +35,15 @@ require_relative "mistri/compaction"
 require_relative "mistri/stores/memory"
 require_relative "mistri/stores/jsonl"
 require_relative "mistri/session"
+require_relative "mistri/child"
+require_relative "mistri/locks"
+require_relative "mistri/console"
+require_relative "mistri/dispatchers"
 require_relative "mistri/compactor"
 require_relative "mistri/result"
 require_relative "mistri/agent"
 require_relative "mistri/sub_agent"
+require_relative "mistri/spawner"
 require_relative "mistri/mcp"
 require_relative "mistri/sinks/action_cable"
 require_relative "mistri/sinks/sse"
@@ -54,6 +60,11 @@ module Mistri
   API_KEY_ENV = { anthropic: "ANTHROPIC_API_KEY", openai: "OPENAI_API_KEY",
                   gemini: "GEMINI_API_KEY" }.freeze
 
+  # The configured lock adapter, nil until a host sets one. See Locks.
+  class << self
+    attr_accessor :locks
+  end
+
   module_function
 
   # Build a provider for a model, inferring which one from the model id and

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mistri
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Muhammad Ahmed Cheema
@@ -31,13 +31,18 @@ files:
 - lib/mistri/abort_signal.rb
 - lib/mistri/agent.rb
 - lib/mistri/budget.rb
+- lib/mistri/child.rb
 - lib/mistri/compaction.rb
 - lib/mistri/compactor.rb
+- lib/mistri/console.rb
 - lib/mistri/content.rb
 - lib/mistri/definition.rb
+- lib/mistri/dispatchers.rb
 - lib/mistri/edit.rb
 - lib/mistri/errors.rb
 - lib/mistri/event.rb
+- lib/mistri/locks.rb
+- lib/mistri/locks/rails_cache.rb
 - lib/mistri/mcp.rb
 - lib/mistri/mcp/client.rb
 - lib/mistri/mcp/oauth.rb
@@ -66,12 +71,14 @@ files:
 - lib/mistri/sinks/sse.rb
 - lib/mistri/skill.rb
 - lib/mistri/skills.rb
+- lib/mistri/spawner.rb
 - lib/mistri/sse.rb
 - lib/mistri/stop_reason.rb
 - lib/mistri/stores/active_record.rb
 - lib/mistri/stores/jsonl.rb
 - lib/mistri/stores/memory.rb
 - lib/mistri/sub_agent.rb
+- lib/mistri/task_output.rb
 - lib/mistri/tool.rb
 - lib/mistri/tool_call.rb
 - lib/mistri/tool_context.rb