riffer-rig 0.3.0 → 0.5.0

data/lib/riffer/rig/runtime.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require 'date'
+
+# One Runtime builds its own Riffer::Agent from a per-instance
+# Riffer::Agent::Config and runs a prompt: streamed as events, or run to
+# completion and returned as riffer's Agent::Response.
+#
+#   runtime = Riffer::Rig::Runtime.new('mock/x')
+#   runtime.prompt('hello') { |event| ... }   # yields riffer StreamEvents
+#   runtime.prompt('hello').each { |event| }  # an Enumerator without a block
+#   response = runtime.ask('hello')           # a Riffer::Agent::Response
+#
+# Two Runtimes in one process share nothing but the process-wide extension
+# registry and riffer's provider repository. One prompt runs at a time; a
+# second while one is running raises Riffer::Rig::Runtime::BusyError. The
+# Runtime never renders, never prints, never reads the filesystem.
+class Riffer::Rig::Runtime
+  # Raised when a second prompt, ask or registrar build runs while one is
+  # already running on this Runtime.
+  class BusyError < StandardError; end
+
+  BASE_PROMPT_TEMPLATE = <<~TEXT
+    You are %<name>s, a general-purpose agent. You work by using the tools you have
+    been given; each tool describes what it does and when to use it.
+
+    - Verify with your tools before answering. When a tool can settle a question,
+      look rather than guess.
+    - Do what was asked, and all of what was asked. Do not widen the scope, tidy
+      nearby things, or add extras that were not requested.
+    - Be concise. Lead with the outcome; do not restate the question.
+  TEXT
+
+  DEFAULT_NAME = 'riffer'
+
+  # The legacy CodingAgent's default: an unlimited agent loop. riffer's own
+  # default (16) is too small for a general-purpose harness.
+  DEFAULT_MAX_STEPS = nil #: Integer?
+
+  # @rbs!
+  #   interface _Host
+  #     def ask: (?String, ?options: Array[String]?, ?secret: bool) -> String?
+  #     def confirm: (?String) -> bool
+  #     def notify: (?String, ?level: Symbol) -> void
+  #     def progress: (?String) { () -> void } -> void
+  #     def capabilities: () -> Set[Symbol]
+  #   end
+
+  # @rbs @agent: Riffer::Agent
+  # @rbs @cwd: String
+  # @rbs @host: _Host
+  # @rbs @settings: Hash[Symbol, untyped]
+  # @rbs @busy: bool
+  # @rbs @registrar: Riffer::Rig::Registrar
+
+  # @dynamic agent, cwd, host, settings
+  attr_reader :agent #: Riffer::Agent
+  attr_reader :cwd #: String
+  attr_reader :host #: _Host
+  attr_reader :settings #: Hash[Symbol, untyped]
+
+  # @rbs model: String
+  # @rbs extensions: Array[Riffer::Rig::Extension]
+  # @rbs tools: Array[String]?
+  # @rbs settings: Hash[Symbol, untyped]
+  # @rbs host: _Host
+  # @rbs cwd: String?
+  # @rbs name: String
+  # @rbs instructions: String?
+  # @rbs credentials: Hash[String, String]
+  # @rbs pricing: Hash[String, Riffer::Rig::Settings::Pricing]
+  # @rbs max_steps: Integer?
+  # @rbs snapshot: Hash[Symbol, untyped]?
+  # @rbs return: void
+  def initialize(
+    model,
+    extensions: [],
+    tools: nil,
+    settings: {},
+    host: Riffer::Rig::Host.new,
+    cwd: nil,
+    name: DEFAULT_NAME,
+    instructions: nil,
+    credentials: {},
+    pricing: {},
+    max_steps: DEFAULT_MAX_STEPS,
+    snapshot: nil
+  )
+    @host = host
+    @cwd = cwd || Dir.pwd
+    @settings = settings
+
+    @busy = false
+    @registrar = build_registrar(extensions)
+    tool_classes = select_tools(@registrar.tools, tools)
+    base_prompt = instructions || format(BASE_PROMPT_TEMPLATE, name: name)
+
+    @agent = Riffer::Agent.new(
+      config: Riffer::Agent::Config.new(
+        model: model,
+        instructions: system_prompt(base_prompt),
+        tools_config: tool_classes,
+        max_steps: max_steps
+      )
+    )
+  end
+
+  # @rbs text: String
+  # @rbs &block: ?(Riffer::StreamEvents::Base) -> void
+  # @rbs return: (nil | Enumerator[Riffer::StreamEvents::Base, void])
+  def prompt(text, &block)
+    raise BusyError, 'a prompt is already running on this Runtime' if @busy
+
+    @busy = true
+    if block
+      @agent.stream(text).each(&block)
+      nil
+    else
+      @agent.stream(text)
+    end
+  ensure
+    @busy = false
+  end
+
+  # @rbs text: String
+  # @rbs return: Riffer::Agent::Response
+  def ask(text)
+    raise BusyError, 'a prompt is already running on this Runtime' if @busy
+
+    @busy = true
+    @agent.stream(text).each { |event| event }
+  ensure
+    @busy = false
+  end
+
+  private
+
+  # @rbs extensions: Array[Riffer::Rig::Extension]
+  # @rbs return: Riffer::Rig::Registrar
+  def build_registrar(extensions)
+    raise BusyError, 'a prompt is already running on this Runtime' if @busy
+
+    extensions.each_with_object(Riffer::Rig::Registrar.new) do |extension, registrar|
+      extension.run(registrar)
+    end
+  end
+
+  # @rbs registered: Array[singleton(Riffer::Tool)]
+  # @rbs allowlist: Array[String]?
+  # @rbs return: Array[singleton(Riffer::Tool)]
+  def select_tools(registered, allowlist)
+    return registered if allowlist.nil?
+
+    registered.select { |klass| allowlist.include?(klass.name) }
+  end
+
+  # @rbs base_prompt: String
+  # @rbs return: String
+  def system_prompt(base_prompt)
+    "#{base_prompt}\n\nCurrent date: #{Date.today}\nCurrent working directory: #{@cwd}"
+  end
+end

