riffer-rig 0.10.0 → 0.12.0

data/lib/riffer/rig/bundled/mcp.rb

@@ -3,7 +3,12 @@
 module Riffer::Rig::Bundled
   Mcp = Riffer::Rig::Extension.new('mcp') do |rig|
     rig.settings[:servers].to_h.each do |name, server|
-      rig.mcp(name.to_s, url: server.fetch(:url), headers: server[:headers].to_h.transform_keys(&:to_s))
+      rig.mcp(
+        name.to_s,
+        url: server.fetch(:url),
+        headers: server[:headers].to_h.transform_keys(&:to_s),
+        auth: Hash(server[:auth])
+      )
     end
   end #: Riffer::Rig::Extension
 end

data/lib/riffer/rig/cli/flags.rb

@@ -5,38 +5,43 @@ require 'optparse'
 class Riffer::Rig::CLI::Flags
   BANNER = <<~TEXT.chomp #: String
     Usage: riffer [options]
-           riffer -p [prompt]   (not available yet)
+           riffer -p [prompt]   run one prompt headless and exit
            riffer acp           (not available yet)
   TEXT
 
-  # @dynamic model, extensions, skills, agents_md, tools, max_steps, help, save, continue, resume
+  # The tokens OptionParser reports a missing argument for when -r is bare.
+  BARE_RESUME = %w[-r --resume].freeze #: Array[String]
+
+  # @dynamic model, extensions, skills, agents_md, tools, max_steps, help, save, verbose, json, prompt, continue, resume
   attr_reader :model #: String?
-  attr_reader :extensions, :skills, :agents_md, :help #: bool
+  attr_reader :extensions, :skills, :agents_md, :help, :verbose, :json #: bool
   attr_reader :tools #: Array[String]?
   attr_reader :max_steps #: Integer?
   attr_reader :save #: bool
+  attr_reader :prompt #: String?
   attr_reader :continue #: bool
   attr_reader :resume #: String?
 
+  # A bare -r (no id) only reaches here for the REPL: the parser requires the
+  # id, and the missing-argument error is translated to an empty resume so the
+  # terminal can open the picker instead. Headless keeps the error and prints
+  # it as the usage failure.
+  #
   # @rbs argv: Array[String]
+  # @rbs prompt: bool
   # @rbs return: Riffer::Rig::CLI::Flags | String
-  def self.parse(argv)
+  def self.parse(argv, prompt: false)
     values = {} #: Hash[Symbol, untyped]
     rest = parser.parse(argv, into: values)
-    return "unexpected argument: #{rest.join(' ')}" unless rest.empty?
+    allowed = rest.empty? || (prompt && rest.size == 1)
+    return "unexpected argument: #{rest.join(' ')}" unless allowed
 
-    new(
-      model: values[:model],
-      extensions: !values.key?(:'no-extensions'),
-      skills: !values.key?(:'no-skills'),
-      agents_md: !values.key?(:'no-agents-md'),
-      tools: values[:tools],
-      max_steps: values[:'max-steps'],
-      save: !values.key?(:'no-save'),
-      continue: values.key?(:continue),
-      resume: values[:resume],
-      help: values.key?(:help)
-    )
+    assemble(values, rest.first, prompt: prompt)
+  rescue OptionParser::MissingArgument => e
+    bare = !prompt && BARE_RESUME.include?(e.args.first.to_s)
+    return assemble(values || {}, nil, prompt: prompt, bare_resume: bare) if bare
+
+    e.message
   rescue OptionParser::ParseError => e
     e.message
   end
@@ -46,6 +51,11 @@ class Riffer::Rig::CLI::Flags
     parser.help
   end
 
+  # @rbs return: Hash[Symbol, untyped]
+  def keywords
+    { model: model, extensions: extensions, skills: skills, agents_md: agents_md, tools: tools, max_steps: max_steps }
+  end
+
   # @rbs return: OptionParser
   def self.parser
     OptionParser.new do |parser|
