riffer-rig 0.4.0 → 0.6.0

data/lib/riffer/rig/events/session_end.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Events::SessionEnd < Riffer::Rig::Events::Event
+  # @dynamic reason
+  attr_reader :reason #: Symbol
+
+  # @rbs reason: Symbol
+  # @rbs return: void
+  def initialize(reason)
+    super()
+    @reason = reason
+    freeze
+  end
+
+  # @rbs return: Symbol
+  def type
+    :session_end
+  end
+
+  # @rbs return: Hash[Symbol, untyped]
+  def to_h
+    { type: type, reason: reason }
+  end
+end

data/lib/riffer/rig/events/session_start.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Events::SessionStart < Riffer::Rig::Events::Event
+  # @dynamic id, reason
+  attr_reader :id #: String
+  attr_reader :reason #: Symbol
+
+  # @rbs id: String
+  # @rbs reason: Symbol
+  # @rbs return: void
+  def initialize(id, reason)
+    super()
+    @id = id
+    @reason = reason
+    freeze
+  end
+
+  # @rbs return: Symbol
+  def type
+    :session_start
+  end
+
+  # @rbs return: Hash[Symbol, untyped]
+  def to_h
+    { type: type, id: id, reason: reason }
+  end
+end

data/lib/riffer/rig/events/skill_activated.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Events::SkillActivated < Riffer::Rig::Events::Event
+  # @dynamic name
+  attr_reader :name #: String
+
+  # @rbs name: String
+  # @rbs return: void
+  def initialize(name)
+    super()
+    @name = name
+    freeze
+  end
+
+  # @rbs return: Symbol
+  def type
+    :skill_activated
+  end
+
+  # @rbs return: Hash[Symbol, untyped]
+  def to_h
+    { type: type, name: name }
+  end
+end

data/lib/riffer/rig/events/turn_end.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Events::TurnEnd < Riffer::Rig::Events::Event
+  # @dynamic stop_reason, usage
+  attr_reader :stop_reason #: Symbol
+  attr_reader :usage #: ::Riffer::Providers::TokenUsage?
+
+  # @rbs stop_reason: Symbol
+  # @rbs usage: ::Riffer::Providers::TokenUsage?
+  # @rbs return: void
+  def initialize(stop_reason, usage)
+    super()
+    @stop_reason = stop_reason
+    @usage = usage
+    freeze
+  end
+
+  # @rbs return: Float?
+  def cost
+    usage&.cost
+  end
+
+  # @rbs return: Symbol
+  def type
+    :turn_end
+  end
+
+  # @rbs return: Hash[Symbol, untyped]
+  def to_h
+    { type: type, stop_reason: stop_reason, usage: usage }
+  end
+end

data/lib/riffer/rig/events.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+module Riffer::Rig::Events
+end

data/lib/riffer/rig/extension.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+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/hosts/base.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Hosts::Base
+  # @rbs return: Set[Symbol]
+  def capabilities
+    raise NotImplementedError, "#{self.class} must implement #{__method__}"
+  end
+
+  # @rbs question: String?
+  # @rbs options: Array[String]?
+  # @rbs secret: bool
+  # @rbs return: String?
+  def ask(question = nil, options: nil, secret: false)
+    raise NotImplementedError, "#{self.class} must implement #{__method__}"
+  end
+
+  # @rbs question: String?
+  # @rbs return: bool
+  def confirm(question = nil)
+    raise NotImplementedError, "#{self.class} must implement #{__method__}"
+  end
+
+  # @rbs message: String?
+  # @rbs level: Symbol
+  # @rbs return: void
+  def notify(message = nil, level: :info)
+    raise NotImplementedError, "#{self.class} must implement #{__method__}"
+  end
+
+  # @rbs label: String?
+  # @rbs &: ? () -> void
+  # @rbs return: void
+  def progress(label = nil, &)
+    raise NotImplementedError, "#{self.class} must implement #{__method__}"
+  end
+end