data/lib/riffer/rig/settings/document.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Settings::Document
+  # @rbs @model: String?
+  # @rbs @reasoning: String?
+  # @rbs @models: Hash[String, Riffer::Rig::Settings::Pricing]
+
+  # @dynamic model, reasoning, models
+  attr_reader :model #: String?
+  attr_reader :reasoning #: String?
+  attr_reader :models #: Hash[String, Riffer::Rig::Settings::Pricing]
+
+  # @rbs source: untyped
+  # @rbs return: void
+  def initialize(source)
+    @model = source['model'].is_a?(String) ? source['model'] : nil
+    @reasoning = source['reasoning'].is_a?(String) ? source['reasoning'] : nil
+    entries = source['models'].is_a?(Hash) ? source['models'] : {} #: Hash[String, untyped]
+    @models = entries.filter_map do |name, entry|
+      [name, Riffer::Rig::Settings::Pricing.from(entry)] if name.is_a?(String) && entry.is_a?(Hash)
+    end.to_h
+  end
+end

data/lib/riffer/rig/settings/pricing.rb

@@ -5,6 +5,17 @@ class Riffer::Rig::Settings::Pricing
   # @dynamic input, output, cache_write, cache_read
   attr_reader :input, :output, :cache_write, :cache_read #: Float
 
+  # @rbs entry: Hash[String, untyped]
+  # @rbs return: ::Riffer::Rig::Settings::Pricing
+  def self.from(entry)
+    new(
+      input: entry.fetch('input', 0).to_f,
+      output: entry.fetch('output', 0).to_f,
+      cache_write: entry.fetch('cache_write', 0).to_f,
+      cache_read: entry.fetch('cache_read', 0).to_f
+    )
+  end
+
   # @rbs input: Float
   # @rbs output: Float
   # @rbs cache_write: Float

data/lib/riffer/rig/settings.rb

@@ -51,7 +51,7 @@ module Riffer::Rig::Settings
   # @rbs path: String
   # @rbs return: String
   def model(path: PATH)
-    read(path).fetch('model', DEFAULT_MODEL)
+    read(path).model || DEFAULT_MODEL
   end
 
   # Returns model options for the configured model and reasoning level, ready
