mistri 0.4.1 → 0.6.0

data/lib/mistri/sinks/coalesced.rb

@@ -4,8 +4,10 @@ module Mistri
   module Sinks
     # Wraps any sink and merges bursts of streaming deltas, so a transport
     # broadcasts at UI speed instead of token speed. Deltas buffer per
-    # content block and flush merged when the interval elapses or any other
-    # event arrives, so ordering is preserved and a turn always ends flushed.
+    # content block per origin and flush merged when the interval elapses or
+    # any other event arrives, so ordering is preserved and a turn always
+    # ends flushed. Safe to share across threads: a background worker's
+    # events serialize with the parent's instead of racing the buffer.
     #
     #   sink = Mistri::Sinks::Coalesced.new(
     #     Mistri::Sinks::ActionCable.new("agent_1"), interval: 0.1,
@@ -18,16 +20,19 @@ module Mistri
         @interval = interval
         @buffer = nil
         @flushed_at = now
+        @mutex = Mutex.new
       end
 
       def call(event)
-        unless DELTAS.include?(event.type)
-          flush
-          return @sink.call(event)
+        @mutex.synchronize do
+          if DELTAS.include?(event.type)
+            merge(event)
+            flush if now - @flushed_at >= @interval
+          else
+            flush
+            @sink.call(event)
+          end
         end
-
-        merge(event)
-        flush if now - @flushed_at >= @interval
       end
 
       def to_proc = method(:call).to_proc
@@ -35,10 +40,12 @@ module Mistri
       private
 
       # Merged deltas keep the newest partial, so a consumer that renders
-      # snapshots always renders the latest one.
+      # snapshots always renders the latest one. Origin is part of a block's
+      # identity: two agents' lanes never fold into one event.
       def merge(event)
         same = @buffer && @buffer.type == event.type &&