@@ -59,12 +69,39 @@ class Riffer::Rig::CLI::Flags
       parser.on('--max-steps N', Integer, 'Stop a turn after N model calls')
       parser.on('--no-save', 'Do not save this session')
       parser.on('-c', '--continue', 'Continue the most recent session in this directory')
-      parser.on('-r ID', '--resume ID', String, 'Resume the session with this id')
+      parser.on('-r ID', '--resume ID', String, 'Resume the session with this id; bare -r opens the picker in the REPL')
+      parser.on('-p', '--print', 'Run one prompt headless and exit; the prompt is the argument, else stdin')
+      parser.on('--verbose', 'With -p, trace each tool call to stderr')
+      parser.on('--json', 'With -p, stream every Runtime event as NDJSON to stdout')
       parser.on('-h', '--help', 'Show this help')
     end
   end
   private_class_method :parser
 
+  # @rbs values: Hash[Symbol, untyped]
+  # @rbs head: String?
+  # @rbs prompt: bool
+  # @rbs bare_resume: bool
+  # @rbs return: Riffer::Rig::CLI::Flags
+  def self.assemble(values, head, prompt:, bare_resume: false)
+    new(
+      model: values[:model],
+      extensions: !values.key?(:'no-extensions'),
+      skills: !values.key?(:'no-skills'),
+      agents_md: !values.key?(:'no-agents-md'),
+      tools: values[:tools],
+      max_steps: values[:'max-steps'],
+      save: !values.key?(:'no-save'),
+      verbose: values.key?(:verbose),
+      json: values.key?(:json),
+      prompt: prompt ? head : nil,
+      continue: values.key?(:continue),
+      resume: bare_resume ? '' : values[:resume],
+      help: values.key?(:help)
+    )
+  end
+  private_class_method :assemble
+
   # @rbs model: String?
   # @rbs extensions: bool
   # @rbs skills: bool
@@ -72,6 +109,9 @@ class Riffer::Rig::CLI::Flags
   # @rbs tools: Array[String]?
   # @rbs max_steps: Integer?
   # @rbs save: bool
+  # @rbs verbose: bool
+  # @rbs json: bool
+  # @rbs prompt: String?
   # @rbs continue: bool
   # @rbs resume: String?
   # @rbs help: bool
@@ -84,6 +124,9 @@ class Riffer::Rig::CLI::Flags
     tools: nil,
     max_steps: nil,
     save: true,
+    verbose: false,
+    json: false,
+    prompt: nil,
     continue: false,
     resume: nil,
     help: false
@@ -95,6 +138,9 @@ class Riffer::Rig::CLI::Flags
     @tools = tools&.freeze
     @max_steps = max_steps
     @save = save
+    @verbose = verbose
+    @json = json
+    @prompt = prompt
     @continue = continue
     @resume = resume
     @help = help

