mistri 0.0.3 → 0.2.0

data/lib/mistri/sub_agent.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+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
+  # 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
+  # sanctioned way to mix models.
+  #
+  # Two shapes on one mechanism. A named specialist the host curates:
+  #
+  #   researcher = Mistri::SubAgent.new(
+  #     name: "researcher", description: "Answers factual questions.",
+  #     provider: Mistri.provider("claude-haiku-4-5-20251001"),
+  #     system: "Research. Report findings only.", tools: [fetch_page],
+  #   )
+  #   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:
+  #
+  #   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
+  # one turn run concurrently on the executor pool.
+  #
+  # Child events forward into the parent's stream tagged with origin
+  # ("researcher#ab12cd34"; nesting of named specialists joins with ">").
+  # Approval-gated tools cannot ride inside a child: a child answers its
+  # parent synchronously and cannot fire-and-forget suspend, so statically
+  # gated tools are refused at construction and a child that suspends at
+  # runtime is denied and reported in band. Gate the delegation itself
+  # instead (needs_approval: on the definition or spawner).
+  class SubAgent
+    SPAWNER_DESCRIPTION =
+      "Delegate a self-contained task to a focused child agent with a clean " \
+      "context. The child starts blank: give it complete instructions and " \
+      "every fact it needs. Use it to keep exploration out of your own " \
+      "context, and spawn several in one turn to fan out independent " \
+      "angles. Only the child's final answer comes back."
+
+    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
+    # synthesizes instead of five styles of prose.
+    def initialize(name:, description:, provider:, system: nil, tools: [], schema: nil,
+                   **agent_options)
+      SubAgent.forbid_gated!(tools)
+      @name = name.to_s
+      @description = description
+      @provider = provider
+      @system = system
+      @tools = tools
+      @schema = schema
+      @agent_options = agent_options
+      @gate = agent_options.delete(:needs_approval) || false
+    end
+
+    # 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.
+    def tool
+      sub = self
+      blurb = "#{@description} Runs as a focused sub-agent with a clean " \
+              "context: give it complete instructions, it starts blank."
+      Tool.define(@name, blurb, needs_approval: @gate,
+                                schema: lambda {
+                                  string :task, "Complete instructions for the sub-agent",
+                                         required: true
+                                }) do |args, context|
+        sub.run_child(args.fetch("task"), context)
+      end
+    end
+
+    def run_child(task, context)
+      SubAgent.run_child(label: @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 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
+
+        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),
+                    system: args.fetch("instructions"),
+                    tools: pick(tools, args["tools"]),
+                    task: args.fetch("task"), context: context, **agent_options)
+        end
+      end
+
+      def run_child(label:, provider:, system:, tools:, task:, context:, schema: nil,
+                    **agent_options)
+        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)
+      end
+
+      def forbid_gated!(tools)
+        gated = tools.select { |tool| statically_gated?(tool) }
+        return if gated.empty?
+
+        raise ConfigurationError,
+              "approval-gated tools cannot run inside a sub-agent " \
+              "(#{gated.map(&:name).join(", ")}); gate the delegation instead"
+      end
+
+      private
+
+      def forward(event, origin, context)
+        return unless context.emit
+
+        tagged = event.origin ? "#{origin}>#{event.origin}" : origin
+        context.emit.call(event.with(origin: tagged))
+      end
+
+      # The parent always gets an in-band answer it can react to. A child
+      # that suspends for approval is denied and abandoned: nothing else
+      # will ever settle it.
+      def answer(result, label, child)
+        link = { "agent" => label, "session_id" => child.id }
+        case result.status
+        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
+          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)
+        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)
+        tool_names = pool.map(&:name)
+        lambda do
+          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
+        end
+      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)
+        tool.needs_approval?({})
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/mistri/tool.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  # A tool the agent can call: a name, a description, a JSON Schema for its
+  # arguments, and a handler. The handler receives the parsed arguments hash
+  # (string keys, exactly as the model sent them) and returns a String, a Hash
+  # (serialized as JSON), or content blocks, so a tool can hand back images as
+  # naturally as text.
+  class Tool
+    # A no-argument tool still needs a valid object schema; providers reject a
+    # bare empty hash.
+    EMPTY_SCHEMA = { type: "object", properties: {} }.freeze
+
+    attr_reader :name, :description, :input_schema, :timeout
+
+    # Define a tool. Give the argument shape as a raw JSON Schema hash via
+    # input_schema:, or build it in Ruby with a schema: block.
+    #
+    #   Tool.define("get_weather", "Weather for a city",
+    #               schema: -> { string :city, "City name", required: true }) do |args|
+    #     Weather.for(args["city"])
+    #   end
+    def self.define(name, description, input_schema: nil, schema: nil, **, &handler)
+      input_schema ||= schema ? Schema.build(&schema) : EMPTY_SCHEMA
+      new(name: name, description: description, input_schema: input_schema, **, &handler)
+    end
+
+    def initialize(name:, description:, input_schema: EMPTY_SCHEMA, eager_input_streaming: false,
+                   needs_approval: false, timeout: nil, &handler)
+      raise ArgumentError, "tool #{name.inspect} needs a handler block" unless handler
+
+      @name = name.to_s
+      @description = description
+      @input_schema = input_schema
+      @eager_input_streaming = eager_input_streaming
+      @needs_approval = needs_approval
+      @timeout = timeout
+      @handler = handler
+    end
+
+    # A handler may return a ToolResult to speak on two channels; its ui
+    # payload is canonicalized through JSON here so the live event and a
+    # reloaded session read the identical shape.
+    #
+    # Handlers receive (arguments, context). A proc that declares one
+    # parameter ignores the context invisibly; a lambda opts in by arity.
+    def call(arguments, context = ToolContext.new)
+      result = invoke(arguments || {}, context)
+      return serialize_result(result) unless result.is_a?(ToolResult)
+
+      result.with(content: serialize_result(result.content),
+                  ui: result.ui && JSON.parse(JSON.generate(result.ui)))
+    end
+
+    # Whether this call should pause for a human. true/false, or a callable
+    # given the parsed arguments so a tool can gate only the risky calls
+    # (needs_approval: ->(args) { args["amount"].to_i > 100 }).
+    def needs_approval?(arguments)
+      @needs_approval.respond_to?(:call) ? @needs_approval.call(arguments) : @needs_approval
+    end
+
+    # The provider-facing definition; every serializer accepts this shape.
+    def spec
+      definition = { name: @name, description: @description, input_schema: @input_schema }
+      definition[:eager_input_streaming] = true if @eager_input_streaming
+      definition
+    end
+
+    private
+
+    def invoke(arguments, context)
+      if @handler.lambda? && @handler.arity.between?(0, 1)
+        @handler.arity.zero? ? @handler.call : @handler.call(arguments)
+      else
+        @handler.call(arguments, context)
+      end
+    end
+
+    # Content blocks pass through so tools can return images; everything else
+    # the model reads as text, with structured data as JSON, never as Ruby
+    # inspect output.
+    def serialize_result(result)
+      case result
+      when String then result
+      when nil then ""
+      when Array
+        content = result.all? { |element| element.respond_to?(:type) || element.is_a?(String) }
+        content ? result : JSON.generate(result)
+      else result.respond_to?(:type) ? result : JSON.generate(result)
+      end
+    end
+  end
+end