@@ -80,15 +80,7 @@ module Riffer::Rig::Settings
   # @rbs path: String
   # @rbs return: Pricing?
   def pricing_for(model, path: PATH)
-    entry = read(path).dig('models', model)
-    return nil unless entry.is_a?(Hash)
-
-    Pricing.new(
-      input: entry.fetch('input', 0).to_f,
-      output: entry.fetch('output', 0).to_f,
-      cache_write: entry.fetch('cache_write', 0).to_f,
-      cache_read: entry.fetch('cache_read', 0).to_f
-    )
+    read(path).models[model]
   end
 
   private
@@ -102,10 +94,10 @@ module Riffer::Rig::Settings
   end
 
   # @rbs path: String
-  # @rbs ?provider: String?
+  # @rbs provider: String?
   # @rbs return: String?
   def reasoning_for(path: PATH, provider: nil)
-    level = read(path)['reasoning']
+    level = read(path).reasoning
     valid_levels = (provider && REASONING_LEVELS_BY_PROVIDER[provider]) || []
     valid_levels.include?(level) ? level : nil
   end
@@ -129,16 +121,16 @@ module Riffer::Rig::Settings
     end
   end
 
-  # The parsed settings file, or an empty hash when the file is absent or
+  # The parsed settings file, or an empty document when the file is absent or
   # malformed.
   #
   # @rbs path: String
-  # @rbs return: Hash[String, untyped]
+  # @rbs return: Document
   def read(path)
-    return {} unless File.file?(path)
+    return Document.new({}) unless File.file?(path)
 
-    JSON.parse(File.read(path))
+    Document.new(JSON.parse(File.read(path)))
   rescue JSON::ParserError
-    {}
+    Document.new({})
   end
 end

data/lib/riffer/rig/token_tally.rb

@@ -22,7 +22,7 @@ class Riffer::Rig::TokenTally
   # @dynamic input_tokens, output_tokens, cache_write_tokens, cache_read_tokens
   attr_reader :input_tokens, :output_tokens, :cache_write_tokens, :cache_read_tokens
 
-  # @rbs ?pricing: Riffer::Rig::Settings::Pricing?
+  # @rbs pricing: Riffer::Rig::Settings::Pricing?
   # @rbs return: void
   def initialize(pricing: nil)
     @pricing = pricing

data/lib/riffer/rig/tools/bash.rb

@@ -15,12 +15,15 @@ class Riffer::Rig::Tools::Bash < Riffer::Tool
 
   params do
     required :command, String, description: 'The shell command to run'
-    optional :timeout_ms, Integer, description: 'Kill the command after this many milliseconds', default: DEFAULT_TIMEOUT_MS
+    optional :timeout_ms,
+             Integer,
+             description: 'Kill the command after this many milliseconds',
+             default: DEFAULT_TIMEOUT_MS
   end
 
   # @rbs context: Riffer::Agent::Context?
   # @rbs command: String
-  # @rbs ?timeout_ms: Integer
+  # @rbs timeout_ms: Integer
   # @rbs return: Riffer::Tools::Response
   def call(context:, command:, timeout_ms: DEFAULT_TIMEOUT_MS)
     output, status = run(command, timeout_ms / 1000.0)

data/lib/riffer/rig/tools/edit.rb

@@ -9,14 +9,17 @@ class Riffer::Rig::Tools::Edit < Riffer::Tool
     required :path, String, description: 'Path to the file (absolute, or relative to the working directory)'
     required :old_string, String, description: 'The exact text to replace'
     required :new_string, String, description: 'The text to replace it with'
-    optional :replace_all, Riffer::Params::Boolean, description: 'Replace all occurrences instead of requiring a unique match', default: false
+    optional :replace_all,
+             Riffer::Params::Boolean,
+             description: 'Replace all occurrences instead of requiring a unique match',
+             default: false
   end
 
   # @rbs context: Riffer::Agent::Context?
   # @rbs path: String
   # @rbs old_string: String
   # @rbs new_string: String