data/lib/riffer/rig/cli/sessions.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::CLI::Sessions
+  # The terminal's sessions collaborator: translates the parsed flags into
+  # Loader builds and store lookups, so the host never sees the flags.
+  #
+  # @rbs @flags: Riffer::Rig::CLI::Flags
+  # @rbs @env: Riffer::Rig::Env | Riffer::Rig::Env::Invalid
+  # @rbs @cwd: String
+  # @rbs @home: String
+  # @rbs @store: Riffer::Rig::Stores::_Store?
+  # @rbs @loader: Riffer::Rig::Loader?
+
+  # @rbs flags: Riffer::Rig::CLI::Flags
+  # @rbs env: Riffer::Rig::Env | Riffer::Rig::Env::Invalid
+  # @rbs cwd: String
+  # @rbs home: String
+  # @rbs return: void
+  def initialize(flags:, env:, cwd:, home:)
+    @flags = flags
+    @env = env
+    @cwd = cwd
+    @home = home
+    @store = flags.save ? Riffer::Rig::Stores::JSONL.new(home: home) : nil
+    @loader = nil
+  end
+
+  # @rbs host: Riffer::Rig::Hosts::_Host
+  # @rbs return: Riffer::Rig::Runtime
+  def start(host)
+    started = find(host)
+    host.notify(missing) if started.nil? && asked?
+
+    started || loader(host).runtime(**@flags.keywords)
+  end
+
+  # @rbs host: Riffer::Rig::Hosts::_Host
+  # @rbs return: Riffer::Rig::Runtime?
+  def find(host)
+    id = resume_id
+    if id
+      loader(host).resume(id, **@flags.keywords)
+    elsif @flags.continue
+      loader(host).continue(**@flags.keywords)
+    end
+  end
+
+  # @rbs host: Riffer::Rig::Hosts::_Host
+  # @rbs return: Riffer::Rig::Runtime
+  def fresh(host)
+    loader(host).runtime(**@flags.keywords)
+  end
+
+  # @rbs host: Riffer::Rig::Hosts::_Host
+  # @rbs id: String
+  # @rbs return: Riffer::Rig::Runtime?
+  def resume(host, id)
+    loader(host).resume(id, **@flags.keywords)
+  end
+
+  # @rbs host: Riffer::Rig::Hosts::_Host
+  # @rbs all: bool
+  # @rbs return: Array[::Riffer::Rig::Terminal::Session]
+  def list(host, all: false)
+    loader(host)
+      .list(all: all)
+      # The id breaks mtime ties so the rows never shuffle under sort_by.
+      .sort_by { |header| [header.updated ? -header.updated.to_f : 0.0, header.id] }
+      .map { |header| row(header) }
+  end
+
+  # @rbs host: Riffer::Rig::Hosts::_Host
+  # @rbs id: String
+  # @rbs return: void
+  def delete(host, id)
+    loader(host).delete(id)
+  end
+
+  # @rbs return: bool
+  def asked?
+    resume_id ? true : @flags.continue
+  end
+
+  # @rbs return: String
+  def missing
+    id = resume_id
+    id ? "No saved session #{id}." : 'No saved session in this directory.'
+  end
+
+  private
+
+  # @rbs header: Riffer::Rig::Stores::Header
+  # @rbs return: ::Riffer::Rig::Terminal::Session
+  def row(header)
+    Riffer::Rig::Terminal::Session.new(
+      id: header.id,
+      title: header.title.gsub(/\s+/, ' ').strip,
+      updated: header.updated,
+      messages: message_count(header.id),
+      cwd: header.cwd
+    )
+  end
+
+  # @rbs id: String
+  # @rbs return: Integer
+  def message_count(id)
+    store = @store
+    return 0 unless store
+
+    store.read(id).count { |entry| entry.is_a?(Riffer::Rig::Stores::MessageEntry) }
+  end
+
+  # @rbs host: Riffer::Rig::Hosts::_Host
+  # @rbs return: Riffer::Rig::Loader
+  def loader(host)
+    @loader ||= Riffer::Rig::Loader.new(cwd: @cwd, host: host, env: @env, home: @home, store: @store)
+  end
+
+  # @rbs return: String?
+  def resume_id
+    id = @flags.resume
+    id unless id.nil? || id.empty?
+  end
+end

data/lib/riffer/rig/cli.rb

@@ -26,12 +26,17 @@ module Riffer::Rig::CLI
     cwd: Dir.pwd,
     home: Dir.home
   )
-    return unavailable("riffer #{ACP_COMMAND}", error) if argv.first == ACP_COMMAND
-    return unavailable('riffer -p', error) if argv.intersect?(PRINT_FLAGS)
+    return refuse("#{ACP_COMMAND} takes no arguments", error) if argv.first == ACP_COMMAND && argv.length > 1
+    return acp(input: input, output: output, env: env, home: home) if argv.first == ACP_COMMAND
 
-    flags = Flags.parse(argv)
+    headless_mode = argv.intersect?(PRINT_FLAGS)
+    flags = Flags.parse(argv, prompt: headless_mode)
     return refuse(flags, error) if flags.is_a?(String)
     return help(output) if flags.help
+    return refuse('--verbose is only available with -p', error) if flags.verbose && !headless_mode
+    return refuse('--json is only available with -p', error) if flags.json && !headless_mode
+
+    return headless(flags, input:, output:, error:, env:, cwd:, home:) if headless_mode
 
     terminal(flags, input:, output:, env:, cwd:, home:)
   end