data/lib/mistri/tool_call.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Mistri
+  # One tool invocation requested by the model. `arguments` is the parsed Hash
+  # exactly as the model emitted it, string keys and all; the top level is owned
+  # and frozen, nested values stay as parsed. `signature` is the opaque
+  # reasoning payload some providers attach to the call and require echoed back,
+  # such as Gemini's thoughtSignature.
+  ToolCall = Data.define(:id, :name, :arguments, :signature) do
+    def initialize(id:, name:, arguments: {}, signature: nil)
+      super(id:, name:, arguments: arguments.dup.freeze, signature:)
+    end
+
+    def type = :tool_call
+
+    def to_h = { type: :tool_call, id:, name:, arguments:, signature: }.compact
+  end
+end

data/lib/mistri/tool_context.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+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)
+      super
+    end
+  end
+end

data/lib/mistri/tool_executor.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module Mistri
+  # Runs a turn's tool calls and returns their results in the order the model
+  # emitted them, regardless of completion order. Independent calls run
+  # concurrently up to max_concurrency; each runs inside the Rails executor
+  # when Rails is present, so ActiveRecord connections return to the pool.
+  #
+  # A tool that raises becomes an in-band error string the model can read. An
+  # abort never starts a not-yet-started call: it gets an interrupted result
+  # instead, so the turn always pairs and the session replays cleanly.
+  module ToolExecutor
+    INTERRUPTED = "[interrupted: this tool call never ran]"
+
+    module_function
+
+    def call(calls, tools_by_name, signal: nil, max_concurrency: 4, session: nil, emit: nil)
+      return [] if calls.empty?
+
+      context = ToolContext.new(session: session, signal: signal, emit: thread_safe(emit))
+      results = Array.new(calls.length)
+      queue = Queue.new
+      calls.each_with_index { |call, index| queue << [call, index] }
+      workers = max_concurrency.clamp(1, calls.length)
+      Array.new(workers) { worker(queue, results, tools_by_name, context) }.each(&:join)
+      calls.zip(results).map do |call, entry|
+        value, seconds = entry || [INTERRUPTED, nil]
+        [call, value, seconds]
+      end
+    end
+
+    def worker(queue, results, tools_by_name, context)
+      Thread.new do
+        loop do
+          call, index = begin
+            queue.pop(true)
+          rescue ThreadError
+            break
+          end
+          if context.signal&.aborted?
+            results[index] = [INTERRUPTED, nil]
+            next
+          end
+
+          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          value = run_one(call, tools_by_name, context)
+          results[index] = [value, Process.clock_gettime(Process::CLOCK_MONOTONIC) - started]
+        end
+      end
+    end
+
+    def run_one(call, tools_by_name, context)
+      tool = tools_by_name[call.name]
+      return "Error: unknown tool #{call.name.inspect}" unless tool
+
+      with_rails_executor { invoke(tool, call, context) }
+    rescue StandardError => e
+      "Error running tool #{call.name.inspect}: #{e.class}: #{e.message}"
+    end
+
+    # A tool with a timeout answers in band when it stalls, so one hung
+    # handler cannot stall the whole run.
+    def invoke(tool, call, context)
+      return tool.call(call.arguments, context) unless tool.timeout
+
+      Timeout.timeout(tool.timeout) { tool.call(call.arguments, context) }
+    rescue Timeout::Error
+      "Error running tool #{call.name.inspect}: timed out after #{tool.timeout}s"
+    end
+
+    # Concurrent tools share the caller's sink; sinks are not required to be
+    # thread-safe, so forwarded events serialize here.
+    def thread_safe(emit)
+      return nil unless emit
+
+      mutex = Mutex.new
+      ->(event) { mutex.synchronize { emit.call(event) } }
+    end
+
+    def with_rails_executor(&)
+      executor = defined?(Rails) && Rails.respond_to?(:application) && Rails.application&.executor
+      executor ? executor.wrap(&) : yield
+    end
+  end
+end

