riffer-rig 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01f34d2a4cb9347ea2d9f7a81a0969415c98b6622d4f78e123034f9b2c15509e
-  data.tar.gz: 5a61c231fcf2832a514ec62513bdf42e56c87dc08ec994f9fb04fa263188b53d
+  metadata.gz: 4a1580a7e4f2ed5e6d1f18714ef469b7d4623bec94552510a836a5f5e5664504
+  data.tar.gz: 7e871b6b1f8c9de6e3788979103f7afe65beea7a9c5fa7813e17b29e4e8eb528
 SHA512:
-  metadata.gz: 1b8518928f77909373cfdfe2783372aa1a6ebb04fed67a70951041c0adf637bf3aba0ee8b85051f9bdb63c1cdcda91554b2fd9c86b4f82a279eed30964984588
-  data.tar.gz: 3cd5548405bcf8607d516e7f8a585cdf327cfc904e1641458aca4802e8a3654127c6ed44a46435003faeca1eaaafcd4bed0968c0787a90aca8c586438b685146
+  metadata.gz: db021260a12a48c02bb6ff92278819416bcc267bd78015f01f80bd3a9ed64c585e37d17573a3ba47ba28d99bd0ef586665a465782d36a6a85231c08ad4a4fd51
+  data.tar.gz: 5ea0ed0a06d1a318267bd3d63b693f974ff8ca814e26be0eb5837cdac09527bea33a75357f7a1a11b419854ed72810a5d571c8508010e8bd62f327eb922f04eb

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [0.5.0](https://github.com/bottrall/riffer-rig/compare/v0.4.0...v0.5.0) (2026-09-19)
+
+
+### Features
+
+* add ask, max_steps and riffer response ([#178](https://github.com/bottrall/riffer-rig/issues/178)) ([948d753](https://github.com/bottrall/riffer-rig/commit/948d75354a7d0a5a9d35055b7d890dea9e51f1a1))
+* add Runtime with a per-instance agent, base prompt and tool seam ([#160](https://github.com/bottrall/riffer-rig/issues/160)) ([97019ca](https://github.com/bottrall/riffer-rig/commit/97019ca6f80c95bcf22e443652f1d90d453d02de))
+* type IO streams and JSON boundaries, dropping explicit untyped ([#174](https://github.com/bottrall/riffer-rig/issues/174)) ([22407be](https://github.com/bottrall/riffer-rig/commit/22407befc471d1fbbe14188456ee1ce248ddc4c7))
+
+
+### Bug Fixes
+
+* drain smoother backlog before every animator restart ([#177](https://github.com/bottrall/riffer-rig/issues/177)) ([3126155](https://github.com/bottrall/riffer-rig/commit/3126155fdeba3de2ab2b9905b7e7de55593de834))
+* drop invalid ? optional markers from rbs-inline annotations ([#171](https://github.com/bottrall/riffer-rig/issues/171)) ([60030bf](https://github.com/bottrall/riffer-rig/commit/60030bf7ca930e9d35cbd8c2e3a8ae8ae1692830))
+
+## [0.4.0](https://github.com/bottrall/riffer-rig/compare/v0.3.0...v0.4.0) (2026-09-13)
+
+
+### Features
+
+* **ui:** one blank line between blocks, prompt-owned gaps ([#170](https://github.com/bottrall/riffer-rig/issues/170)) ([636e4d8](https://github.com/bottrall/riffer-rig/commit/636e4d82a069f158775043037a43e2aa494f56dc))
+
+
+### Bug Fixes
+
+* **lint:** adjust rubocop rules and reformat to match ([#168](https://github.com/bottrall/riffer-rig/issues/168)) ([56b81aa](https://github.com/bottrall/riffer-rig/commit/56b81aa904609f246340c8b8135ee7e57791abdd))
+
 ## [0.3.0](https://github.com/bottrall/riffer-rig/compare/v0.2.1...v0.3.0) (2026-09-10)
 
 

data/lib/riffer/rig/cli.rb

@@ -12,8 +12,8 @@ module Riffer::Rig::CLI
     'openrouter' => 'https://openrouter.ai/keys'
   }.freeze #: Hash[String, String]
 
-  # @rbs output: untyped
-  # @rbs input: untyped
+  # @rbs output: IO
+  # @rbs input: IO
   # @rbs return: Integer
   def start(output: $stdout, input: $stdin)
     theme = Riffer::Rig::UI::Theme.for(output)
@@ -21,8 +21,7 @@ module Riffer::Rig::CLI
     model    = Riffer::Rig::Settings.model
     provider = Riffer::Rig::Settings.provider_for(model)
 
-    api_key = (provider && Riffer::Rig::Credentials.api_key_for(provider)) ||
-              onboard(provider, theme, output:, input:)
+    api_key = (provider && Riffer::Rig::Credentials.api_key_for(provider)) || onboard(provider, theme, output:, input:)
     return 1 if api_key.nil?
 
     configure_provider(provider, api_key)
@@ -55,8 +54,8 @@ module Riffer::Rig::CLI
 
   # @rbs provider: String?
   # @rbs theme: Riffer::Rig::UI::Theme
-  # @rbs output: untyped
-  # @rbs input: untyped
+  # @rbs output: IO
+  # @rbs input: IO
   # @rbs return: String?
   def onboard(provider, theme, output:, input:)
     url  = (provider && PROVIDER_URLS[provider]) || 'your provider'
@@ -85,7 +84,7 @@ module Riffer::Rig::CLI
     (provider && Riffer::Rig::Credentials::PROVIDER_ENV_VARS[provider]) || 'the appropriate API key env var'
   end
 
-  # @rbs input: untyped
+  # @rbs input: IO
   # @rbs return: String?
   def read_secret(input)
     return input.noecho(&:gets) if input.respond_to?(:noecho) && input.tty?
@@ -101,7 +100,16 @@ module Riffer::Rig::CLI
     loaded  = [Riffer::Rig::CodingAgent::GLOBAL_AGENTS_FILE, File.join(Dir.pwd, 'AGENTS.md')].select { |path| File.file?(path) }
     context = loaded.empty? ? 'none' : loaded.join(', ')
 
-    animator.reveal([Riffer::Rig::UI::Banner.lines(theme, model: model, cwd: Dir.pwd, context: context, skills: count_skills, version: Riffer::Rig::VERSION)])
+    animator.reveal(
+      [Riffer::Rig::UI::Banner.lines(
+        theme,
+        model: model,
+        cwd: Dir.pwd,
+        context: context,
+        skills: count_skills,
+        version: Riffer::Rig::VERSION
+      )]
+    )
   end
 
   # @rbs return: String

data/lib/riffer/rig/coding_agent.rb

@@ -12,12 +12,7 @@ class Riffer::Rig::CodingAgent < Riffer::Agent
   model Riffer::Rig::Settings.model
   model_options Riffer::Rig::Settings.model_options
 
-  uses_tools [
-    Riffer::Rig::Tools::Read,
-    Riffer::Rig::Tools::Write,
-    Riffer::Rig::Tools::Edit,
-    Riffer::Rig::Tools::Bash
-  ]
+  uses_tools [Riffer::Rig::Tools::Read, Riffer::Rig::Tools::Write, Riffer::Rig::Tools::Edit, Riffer::Rig::Tools::Bash]
 
   skills do
     backend(->(_ctx) { Riffer::Skills::FilesystemBackend.new(GLOBAL_SKILLS_DIR, PROJECT_SKILLS_DIR.call) })
@@ -25,32 +20,34 @@ class Riffer::Rig::CodingAgent < Riffer::Agent
 
   max_steps nil
 
-  instructions(lambda do
-    context_files = [GLOBAL_AGENTS_FILE, File.join(Dir.pwd, 'AGENTS.md')]
-      .select { |path| File.file?(path) }
-      .map { |path| "<project_instructions path=\"#{path}\">\n#{File.read(path)}\n</project_instructions>" }
-
-    project_context =
-      if context_files.empty?
-        ''
-      else
-        "\n\n<project_context>\n#{context_files.join("\n\n")}\n</project_context>"
-      end
-
-    <<~PROMPT.chomp + project_context + "\n\nCurrent date: #{Date.today}\nCurrent working directory: #{Dir.pwd}"
-      You are an expert coding assistant running inside riffer-rig, a terminal coding agent. You help the user by reading files, running shell commands, editing code, and writing new files.
-
-      Available tools:
-      - read: read a file's contents
-      - write: write content to a file
-      - edit: replace an exact string in a file
-      - bash: run a shell command in the working directory
-
-      Guidelines:
-      - Be concise and direct in your responses.
-      - Show file paths clearly when working with files.
-      - Use bash for file exploration (ls, rg, find) rather than guessing.
-      - Prefer editing existing files over creating new ones.
-    PROMPT
-  end)
+  instructions(
+    lambda do
+      context_files = [GLOBAL_AGENTS_FILE, File.join(Dir.pwd, 'AGENTS.md')]
+        .select { |path| File.file?(path) }
+        .map { |path| "<project_instructions path=\"#{path}\">\n#{File.read(path)}\n</project_instructions>" }
+
+      project_context =
+        if context_files.empty?
+          ''
+        else
+          "\n\n<project_context>\n#{context_files.join("\n\n")}\n</project_context>"
+        end
+
+      <<~PROMPT.chomp + project_context + "\n\nCurrent date: #{Date.today}\nCurrent working directory: #{Dir.pwd}"
+        You are an expert coding assistant running inside riffer-rig, a terminal coding agent. You help the user by reading files, running shell commands, editing code, and writing new files.
+
+        Available tools:
+        - read: read a file's contents
+        - write: write content to a file
+        - edit: replace an exact string in a file
+        - bash: run a shell command in the working directory
+
+        Guidelines:
+        - Be concise and direct in your responses.
+        - Show file paths clearly when working with files.
+        - Use bash for file exploration (ls, rg, find) rather than guessing.
+        - Prefer editing existing files over creating new ones.
+      PROMPT
+    end
+  )
 end

data/lib/riffer/rig/credentials.rb

@@ -54,7 +54,7 @@ module Riffer::Rig::Credentials
   # @rbs return: String
   def save_api_key(provider, key, path: PATH)
     FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
-    data = read(path).tap { |h| h[provider] = key }
+    data = read(path).merge(provider => key)
     File.open(path, File::WRONLY | File::CREAT | File::TRUNC, 0o600) do |file|
       file.write(JSON.pretty_generate(data))
     end
@@ -68,21 +68,21 @@ module Riffer::Rig::Credentials
   # @rbs return: String?
   def key_from_file(provider, path)
     key = read(path)[provider]
-    return nil unless key.is_a?(String)
-    return key unless key.strip.empty?
+    return nil if key.nil? || key.strip.empty?
 
-    nil
+    key
   end
 
   # The parsed auth file, or an empty hash when the file is absent or
-  # malformed.
+  # malformed. Non-string values can't be keys, so they're dropped here rather
+  # than re-checked by every reader.
   #
   # @rbs path: String
-  # @rbs return: Hash[String, untyped]
+  # @rbs return: Hash[String, String]
   def read(path)
     return {} unless File.file?(path)
 
-    JSON.parse(File.read(path))
+    JSON.parse(File.read(path)).select { |_provider, key| key.is_a?(String) }
   rescue JSON::ParserError
     {}
   end

data/lib/riffer/rig/extension.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# An extension recorded by <tt>Riffer::Rig.extension</tt>: a name, an optional
+# Gem::Requirement on riffer-rig, and the block that runs against a Runtime's
+# registrar. The process registry holds these objects; Runtime.new runs their
+# blocks.
+class Riffer::Rig::Extension
+  # @rbs @name: String
+  # @rbs @requires: Gem::Requirement?
+  # @rbs @block: ^(::Riffer::Rig::Registrar) -> void
+
+  # @dynamic name, requires
+  attr_reader :name #: String
+  attr_reader :requires #: Gem::Requirement?
+
+  # @rbs name: String
+  # @rbs requires: String?
+  # @rbs &block: (::Riffer::Rig::Registrar) -> void
+  # @rbs return: void
+  def initialize(name, requires: nil, &block)
+    @name = name
+    @requires = requires && Gem::Requirement.new(requires)
+    @block = block
+  end
+
+  # @rbs registrar: Riffer::Rig::Registrar
+  # @rbs return: void
+  def run(registrar)
+    @block.call(registrar)
+  end
+end

data/lib/riffer/rig/host.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# A host receives questions and out-of-band messages from a Runtime. It is
+# duck-typed: any object with #ask, #confirm, #notify, #progress and
+# #capabilities is a host.
+#
+#   class HeadlessHost
+#     def capabilities = Set[:notify, :progress].freeze
+#     def ask(*) = nil
+#     def confirm(*) = false
+#     def notify(message, level:) = warn("[#{level}] #{message}")
+#     def progress(label) = yield
+#   end
+#
+# Callers check #capabilities before asking, so a host that declines a
+# capability is never asked and the caller takes the declined path.
+# The do-nothing host: the default +host:+ for a Runtime. Every capability is
+# declined, so callers take the declined path without any UI attempt.
+class Riffer::Rig::Host
+  # @rbs return: Set[Symbol]
+  def capabilities
+    Set.new.freeze
+  end
+
+  # @rbs _question: String?
+  # @rbs options: Array[String]?
+  # @rbs secret: bool
+  # @rbs return: String?
+  def ask(_question = nil, options: nil, secret: false)
+    nil
+  end
+
+  # @rbs _question: String?
+  # @rbs return: bool
+  def confirm(_question = nil)
+    false
+  end
+
+  # @rbs _message: String?
+  # @rbs level: Symbol
+  # @rbs return: void
+  def notify(_message = nil, level: :info)
+    nil
+  end
+
+  # @rbs _label: String?
+  # @rbs &block: ^() -> void
+  # @rbs return: void
+  def progress(_label = nil, &block)
+    block&.call
+  end
+end

data/lib/riffer/rig/registrar.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# The per-Runtime registrar extension blocks run against. Seams are added one
+# at a time; today only #tool exists.
+class Riffer::Rig::Registrar
+  # @rbs @tools: Array[singleton(Riffer::Tool)]
+
+  # @rbs return: void
+  def initialize
+    @tools = []
+  end
+
+  # @rbs klass: singleton(Riffer::Tool)
+  # @rbs return: void
+  def tool(klass)
+    @tools << klass
+  end
+
+  # @rbs return: Array[singleton(Riffer::Tool)]
+  def tools
+    @tools.dup
+  end
+end

data/lib/riffer/rig/repl.rb

@@ -11,20 +11,28 @@ class Riffer::Rig::REPL
   # @rbs @smoother: Riffer::Rig::UI::Smoother
   # @rbs @cursor: Riffer::Rig::UI::Cursor
   # @rbs @theme: Riffer::Rig::UI::Theme
-  # @rbs @input: untyped
-  # @rbs @output: untyped
-  # @rbs @pending_tool_calls: Array[Riffer::StreamEvents::ToolCallDone]
-
-  # @rbs ?agent: Riffer::Agent
-  # @rbs ?renderer: Riffer::Rig::UI::Renderer
-  # @rbs input: untyped
-  # @rbs output: untyped
-  # @rbs ?theme: Riffer::Rig::UI::Theme
-  # @rbs ?animator: Riffer::Rig::UI::Animator
-  # @rbs ?smoother: Riffer::Rig::UI::Smoother
-  # @rbs ?cursor: Riffer::Rig::UI::Cursor
+  # @rbs @input: IO
+  # @rbs @output: IO
+
+  # @rbs agent: Riffer::Agent
+  # @rbs renderer: Riffer::Rig::UI::Renderer
+  # @rbs input: IO
+  # @rbs output: IO
+  # @rbs theme: Riffer::Rig::UI::Theme
+  # @rbs animator: Riffer::Rig::UI::Animator
+  # @rbs smoother: Riffer::Rig::UI::Smoother
+  # @rbs cursor: Riffer::Rig::UI::Cursor
   # @rbs return: void
-  def initialize(agent:, renderer:, input: $stdin, output: $stdout, theme: Riffer::Rig::UI::Theme.for(output), animator: Riffer::Rig::UI::Animator.new(io: output, theme:), smoother: Riffer::Rig::UI::Smoother.new(io: output, theme:), cursor: Riffer::Rig::UI::Cursor.new(io: output, theme:))
+  def initialize(
+    agent:,
+    renderer:,
+    input: $stdin,
+    output: $stdout,
+    theme: Riffer::Rig::UI::Theme.for(output),
+    animator: Riffer::Rig::UI::Animator.new(io: output, theme:),
+    smoother: Riffer::Rig::UI::Smoother.new(io: output, theme:),
+    cursor: Riffer::Rig::UI::Cursor.new(io: output, theme:)
+  )
     @agent = agent
     @renderer = renderer
     @animator = animator
@@ -33,14 +41,13 @@ class Riffer::Rig::REPL
     @theme = theme
     @input = input
     @output = output
-    @pending_tool_calls = []
     @agent.session.on_message { |message| render_tool_result(message) }
   end
 
   # @rbs return: Symbol
   def run
     loop do
-      @output.print("\n#{@theme.pink('›')} ")
+      @renderer.prompt
       line = @input.gets
       break if line.nil?
 
@@ -57,7 +64,7 @@ class Riffer::Rig::REPL
       end
     end
 
-    @output.puts("\n#{@theme.grey('see you on the next riff.')}")
+    print_block { @theme.grey('see you on the next riff.') }
     :done
   end
 
@@ -67,49 +74,41 @@ class Riffer::Rig::REPL
   # @rbs return: void
   def run_turn(prompt)
     @cursor.hide
-    @animator.start
+    start_animator
     @smoother.start
     @agent.stream(prompt).each do |event|
       case event
       when Riffer::StreamEvents::ReasoningDelta
-        @animator.start(:reasoning)
+        start_animator(:reasoning)
       when Riffer::StreamEvents::ReasoningDone
-        @animator.start
+        start_animator
       when Riffer::StreamEvents::ToolCallDelta, Riffer::StreamEvents::FinishReasonDone
-        # Round bookkeeping: nothing renders, so the indicator just carries on
-        # (or stays parked while the smoother finishes typing earlier text).
         next
-      when Riffer::StreamEvents::ToolCallDone
-        # Tool call lines are held back so the round's stats line can print
-        # above them (see flush_pending_tool_calls).
-        @pending_tool_calls << event
-        next
-      when Riffer::StreamEvents::SkillActivation, Riffer::StreamEvents::TokenUsageDone
-        # The spinner shares its line with what's about to print, and tool
-        # execution plus the next model invocation emit no events — stop it for
-        # the render, then bring it straight back to cover the silent stretch.
-        # Stats print before any pending tool call lines (see below).
+      when Riffer::StreamEvents::SkillActivation
+        # Tool execution and the next model invocation emit no events, so the
+        # spinner comes straight back on to cover the silent stretch.
         @animator.stop
         @renderer.render(event)
-        flush_pending_tool_calls
-        @animator.start
+        start_animator
+        next
+      when Riffer::StreamEvents::TokenUsageDone
+        # Usage renders nothing inline — it flushes below the turn's output.
+        # Restarting here covers the silent tool-execution stretch that follows.
+        @renderer.render(event)
+        start_animator
         next
       else
         @animator.stop
       end
-      flush_pending_tool_calls
       @renderer.render(event)
     end
     @animator.stop
-    flush_pending_tool_calls
     @smoother.finish
-    @output.puts
+    @renderer.flush_usage
   rescue StandardError => e
-    @animator.stop
-    flush_pending_tool_calls
-    @output.puts("\nError: #{e.message}")
-  ensure
     @smoother.finish
+    print_block { @theme.red("Error: #{e.message}") }
+  ensure
     @animator.stop
     @cursor.show
   end
@@ -130,7 +129,7 @@ class Riffer::Rig::REPL
     skills = @agent.context.skills
 
     unless skills
-      @output.puts(@theme.grey('No skills configured.'))
+      print_block { @theme.grey('No skills configured.') }
       return
     end
 
@@ -138,13 +137,13 @@ class Riffer::Rig::REPL
     # a non-mutating Context#read. `activate` marks the skill model-activated as
     # a side effect, which drops it from the model's catalog after manual use.
     body = skills.activate(name)
-    @output.puts(@theme.magenta("✦ skill: #{name}"))
+    print_block { @theme.magenta("✦ skill: #{name}") }
     skill_block(name, body)
   rescue Riffer::ArgumentError
-    @output.puts(@theme.red("Unknown skill: #{name}"))
+    print_block { @theme.red("Unknown skill: #{name}") }
     nil
   rescue StandardError => e
-    @output.puts(@theme.red("Error activating skill: #{e.message}"))
+    print_block { @theme.red("Error activating skill: #{e.message}") }
     nil
   end
 
@@ -155,24 +154,18 @@ class Riffer::Rig::REPL
     "<skill name=\"#{name}\">\n#{body}\n</skill>"
   end
 
-  # Tool call lines print below their round's stats line to reflect the actual
-  # timeline (usage is reported when the model stream closes, after the calls
-  # were decided). ToolCallDone events are therefore held until the stats line
-  # or the next event forces them out. Callers must have the spinner stopped —
-  # the flush renders between their existing stop/start pair.
+  # Chrome lines that never pass through the renderer (errors, exit line) end
+  # their line with a newline but leave the renderer's tool-group state alone —
+  # they can only follow prose, never mid-group.
   #
+  # @rbs &block: () -> String
   # @rbs return: void
-  def flush_pending_tool_calls
-    return if @pending_tool_calls.empty?
-
-    @pending_tool_calls.each { |event| @renderer.render(event) }
-    @pending_tool_calls = []
+  def print_block(&)
+    @output.puts
+    @output.puts(yield)
+    @output.flush
   end
 
-  # Tool results can land mid-animation (tool execution emits no stream events,
-  # so the indicator is up); stop it around the line so its next frame doesn't
-  # erase what we printed.
-  #
   # @rbs message: Riffer::Messages::Base
   # @rbs return: void
   def render_tool_result(message)
@@ -180,6 +173,17 @@ class Riffer::Rig::REPL
 
     @animator.stop
     @renderer.render_tool_result(message)
-    @animator.start
+    start_animator
+  end
+
+  # Every animator start sits behind a smoother drain: the smoother's backlog
+  # may still be trickling out from streamed prose, and spinner frames drawn
+  # mid-drain would carve `\r…\e[K` through a half-printed sentence.
+  #
+  # @rbs mode: Symbol
+  # @rbs return: void
+  def start_animator(mode = :neutral)
+    @smoother.drain
+    @animator.start(mode)
   end
 end