data/lib/riffer/rig/hosts/mirror.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Hosts::Mirror < Riffer::Rig::Hosts::Base
+  # @rbs @host: Riffer::Rig::Hosts::Base
+  # @rbs @queue: Array[Riffer::Rig::Events::Event]
+
+  # @dynamic capabilities
+  attr_reader :capabilities #: Set[Symbol]
+
+  # @rbs host: Riffer::Rig::Hosts::Base
+  # @rbs return: void
+  def initialize(host)
+    super()
+    @host = host
+    @capabilities = host.capabilities
+    @queue = []
+  end
+
+  # @rbs question: String?
+  # @rbs options: Array[String]?
+  # @rbs secret: bool
+  # @rbs return: String?
+  def ask(question = nil, options: nil, secret: false)
+    @host.ask(question, options: options, secret: secret)
+  end
+
+  # @rbs question: String?
+  # @rbs return: bool
+  def confirm(question = nil)
+    @host.confirm(question)
+  end
+
+  # @rbs message: String?
+  # @rbs level: Symbol
+  # @rbs return: void
+  def notify(message = nil, level: :info)
+    queue(Riffer::Rig::Events::Notify.new(message, level))
+    @host.notify(message, level: level)
+  end
+
+  # @rbs label: String?
+  # @rbs &block: ? () -> void
+  # @rbs return: void
+  def progress(label = nil, &block)
+    @host.progress(label) { block&.call }
+  end
+
+  # @rbs event: Riffer::Rig::Events::Event
+  # @rbs return: void
+  def queue(event)
+    @queue << event
+  end
+
+  # @rbs return: Array[Riffer::Rig::Events::Event]
+  def drain
+    queued = @queue
+    @queue = []
+    queued
+  end
+end

data/lib/riffer/rig/hosts/null.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Hosts::Null < Riffer::Rig::Hosts::Base
+  # @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/provider_setup/field.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::ProviderSetup::Field
+  # @dynamic name, env, secret, required, fallback
+  attr_reader :name #: Symbol
+  attr_reader :env #: Array[String]
+  attr_reader :secret, :required #: bool
+  attr_reader :fallback #: (^() -> String?)?
+
+  # @rbs name: Symbol
+  # @rbs env: Array[String]
+  # @rbs secret: bool
+  # @rbs required: bool
+  # @rbs fallback: (^() -> String?)?
+  # @rbs return: void
+  def initialize(name:, env:, secret:, required:, fallback: nil)
+    @name = name
+    @env = env.freeze
+    @secret = secret
+    @required = required
+    @fallback = fallback
+    freeze
+  end
+end

data/lib/riffer/rig/provider_setup.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::ProviderSetup
+  # @dynamic url, chain, fields
+  attr_reader :url #: String?
+  attr_reader :chain #: bool
+  attr_reader :fields #: Array[Riffer::Rig::ProviderSetup::Field]
+
+  # @rbs fields: Array[Riffer::Rig::ProviderSetup::Field]
+  # @rbs url: String?
+  # @rbs chain: bool
+  # @rbs return: void
+  def initialize(fields:, url: nil, chain: false)
+    @url = url
+    @chain = chain
+    @fields = fields.freeze
+    freeze
+  end
+
+  AWS_SHARED_CONFIG_REGION = lambda do
+    require 'aws-sdk-core'
+    Object.const_get(:Aws).shared_config.region
+  rescue LoadError
+    nil
+  end #: ^() -> String?
+
+  # Upstream candidate: each riffer provider could declare its own credential
+  # fields, and this table would go.
+  TABLE = {
+    anthropic: new(
+      url: 'https://console.anthropic.com/settings/keys',
+      fields: [Field.new(name: :api_key, env: ['ANTHROPIC_API_KEY'], secret: true, required: true)]
+    ),
+    openai: new(
+      url: 'https://platform.openai.com/api-keys',
+      fields: [
+        Field.new(name: :api_key, env: ['OPENAI_API_KEY'], secret: true, required: true),
+        Field.new(name: :base_url, env: ['OPENAI_BASE_URL'], secret: false, required: false)
+      ]
+    ),
+    gemini: new(
+      url: 'https://aistudio.google.com/app/apikey',
+      fields: [Field.new(name: :api_key, env: ['GEMINI_API_KEY'], secret: true, required: true)]
+    ),
+    openrouter: new(
+      url: 'https://openrouter.ai/keys',
+      fields: [Field.new(name: :api_key, env: ['OPENROUTER_API_KEY'], secret: true, required: true)]
+    ),
+    azure_openai: new(
+      url: 'https://portal.azure.com',
+      fields: [
+        Field.new(name: :endpoint, env: ['AZURE_OPENAI_ENDPOINT'], secret: false, required: true),
+        Field.new(name: :api_key, env: ['AZURE_OPENAI_API_KEY'], secret: true, required: true)
+      ]
+    ),
+    amazon_bedrock: new(
+      url: 'https://console.aws.amazon.com/bedrock',
+      chain: true,
+      fields: [
+        Field.new(
+          name: :region,
+          env: %w[AWS_REGION AWS_DEFAULT_REGION],
+          secret: false,
+          required: true,
+          fallback: AWS_SHARED_CONFIG_REGION
+        ),
+        Field.new(name: :api_token, env: ['AWS_BEARER_TOKEN_BEDROCK'], secret: true, required: false)
+      ]
+    )
+  }.freeze #: Hash[Symbol, Riffer::Rig::ProviderSetup]
+
+  # @rbs identifier: String | Symbol
+  # @rbs return: Riffer::Rig::ProviderSetup?
+  def self.[](identifier)
+    TABLE[identifier.to_sym]
+  end
+
+  # @rbs identifier: String | Symbol
+  # @rbs return: Riffer::Rig::ProviderSetup
+  def self.for(identifier)
+    self[identifier] ||
+      new(fields: [Field.new(name: :api_key, env: ["#{identifier.to_s.upcase}_API_KEY"], secret: true, required: true)])
+  end
+end