data/lib/mistri/tool_result.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Mistri
+  # A two-channel tool result: content goes to the model, ui goes only to the
+  # host. The ui payload rides the tool message and its :tool_result event,
+  # persists with the session for transcript re-renders, and never reaches a
+  # provider. Return one from a handler when the UI needs more than the model
+  # should read or pay for: full query rows behind a compact answer, the
+  # updated document behind "saved".
+  #
+  #   Tool.define("edit_page", "Edits the page.") do |args|
+  #     page = apply(args)
+  #     Mistri::ToolResult.new(content: "Updated.", ui: { "html" => page })
+  #   end
+  #
+  # ui must be JSON-serializable; it is stored and delivered in canonical
+  # JSON form (string keys), the same shape a reloaded session reads.
+  ToolResult = Data.define(:content, :ui) do
+    def initialize(content:, ui: nil)
+      super
+    end
+  end
+end

data/lib/mistri/tools/edit_file.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Mistri
+  module Tools
+    module_function
+
+    # The model-facing shape is flat {path, old_string, new_string,
+    # replace_all} on purpose: it is the shape frontier models are trained on,
+    # and nested edit arrays measurably degrade their calls. Failures come
+    # back in band with the closest region and its exact difference, so the
+    # model's retry is one shot.
+    def edit_file(workspace)
+      Tool.define("edit_file",
+                  "Replace an exact snippet of a document. Copy old_string verbatim from " \
+                  "read_file output including whitespace, without line-number prefixes. " \
+                  "It must match exactly one place; add surrounding lines to make it " \
+                  "unique, or set replace_all to change every occurrence.",
+                  eager_input_streaming: true,
+                  schema: lambda {
+                    string :path, "Document path", required: true
+                    string :old_string, "Exact text to replace (whitespace matters)", required: true
+                    string :new_string, "Replacement text", required: true
+                    boolean :replace_all, "Replace every occurrence instead of exactly one"
+                  }) do |args|
+        args = Tools.tolerate(args)
+        with_document(workspace, args) do |content|
+          result = Edit.replace(content, args["old_string"], args["new_string"],
+                                replace_all: args["replace_all"] == true)
+          workspace.write(args["path"], result.content)
+          "Replaced #{result.count} occurrence(s) in #{args["path"]}"
+        end
+      rescue EditError => e
+        "edit_file failed: #{e.message}"
+      end
+    end
+  end
+end

