mistri 0.0.2 → 0.1.0

data/lib/mistri/skills.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+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
+  # skill is actually used.
+  module Skills
+    module_function
+
+    # Reads a directory of skills in either layout: <dir>/<name>/SKILL.md
+    # or <dir>/<name>.md. Frontmatter (name:, description:) overrides the
+    # path-derived name.
+    def load(path)
+      raise ConfigurationError, "no skills directory at #{path}" unless File.directory?(path)
+
+      skills = Dir.children(path).sort.filter_map do |child|
+        full = File.join(path, child)
+        if File.directory?(full) && File.file?(File.join(full, "SKILL.md"))
+          read(File.join(full, "SKILL.md"), default_name: child)
+        elsif child.end_with?(".md") && File.file?(full)
+          read(full, default_name: File.basename(child, ".md"))
+        end
+      end
+      skills.sort_by(&:name)
+    end
+
+    def read(file, default_name:)
+      meta, body = parse(File.read(file))
+      Skill.new(name: meta.fetch("name", default_name),
+                description: meta.fetch("description", ""), body: body)
+    end
+
+    # The always-present cost of a skill library: one line per skill.
+    def section(skills)
+      lines = skills.map { |skill| "- #{skill.name}: #{skill.description}" }
+      <<~TEXT.strip
+        ## Skills
+
+        Expert playbooks. Before acting, check this list: when a skill
+        matches the task, you MUST call read_skill with its name and follow
+        the playbook.
+
+        #{lines.join("\n")}
+      TEXT
+    end
+
+    def amend(system, skills)
+      return system if skills.empty?
+
+      [system, section(skills)].compact.join("\n\n")
+    end
+
+    def reader(skills)
+      by_name = skills.to_h { |skill| [skill.name, skill] }
+      Tool.define("read_skill", "Reads the full playbook for a named skill.",
+                  schema: -> { string :name, "Skill name", required: true }) do |args|
+        skill = by_name[args["name"]]
+        next skill.body if skill
+
+        "Unknown skill #{args["name"].inspect}. Available: #{by_name.keys.join(", ")}"
+      end
+    end
+
+    # Frontmatter is deliberately a subset: flat string keys between ---
+    # markers, quotes optional. name and description are the whole contract,
+    # and a YAML dependency is not worth two fields.
+    def parse(text)
+      return [{}, text] unless text.start_with?("---\n")
+
+      head, separator, body = text[4..].partition("\n---\n")
+      return [{}, text] if separator.empty?
+
+      meta = {}
+      head.scan(/^([a-z_]+):[ \t]*(.+?)[ \t]*$/) do |key, value|
+        meta[key] = value.gsub(/\A["']|["']\z/, "")
+      end
+      [meta, body.sub(/\A\n+/, "")]
+    end
+  end
+end

data/lib/mistri/sse.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  # 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.
+  #
+  # The decode is deliberately tolerant of what the provider APIs actually
+  # 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.
+  class SSE
+    def initialize
+      @buffer = +""
+    end
+
+    def feed(fragment, &)
+      @buffer << fragment
+      while (newline = @buffer.index("\n"))
+        line = @buffer.slice!(0, newline + 1)
+        decode(line.chomp, &)
+      end
+      nil
+    end
+
+    # Flush a trailing record that arrived without a final newline.
+    def finish(&)
+      decode(@buffer.chomp, &) unless @buffer.empty?
+      @buffer.clear
+      nil
+    end
+
+    private
+
+    def decode(line)
+      return unless line.start_with?("data:")
+
+      data = line.delete_prefix("data:").strip
+      return if data.empty? || data == "[DONE]"
+
+      decoded = JSON.parse(data)
+      yield decoded if decoded.is_a?(Hash)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/mistri/stop_reason.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Mistri
+  # Why an assistant turn stopped. Providers map their native finish reasons
+  # onto this one set, so the loop and the host never read wire spellings.
+  #
+  #   :stop     - the model finished its answer
+  #   :length   - it hit the max-tokens ceiling mid-turn
+  #   :tool_use - it paused to call one or more tools
+  #   :error    - the provider or runtime failed
+  #   :aborted  - the host cancelled the turn
+  #   :budget   - a configured ceiling stopped the run
+  module StopReason
+    STOP = :stop
+    LENGTH = :length
+    TOOL_USE = :tool_use
+    ERROR = :error
+    ABORTED = :aborted
+    BUDGET = :budget
+
+    ALL = [STOP, LENGTH, TOOL_USE, ERROR, ABORTED, BUDGET].freeze
+
+    def self.valid?(reason) = ALL.include?(reason)
+  end
+end

data/lib/mistri/stores/active_record.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  module Stores
+    # Entries in the host's own database, through a model class the host
+    # supplies, so sessions live where application data lives: MySQL,
+    # Postgres, whatever the app runs. Not auto-required; load it with
+    # require "mistri/stores/active_record".
+    #
+    # The model needs three columns: session_id (string, indexed), position
+    # (integer), payload (text). A migration to copy:
+    #
+    #   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.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.
+    #
+    # Reads select only (position, payload) and sort in Ruby: ORDER BY over
+    # rows carrying multi-megabyte payloads exhausts MySQL's sort buffer.
+    class ActiveRecord
+      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
+      end
+
+      def load(id)
+        @model.where(session_id: id).pluck(:position, :payload)
+              .sort_by(&:first)
+              .map { |_position, payload| JSON.parse(payload) }
+      end
+    end
+  end
+end

data/lib/mistri/stores/jsonl.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Mistri
+  module Stores
+    # One JSONL file per session under a directory: durable sessions without
+    # a database, and a transcript any tool can read line by line.
+    class JSONL
+      def initialize(dir)
+        @dir = dir
+        FileUtils.mkdir_p(dir)
+      end
+
+      def append(id, entry)
+        File.open(path(id), "a") { |file| file.puts(JSON.generate(entry)) }
+        nil
+      end
+
+      def load(id)
+        return [] unless File.exist?(path(id))
+
+        File.readlines(path(id)).filter_map do |line|
+          JSON.parse(line) unless line.strip.empty?
+        end
+      end
+
+      private
+
+      # Session ids become filenames; anything path-hostile is replaced.
+      def path(id)
+        File.join(@dir, "#{id.to_s.gsub(/[^a-zA-Z0-9_-]/, "-")}.jsonl")
+      end
+    end
+  end
+end

data/lib/mistri/stores/memory.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Mistri
+  module Stores
+    # Entries in a plain Hash: for tests and runs that need no persistence.
+    class Memory
+      def initialize
+        @entries = Hash.new { |hash, key| hash[key] = [] }
+        @mutex = Mutex.new
+      end
+
+      def append(id, entry)
+        @mutex.synchronize { @entries[id] << entry }
+        nil
+      end
+
+      def load(id)
+        @mutex.synchronize { @entries[id].dup }
+      end
+    end
+  end
+end

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,94 @@
+# 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
+
+    # 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, &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
+      @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,66 @@
+# frozen_string_literal: true
+
+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 { |call, result| [call, result || INTERRUPTED] }
+    end
+
+    def worker(queue, results, tools_by_name, context)
+      Thread.new do
+        loop do
+          call, index = begin
+            queue.pop(true)
+          rescue ThreadError
+            break
+          end
+          interrupted = context.signal&.aborted?
+          results[index] = interrupted ? INTERRUPTED : run_one(call, tools_by_name, context)
+        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 { tool.call(call.arguments, context) }
+    rescue StandardError => e
+      "Error running tool #{call.name.inspect}: #{e.class}: #{e.message}"
+    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