-  # @rbs ?replace_all: bool
+  # @rbs replace_all: bool
   # @rbs return: Riffer::Tools::Response
   def call(context:, path:, old_string:, new_string:, replace_all: false)
     resolved = File.expand_path(path, Dir.pwd)
@@ -26,7 +29,12 @@ class Riffer::Rig::Tools::Edit < Riffer::Tool
     occurrences = content.scan(old_string).length
 
     return error("old_string not found in #{path}", type: :not_found) if occurrences.zero?
-    return error("old_string is not unique in #{path} (#{occurrences} matches). Pass replace_all or add more context.", type: :ambiguous_match) if occurrences > 1 && !replace_all
+    if occurrences > 1 && !replace_all
+      return error(
+        "old_string is not unique in #{path} (#{occurrences} matches). Pass replace_all or add more context.",
+        type: :ambiguous_match
+      )
+    end
 
     # Block form so backslash sequences in new_string (\0, \1, \\) are inserted
     # literally instead of being interpreted as regexp backreferences.

data/lib/riffer/rig/tools/read.rb

@@ -15,8 +15,8 @@ class Riffer::Rig::Tools::Read < Riffer::Tool
 
   # @rbs context: Riffer::Agent::Context?
   # @rbs path: String
-  # @rbs ?offset: Integer?
-  # @rbs ?limit: Integer
+  # @rbs offset: Integer?
+  # @rbs limit: Integer
   # @rbs return: Riffer::Tools::Response
   def call(context:, path:, offset: nil, limit: DEFAULT_LIMIT)
     resolved = File.expand_path(path, Dir.pwd)

data/lib/riffer/rig/ui/animator.rb

@@ -23,15 +23,15 @@ class Riffer::Rig::UI::Animator
 
   REASONING_TICK_RANGE = (1..5) #: Range[Integer]
 
-  # @rbs @io: untyped
+  # @rbs @io: IO
   # @rbs @theme: Riffer::Rig::UI::Theme
   # @rbs @thread: Thread?
   # @rbs @mode: Symbol
   # @rbs @phrase: String?
   # @rbs @stop: bool
 
-  # @rbs io: untyped
-  # @rbs ?theme: Riffer::Rig::UI::Theme
+  # @rbs io: IO
+  # @rbs theme: Riffer::Rig::UI::Theme
   # @rbs return: void
   def initialize(io: $stdout, theme: Riffer::Rig::UI::Theme.for(io))
     @io = io
@@ -60,7 +60,7 @@ class Riffer::Rig::UI::Animator
     end
   end
 
-  # @rbs ?mode: Symbol
+  # @rbs mode: Symbol
   # @rbs return: void
   def start(mode = :neutral)
     return unless enabled?
@@ -88,7 +88,7 @@ class Riffer::Rig::UI::Animator
   end
 
   # @rbs tick: Integer
-  # @rbs ?label: String
+  # @rbs label: String
   # @rbs return: String
   def equalizer(tick, label = NEUTRAL_LABEL)
     bars = Array.new(EQ_BARS) do |i|
@@ -141,6 +141,6 @@ class Riffer::Rig::UI::Animator
 
   # @rbs return: bool
   def enabled?
-    @theme.enabled && @io.respond_to?(:tty?) && @io.tty?
+    @theme.enabled && @io.tty?
   end
 end

data/lib/riffer/rig/ui/cursor.rb

@@ -7,11 +7,11 @@ class Riffer::Rig::UI::Cursor
 
   SHOW = "\e[?25h" #: String
 
-  # @rbs @io: untyped
+  # @rbs @io: IO
   # @rbs @theme: Riffer::Rig::UI::Theme
 
-  # @rbs io: untyped
-  # @rbs ?theme: Riffer::Rig::UI::Theme
+  # @rbs io: IO
+  # @rbs theme: Riffer::Rig::UI::Theme
   # @rbs return: void
   def initialize(io: $stdout, theme: Riffer::Rig::UI::Theme.for(io))
     @io = io
@@ -41,6 +41,6 @@ class Riffer::Rig::UI::Cursor
 
   # @rbs return: bool
   def enabled?
-    @theme.enabled && @io.respond_to?(:tty?) && @io.tty?
+    @theme.enabled && @io.tty?
   end
 end

