riffer-rig 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d49bc7e8176b7eec0bc8cc2249bc39668f9637557db92bdd34c1f4baf9ee7ce0
-  data.tar.gz: c9d563f1ff2de6cbece63dc6735107537bc33fd1b8cefde8541e7e2fc3262f3a
+  metadata.gz: 5f79d98c522224290937a01b701fa7f4ac72f2be08fbbb39abf32f06691880f7
+  data.tar.gz: 3c66dbd81e98e86b1c1132094431e0803d23c757a950684c6663ad5abd8c3369
 SHA512:
-  metadata.gz: 7b89243587acc30185f2a0f16ebc5adfb43c860f537ec5f1cab6b7fae116322109f74f49b6e990c7d4d0b48dab1a8db3ec61f804c84b69bb06f3fa14cba2f0d7
-  data.tar.gz: cdb0fdd4d2354fd7ed1625c022e6f0fff02f2a34b3f37babfdf1a443a57427e45bb88fab58edf07cd3cfc9e1ef14ad492589ca847df7ff9339c0695728d21290
+  metadata.gz: 6087cb7527548ca826bf04ab3b214c36ab29e18c676c62f7df84377010bb47fddae9e88b1354d1fa8815efa4967d4599ccc63e022c57660a567b58e226554679
+  data.tar.gz: 2aae83bea0978c35b33674149527c0281baeb33f7bf186ba38d9b6abdeb905a3649989eae97430d7eae6284a80a253152d0532c8ba3d75f3ae3d7adee6f6a757

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 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)
+
+
+### Features
+
+* continue and resume sessions with -c and -r ([#220](https://github.com/bottrall/riffer-rig/issues/220)) ([e43d3ac](https://github.com/bottrall/riffer-rig/commit/e43d3ac44678e56016791545ea241779569687c9))
+* reload automatically before each request ([#222](https://github.com/bottrall/riffer-rig/issues/222)) ([fe96aa4](https://github.com/bottrall/riffer-rig/commit/fe96aa4476b0765e58824a8eb59301f0986e397c))
+
 ## [0.9.0](https://github.com/bottrall/riffer-rig/compare/v0.8.0...v0.9.0) (2026-10-04)
 
 

data/README.md

@@ -47,9 +47,25 @@ The model is the first of these that is set: `--model`, `RIFFER_MODEL`, `model`
 | `--tools read,bash`     | only these tools, by identifier ([Tools](docs/TOOLS.md))                    |
 | `--max-steps N`         | stops a turn after `N` model calls                                          |
 | `--no-save`             | does not save this session to the [store](docs/SESSIONS.md)                 |
+| `-c`, `--continue`      | continues the most recent session in this directory ([Sessions](docs/SESSIONS.md#resuming)) |
+| `-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,23 +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
+  # @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],
@@ -31,6 +36,10 @@ 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)
     )
   rescue OptionParser::ParseError => e
@@ -54,6 +63,10 @@ class Riffer::Rig::CLI::Flags
       parser.on('--tools NAME,NAME', Array, 'Only these tools, by identifier')
       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('-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
@@ -66,6 +79,10 @@ 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
   # @rbs return: void
   def initialize(
@@ -76,6 +93,10 @@ class Riffer::Rig::CLI::Flags
     tools: nil,
     max_steps: nil,
     save: true,
+    verbose: false,
+    prompt: nil,
+    continue: false,
+    resume: nil,
     help: false
   )
     @model = model
@@ -85,6 +106,10 @@ class Riffer::Rig::CLI::Flags
     @tools = tools&.freeze
     @max_steps = max_steps
     @save = save
+    @verbose = verbose
+    @prompt = prompt
+    @continue = continue
+    @resume = resume
     @help = help
     freeze
   end

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,22 +78,73 @@ module Riffer::Rig::CLI
       version: Riffer::Rig::VERSION,
       no_color: env.is_a?(Riffer::Rig::Env) && env.no_color
     ).run do |host|
-      Riffer::Rig::Loader.runtime(
-        cwd: cwd,
-        host: host,
-        env: env,
-        home: home,
-        model: flags.model,
-        extensions: flags.extensions,
-        skills: flags.skills,
-        agents_md: flags.agents_md,
-        tools: flags.tools,
-        max_steps: flags.max_steps,
-        store: flags.save ? Riffer::Rig::Stores::JSONL.new : nil
-      )
+      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 find_session(flags, loader)
+    if flags.resume
+      loader.resume(flags.resume, **keywords(flags))
+    elsif flags.continue
+      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
+  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
+    }
+  end
+
   # @rbs name: String
   # @rbs error: IO
   # @rbs return: Integer

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