riffer-rig 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0bc260756e56f8ed0d89556ef071a3ecb1922b637eb5b10cc0268416e0ceb26d
-  data.tar.gz: b7e6d6314a893ff23f289336b5e3df25f11e032f060272d7656695f1e96e584d
+  metadata.gz: 5f79d98c522224290937a01b701fa7f4ac72f2be08fbbb39abf32f06691880f7
+  data.tar.gz: 3c66dbd81e98e86b1c1132094431e0803d23c757a950684c6663ad5abd8c3369
 SHA512:
-  metadata.gz: edda5ec3d1675966361db52a009328703f0f62340d8d18ea3f5e689f3e9194762fec33804072989f1cb92d357038e03ca9481e7ab9f34eb123964f3f025b8749
-  data.tar.gz: c1953f30afa3a7871291852d3aaeba52a256006732582c82f71ad3245234f1e2a974524b174a801df81096af6effc37186e3a10e11ace5f5be644edbe4ed1c49
+  metadata.gz: 6087cb7527548ca826bf04ab3b214c36ab29e18c676c62f7df84377010bb47fddae9e88b1354d1fa8815efa4967d4599ccc63e022c57660a567b58e226554679
+  data.tar.gz: 2aae83bea0978c35b33674149527c0281baeb33f7bf186ba38d9b6abdeb905a3649989eae97430d7eae6284a80a253152d0532c8ba3d75f3ae3d7adee6f6a757

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.11.0](https://github.com/bottrall/riffer-rig/compare/v0.10.0...v0.11.0) (2026-10-06)
+
+
+### Features
+
+* riffer -p runs one prompt headless with exit codes ([#226](https://github.com/bottrall/riffer-rig/issues/226)) ([eaa91d6](https://github.com/bottrall/riffer-rig/commit/eaa91d625eb303e4dc8a08c317ea38fc136a729d)), closes [#137](https://github.com/bottrall/riffer-rig/issues/137)
+* store entries as typed POROs at the store boundary ([#225](https://github.com/bottrall/riffer-rig/issues/225)) ([05431e5](https://github.com/bottrall/riffer-rig/commit/05431e583c412ee7c3551dadd61db1089af465a9))
+
 ## [0.10.0](https://github.com/bottrall/riffer-rig/compare/v0.9.0...v0.10.0) (2026-10-05)
 
 

data/README.md

@@ -51,7 +51,21 @@ The model is the first of these that is set: `--model`, `RIFFER_MODEL`, `model`
 | `-r ID`, `--resume ID`  | resumes the session with id `ID` ([Sessions](docs/SESSIONS.md#resuming))    |
 | `-h`, `--help`          | prints the usage                                                            |
 
-`riffer -p` (one prompt, no terminal) and `riffer acp` (an editor's agent over stdio) are reserved: for now each prints the usage and exits with status 2.
+`riffer acp` (an editor's agent over stdio) is reserved: for now it prints the usage and exits with status 2.
+
+### Headless
+
+Run one prompt with no terminal ([Headless](docs/HEADLESS.md)):
+
+```bash
+riffer -p "what does this repo do"
+git diff | riffer -p "review this diff"   # piped stdin appended as context
+echo "explain this diff" | riffer -p      # piped stdin alone is the prompt
+```
+
+Everything loads exactly as the REPL does, the shared flags work the same — `-c` and `-r` included: `riffer -p -c "now run the tests"` continues the most recent session in this directory, and a missing session exits 2 ([Headless](docs/HEADLESS.md)). The session is saved like any other unless `--no-save`. Only the assistant's text is printed, streamed to stdout; errors and warnings go to stderr, and `--verbose` adds a one-line trace of each tool call there. Headless never prompts: a missing model, credential, or SDK prints the reason on stderr and exits 2.
+
+The exit code says how the turn ended: `0` finished, `1` runtime error, `2` usage or configuration, `3` the turn ended without completing (`--max-steps`, a full context window, a provider content filter), `130` SIGINT (the turn is cancelled first).
 
 ### In the session
 

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

@@ -5,25 +5,28 @@ 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
+  # @dynamic model, extensions, skills, agents_md, tools, max_steps, help, save, verbose, prompt, continue, resume
   attr_reader :model #: String?
-  attr_reader :extensions, :skills, :agents_md, :help #: bool
+  attr_reader :extensions, :skills, :agents_md, :help, :verbose #: 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?
 
   # @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],
@@ -33,6 +36,8 @@ class Riffer::Rig::CLI::Flags
       tools: values[:tools],
       max_steps: values[:'max-steps'],
       save: !values.key?(:'no-save'),
+      verbose: values.key?(:verbose),
+      prompt: prompt ? rest.first : nil,
       continue: values.key?(:continue),
       resume: values[:resume],
       help: values.key?(:help)
@@ -60,6 +65,8 @@ class Riffer::Rig::CLI::Flags
       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('-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('-h', '--help', 'Show this help')
     end
   end
@@ -72,6 +79,8 @@ class Riffer::Rig::CLI::Flags
   # @rbs tools: Array[String]?
   # @rbs max_steps: Integer?
   # @rbs save: bool
+  # @rbs verbose: bool
+  # @rbs prompt: String?
   # @rbs continue: bool
   # @rbs resume: String?
   # @rbs help: bool
@@ -84,6 +93,8 @@ class Riffer::Rig::CLI::Flags
     tools: nil,
     max_steps: nil,
     save: true,
+    verbose: false,
+    prompt: nil,
     continue: false,
     resume: nil,
     help: false
@@ -95,6 +106,8 @@ class Riffer::Rig::CLI::Flags
     @tools = tools&.freeze
     @max_steps = max_steps
     @save = save
+    @verbose = verbose
+    @prompt = prompt
     @continue = continue
     @resume = resume
     @help = help

data/lib/riffer/rig/cli.rb

@@ -27,17 +27,43 @@ module Riffer::Rig::CLI
     home: Dir.home
   )
     return unavailable("riffer #{ACP_COMMAND}", error) if argv.first == ACP_COMMAND
-    return unavailable('riffer -p', error) if argv.intersect?(PRINT_FLAGS)
 
-    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 headless(flags, input:, output:, error:, env:, cwd:, home:) if headless_mode
 
     terminal(flags, input:, output:, env:, cwd:, home:)
   end
 
   private
 
+  # @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 headless(flags, input:, output:, error:, env:, cwd:, home:)
+    Riffer::Rig::Headless.for(
+      input: input,
+      output: output,
+      error: error,
+      verbose: flags.verbose
+    ).run(prompt: flags.prompt) do |host|
+      loader = new_loader(flags, host: host, env: env, cwd: cwd, home: home)
+      started = find_session(flags, loader)
+      raise Riffer::Rig::Loader::ConfigurationError, missing_session(flags) if started.nil? && session_flags?(flags)
+
+      started || build(loader, flags)
+    end
+  end
+
   # @rbs flags: Riffer::Rig::CLI::Flags
   # @rbs input: IO
   # @rbs output: IO
@@ -52,33 +78,53 @@ module Riffer::Rig::CLI
       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)
+      loader = new_loader(flags, host: host, env: env, cwd: cwd, home: home)
+      started = find_session(flags, loader)
+      host.notify(missing_session(flags)) if started.nil? && session_flags?(flags)
+
+      started || build(loader, flags)
     end
   end
 
   # @rbs flags: Riffer::Rig::CLI::Flags
   # @rbs host: Riffer::Rig::Hosts::_Host
+  # @rbs env: Riffer::Rig::Env | Riffer::Rig::Env::Invalid
+  # @rbs cwd: String
+  # @rbs home: String
+  # @rbs return: Riffer::Rig::Loader
+  def new_loader(flags, host:, env:, cwd:, home:)
+    Riffer::Rig::Loader.new(
+      cwd: cwd,
+      host: host,
+      env: env,
+      home: home,
+      store: flags.save ? Riffer::Rig::Stores::JSONL.new : nil
+    )
+  end
+
+  # @rbs flags: Riffer::Rig::CLI::Flags
   # @rbs loader: Riffer::Rig::Loader
   # @rbs return: Riffer::Rig::Runtime?
-  def resumed(flags, host, loader)
+  def find_session(flags, loader)
     if flags.resume
-      started = loader.resume(flags.resume, **keywords(flags))
-      host.notify("No saved session #{flags.resume}.") unless started
-      started
+      loader.resume(flags.resume, **keywords(flags))
     elsif flags.continue
-      started = loader.continue(**keywords(flags))
-      host.notify('No saved session in this directory.') unless started
-      started
+      loader.continue(**keywords(flags))
     end
   end
 
+  # @rbs flags: Riffer::Rig::CLI::Flags
+  # @rbs return: bool
+  def session_flags?(flags)
+    flags.resume ? true : flags.continue
+  end
+
+  # @rbs flags: Riffer::Rig::CLI::Flags
+  # @rbs return: String
+  def missing_session(flags)
+    flags.resume ? "No saved session #{flags.resume}." : 'No saved session in this directory.'
+  end
+
   # @rbs loader: Riffer::Rig::Loader
   # @rbs flags: Riffer::Rig::CLI::Flags
   # @rbs return: Riffer::Rig::Runtime

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Headless::Host
+  CAPABILITIES = Set[:notify, :progress].freeze #: Set[Symbol]
+
+  # @rbs @error: IO
+
+  # @rbs error: IO
+  # @rbs return: void
+  def initialize(error: $stderr)
+    @error = error
+  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)
+    @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.rb

@@ -0,0 +1,142 @@
+# 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 @streamed_text: bool
+
+  # @rbs input: IO
+  # @rbs output: IO
+  # @rbs error: IO
+  # @rbs verbose: bool
+  # @rbs return: Riffer::Rig::Headless
+  def self.for(input:, output:, error:, verbose: false)
+    host = Riffer::Rig::Headless::Host.new(error: error)
+    new(input: input, output: output, error: error, host: host, verbose: verbose)
+  end
+
+  # @rbs input: IO
+  # @rbs output: IO
+  # @rbs error: IO
+  # @rbs host: Riffer::Rig::Headless::Host
+  # @rbs verbose: bool
+  # @rbs return: void
+  def initialize(input:, output:, error:, host:, verbose: false)
+    @input = input
+    @output = output
+    @error = error
+    @host = host
+    @verbose = verbose
+  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
+    @error.puts("riffer: #{e.message}")
+    USAGE_ERROR
+  rescue Interrupt
+    130
+  rescue StandardError => e
+    @error.puts("riffer: #{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
+    @error.puts('riffer: no prompt: pass one as an argument, or pipe it to stdin')
+    USAGE_ERROR
+  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
+        else
+          handle(event)
+        end
+      end
+    rescue StandardError => e
+      @error.puts("riffer: #{e.message}")
+      return 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)
+    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

data/lib/riffer/rig/loader.rb

@@ -176,11 +176,10 @@ class Riffer::Rig::Loader
     store = @store
     return nil unless store
 
-    latest = store.list(cwd: @cwd).max_by { |header| store.updated(header.fetch(:id)) || Time.at(0) }
+    latest = store.list(cwd: @cwd).max_by { |header| header.updated || Time.at(0) }
     return nil unless latest
 
-    id = latest.fetch(:id) #: String
-    resume(id, model:, extensions:, skills:, agents_md:, tools:, max_steps:)
+    resume(latest.id, model:, extensions:, skills:, agents_md:, tools:, max_steps:)
   end
 
   # A resume carries the history over and nothing else: the settings,
@@ -212,7 +211,7 @@ class Riffer::Rig::Loader
   end
 
   # @rbs all: bool
-  # @rbs return: Array[Hash[Symbol, untyped]]
+  # @rbs return: Array[::Riffer::Rig::Stores::Header]
   def list(all: false)
     store = @store
     return [] unless store
@@ -563,16 +562,15 @@ class Riffer::Rig::Loader
     File.join(@home, '.riffer', 'settings.json')
   end
 
-  # @rbs entries: Array[Hash[Symbol, untyped]]
+  # @rbs entries: Array[Riffer::Rig::Stores::entry]
   # @rbs id: String
   # @rbs return: Hash[Symbol, untyped]
   def snapshot_of(entries, id)
-    models = entries.select { |entry| entry[:type] == 'model' }
     {
       id: id,
-      messages: entries.select { |entry| entry[:type] == 'message' }.map { |entry| entry.fetch(:message) },
-      model: models.last&.fetch(:model),
-      skills: entries.select { |entry| entry[:type] == 'skill' }.map { |entry| entry.fetch(:skill) }
+      messages: entries.filter_map { |entry| entry.message if entry.is_a?(Riffer::Rig::Stores::MessageEntry) },
+      model: entries.filter_map { |entry| entry.model if entry.is_a?(Riffer::Rig::Stores::ModelEntry) }.last,
+      skills: entries.filter_map { |entry| entry.skill if entry.is_a?(Riffer::Rig::Stores::SkillEntry) }
     }
   end
 

data/lib/riffer/rig/stores/header.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Stores::Header
+  TYPE = 'header' #: String
+
+  include Riffer::Rig::Support::Equatable
+
+  # @rbs @schema_version: Integer
+  # @rbs @id: String
+  # @rbs @cwd: String
+  # @rbs @created_at: String
+  # @rbs @model: String
+  # @rbs @riffer_rig_version: String
+  # @rbs @riffer_version: String
+  # @rbs @title: String
+  # @rbs @updated: Time?
+
+  # @dynamic schema_version, id, cwd, created_at, model, riffer_rig_version, riffer_version, title, updated
+  attr_reader :schema_version #: Integer
+  attr_reader :id #: String
+  attr_reader :cwd #: String
+  attr_reader :created_at #: String
+  attr_reader :model #: String
+  attr_reader :riffer_rig_version #: String
+  attr_reader :riffer_version #: String
+  attr_reader :title #: String
+  # Store-derived metadata, not entry data: stamped by the store while it
+  # holds the physical artifact (the JSONL file's mtime), so it is excluded
+  # from to_h.
+  attr_reader :updated #: Time?
+
+  # @rbs hash: Hash[Symbol, untyped]
+  # @rbs updated: Time?
+  # @rbs return: ::Riffer::Rig::Stores::Header?
+  def self.from_hash(hash, updated: nil)
+    schema_version = hash[:schema_version]
+    id = hash[:id]
+    cwd = hash[:cwd]
+    created_at = hash[:created_at]
+    model = hash[:model]
+    riffer_rig_version = hash[:riffer_rig_version]
+    riffer_version = hash[:riffer_version]
+    title = hash[:title]
+    return nil unless schema_version.is_a?(Integer)
+    return nil unless [id, cwd, created_at, model, riffer_rig_version, riffer_version, title].all?(String)
+
+    new(
+      schema_version: schema_version,
+      id: id,
+      cwd: cwd,
+      created_at: created_at,
+      model: model,
+      riffer_rig_version: riffer_rig_version,
+      riffer_version: riffer_version,
+      title: title,
+      updated: updated
+    )
+  end
+
+  # @rbs schema_version: Integer
+  # @rbs id: String
+  # @rbs cwd: String
+  # @rbs created_at: String
+  # @rbs model: String
+  # @rbs riffer_rig_version: String
+  # @rbs riffer_version: String
+  # @rbs title: String
+  # @rbs updated: Time?
+  # @rbs return: void
+  def initialize(
+    schema_version:,
+    id:,
+    cwd:,
+    created_at:,
+    model:,
+    riffer_rig_version:,
+    riffer_version:,
+    title:,
+    updated: nil
+  )
+    @schema_version = schema_version
+    @id = id
+    @cwd = cwd
+    @created_at = created_at
+    @model = model
+    @riffer_rig_version = riffer_rig_version
+    @riffer_version = riffer_version
+    @title = title
+    @updated = updated
+    freeze
+  end
+
+  # @rbs return: Hash[Symbol, untyped]
+  def to_h
+    {
+      type: TYPE,
+      schema_version: @schema_version,
+      id: @id,
+      cwd: @cwd,
+      created_at: @created_at,
+      model: @model,
+      riffer_rig_version: @riffer_rig_version,
+      riffer_version: @riffer_version,
+      title: @title
+    }
+  end
+end