mistri 0.0.3 → 0.2.0

data/lib/mistri/session.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "time"
+
+module Mistri
+  # The durable record of a run: an append-only log of typed entries over a
+  # pluggable store. Messages replay into provider-ready history; other entry
+  # types (reminders, custom host data) ride alongside without the loop
+  # knowing their shapes.
+  #
+  # A store implements two methods: append(id, entry_hash) and load(id) ->
+  # array of entry hashes in append order. Everything else lives here.
+  class Session
+    attr_reader :id, :store
+
+    def initialize(store:, id: nil)
+      @store = store
+      @id = id || SecureRandom.uuid
+    end
+
+    def append_message(message)
+      append("message", "message" => message.to_h)
+      message
+    end
+
+    # Entries are normalized through JSON at write time, so every store holds
+    # the same canonical shape (string keys, JSON values) and reads behave
+    # identically whether the entry round-tripped a database or stayed in
+    # memory.
+    def append(type, data = {})
+      entry = { "type" => type, "at" => Time.now.utc.iso8601 }.merge(data)
+      @store.append(@id, JSON.parse(JSON.generate(entry)))
+      nil
+    end
+
+    def entries = @store.load(@id)
+
+    # The conversation as the model replays it.
+    def messages = replay.map(&:first)
+
+    # Replay messages paired with the entry index each came from, starting at
+    # the latest compaction boundary. The synthetic summary message carries a
+    # nil index. Compaction places its cuts by these indexes; the full entry
+    # log stays in the store for transcript views.
+    def replay
+      compaction = last_compaction
+      from = compaction ? compaction["kept_from"] : 0
+      pairs = entries.each_with_index.filter_map do |entry, index|
+        [Message.from_h(entry["message"]), index] if index >= from && entry["type"] == "message"
+      end
+      compaction ? [[summary_message(compaction["summary"]), nil], *pairs] : pairs
+    end
+
+    def last_compaction
+      entries.reverse_each.find { |entry| entry["type"] == "compaction" }
+    end
+
+    # Queue a message for a running exchange from any process. The loop folds
+    # pending steers into the transcript at the next turn boundary, so the
+    # model sees them mid-run; one that arrives as the model finishes cleanly
+    # extends the run another turn so it is answered, not left dangling.
+    def steer(text)
+      append("steer", "id" => SecureRandom.uuid, "message" => Message.user(text).to_h)
+    end
+
+    # Steers not yet folded into the transcript, oldest first. The folding
+    # message entry carries the steer id, so consumption is derived from the
+    # log alone and reads the same from every process.
+    def pending_steers
+      folded = entries.filter_map { |entry| entry["steer_id"] }
+      entries.select { |entry| entry["type"] == "steer" && !folded.include?(entry["id"]) }
+    end
+
+    # Record a human's decision on a parked tool call. Decisions are session
+    # entries, so they can be written from any process, days later, with no
+    # agent constructed; the next resume settles them.
+    def approve(call_id, note: nil) = decide(call_id, approved: true, note: note)
+
+    def deny(call_id, note: nil) = decide(call_id, approved: false, note: note)
+
+    # Parked tool calls not yet settled by a tool result, each with its
+    # decision when one has been recorded. Derived from the entry log alone,
+    # so it survives crashes and reads the same from every process.
+    def open_approvals
+      answered = []
+      decisions = {}
+      requests = []
+      entries.each do |entry|
+        case entry["type"]
+        when "message"
+          call_id = entry.dig("message", "tool_call_id")
+          answered << call_id if call_id
+        when "approval_request" then requests << entry["call"]
+        when "approval_decision" then decisions[entry["call_id"]] = entry
+        end
+      end
+      requests.reject { |call| answered.include?(call["id"]) }
+              .map { |call| { call: rebuild_call(call), decision: decisions[call["id"]] } }
+    end
+
+    private
+
+    def summary_message(summary)
+      Message.user("#{Compaction::SUMMARY_PREFACE}\n\n#{summary}")
+    end
+
+    def decide(call_id, approved:, note:)
+      unless open_approvals.any? { |open| open[:call].id == call_id }
+        raise ConfigurationError, "no open approval for #{call_id.inspect}"
+      end
+
+      entry = { "call_id" => call_id, "approved" => approved }
+      entry["note"] = note if note
+      append("approval_decision", entry)
+    end
+
+    def rebuild_call(hash)
+      ToolCall.new(id: hash["id"], name: hash["name"],
+                   arguments: hash["arguments"] || {}, signature: hash["signature"])
+    end
+  end
+end