data/lib/riffer/rig/registrar.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Registrar
+  # @rbs @tools: Array[singleton(Riffer::Tool)]
+  # @rbs @prompts: Hash[Symbol, ^(Riffer::Rig::Runtime) -> String?]
+
+  # @rbs return: void
+  def initialize
+    @tools = []
+    @prompts = {}
+  end
+
+  # @rbs klass: singleton(Riffer::Tool)
+  # @rbs return: void
+  def tool(klass)
+    @tools << klass
+  end
+
+  # @rbs name: Symbol
+  # @rbs &block: (Riffer::Rig::Runtime) -> String?
+  # @rbs return: void
+  def prompt(name, &block)
+    @prompts[name] = block
+  end
+
+  # @rbs return: Array[singleton(Riffer::Tool)]
+  def tools
+    @tools.dup
+  end
+
+  # @rbs return: Hash[Symbol, ^(Riffer::Rig::Runtime) -> String?]
+  def prompts
+    @prompts.dup
+  end
+end

data/lib/riffer/rig/repl.rb

@@ -11,28 +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 ?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
@@ -73,15 +73,17 @@ class Riffer::Rig::REPL
   # @rbs prompt: String
   # @rbs return: void
   def run_turn(prompt)
+    # A hidden cursor can't flicker against the animator's erase-and-redraw
+    # churn.
     @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
         next
       when Riffer::StreamEvents::SkillActivation
@@ -89,13 +91,13 @@ class Riffer::Rig::REPL
         # spinner comes straight back on to cover the silent stretch.
         @animator.stop
         @renderer.render(event)
-        @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)
-        @animator.start
+        start_animator
         next
       else
         @animator.stop
@@ -154,12 +156,11 @@ class Riffer::Rig::REPL
     "<skill name=\"#{name}\">\n#{body}\n</skill>"
   end
 
-  # 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 print_block(&)
+    # Bypasses the renderer's tool-group state: these lines (errors, the exit
+    # line) can only follow prose, never land mid-group.
     @output.puts
     @output.puts(yield)
     @output.flush
@@ -172,6 +173,16 @@ class Riffer::Rig::REPL
 
     @animator.stop
     @renderer.render_tool_result(message)
-    @animator.start
+    start_animator
+  end
+
+  # @rbs mode: Symbol
+  # @rbs return: void
+  def start_animator(mode = :neutral)
+    # 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.
+    @smoother.drain
+    @animator.start(mode)
   end
 end

data/lib/riffer/rig/runtime/cancel_flag.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Runtime::CancelFlag
+  # @rbs @mutex: Thread::Mutex
+  # @rbs @set: bool
+
+  # @rbs return: void
+  def initialize
+    @mutex = Mutex.new
+    @set = false
+  end
+
+  # @rbs return: void
+  def set
+    @mutex.synchronize { @set = true }
+  end
+
+  # @rbs return: void
+  def clear
+    @mutex.synchronize { @set = false }
+  end
+
+  # @rbs return: bool
+  def set?
+    @mutex.synchronize { @set }
+  end
+end