data/lib/riffer/rig/ui/renderer.rb

@@ -5,21 +5,25 @@ require 'json'
 class Riffer::Rig::UI::Renderer
   RESULT_PREVIEW_LIMIT = 200 #: Integer
 
-  # @rbs @io: untyped
+  # @rbs @io: IO
   # @rbs @theme: Riffer::Rig::UI::Theme
   # @rbs @tally: Riffer::Rig::TokenTally?
   # @rbs @smoother: Riffer::Rig::UI::Smoother | PassThroughSmoother?
+  # @rbs @deferred_usage: Riffer::Providers::TokenUsage?
+  # @rbs @prose_gap_pending: bool
 
-  # @rbs io: untyped
-  # @rbs ?theme: Riffer::Rig::UI::Theme
-  # @rbs ?tally: Riffer::Rig::TokenTally?
-  # @rbs ?smoother: Riffer::Rig::UI::Smoother | PassThroughSmoother?
+  # @rbs io: IO
+  # @rbs theme: Riffer::Rig::UI::Theme
+  # @rbs tally: Riffer::Rig::TokenTally?
+  # @rbs smoother: Riffer::Rig::UI::Smoother | PassThroughSmoother?
   # @rbs return: void
   def initialize(io: $stdout, theme: Riffer::Rig::UI::Theme.for(io), tally: nil, smoother: nil)
     @io = io
     @theme = theme
     @tally = tally
     @smoother = smoother
+    @deferred_usage = nil
+    @prose_gap_pending = false
   end
 
   # @rbs event: Riffer::StreamEvents::Base
@@ -27,33 +31,127 @@ class Riffer::Rig::UI::Renderer
   def render(event)
     case event
     when Riffer::StreamEvents::TextDelta
-      smoother << event.content
+      render_prose(event.content)
     when Riffer::StreamEvents::ToolCallDone