data/lib/mistri/sinks/action_cable.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Mistri
+  module Sinks
+    # Broadcasts every event to an Action Cable stream as its to_h shape.
+    # The server resolves lazily at first call, so this file loads without
+    # Rails; pass server: explicitly to use another broadcaster.
+    #
+    #   sink = Mistri::Sinks::ActionCable.new("agent_#{session.id}")
+    #   agent.run(input, &sink)
+    class ActionCable
+      def initialize(stream, server: nil)
+        @stream = stream
+        @server = server
+      end
+
+      def call(event)
+        server.broadcast(@stream, event.to_h)
+      end
+
+      def to_proc = method(:call).to_proc
+
+      private
+
+      def server
+        @server ||= ::ActionCable.server
+      end
+    end
+  end
+end

data/lib/mistri/sinks/coalesced.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+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.
+    #
+    #   sink = Mistri::Sinks::Coalesced.new(
+    #     Mistri::Sinks::ActionCable.new("agent_1"), interval: 0.1,
+    #   )
+    class Coalesced
+      DELTAS = %i[text_delta thinking_delta toolcall_delta].freeze
+
+      def initialize(sink, interval: 0.05)
+        @sink = sink
+        @interval = interval
+        @buffer = nil
+        @flushed_at = now
+      end
+
+      def call(event)
+        unless DELTAS.include?(event.type)
+          flush
+          return @sink.call(event)
+        end
+
+        merge(event)
+        flush if now - @flushed_at >= @interval
+      end
+
+      def to_proc = method(:call).to_proc
+
+      private
+
+      # Merged deltas keep the newest partial, so a consumer that renders
+      # snapshots always renders the latest one.
+      def merge(event)
+        same = @buffer && @buffer.type == event.type &&
+               @buffer.content_index == event.content_index
+        flush if @buffer && !same
+        @buffer = if same
+                    @buffer.with(delta: @buffer.delta.to_s + event.delta.to_s,
+                                 partial: event.partial)
+                  else
+                    event
+                  end
+      end
+
+      def flush
+        pending = @buffer
+        @buffer = nil
+        @flushed_at = now
+        @sink.call(pending) if pending
+      end
+
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/mistri/sinks/sse.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  module Sinks
+    # Writes events as Server-Sent Events to any IO-like object: a Rack
+    # streaming body, an ActionController::Live stream, a socket. Pure
+    # formatting, the outbound counterpart of the Mistri::SSE decoder.
+    #
+    #   response.headers["Content-Type"] = "text/event-stream"
+    #   agent.run(input, &Mistri::Sinks::SSE.new(response.stream))
+    class SSE
+      def initialize(io)
+        @io = io
+      end
+
+      def call(event)
+        @io.write("event: #{event.type}\ndata: #{JSON.generate(event.to_h)}\n\n")
+        @io.flush if @io.respond_to?(:flush)
+      end
+
+      def to_proc = method(:call).to_proc
+    end
+  end
+end

data/lib/mistri/skill.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+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
+  # skills in a database constructs these directly.
+  Skill = Data.define(:name, :description, :body) do
+    def initialize(name:, description: "", body: "")
+      raise ConfigurationError, "a skill needs a name" if name.to_s.empty?
+
+      super(name: name.to_s, description: description.to_s, body: body.to_s)
+    end
+  end
+end

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