mistri 0.0.3 → 0.1.0

data/lib/mistri/agent.rb

@@ -0,0 +1,340 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  # The agent loop: prompt the provider, run any tools it calls, feed the
+  # results back, and repeat until it answers without calling tools. Every
+  # streamed event reaches the caller's block as it arrives, and every run
+  # returns a Result.
+  #
+  # Each message persists to the session the moment it completes, so a crash
+  # or an abort leaves a replay-valid transcript with no repair step. A tool
+  # marked needs_approval suspends the run instead of executing: the run
+  # returns at once (no thread ever waits on a human), the decision arrives
+  # later as a session entry from any process, and resume settles it and
+  # carries on. Session#steer queues a user message from any process while
+  # the loop runs; it folds into the transcript at the next turn boundary.
+  class Agent
+    # compaction defaults on so long sessions survive their context window;
+    # pass false to disable, or a tuned Compaction. It only ever triggers
+    # when the model's window is known (catalog or Compaction#window).
+    # skills: an array of Skill (or a directory path for Skills.load). Their
+    # descriptions join the system prompt and a read_skill tool serves full
+    # bodies on demand.
+    def initialize(provider:, session: nil, system: nil, tools: [], budget: nil,
+                   max_concurrency: 4, transform_context: nil, compaction: Compaction.new,
+                   retries: RetryPolicy.new, skills: [])
+      @provider = provider
+      @session = session || Session.new(store: Stores::Memory.new)
+      skills = skills.is_a?(String) ? Skills.load(skills) : Array(skills)
+      @system = Skills.amend(system, skills)
+      @tools = skills.empty? ? tools : tools + [Skills.reader(skills)]
+      @tools_by_name = @tools.to_h { |tool| [tool.name, tool] }
+      raise ConfigurationError, "duplicate tool names" if @tools_by_name.length != @tools.length
+
+      @budget = budget || Budget.new
+      @max_concurrency = max_concurrency
+      @transform_context = transform_context
+      @compaction = compaction || nil
+      @retries = retries || nil
+    end
+
+    attr_reader :session
+
+    # Run one exchange: append the user turn, then loop until the model
+    # answers without tools, a gated tool suspends the run, the run aborts,
+    # or a budget stops it.
+    # output_schema constrains every non-tool answer to JSON matching the
+    # schema, natively where the provider supports it. task adds validation
+    # on top; run alone does not validate.
+    def run(input, images: [], signal: nil, output_schema: nil, &emit)
+      if @session.open_approvals.any?
+        raise ConfigurationError, "session is awaiting approval decisions; call resume"
+      end
+      if input.to_s.empty? && Array(images).empty?
+        raise ArgumentError, "run needs input text or images"
+      end
+
+      fold_steers # steers queued while idle arrived first; keep that order
+      @session.append_message(Message.user_with_images(input, images))
+      loop_turns(signal, output_schema, &emit)
+    end
+
+    # Continue a suspended run. Undecided approvals return immediately, still
+    # suspended. Decided ones settle first: approved calls execute, denied
+    # calls answer in band so the model knows and can react. Then the loop
+    # carries on as if it never stopped.
+    def resume(signal: nil, &emit)
+      open = @session.open_approvals
+      pending = open.select { |approval| approval[:decision].nil? }
+      if pending.any?
+        return Result.new(message: nil, status: :awaiting_approval,
+                          pending: pending.map { |approval| approval[:call] })
+      end
+
+      settle(open, signal, &emit)
+      loop_turns(signal, nil, &emit)
+    end
+
+    # Run an exchange that must end in a JSON value matching schema. Tools
+    # run as usual; providers constrain the final answer natively where they
+    # can, and the answer is validated here regardless. A violation goes
+    # back to the model (fixes more times), then raises SchemaError. The
+    # Result carries the validated value as output.
+    #
+    # A run that suspends for approval returns as-is: validation applies to
+    # completed runs only, so resume the session and re-ask if that happens
+    # mid-task.
+    def task(input, schema:, images: [], signal: nil, fixes: 1, &emit)
+      result = run(task_input(input, schema), images: images, signal: signal,
+                                              output_schema: schema, &emit)
+      fixes.downto(0) do |remaining|
+        return result unless result.completed?
+
+        value = parse_output(result.text)
+        errors = task_errors(value, schema)
+        return result.with(output: value) if errors.empty?
+        raise SchemaError, "task output failed validation: #{errors.join("; ")}" if remaining.zero?
+
+        result = run(fix_prompt(errors), signal: signal, output_schema: schema, &emit)
+      end
+    end
+
+    # How full the context is: {tokens:, window:, fraction:}. Hosts render
+    # meters and near-limit warnings from this; window is nil for models the
+    # catalog does not know unless Compaction#window supplies one.
+    def context_usage
+      tokens = Compaction.context_tokens(@session.messages)
+      window = context_window
+      { tokens: tokens, window: window,
+        fraction: window && (tokens.to_f / window).round(3) }
+    end
+
+    # Compact now (a UI button, a pre-flight trim before a big task). Returns
+    # the Compactor result, or nil when there is nothing worth compacting.
+    def compact(&)
+      Compactor.call(session: @session, provider: @provider,
+                     settings: @compaction || Compaction.new, &)
+    end
+
+    private
+
+    def loop_turns(signal, output_schema = nil, &emit)
+      turns = 0
+      usage = Usage.zero
+      started = monotonic_now
+      loop do
+        reason = @budget.exceeded(turns: turns, usage: usage, elapsed: monotonic_now - started)
+        return stop_for_budget(reason, &emit) if reason
+
+        fold_steers
+        compacted = auto_compact(&emit)
+        usage += compacted[:usage] if compacted&.dig(:usage)
+        last = run_turn(signal, output_schema, &emit)
+        turns += 1
+        usage += last.usage if last.usage
+
+        # Any tool call the turn made must be answered or parked, or the
+        # transcript is unpairable and replay fails.
+        parked = last.tool_calls? ? run_tools(last, signal, &emit) : []
+        return suspended(last, parked) if parked.any?
+        return finished(last) if done?(last, signal)
+      end
+    end
+
+    # A steer that lands while the model finishes cleanly extends the run one
+    # more turn so it gets answered. Aborts, errors, and length stops always
+    # end the run; the steer stays pending for the next one.
+    def done?(last, signal)
+      return false if last.stop_reason == StopReason::TOOL_USE && !signal&.aborted?
+      return true if signal&.aborted? || last.stop_reason != StopReason::STOP
+
+      @session.pending_steers.empty?
+    end
+
+    # Compact when the context has grown into the reserve. A failed
+    # summarization skips quietly here: if the context genuinely no longer
+    # fits, the next turn surfaces the real provider error.
+    def auto_compact(&)
+      return nil unless @compaction
+
+      tokens = Compaction.context_tokens(@session.messages)
+      return nil unless @compaction.needed?(tokens, context_window)
+
+      Compactor.call(session: @session, provider: @provider, settings: @compaction, &)
+    rescue CompactionError
+      nil
+    end
+
+    def context_window
+      @compaction&.window || Models.find(@provider.model)&.context_window
+    end
+
+    # Materialize queued steers into the transcript in arrival order. The
+    # folded message entry carries the steer id, which is what marks the steer
+    # consumed: one append is both the fold and the marker, so a crash between
+    # steers never double-delivers.
+    def fold_steers
+      @session.pending_steers.each do |steer|
+        @session.append("message", "message" => steer["message"], "steer_id" => steer["id"])
+      end
+    end
+
+    # transform_context reshapes what the model sees each turn (reminders,
+    # redaction, windowing) without touching what the session stores. The
+    # lambda gets the replay messages and returns the messages to send; it
+    # must keep every tool call paired with its result or providers reject
+    # the request.
+    #
+    # A transient failure retries the same request with backoff; the failed
+    # attempt is recorded as a retry entry, never as a message, so retries
+    # stay invisible to the model. Only the final outcome persists.
+    def run_turn(signal, output_schema = nil, &emit)
+      history = @session.messages
+      history = @transform_context.call(history) if @transform_context
+      attempt = 0
+      loop do
+        message = @provider.stream(messages: history, system: @system,
+                                   tools: @tools.map(&:spec), signal: signal,
+                                   output_schema: output_schema, &emit)
+        attempt += 1
+        if retry_turn?(message, attempt, signal)
+          pause = @retries.delay(attempt, message.error&.dig("retry_after"))
+          record_retry(message, attempt, pause, &emit)
+          wait(pause, signal)
+          next unless signal&.aborted?
+        end
+        @session.append_message(message)
+        return message
+      end
+    end
+
+    def retry_turn?(message, attempt, signal)
+      return false unless @retries && message.stop_reason == StopReason::ERROR
+      return false if signal&.aborted?
+
+      @retries.retry?(message.error, attempt)
+    end
+
+    def record_retry(message, attempt, pause, &emit)
+      @session.append("retry", "attempt" => attempt, "error" => message.error,
+                               "delay" => pause.round(2))
+      note = format("attempt %<attempt>d failed; retrying in %<pause>.1fs",
+                    attempt: attempt, pause: pause)
+      emit&.call(Event.new(type: :retry, content: note, reason: StopReason::ERROR,
+                           message: message))
+    end
+
+    # Backoff that an abort can cut short.
+    def wait(seconds, signal)
+      deadline = monotonic_now + seconds
+      sleep(0.1) while monotonic_now < deadline && !signal&.aborted?
+    end
+
+    # Answer or park the assistant's tool calls. Ungated calls execute (only
+    # on a genuine tool_use turn with no abort; otherwise they pair with
+    # interrupted results). Gated calls park as approval requests and are
+    # returned, so the loop can suspend. Nothing is left dangling either way.
+    def run_tools(assistant, signal, &emit)
+      calls = assistant.tool_calls
+      unless assistant.stop_reason == StopReason::TOOL_USE && !signal&.aborted?
+        calls.each { |call| answer(call, ToolExecutor::INTERRUPTED, &emit) }
+        return []
+      end
+
+      parked, free = calls.partition { |call| gated?(call) }
+      execute(free, signal, &emit)
+      parked.each do |call|
+        @session.append("approval_request", "call" => call.to_h)
+        emit&.call(Event.new(type: :approval_needed, tool_call: call))
+      end
+      parked
+    end
+
+    def settle(open, signal, &emit)
+      approved, denied = open.partition { |approval| approval[:decision]["approved"] }
+      execute(approved.map { |approval| approval[:call] }, signal, &emit)
+      denied.each do |approval|
+        note = approval[:decision]["note"]
+        text = "The user denied this tool call#{note ? ": #{note}" : "."}"
+        answer(approval[:call], text, &emit)
+      end
+    end
+
+    def execute(calls, signal, &emit)
+      return if calls.empty?
+
+      results = ToolExecutor.call(calls, @tools_by_name, signal: signal,
+                                                         max_concurrency: @max_concurrency,
+                                                         session: @session, emit: emit)
+      results.each { |call, result| answer(call, result, &emit) }
+    end
+
+    # The tool message carries both channels; the :tool_result event exposes
+    # it whole so hosts read event.message.ui for their side of the result.
+    def answer(call, result, &emit)
+      content, ui = result.is_a?(ToolResult) ? [result.content, result.ui] : [result, nil]
+      message = @session.append_message(Message.tool(content: content, tool_call_id: call.id,
+                                                     tool_name: call.name, ui: ui))
+      text = content.is_a?(String) ? content : "[content]"
+      emit&.call(Event.new(type: :tool_result, tool_call: call, content: text, message: message))
+    end
+
+    def gated?(call)
+      tool = @tools_by_name[call.name]
+      tool ? tool.needs_approval?(call.arguments) : false
+    end
+
+    def finished(message)
+      status = { StopReason::ABORTED => :aborted, StopReason::BUDGET => :budget,
+                 StopReason::ERROR => :error }.fetch(message.stop_reason, :completed)
+      Result.new(message: message, status: status)
+    end
+
+    def suspended(message, parked)
+      Result.new(message: message, status: :awaiting_approval, pending: parked)
+    end
+
+    def stop_for_budget(reason, &emit)
+      message = Message.assistant(content: "Run stopped: #{reason} budget reached.",
+                                  stop_reason: StopReason::BUDGET,
+                                  error_message: "budget_#{reason}")
+      @session.append_message(message)
+      emit&.call(Event.new(type: :error, reason: StopReason::BUDGET, message: message,
+                           error_message: "budget_#{reason}"))
+      Result.new(message: message, status: :budget)
+    end
+
+    # Distinguishable from a parsed nil: JSON "null" is a valid value.
+    PARSE_FAILED = Object.new.freeze
+    private_constant :PARSE_FAILED
+
+    def task_input(input, schema)
+      "#{input}\n\nAnswer with ONLY a JSON value matching this schema:\n" \
+        "#{JSON.generate(Schema.strict(schema))}"
+    end
+
+    def parse_output(text)
+      body = text.to_s.strip
+      body = body[/\A```(?:json)?\s*(.*?)```\z/m, 1] || body
+      JSON.parse(body)
+    rescue JSON::ParserError
+      PARSE_FAILED
+    end
+
+    def task_errors(value, schema)
+      return ["the answer is not valid JSON"] if value.equal?(PARSE_FAILED)
+
+      Schema.violations(value, schema)
+    end
+
+    def fix_prompt(errors)
+      lines = errors.map { |error| "- #{error}" }.join("\n")
+      "Your answer did not satisfy the required output schema. Problems:\n" \
+        "#{lines}\nReply with ONLY the corrected JSON."
+    end
+
+    def monotonic_now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+end