@@ -41,69 +46,51 @@ module Riffer::Rig::CLI
   # @rbs flags: Riffer::Rig::CLI::Flags
   # @rbs input: IO
   # @rbs output: IO
+  # @rbs error: IO
   # @rbs env: Riffer::Rig::Env | Riffer::Rig::Env::Invalid
   # @rbs cwd: String
   # @rbs home: String
   # @rbs return: Integer
-  def terminal(flags, input:, output:, env:, cwd:, home:)
-    Riffer::Rig::Terminal.for(
+  def headless(flags, input:, output:, error:, env:, cwd:, home:)
+    sessions = Sessions.new(flags: flags, env: env, cwd: cwd, home: home)
+    Riffer::Rig::Headless.for(
       input: input,
       output: output,
-      version: Riffer::Rig::VERSION,
-      no_color: env.is_a?(Riffer::Rig::Env) && env.no_color
-    ).run do |host|
-      loader = Riffer::Rig::Loader.new(
-        cwd: cwd,
-        host: host,
-        env: env,
-        home: home,
-        store: flags.save ? Riffer::Rig::Stores::JSONL.new : nil
-      )
-      resumed(flags, host, loader) || build(loader, flags)
-    end
-  end
+      error: error,
+      verbose: flags.verbose,
+      json: flags.json
+    ).run(prompt: flags.prompt) do |host|
+      started = sessions.find(host)
+      raise Riffer::Rig::Loader::ConfigurationError, sessions.missing if started.nil? && sessions.asked?
 
-  # @rbs flags: Riffer::Rig::CLI::Flags
-  # @rbs host: Riffer::Rig::Hosts::_Host
-  # @rbs loader: Riffer::Rig::Loader
-  # @rbs return: Riffer::Rig::Runtime?
-  def resumed(flags, host, loader)
-    if flags.resume
-      started = loader.resume(flags.resume, **keywords(flags))
-      host.notify("No saved session #{flags.resume}.") unless started
-      started
-    elsif flags.continue
-      started = loader.continue(**keywords(flags))
-      host.notify('No saved session in this directory.') unless started
-      started
+      started || sessions.fresh(host)
     end
   end
 
-  # @rbs loader: Riffer::Rig::Loader
-  # @rbs flags: Riffer::Rig::CLI::Flags
-  # @rbs return: Riffer::Rig::Runtime
-  def build(loader, flags)
-    loader.runtime(**keywords(flags))
-  end
-
   # @rbs flags: Riffer::Rig::CLI::Flags
-  # @rbs return: Hash[Symbol, untyped]
-  def keywords(flags)
-    {
-      model: flags.model,
-      extensions: flags.extensions,
-      skills: flags.skills,
-      agents_md: flags.agents_md,
-      tools: flags.tools,
-      max_steps: flags.max_steps
-    }
+  # @rbs input: IO
+  # @rbs output: IO
+  # @rbs env: Riffer::Rig::Env | Riffer::Rig::Env::Invalid
+  # @rbs cwd: String
+  # @rbs home: String
+  # @rbs return: Integer
+  def terminal(flags, input:, output:, env:, cwd:, home:)
+    Riffer::Rig::Terminal.for(
+      input: input,
+      output: output,
+      version: Riffer::Rig::VERSION,
+      no_color: env.is_a?(Riffer::Rig::Env) && env.no_color,
+      sessions: Sessions.new(flags: flags, env: env, cwd: cwd, home: home)
+    ).run(open_picker: flags.resume == '')
   end
 
-  # @rbs name: String
-  # @rbs error: IO
+  # @rbs input: IO
+  # @rbs output: IO
+  # @rbs env: Riffer::Rig::Env | Riffer::Rig::Env::Invalid
+  # @rbs home: String
   # @rbs return: Integer
-  def unavailable(name, error)
-    refuse("#{name} is not available yet", error)
+  def acp(input:, output:, env:, home:)
+    Riffer::Rig::ACP.for(input: input, output: output, env: env, home: home).run
   end
 
   # @rbs message: String