data/lib/mistri/tools/find_in_file.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Mistri
+  module Tools
+    module_function
+
+    def find_in_file(workspace)
+      Tool.define("find_in_file",
+                  "Find text in a document. Returns line-numbered matches with context, " \
+                  "so you can locate a region without reading the whole document.",
+                  schema: lambda {
+                    string :path, "Document path", required: true
+                    string :query, "Text to find (plain substring)", required: true
+                    integer :context, "Context lines around each match"
+                  }) do |args|
+        with_document(workspace, args) do |content|
+          Tools.find_matches(content, args["query"], (args["context"] || 2).to_i)
+        end
+      end
+    end
+
+    def find_matches(content, query, context)
+      lines = content.lines
+      hits = lines.each_index.select { |i| lines[i].include?(query) }
+      return "No matches for #{query.inspect}." if hits.empty?
+
+      blocks = hits.first(20).map do |hit|
+        from = [hit - context, 0].max
+        to = [hit + context, lines.length - 1].min
+        (from..to).map { |n| "#{n + 1}: #{lines[n]}" }.join
+      end
+      notice = hits.length > 20 ? "\n[#{hits.length - 20} more matches not shown]" : ""
+      "#{blocks.join("---\n")}#{notice}"
+    end
+  end
+end

data/lib/mistri/tools/list_files.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Mistri
+  module Tools
+    module_function
+
+    def list_files(workspace)
+      Tool.define("list_files",
+                  "List document paths in the workspace, optionally under a prefix.",
+                  schema: -> { string :prefix, "Only paths starting with this" }) do |args|
+        paths = workspace.list(args["prefix"])
+        paths.empty? ? "No documents found." : paths.join("\n")
+      end
+    end
+  end
+end

data/lib/mistri/tools/read_file.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Mistri
+  module Tools
+    MAX_READ_CHARS = 20_000
+
+    module_function
+
+    def read_file(workspace)
+      Tool.define("read_file",
+                  "Read a document with line numbers. Use offset and limit for a window " \
+                  "into a long document.",
+                  schema: lambda {
+                    string :path, "Document path", required: true
+                    integer :offset, "First line to read (1-based)"
+                    integer :limit, "How many lines to read"
+                  }) do |args|
+        with_document(workspace, args) do |content|
+          Tools.numbered_window(content, args["offset"], args["limit"])
+        end
+      end
+    end
+
+    def numbered_window(content, offset, limit)
+      lines = content.lines
+      from = [(offset || 1).to_i, 1].max
+      to = limit ? [from + limit.to_i - 1, lines.length].min : lines.length
+      numbered = (from..to).map { |n| "#{n}: #{lines[n - 1]}" }.join
+      windowed = to < lines.length || from > 1
+      suffix = windowed ? "\n[showing lines #{from}-#{to} of #{lines.length}]" : ""
+      return "#{numbered}#{suffix}" if numbered.length <= MAX_READ_CHARS
+
+      cut = numbered[0, MAX_READ_CHARS]
+      cut = cut[0..(cut.rindex("\n") || -1)]
+      "#{cut}\n[truncated at #{MAX_READ_CHARS} chars; use offset/limit to read more]"
+    end
+  end
+end

data/lib/mistri/tools/read_memory.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Mistri
+  module Tools
+    module_function
+
+    def read_memory(memory)
+      Tool.define("read_memory",
+                  "Read the durable memory: knowledge kept across sessions. Check it " \
+                  "before starting work that earlier sessions may have learned about.") do |_args|
+        content = memory.read
+        content.empty? ? "Memory is empty." : content
+      end
+    end
+  end
+end

data/lib/mistri/tools/update_memory.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Mistri
+  module Tools
+    module_function
+
+    # Whole-document replace on purpose: the model rewrites memory as one
+    # coherent text instead of appending fragments that drift.
+    def update_memory(memory)
+      Tool.define("update_memory",
+                  "Replace the durable memory with an updated version. Pass the FULL " \
+                  "text: what you were given plus what you learned, rewritten to stay " \
+                  "short and current.",
+                  schema: lambda {
+                    string :content, "The complete new memory text", required: true
+                  }) do |args|
+        memory.replace(args["content"])
+        "Memory updated (#{args["content"].to_s.length} chars)."
+      end
+    end
+  end
+end

data/lib/mistri/tools/write_file.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Mistri
+  module Tools
+    module_function
+
+    def write_file(workspace)
+      Tool.define("write_file",
+                  "Create or fully overwrite a document with the given content.",
+                  eager_input_streaming: true,
+                  schema: lambda {
+                    string :path, "Document path", required: true
+                    string :content, "The full document content", required: true
+                  }) do |args|
+        workspace.write(args["path"], args["content"])
+        "Wrote #{args["path"]} (#{args["content"].to_s.length} chars)"
+      end
+    end
+  end
+end