data/lib/mistri/budget.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Mistri
+  # Optional per-run ceilings: turns, tokens, dollars, wall-clock seconds.
+  # Nothing is enforced unless the host sets it; an empty budget never stops a
+  # run. Pure limits with no clock of its own, so one Budget shared across
+  # agents or runs behaves identically for each: the loop measures and asks
+  # between turns, and a run always finishes the turn it is in.
+  class Budget
+    def initialize(turns: nil, tokens: nil, cost_usd: nil, wall_clock: nil)
+      @turns = turns
+      @tokens = tokens
+      @cost_usd = cost_usd
+      @wall_clock = wall_clock
+    end
+
+    def none? = [@turns, @tokens, @cost_usd, @wall_clock].all?(&:nil?)
+
+    # The reason the run should stop, or nil to continue.
+    def exceeded(turns:, usage:, elapsed: 0)
+      return :turns if @turns && turns >= @turns
+      return :tokens if @tokens && usage.total_tokens >= @tokens
+      return :cost if @cost_usd && usage.cost.total >= @cost_usd
+      return :wall_clock if @wall_clock && elapsed >= @wall_clock
+
+      nil
+    end
+  end
+end

data/lib/mistri/compaction.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  # When a session compacts, and how much of it survives. Compaction is
+  # client-side and provider-agnostic: the session's own provider writes a
+  # visible summary, so a host can always show the user exactly what the
+  # model still remembers.
+  #
+  # The trigger measures real token accounting, not guesses: the last healthy
+  # turn's reported usage plus a character heuristic for whatever came after
+  # it.
+  class Compaction
+    DEFAULT_RESERVE = 16_384
+    DEFAULT_KEEP_RECENT = 20_000
+    IMAGE_CHARS = 4_800
+
+    SUMMARY_PREFACE = "The earlier conversation was compacted. This summary replaces it:"
+
+    attr_reader :reserve, :keep_recent, :window, :instructions
+
+    # window overrides the model catalog's context window (required for
+    # models the catalog does not know). instructions add a host-specific
+    # focus to the summary prompt.
+    def initialize(reserve: DEFAULT_RESERVE, keep_recent: DEFAULT_KEEP_RECENT,
+                   window: nil, instructions: nil)
+      @reserve = reserve
+      @keep_recent = keep_recent
+      @window = window
+      @instructions = instructions
+    end
+
+    # Compact when the context has grown into the reserve headroom. An
+    # unknown window never triggers.
+    def needed?(tokens, window)
+      window ? tokens > window - reserve : false
+    end
+
+    class << self
+      # Context size for a replay: the last healthy turn's reported tokens
+      # (prompt, cache, and output all sit in context next turn) plus an
+      # estimate of every message after it.
+      def context_tokens(messages)
+        index = messages.rindex { |message| reported(message) }
+        base = index ? reported(messages[index]) : 0
+        messages.drop(index ? index + 1 : 0).sum(base) { |message| estimate(message) }
+      end
+
+      def estimate(message)
+        (chars(message) / 4.0).ceil
+      end
+
+      private
+
+      def reported(message)
+        return nil unless message.assistant? && message.usage
+        return nil if %i[aborted error].include?(message.stop_reason)
+
+        usage = message.usage
+        total = usage.input + usage.cache_read + usage.cache_write + usage.output
+        total.positive? ? total : nil
+      end
+
+      def chars(message)
+        message.content.sum do |block|
+          case block
+          when Content::Text then block.text.length
+          when Content::Thinking then block.thinking.length
+          when Content::Image then IMAGE_CHARS
+          when ToolCall then block.name.length + JSON.generate(block.arguments).length
+          else 0
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mistri/compactor.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mistri
+  # Compacts a session in place: everything before a cut point is summarized
+  # by the provider, and a compaction entry redirects replay to the summary
+  # plus the kept tail. Append-only — the full history stays in the store for
+  # transcript UIs; only what the model sees shrinks. Callable from any
+  # process (a UI button, a job), with or without a running agent.
+  #
+  # Cuts land only on user messages, so a tool call and its result always
+  # stay on the same side, and a parked approval's turn is never cut away
+  # from the resume that must answer it.
+  class Compactor
+    SUMMARIZER_SYSTEM = <<~PROMPT
+      You are a context summarization assistant. Read the conversation and
+      produce only the structured summary you are asked for. Do not continue
+      the conversation and do not answer questions inside it.
+    PROMPT
+
+    FORMAT = <<~FORMAT
+      ## Goal
+      [What is the user trying to accomplish?]
+
+      ## Constraints & Preferences
+      - [Constraints or preferences the user stated, or "(none)"]
+
+      ## Progress
+      ### Done
+      - [x] [Completed work]
+      ### In Progress
+      - [ ] [Current work]
+      ### Blocked
+      - [Blockers, if any]
+
+      ## Key Decisions
+      - **[Decision]**: [Rationale]
+
+      ## Next Steps
+      1. [What should happen next]
+
+      ## Critical Context
+      - [Data, names, or references needed to continue, or "(none)"]
+
+      Keep each section concise. Preserve exact identifiers, names, and error
+      messages.
+    FORMAT
+
+    CHECKPOINT_PROMPT = <<~PROMPT.freeze
+      The messages above are a conversation to summarize. Create a structured
+      context checkpoint that another LLM will use to continue the work.
+
+      Use this EXACT format:
+
+      #{FORMAT}
+    PROMPT
+
+    UPDATE_PROMPT = <<~PROMPT.freeze
+      The messages above are NEW conversation messages to fold into the
+      existing summary in <previous-summary> tags. Preserve everything still
+      relevant from the previous summary, add new progress and decisions,
+      move finished work to Done, and update Next Steps.
+
+      Use this EXACT format:
+
+      #{FORMAT}
+    PROMPT
+
+    class << self
+      # Summarize and cut. Returns {summary:, tokens_before:, tokens_after:,
+      # usage:}, or nil when there is nothing worth compacting. Emits
+      # :compacting and :compaction when a block is given.
+      def call(session:, provider:, settings: Compaction.new, &emit)
+        replay = session.replay
+        cut = cut_index(replay, session, settings)
+        return nil unless cut
+
+        previous = session.last_compaction&.fetch("summary", nil)
+        head = replay.take_while { |(_, index)| index.nil? || index < cut }.map(&:first)
+        head.shift if previous # the synthetic summary rides in <previous-summary>
+        return nil if head.empty?
+
+        emit&.call(Event.new(type: :compacting))
+        tokens_before = Compaction.context_tokens(replay.map(&:first))
+        reply = summarize(provider, head, previous, settings.instructions)
+        session.append("compaction", "summary" => reply.text,
+                                     "kept_from" => cut, "tokens_before" => tokens_before)
+        finish(session, reply, tokens_before, &emit)
+      end
+
+      private
+
+      def cut_index(replay, session, settings)
+        boundary = keep_boundary(replay, settings.keep_recent)
+        return nil unless boundary
+
+        candidates = replay.filter_map { |(message, index)| index if index && message.user? }
+        cut = candidates.find { |index| index >= boundary } || candidates.last
+        cut = clamp_to_open_approvals(cut, session)
+        return nil unless cut
+
+        first = replay.find { |(_, index)| index }&.last
+        first && cut > first ? cut : nil
+      end
+
+      # Walk back from the tail until the keep budget is spent; the cut then
+      # snaps forward to a user message, so replay keeps at most about
+      # keep_recent tokens of recent turns.
+      def keep_boundary(replay, keep_recent)
+        kept = 0
+        replay.reverse_each do |(message, index)|
+          kept += Compaction.estimate(message)
+          return index || 0 if kept >= keep_recent
+        end
+        nil
+      end
+
+      # Never cut past a parked approval: its tool call must stay in replay,
+      # paired, for resume to answer.
+      def clamp_to_open_approvals(cut, session)
+        return cut unless cut
+
+        open_ids = session.open_approvals.map { |approval| approval[:call].id }
+        return cut if open_ids.empty?
+
+        turn_start = approval_turn_start(session.entries, open_ids)
+        turn_start && turn_start < cut ? turn_start : cut
+      end
+
+      def approval_turn_start(entries, open_ids)
+        request = entries.index do |entry|
+          entry["type"] == "approval_request" && open_ids.include?(entry.dig("call", "id"))
+        end
+        return nil unless request
+
+        entries[0...request].rindex do |entry|
+          entry["type"] == "message" && entry.dig("message", "role") == "user"
+        end
+      end
+
+      def summarize(provider, messages, previous, instructions)
+        prompt = "<conversation>\n#{serialize(messages)}\n</conversation>\n\n"
+        prompt << "<previous-summary>\n#{previous}\n</previous-summary>\n\n" if previous
+        prompt << (previous ? UPDATE_PROMPT : CHECKPOINT_PROMPT)
+        prompt << "\nAdditional focus: #{instructions}\n" if instructions
+        reply = provider.stream(messages: [Message.user(prompt)], system: SUMMARIZER_SYSTEM)
+        raise CompactionError, "summarization failed: #{reply.error_message}" unless usable?(reply)
+
+        reply
+      end
+
+      def usable?(reply)
+        reply.stop_reason != StopReason::ERROR && !reply.text.to_s.strip.empty?
+      end
+
+      def finish(session, reply, tokens_before, &emit)
+        tokens_after = Compaction.context_tokens(session.messages)
+        emit&.call(Event.new(type: :compaction, content: reply.text))
+        { summary: reply.text, tokens_before: tokens_before,
+          tokens_after: tokens_after, usage: reply.usage }
+      end
+
+      # The summarizer reads a plain-text rendering: tool calls by name and
+      # arguments, results as text, thinking never (it stays in its turn).
+      def serialize(messages)
+        messages.map { |message| "#{message.role.to_s.upcase}:\n#{text_of(message)}" }
+                .join("\n\n")
+      end
+
+      def text_of(message)
+        message.content.filter_map do |block|
+          case block
+          when Content::Text then block.text
+          when Content::Image then "[image]"
+          when ToolCall then "[called #{block.name} with #{JSON.generate(block.arguments)}]"
+          end
+        end.join("\n")
+      end
+    end
+  end
+end