data/lib/riffer/rig/headless/host.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Headless::Host
+  CAPABILITIES = Set[:notify, :progress].freeze #: Set[Symbol]
+
+  # @rbs @error: IO
+  # @rbs @json: bool
+
+  # @rbs error: IO
+  # @rbs json: bool
+  # @rbs return: void
+  def initialize(error: $stderr, json: false)
+    @error = error
+    @json = json
+  end
+
+  # @rbs return: Set[Symbol]
+  def capabilities
+    CAPABILITIES
+  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)
+    # In --json the Mirror queues the Notify event onto the Runtime's stream,
+    # where the printer emits it as a line; printing here would duplicate it
+    # on stderr.
+    return if @json
+
+    @error.puts(message.to_s)
+  end
+
+  # @rbs label: String?
+  # @rbs &block: ? () -> void
+  # @rbs return: void
+  def progress(label = nil, &block)
+    @error.puts(label) if label
+    block&.call
+  end
+end

data/lib/riffer/rig/headless/ndjson.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Riffer::Rig::Headless::Ndjson
+  extend self
+
+  # @rbs event: ::Riffer::StreamEvents::Base | Riffer::Rig::Events::_Event
+  # @rbs return: String
+  def line(event)
+    "#{JSON.generate(envelope(event))}\n"
+  end
+
+  # @rbs message: String
+  # @rbs return: String
+  def error(message)
+    "#{JSON.generate({ 'type' => 'error', 'message' => message })}\n"
+  end
+
+  # @rbs event: ::Riffer::StreamEvents::Base | Riffer::Rig::Events::_Event
+  # @rbs return: Hash[String, Riffer::Rig::Headless::json]
+  def envelope(event)
+    json_hash(event.to_h).merge('type' => event_type(event))
+  end
+
+  # @rbs hash: Hash[Symbol, untyped]
+  # @rbs return: Hash[String, Riffer::Rig::Headless::json]
+  def json_hash(hash)
+    hash.to_h { |key, item| [key.to_s, json_value(item)] }
+  end
+
+  # @rbs event: ::Riffer::StreamEvents::Base | Riffer::Rig::Events::_Event
+  # @rbs return: String
+  def event_type(event)
+    event.class.name.to_s.split('::').last.to_s.gsub(/(?<=[a-z\d])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/, '_').downcase
+  end
+
+  # @rbs value: untyped
+  # @rbs return: Riffer::Rig::Headless::json
+  def json_value(value)
+    case value
+    when String, Integer, Float, true, false, nil then value
+    when Symbol then value.to_s
+    when Hash then value.to_h { |key, item| [key.to_s, json_value(item)] }
+    when Array then value.map { |item| json_value(item) }
+    else value.respond_to?(:to_h) ? json_value(value.to_h) : value.to_s
+    end
+  end
+end