-      drain_smoother
-      @io.puts("\n#{@theme.cyan("⚙ #{event.name}(#{format_arguments(event.arguments)})")}")
+      render_tool_activity(2) { @theme.cyan("⚙ #{event.name}(#{format_arguments(event.arguments)})") }
     when Riffer::StreamEvents::SkillActivation
-      drain_smoother
-      @io.puts("\n#{@theme.magenta("✦ skill: #{event.name}")}")
+      render_block(0) { @theme.magenta("✦ skill: #{event.name}") }
     when Riffer::StreamEvents::Interrupt
-      drain_smoother
-      @io.puts(@theme.dim("[interrupted: #{event.reason}]"))
+      render_block(0) { @theme.dim("[interrupted: #{event.reason}]") }
     when Riffer::StreamEvents::TokenUsageDone
-      drain_smoother
-      render_token_usage(event.token_usage)
+      current = @deferred_usage
+      @deferred_usage = current ? current + event.token_usage : event.token_usage
     end
   end
 
+  # The prompt holds the line open for typed input, so unlike render_block it
+  # ends without a newline. It sits at the renderer so a tool group left open by
+  # the previous turn closes here, and the next turn's blocks open cleanly.
+  #
+  # @rbs return: void
+  def prompt
+    @prose_gap_pending = true
+    @io.puts
+    @io.print("#{@theme.pink('›')} ")
+    @io.flush
+  end
+
+  # Usage arrives per model call but tool results arrive via the session
+  # callback after each call's stream ends, so rendering inline would print the
+  # stats above the results they belong with. Held until the turn's output is
+  # done, then printed as one line below it.
+  #
+  # @rbs return: void
+  def flush_usage
+    usage = @deferred_usage
+    @deferred_usage = nil
+    tally = @tally
+    return unless usage && tally
+
+    tally.add(usage)
+    render_block(0) { @theme.dim(usage_line(usage, tally)) }
+  end
+
   # @rbs message: Riffer::Messages::Base
   # @rbs return: void
   def render_tool_result(message)
     return unless message.is_a?(Riffer::Messages::Tool)
 
+    open_tool_activity
     line = "↳ #{preview(message.content)}"
-    @io.puts(message.error? ? @theme.red(line) : @theme.dim(line))
+    styled = message.error? ? @theme.red(line) : @theme.dim(line)
+    @io.print("    #{styled}\n")
+    @io.flush
   end
 
   private
 
+  # Rule 2 for one-off blocks (skill line, interrupt, stats): one blank line
+  # above, no indent. The smoother drains first so any pending partial prose
+  # block ends cleanly before the gap is written, and any open tool group closes
+  # so the next group opens with its own gap.
+  #
+  # @rbs indent: Integer
+  # @rbs &block: () -> String
+  # @rbs return: void
+  def render_block(indent, &)
+    drain_smoother
+    @io.puts
+    @prose_gap_pending = true
+    @io.puts((' ' * indent) + yield)
+    @io.flush
+  end
+
+  # The blank line above a prose block is written at the first delta after a
+  # non-prose block. Streaming makes "which block is first?" a stateful
+  # question, so the answer is tracked rather than embedded at each render site.
+  #
+  # @rbs content: String
+  # @rbs return: void
+  def render_prose(content)
+    if @prose_gap_pending
+      @prose_gap_pending = false
+      @io.print("\n")
+    end
+    smoother << content
+  end
+
+  # @rbs indent: Integer
+  # @rbs &block: () -> String
+  # @rbs return: void
+  def render_tool_activity(indent, &)
+    open_tool_activity
+    @io.puts((' ' * indent) + yield)
+    @io.flush
+  end
+
+  # Tool-activity lines (⚙ calls, ↳ results) share one blank line above the
+  # group instead of one between each line — the gap goes between groups, not
+  # inside a pair. The group stays open so prose after it pays the closing gap.
+  #
+  # @rbs return: void
+  def open_tool_activity
+    return if @prose_gap_pending
+
+    drain_smoother
+    @io.puts
+    @prose_gap_pending = true
+  end
+
+  # @rbs usage: Riffer::Providers::TokenUsage
+  # @rbs tally: Riffer::Rig::TokenTally
+  # @rbs return: String
+  def usage_line(usage, tally)
+    parts = ["↑#{usage.input_tokens}", "↓#{usage.output_tokens}"]
+    parts << "cache_write:#{usage.cache_write_tokens}" if usage.cache_write_tokens&.positive?
+    parts << "cache_read:#{usage.cache_read_tokens}" if usage.cache_read_tokens&.positive?
+    parts << "session #{tally.total_tokens} tok"
+    cost = tally.estimated_cost
+    parts << format('~$%.4f', cost) if cost
+
+    parts.join(' · ')
+  end
+
   # @rbs return: Riffer::Rig::UI::Smoother | PassThroughSmoother
   def smoother
     @smoother || PassThroughSmoother.new(@io)
@@ -62,9 +160,9 @@ class Riffer::Rig::UI::Renderer
   # Stand-in when no smoother is injected, so a bare Riffer::Rig::UI::Renderer still prints
   # synchronously.
   class PassThroughSmoother
-    # @rbs @io: untyped
+    # @rbs @io: IO
 
-    # @rbs io: untyped
+    # @rbs io: IO
     # @rbs return: void
     def initialize(io) = @io = io
 
@@ -88,25 +186,6 @@ class Riffer::Rig::UI::Renderer
     smoother.drain
   end
 
-  # @rbs usage: Riffer::Providers::TokenUsage
-  # @rbs return: void
-  def render_token_usage(usage)
-    tally = @tally
-    return unless tally
-
-    tally.add(usage)
-
-    parts = ["↑#{usage.input_tokens}", "↓#{usage.output_tokens}"]
-    parts << "cache_write:#{usage.cache_write_tokens}" if usage.cache_write_tokens&.positive?
-    parts << "cache_read:#{usage.cache_read_tokens}" if usage.cache_read_tokens&.positive?
-
-    session_parts = ["session #{tally.total_tokens} tok"]
-    cost = tally.estimated_cost
-    session_parts << format('~$%.4f', cost) if cost
-
-    @io.puts("\n#{@theme.dim("#{parts.join(' · ')}   #{session_parts.join(' · ')}")}")
-  end
-
   # @rbs arguments: String
   # @rbs return: String
   def format_arguments(arguments)