-               @buffer.content_index == event.content_index
+               @buffer.content_index == event.content_index &&
+               @buffer.origin == event.origin
         flush if @buffer && !same
         @buffer = if same
                     @buffer.with(delta: @buffer.delta.to_s + event.delta.to_s,

data/lib/mistri/skill.rb

@@ -3,7 +3,7 @@
 module Mistri
   # One expert playbook: a name the model selects by, a description that
   # earns the selection, and the full body it reads before acting. Build
-  # them from anywhere — Skills.load reads a directory, and a host with
+  # them from anywhere: Skills.load reads a directory, and a host with
   # skills in a database constructs these directly.
   Skill = Data.define(:name, :description, :body) do
     def initialize(name:, description: "", body: "")

data/lib/mistri/skills.rb

@@ -3,7 +3,7 @@
 module Mistri
   # Loads skills and wires them into an agent: their one-line descriptions
   # ride the system prompt, and the model pulls a full body on demand with
-  # the read_skill tool — so a large library costs almost nothing until a
+  # the read_skill tool, so a large library costs almost nothing until a
   # skill is actually used.
   module Skills
     module_function

data/lib/mistri/spawner.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+module Mistri
+  # Host policy for spawning workers, as one object: the tool pool children
+  # may draw from, the curated types, the model allowlist, the headcount
+  # cap, and the dispatcher that makes background mode real. A host runtime
+  # factory reconstructs live dependencies after the dispatch boundary;
+  # model text never chooses or proves resource isolation. #tool builds the
+  # spawn_agent tool the top-level agent holds; SubAgent.spawner and
+  # SubAgent.pack are the front doors.
+  #
+  # Every policy violation answers the model in band (unknown type, missing
+  # instructions, over capacity); only host configuration mistakes raise,
+  # and they raise at construction.
+  class Spawner
+    def initialize(provider:, tools: [], types: {}, models: [], max_children: 4,
+                   dispatcher: nil, runtime_factory: nil, needs_approval: false,
+                   **agent_options)
+      tools = Array.new(tools) if tools.is_a?(Array)
+      models = Array.new(models) if models.is_a?(Array)
+      ChildAgentOptions.validate!(agent_options)
+      validate_configuration!(tools, models, dispatcher, runtime_factory)
+
+      @provider = provider
+      @pool = tools.freeze
+      # Symbol keys are natural Ruby; the wire speaks strings. One
+      # normalization here and lookup, schema, and menu all agree.
+      @types = types.transform_keys(&:to_s).freeze
+      @models = models.map { |model| String.new(model).freeze }.freeze
+      @max_children = max_children
+      @dispatcher = dispatcher
+      @runtime_factory = runtime_factory
+      @needs_approval = needs_approval
+      @agent_options = agent_options
+      validate_types!
+    end
+
+    def tool
+      spawner = self
+      Tool.define("spawn_agent", description, needs_approval: @needs_approval,
+                                              schema: schema) do |args, context|
+        spawner.spawn(args, context)
+      end
+    end
+
+    def spawn(args, context)
+      crowded = over_capacity(context.session)
+      return crowded if crowded
+
+      worker = resolve_worker(args)
+      return worker if worker.is_a?(String)
+
+      return dispatch(args, worker, context) if args["mode"] == "background" && @dispatcher
+
+      SubAgent.run_child(label: label_for(args), provider: provider_for(worker),
+                         system: worker[:system], tools: worker[:tools],
+                         task: args.fetch("task"), parent_context: context,
+                         agent_options: @agent_options)
+    end
+
+    private
+
+    def validate_configuration!(tools, models, dispatcher, runtime_factory)
+      validate_tool_pool!(tools)
+      validate_models!(models)
+      validate_dispatcher!(dispatcher, runtime_factory)
+    end
+
+    def validate_tool_pool!(tools)
+      unless tools.is_a?(Array) && tools.all?(Tool)
+        raise ConfigurationError, "the spawn tool pool must contain only Mistri::Tool instances"
+      end
+
+      SubAgent.forbid_gated!(tools)
+      if tools.any? { |tool| tool.name == "spawn_agent" }
+        raise ConfigurationError, "the spawn tool never goes in its own pool"
+      end
+      return if tools.map(&:name).uniq.length == tools.length
+
+      raise ConfigurationError, "the spawn tool pool has duplicate tool names"
+    end
+
+    def validate_models!(models)
+      unless models.is_a?(Array) &&
+             models.all? { |model| model.is_a?(String) && !model.empty? }
+        raise ConfigurationError, "the spawn model allowlist must contain non-empty strings"
+      end
+      return if models.uniq.length == models.length
+
+      raise ConfigurationError, "the spawn model allowlist has duplicate model names"
+    end
+
+    def validate_dispatcher!(dispatcher, runtime_factory)
+      if dispatcher && !dispatcher.respond_to?(:call)
+        raise ConfigurationError, "dispatcher must be callable"
+      end
+      if dispatcher && !runtime_factory.respond_to?(:call)
+        raise ConfigurationError,
+              "a dispatcher requires runtime_factory: to reconstruct background children"
+      end
+      return unless runtime_factory && !dispatcher
+
+      raise ConfigurationError, "runtime_factory: requires a dispatcher"
+    end
+
+    # Create the child session and its lifecycle entries, hand the
+    # dispatcher the serializable spec plus an in-process runner that calls
+    # the host factory inside the worker, and answer with a truthful receipt:
+    # what the child's status says after dispatch, not what the mode
+    # promised. The runner closes over the spawn-time emit, so in-process
+    # dispatchers keep streaming to whoever watched the spawn.
+    def dispatch(args, worker, context)
+      store = context.session ? context.session.store : Stores::Memory.new
+      child = Session.new(store: store)
+      label = label_for(args)
+      spec = spec_for(args, worker, child, label, context)
+      context.session&.append("subagent", "name" => label, "session_id" => child.id)
+      child.append(Child::DISPATCHED, "spec" => spec)
+      emit = context.emit
+      runtime_factory = @runtime_factory
+      runner = lambda do
+        SubAgent.run_dispatched(spec, runtime_factory: runtime_factory,
+                                      store: store, emit: emit,
+                                      retry_factory_errors: false)
+      end
+      @dispatcher.call(spec, runner)
+      receipt(label, child, store)
+    end
+
+    def spec_for(args, worker, child, label, context)
+      model = worker[:model]
+      unless model.is_a?(String) && !model.empty?
+        raise ConfigurationError,
+              "a background child provider must expose a non-empty model identity"
+      end
+      spec = { "spec_version" => SubAgent::DISPATCH_SPEC_VERSION,
+               "name" => label, "session_id" => child.id,
+               "parent_session_id" => context.session&.id,
+               "type" => args["type"] || "general-purpose",
+               "instructions" => args["instructions"], "task" => args.fetch("task"),
+               "tool_names" => worker[:tools].map(&:name),
+               "model" => model }
+      owned, error = ToolArguments.canonicalize(spec)
+      return owned unless error
+
+      raise ConfigurationError, "background child spec is not bounded JSON"
+    end
+
+    def receipt(label, child, store)
+      status = Child.new(name: label, session_id: child.id, store: store).status
+      state = if %i[running queued].include?(status)
+                "is working in the background"
+              else
+                "already finished (#{status})"
+              end
+      ToolResult.new(
+        content: "#{label} #{state} (agent id #{child.id[0, 8]}). Keep working: its " \
+                 "report will arrive in your context when it finishes. Meanwhile " \
+                 "read_agent checks on it (wait: true blocks for the report), " \
+                 "steer_agent adjusts it, stop_agent stops it.",
+        ui: { "agent" => label, "session_id" => child.id, "mode" => "background" }
+      )
+    end
+
+    # A worker's system prompt, tools, and provider, resolved from its
+    # type; a String answers the model in band instead of raising.
+    def resolve_worker(args)
+      type = args["type"].to_s
+      return general_worker(args) if type.empty? || type == "general-purpose"
+
+      definition = @types[type]
+      unless definition
+        return "Unknown worker type #{type.inspect}; available: " \
+               "#{["general-purpose", *@types.keys].join(", ")}."
+      end
+
+      system = [definition.render, args["instructions"]]
+               .reject { |part| part.to_s.strip.empty? }.join("\n\n")
+      chosen = args["tools"].nil? ? definition.tool_names : args["tools"]
+      { system: system, tools: pick(chosen),
+        **provider_choice(args["model"], definition.model) }
+    end
+
+    def general_worker(args)
+      system = args["instructions"].to_s
+      if system.strip.empty?
+        return "A general-purpose worker needs instructions: write its system prompt, " \
+               "or pick a type."
+      end
+
+      { system: system, tools: pick(args["tools"]), **provider_choice(args["model"]) }
+    end
+
+    # A background grant needs only a stable model identity; constructing
+    # its live provider belongs to the worker factory. Inline execution turns
+    # the same choice into a provider immediately before the child starts.
+    def provider_choice(requested, definition_model = nil)
+      if requested.nil? || requested.to_s.empty?
+        return { model: definition_model } unless definition_model.to_s.empty?
+
+        model = @provider.model if @provider.respond_to?(:model)
+        return { provider: @provider, model: model }
+      end
+      unless @models.include?(requested)
+        raise ArgumentError,
+              "model #{requested.inspect} is not allowed; available: #{@models.join(", ")}"
+      end
+
+      { model: requested }
+    end
+
+    def provider_for(worker)
+      worker[:provider] || Mistri.provider(worker.fetch(:model))
+    end
+
+    def over_capacity(session)
+      return nil unless session
+
+      busy = session.children.count { |child| Child::LIVE.include?(child.status) }
+      return nil if busy < @max_children
+
+      "You already have #{busy} workers running; wait for one to finish or stop one."
+    end
+
+    # Types fail at construction, never mid-spawn: every definition must
+    # render without vars (spawn types are self-contained prompts) and
+    # declare only tools the pool actually carries.
+    def validate_types!
+      return if @types.empty?
+      if @types.key?("general-purpose")
+        raise ConfigurationError, "\"general-purpose\" is the built-in type; pick another name"
+      end
+
+      pool_names = @pool.map(&:name)
+      @types.each do |name, definition|
+        begin
+          definition.render
+        rescue ConfigurationError => e
+          raise ConfigurationError,
+                "type #{name.inspect} cannot be a spawn type: #{e.message}"
+        end
+        missing = definition.tool_names - pool_names
+        unless missing.empty?
+          raise ConfigurationError,
+                "type #{name.inspect} declares tools the pool lacks: #{missing.join(", ")}"
+        end
+      end
+    end
+
+    def pick(names)
+      return @pool if names.nil?
+      if names.uniq.length != names.length
+        raise ArgumentError, "tool selections cannot contain duplicate names"
+      end
+
+      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 schema
+      pool_names = @pool.map(&:name)
+      type_names = ["general-purpose", *@types.keys]
+      types = @types
+      models = @models
+      dispatcher = @dispatcher
+      default = @provider.model if @provider.respond_to?(:model)
+      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
+        if types.any?
+          string :type, "The kind of worker (default: general-purpose)", enum: type_names
+          string :instructions, "The worker's system prompt (required for " \
+                                "general-purpose; appended to a typed worker's own)"
+        else
+          string :instructions, "The child's system prompt", required: true
+        end
+        if pool_names.any?
+          array :tools, "Exact tools to grant (omit for all, or the type's own list; " \
+                        "an empty list grants none)",
+                items: { type: "string", enum: pool_names }, uniqueItems: true
+        end
+        string :model, "Model for the child#{fallback}", enum: models if models.any?
+        if dispatcher
+          string :mode, "inline blocks until the report; background returns a receipt " \
+                        "now and you keep working (default: inline)",
+                 enum: %w[inline background]
+        end
+      end
+    end
+
+    def description
+      text = SubAgent::SPAWNER_DESCRIPTION
+      unless @types.empty?
+        text += " Typed workers come ready-made (#{@types.keys.join(", ")}): their " \
+                "instructions, tools, and model are set; add instructions only to " \
+                "focus them. general-purpose workers are yours to compose."
+      end
+      if @dispatcher
+        text += " Use background mode when the work is long and you can keep helping " \
+                "meanwhile: you get a receipt now, its report arrives on its own when " \
+                "the worker finishes, and the console tools manage it in between."
+      end
+      text
+    end
+
+    def label_for(args)
+      SubAgent.sanitize_label(args["name"], fallback: "spawn")
+    end
+  end
+end

data/lib/mistri/sse.rb

@@ -3,6 +3,9 @@
 require "json"
 
 module Mistri
+  DEFAULT_MAX_RECORD_BYTES = 8 * 1024 * 1024
+  private_constant :DEFAULT_MAX_RECORD_BYTES
+
   # An incremental Server-Sent Events decoder. Feed it raw socket fragments in
   # any chunking; it buffers partial lines across fragments and yields each
   # complete "data:" record as a parsed Hash.
@@ -11,40 +14,80 @@ module Mistri
   # send: one single-line JSON object per "data:" record. "event:", "id:",
   # comment, and blank lines are ignored (the event name is duplicated inside
   # the data payload), OpenAI's "[DONE]" sentinel is dropped, and a record that
-  # fails to parse is skipped rather than killing a live stream.
+  # fails to parse is skipped rather than killing a live stream. Only the
+  # partial line is bounded; the complete stream is not.
   class SSE
-    def initialize
+    def initialize(max_record_bytes: DEFAULT_MAX_RECORD_BYTES)
+      unless max_record_bytes.is_a?(Integer) && max_record_bytes.positive?
+        raise ConfigurationError, "max_record_bytes: must be a positive integer"
+      end
+
+      @max_record_bytes = max_record_bytes
       @buffer = +""
     end
 
     def feed(fragment, &)
-      @buffer << fragment
-      while (newline = @buffer.index("\n"))
-        line = @buffer.slice!(0, newline + 1)
-        decode(line.chomp, &)
+      scan = fragment.encoding == Encoding::BINARY ? fragment : fragment.b
+      offset = 0
+      while (newline = scan.index("\n", offset))
+        append(fragment, offset, newline - offset)
+        line = @buffer
+        @buffer = +""
+        line.chomp!
+        decode(line, &)
+        offset = newline + 1
       end
+      append(fragment, offset, scan.bytesize - offset)
       nil
     end
 
     # Flush a trailing record that arrived without a final newline.
     def finish(&)
-      decode(@buffer.chomp, &) unless @buffer.empty?
-      @buffer.clear
+      unless @buffer.empty?
+        line = @buffer
+        @buffer = +""
+        line.chomp!
+        decode(line, &)
+      end
       nil
     end
 
     private
 
+    def append(fragment, offset, length)
+      return if length.zero?
+
+      if @buffer.bytesize + length > @max_record_bytes
+        raise ResponseTooLargeError.new(kind: :sse_line, limit: @max_record_bytes)
+      end
+
+      @buffer << fragment.byteslice(offset, length)
+    end
+
     def decode(line)
-      return unless line.start_with?("data:")
+      return unless line.delete_prefix!("data:")
+
+      line.strip!
+      return if line.empty? || line == "[DONE]"
 
-      data = line.delete_prefix("data:").strip
-      return if data.empty? || data == "[DONE]"
+      case ToolArguments.raw_json_resource_error(line)
+      when "too_many_nodes"
+        raise ResponseTooComplexError.new(kind: :sse_record_tokens,
+                                          limit: ToolArguments::MAX_LEXICAL_TOKENS)
+      when "too_deep"
+        raise ResponseTooComplexError.new(kind: :sse_record_depth,
+                                          limit: ToolArguments::MAX_DEPTH)
+      when "number_too_large"
+        raise ResponseTooComplexError.new(kind: :sse_numeric_token,
+                                          limit: ToolArguments::MAX_NUMBER_BYTES)
+      end
 
-      decoded = JSON.parse(data)
+      decoded = begin
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
       yield decoded if decoded.is_a?(Hash)
-    rescue JSON::ParserError
-      nil
     end
   end
 end

data/lib/mistri/stores/active_record.rb

@@ -15,26 +15,41 @@ module Mistri
     #   create_table :mistri_entries do |t|
     #     t.string :session_id, null: false, index: true
     #     t.integer :position, null: false
-    #     t.text :payload, size: :medium, null: false
+    #     t.text :payload, size: :long, null: false
     #     t.timestamps
     #   end
     #   add_index :mistri_entries, [:session_id, :position], unique: true
     #
-    # The unique index is load-bearing: one session has one writer at a time
-    # (the loop is serial), and if a host ever runs two agents on one session,
-    # a colliding append raises instead of silently corrupting entry order.
+    # The unique index is load-bearing: a session's loop is serial, but other
+    # writers append alongside it by design (a steer from a web process, a
+    # background child's report from a job), so appends are optimistic. Two
+    # writers that pick the same position collide on the index and the loser
+    # retries at the next one; entry order stays intact without a lock.
     #
     # Reads select only (position, payload) and sort in Ruby: ORDER BY over
     # rows carrying multi-megabyte payloads exhausts MySQL's sort buffer.
     class ActiveRecord
+      # Concurrent writers converge in one or two retries; a session would
+      # need this many simultaneous appenders to exhaust them.
+      APPEND_ATTEMPTS = 5
+
       def initialize(model)
         @model = model
       end
 
       def append(id, entry)
-        position = @model.where(session_id: id).maximum(:position).to_i + 1
-        @model.create!(session_id: id, position: position, payload: JSON.generate(entry))
-        nil
+        payload = JSON.generate(entry)
+        attempts = 0
+        begin
+          position = @model.where(session_id: id).maximum(:position).to_i + 1
+          @model.create!(session_id: id, position: position, payload: payload)
+          nil
+        rescue ::ActiveRecord::RecordNotUnique
+          attempts += 1
+          raise if attempts >= APPEND_ATTEMPTS
+
+          retry
+        end
       end
 
       def load(id)

data/lib/mistri/stores/jsonl.rb

@@ -13,8 +13,10 @@ module Mistri
         FileUtils.mkdir_p(dir)
       end
 
+      # One write call per line: concurrent appenders (a steer, a child's
+      # report) interleave whole lines, never fragments.
       def append(id, entry)
-        File.open(path(id), "a") { |file| file.puts(JSON.generate(entry)) }
+        File.write(path(id), "#{JSON.generate(entry)}\n", mode: "a")
         nil
       end
 

data/lib/mistri/stores/memory.rb

@@ -10,12 +10,31 @@ module Mistri
       end
 
       def append(id, entry)
-        @mutex.synchronize { @entries[id] << entry }
+        @mutex.synchronize { @entries[id] << json_copy(entry, freeze: true) }
         nil
       end
 
       def load(id)
-        @mutex.synchronize { @entries[id].dup }
+        @mutex.synchronize do
+          @entries[id].map { |entry| json_copy(entry, freeze: false) }
+        end
+      end
+
+      private
+
+      # Memory must preserve the same value ownership as stores that decode
+      # every read; otherwise a transcript reader can rewrite durable history.
+      def json_copy(value, freeze:)
+        owned = case value
+                when Hash
+                  value.to_h do |key, nested|
+                    [json_copy(key, freeze:), json_copy(nested, freeze:)]
+                  end
+                when Array then value.map { |nested| json_copy(nested, freeze:) }
+                when String then value.dup
+                else value
+                end
+        freeze ? owned.freeze : owned
       end
     end
   end

data/lib/mistri/sub_agent/execution.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Mistri
+  class SubAgent
+    class << self
+      # The hardened execution path every child uses. Inline work acquires
+      # and cleans up its lease here; a dispatched owner supplies its lease
+      # and retains it through terminal persistence and parent reporting.
+      def execute_child(child:, label:, provider:, system:, tools:, task:, schema:,
+                        signal:, emit:, lease: nil, started: false, agent_options: {})
+        ChildAgentOptions.validate!(agent_options)
+        child.append(Child::STARTED, {}) unless started
+        owns_lease = lease.nil?
+        primary_error = nil
+        begin
+          lease ||= Locks.hold(Child.lease_key(child.id),
+                               stop_key: Child.stop_key(child.id), signal: signal)
+          abort_before_child_start!(child, signal, lease)
+          if signal.aborted?
+            Result.new(message: nil, status: :aborted)
+          else
+            run_child_agent(child:, label:, provider:, system:, tools:, task:, schema:,
+                            signal:, emit:, agent_options:)
+          end
+        rescue StandardError => e
+          primary_error = e
+          reported = EventDelivery.original(e)
+          child.append(Child::TERMINAL, "status" => "failed",
+                                        "error" => "#{reported.class}: #{reported.message}")
+          raise
+        ensure
+          cleanup_error = release_inline_lease(child, lease) if owns_lease
+          raise cleanup_error if cleanup_error && primary_error.nil?
+        end
+      end
+
+      def release_inline_lease(child, lease)
+        errors = []
+        begin
+          lease&.release
+        rescue StandardError => e
+          errors << e
+        end
+        begin
+          Mistri.locks&.clear_flag(Child.stop_key(child.id))
+        rescue StandardError => e
+          errors << e
+        end
+        errors.first
+      end
+
+      def abort_before_child_start!(child, signal, lease)
+        return unless Mistri.locks
+        return if lease && !Mistri.locks.flag?(Child.stop_key(child.id))
+
+        signal.abort!("stopped by user")
+      end
+
+      def run_child_agent(child:, label:, provider:, system:, tools:, task:, schema:,
+                          signal:, emit:, agent_options:)
+        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) }
+        return agent.task(task, schema: schema, signal: signal, &tagged) if schema
+
+        agent.run(task, signal: signal, &tagged)
+      end
+
+      def forward(event, origin, emit)
+        return unless emit
+
+        tagged = event.origin ? "#{origin}>#{event.origin}" : origin
+        emit.call(event.with(origin: tagged))
+      end
+
+      private :abort_before_child_start!, :execute_child, :forward,
+              :release_inline_lease, :run_child_agent
+    end
+  end
+end