data/lib/riffer/rig/headless.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Headless
+  USAGE_ERROR = 2 #: Integer
+
+  # The plan's exit-3 set: the cap plus the provider stop reasons that mean the
+  # turn ended without completing. Riffer's remaining stop reasons (:error,
+  # :other, :guardrail_blocked) are runtime failures and map to 1.
+  STOPPED_WITHOUT_COMPLETING = %i[
+    max_steps context_window length content_filter malformed_output
+  ].freeze #: Array[Symbol]
+
+  # @rbs @input: IO
+  # @rbs @output: IO
+  # @rbs @error: IO
+  # @rbs @host: Riffer::Rig::Headless::Host
+  # @rbs @verbose: bool
+  # @rbs @json: bool
+  # @rbs @streamed_text: bool
+
+  # @rbs input: IO
+  # @rbs output: IO
+  # @rbs error: IO
+  # @rbs verbose: bool
+  # @rbs json: bool
+  # @rbs return: Riffer::Rig::Headless
+  def self.for(input:, output:, error:, verbose: false, json: false)
+    host = Riffer::Rig::Headless::Host.new(error: error, json: json)
+    new(input: input, output: output, error: error, host: host, verbose: verbose, json: json)
+  end
+
+  # @rbs input: IO
+  # @rbs output: IO
+  # @rbs error: IO
+  # @rbs host: Riffer::Rig::Headless::Host
+  # @rbs verbose: bool
+  # @rbs json: bool
+  # @rbs return: void
+  def initialize(input:, output:, error:, host:, verbose: false, json: false)
+    @input = input
+    @output = output
+    @error = error
+    @host = host
+    @verbose = verbose
+    @json = json
+  end
+
+  # @rbs prompt: String?
+  # @rbs &build: (Riffer::Rig::Hosts::_Host) -> Riffer::Rig::Runtime
+  # @rbs return: Integer
+  def run(prompt:, &build)
+    text = prompt_text(prompt)
+    return usage_error if text.empty?
+
+    drive(yield(@host), text)
+  rescue Riffer::Rig::Loader::ConfigurationError => e
+    fatal(e.message, USAGE_ERROR)
+  rescue Interrupt
+    130
+  rescue StandardError => e
+    fatal(e.message, 1)
+  end
+
+  private
+
+  # @rbs prompt: String?
+  # @rbs return: String
+  def prompt_text(prompt)
+    piped = @input.tty? ? '' : @input.read.to_s.strip
+    [prompt, piped].compact.reject(&:empty?).join("\n\n")
+  end
+
+  # @rbs return: Integer
+  def usage_error
+    fatal('no prompt: pass one as an argument, or pipe it to stdin', USAGE_ERROR)
+  end
+
+  # @rbs message: String
+  # @rbs code: Integer
+  # @rbs return: Integer
+  def fatal(message, code)
+    if @json
+      @output.write(Ndjson.error(message))
+    else
+      @error.puts("riffer: #{message}")
+    end
+    code
+  end
+
+  # @rbs runtime: Riffer::Rig::Runtime
+  # @rbs text: String
+  # @rbs return: Integer
+  def drive(runtime, text)
+    turn(text, runtime)
+  ensure
+    runtime.close
+  end
+
+  # @rbs text: String
+  # @rbs runtime: Riffer::Rig::Runtime
+  # @rbs return: Integer
+  def turn(text, runtime)
+    # @type var stop_reason: Symbol?
+    stop_reason = nil
+    # Runtime#cancel takes a Mutex, which Ruby refuses inside a trap handler,
+    # so the handler hands the cancel to a thread.
+    previous = Signal.trap('INT') { Thread.new { runtime.cancel } }
+    begin
+      runtime.prompt(text) do |event|
+        case event
+        when Riffer::Rig::Events::TurnEnd
+          stop_reason = event.stop_reason
+          @output.write(Ndjson.line(event)) if @json
+        else
+          handle(event)
+        end
+      end
+    rescue StandardError => e
+      return fatal(e.message, 1)
+    ensure
+      Signal.trap('INT', previous)
+    end
+    finish(stop_reason)
+  end
+
+  # @rbs event: ::Riffer::StreamEvents::Base | Riffer::Rig::Events::_Event
+  # @rbs return: void
+  def handle(event)
+    return @output.write(Ndjson.line(event)) if @json
+
+    case event
+    when Riffer::StreamEvents::TextDelta
+      @output.write(event.content)
+      @streamed_text = true
+    when Riffer::StreamEvents::TextDone
+      # A provider that streams nothing hands over the whole text here; one
+      # that streamed deltas has already written it.
+      @output.write(event.content) if !@streamed_text && !event.content.empty?
+      @output.puts if @streamed_text || !event.content.empty?
+      @streamed_text = false
+    when Riffer::StreamEvents::ToolCallDone
+      @error.puts("tool_call #{event.name} #{event.arguments}") if @verbose
+    end
+  end
+
+  # @rbs stop_reason: Symbol?
+  # @rbs return: Integer
+  def finish(stop_reason)
+    return 0 if stop_reason == :completed
+
+    @error.puts("turn ended: #{stop_reason}") if stop_reason
+    return 130 if stop_reason == Riffer::Rig::Runtime::INTERRUPT_CANCELLED
+    return 3 if stop_reason && STOPPED_WITHOUT_COMPLETING.include?(stop_reason)
+
+    1
+  end
+end