riffer-rig 0.6.0 → 0.7.0

data/sig/generated/riffer/rig/loader.rbs

@@ -0,0 +1,77 @@
+# Generated from lib/riffer/rig/loader.rb with RBS::Inline
+
+class Riffer::Rig::Loader
+  class ConfigurationError < StandardError
+  end
+
+  PROVIDER_LIST: String
+
+  ONBOARDING_QUESTION: String
+
+  NO_MODEL: String
+
+  @riffer_config: Riffer::Config
+
+  @home: String
+
+  @env: Riffer::Rig::Env
+
+  @host: Riffer::Rig::Hosts::_Host
+
+  @cwd: String
+
+  # @rbs cwd: String
+  # @rbs host: Riffer::Rig::Hosts::_Host
+  # @rbs env: Riffer::Rig::Env | Riffer::Rig::Env::Invalid
+  # @rbs home: String
+  # @rbs riffer_config: Riffer::Config
+  # @rbs model: String?
+  # @rbs extensions: bool
+  # @rbs skills: bool
+  # @rbs agents_md: bool
+  # @rbs tools: Array[String]?
+  # @rbs max_steps: Integer?
+  # @rbs return: Riffer::Rig::Runtime
+  def self.runtime: (cwd: String, host: Riffer::Rig::Hosts::_Host, ?env: Riffer::Rig::Env | Riffer::Rig::Env::Invalid, ?home: String, ?riffer_config: Riffer::Config, ?model: String?, ?extensions: bool, ?skills: bool, ?agents_md: bool, ?tools: Array[String]?, ?max_steps: Integer?) -> Riffer::Rig::Runtime
+
+  # @rbs cwd: String
+  # @rbs host: Riffer::Rig::Hosts::_Host
+  # @rbs env: Riffer::Rig::Env | Riffer::Rig::Env::Invalid
+  # @rbs home: String
+  # @rbs riffer_config: Riffer::Config
+  # @rbs return: void
+  def initialize: (cwd: String, host: Riffer::Rig::Hosts::_Host, ?env: Riffer::Rig::Env | Riffer::Rig::Env::Invalid, ?home: String, ?riffer_config: Riffer::Config) -> void
+
+  # @rbs model: String?
+  # @rbs extensions: bool
+  # @rbs skills: bool
+  # @rbs agents_md: bool
+  # @rbs tools: Array[String]?
+  # @rbs max_steps: Integer?
+  # @rbs return: Riffer::Rig::Runtime
+  def runtime: (?model: String?, ?extensions: bool, ?skills: bool, ?agents_md: bool, ?tools: Array[String]?, ?max_steps: Integer?) -> Riffer::Rig::Runtime
+
+  private
+
+  # @rbs configured: String?
+  # @rbs return: String
+  def select_model: (String? configured) -> String
+
+  # @rbs return: String
+  def ask_for_model: () -> String
+
+  # @rbs provider: String
+  # @rbs return: Hash[Symbol, String]
+  def credentials_for: (String provider) -> Hash[Symbol, String]
+
+  # @rbs provider: String
+  # @rbs missing: Array[Symbol]
+  # @rbs return: String
+  def missing_credentials: (String provider, Array[Symbol] missing) -> String
+
+  # @rbs return: Riffer::Rig::Hosts::_Host
+  def asking_host: () -> Riffer::Rig::Hosts::_Host
+
+  # @rbs return: String
+  def home_settings_path: () -> String
+end

data/sig/generated/riffer/rig/mcp/declaration.rbs

@@ -0,0 +1,18 @@
+# Generated from lib/riffer/rig/mcp/declaration.rb with RBS::Inline
+
+class Riffer::Rig::Mcp::Declaration
+  include Riffer::Rig::Support::Equatable
+
+  # @dynamic url, headers
+  attr_reader url: String
+
+  attr_reader headers: Hash[String, String]
+
+  # @rbs url: String
+  # @rbs headers: Hash[String, String]
+  # @rbs return: void
+  def initialize: (url: String, headers: Hash[String, String]) -> void
+
+  # @rbs return: Hash[Symbol, untyped]
+  def to_h: () -> Hash[Symbol, untyped]
+end

data/sig/generated/riffer/rig/mcp/server.rbs

@@ -0,0 +1,13 @@
+# Generated from lib/riffer/rig/mcp/server.rb with RBS::Inline
+
+class Riffer::Rig::Mcp::Server
+  # @dynamic declaration, registration
+  attr_reader declaration: Riffer::Rig::Mcp::Declaration
+
+  attr_reader registration: Riffer::Mcp::Registration
+
+  # @rbs declaration: Riffer::Rig::Mcp::Declaration
+  # @rbs registration: Riffer::Mcp::Registration
+  # @rbs return: void
+  def initialize: (declaration: Riffer::Rig::Mcp::Declaration, registration: Riffer::Mcp::Registration) -> void
+end

data/sig/generated/riffer/rig/mcp.rbs

@@ -0,0 +1,8 @@
+# Generated from lib/riffer/rig/mcp.rb with RBS::Inline
+
+module Riffer::Rig::Mcp
+  # @rbs home: Hash[Symbol, untyped]
+  # @rbs project: Hash[Symbol, untyped]
+  # @rbs return: Hash[Symbol, untyped]
+  def merge: (Hash[Symbol, untyped] home, Hash[Symbol, untyped] project) -> Hash[Symbol, untyped]
+end

data/sig/generated/riffer/rig/prompts/agents_md.rbs

@@ -0,0 +1,19 @@
+# Generated from lib/riffer/rig/prompts/agents_md.rb with RBS::Inline
+
+module Riffer::Rig::Prompts::AgentsMd
+  FRAMING: String
+
+  # @rbs cwd: String
+  # @rbs return: Array[String]
+  def paths: (String cwd) -> Array[String]
+
+  # @rbs cwd: String
+  # @rbs return: String?
+  def section: (String cwd) -> String?
+
+  private
+
+  # @rbs path: String
+  # @rbs return: String
+  def block: (String path) -> String
+end

data/sig/generated/riffer/rig/prompts.rbs

@@ -0,0 +1,4 @@
+# Generated from lib/riffer/rig/prompts.rb with RBS::Inline
+
+module Riffer::Rig::Prompts
+end

data/sig/generated/riffer/rig/registrar.rbs

@@ -1,12 +1,39 @@
 # Generated from lib/riffer/rig/registrar.rb with RBS::Inline
 
 class Riffer::Rig::Registrar
-  @tools: Array[singleton(Riffer::Tool)]
+  class NameCollisionError < StandardError
+  end
+
+  CORE_SETTINGS_KEYS: Array[String]
+
+  EVENTS: Array[Symbol]
+
+  @hooks: Hash[Symbol, Array[^(Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base) -> untyped]]
+
+  @mcp_servers: Hash[String, Riffer::Rig::Mcp::Declaration]
+
+  @given_settings: Hash[Symbol, untyped]
+
+  @declared_settings: Hash[Symbol, untyped]
+
+  @skill_sources: Array[^(Riffer::Rig::Runtime) -> Riffer::Skills::Backend]
+
+  @commands: Hash[String, Riffer::Rig::Command]
 
   @prompts: Hash[Symbol, ^(Riffer::Rig::Runtime) -> String?]
 
+  @tools: Hash[String, singleton(Riffer::Tool)]
+
+  # @dynamic extension
+  attr_reader extension: String
+
+  # @rbs extension: String
+  # @rbs settings: Hash[Symbol, untyped]
   # @rbs return: void
-  def initialize: () -> void
+  def initialize: (String extension, ?Hash[Symbol, untyped] settings) -> void
+
+  # @rbs return: NameCollisionError?
+  def collision: () -> NameCollisionError?
 
   # @rbs klass: singleton(Riffer::Tool)
   # @rbs return: void
@@ -17,9 +44,56 @@ class Riffer::Rig::Registrar
   # @rbs return: void
   def prompt: (Symbol name) { (Riffer::Rig::Runtime) -> String? } -> void
 
-  # @rbs return: Array[singleton(Riffer::Tool)]
-  def tools: () -> Array[singleton(Riffer::Tool)]
+  # @rbs name: String
+  # @rbs description: String
+  # @rbs &block: (Riffer::Rig::Command::Context) -> void
+  # @rbs return: void
+  def command: (String name, description: String) { (Riffer::Rig::Command::Context) -> void } -> void
+
+  # @rbs &block: (Riffer::Rig::Runtime) -> Riffer::Skills::Backend
+  # @rbs return: void
+  def skills: () { (Riffer::Rig::Runtime) -> Riffer::Skills::Backend } -> void
+
+  # @rbs key: Symbol
+  # @rbs default: untyped
+  # @rbs return: void
+  def setting: (Symbol key, default: untyped) -> void
+
+  # @rbs name: String
+  # @rbs url: String
+  # @rbs headers: Hash[String, String]
+  # @rbs return: void
+  def mcp: (String name, url: String, ?headers: Hash[String, String]) -> void
+
+  # @rbs event: Symbol
+  # @rbs &block: (Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base) -> untyped
+  # @rbs return: void
+  def on: (Symbol event) { (Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base) -> untyped } -> void
+
+  # @rbs return: Hash[String, singleton(Riffer::Tool)]
+  def tools: () -> Hash[String, singleton(Riffer::Tool)]
 
   # @rbs return: Hash[Symbol, ^(Riffer::Rig::Runtime) -> String?]
   def prompts: () -> Hash[Symbol, ^(Riffer::Rig::Runtime) -> String?]
+
+  # @rbs return: Hash[String, Riffer::Rig::Command]
+  def commands: () -> Hash[String, Riffer::Rig::Command]
+
+  # @rbs return: Array[^(Riffer::Rig::Runtime) -> Riffer::Skills::Backend]
+  def skill_sources: () -> Array[^(Riffer::Rig::Runtime) -> Riffer::Skills::Backend]
+
+  # @rbs return: Hash[Symbol, untyped]
+  def settings: () -> Hash[Symbol, untyped]
+
+  # @rbs return: Hash[Symbol, untyped]
+  def declared_settings: () -> Hash[Symbol, untyped]
+
+  # @rbs return: Hash[String, Riffer::Rig::Mcp::Declaration]
+  def mcp_servers: () -> Hash[String, Riffer::Rig::Mcp::Declaration]
+
+  # @rbs return: Array[String]
+  def registrations: () -> Array[String]
+
+  # @rbs return: Hash[Symbol, Array[^(Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base) -> untyped]]
+  def hooks: () -> Hash[Symbol, Array[^(Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base) -> untyped]]
 end

data/sig/generated/riffer/rig/runtime/blocked.rbs

@@ -0,0 +1,10 @@
+# Generated from lib/riffer/rig/runtime/blocked.rb with RBS::Inline
+
+class Riffer::Rig::Runtime::Blocked
+  # @dynamic reason
+  attr_reader reason: String
+
+  # @rbs reason: String
+  # @rbs return: void
+  def initialize: (String reason) -> void
+end

data/sig/generated/riffer/rig/runtime/hooks.rbs

@@ -0,0 +1,49 @@
+# Generated from lib/riffer/rig/runtime/hooks.rb with RBS::Inline
+
+class Riffer::Rig::Runtime::Hooks
+  @hooks: Hash[Symbol, Array[^(Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base) -> untyped]]
+
+  @host: Riffer::Rig::Hosts::_Host
+
+  # @rbs hooks: Hash[Symbol, Array[^(Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base) -> untyped]]
+  # @rbs host: Riffer::Rig::Hosts::_Host
+  # @rbs return: void
+  def initialize: (Hash[Symbol, Array[^(Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base) -> untyped]] hooks, Riffer::Rig::Hosts::_Host host) -> void
+
+  # @rbs name: Symbol
+  # @rbs event: Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base
+  # @rbs return: void
+  def observe: (Symbol name, Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base event) -> void
+
+  # @rbs text: String
+  # @rbs return: String | Riffer::Rig::Runtime::Blocked
+  def before_prompt: (String text) -> (String | Riffer::Rig::Runtime::Blocked)
+
+  # @rbs tool: String
+  # @rbs args: Hash[Symbol, untyped]
+  # @rbs return: Hash[Symbol, untyped] | Riffer::Rig::Runtime::Blocked
+  def before_tool_call: (String tool, Hash[Symbol, untyped] args) -> (Hash[Symbol, untyped] | Riffer::Rig::Runtime::Blocked)
+
+  # @rbs messages: Array[::Riffer::Messages::Base]
+  # @rbs return: Array[::Riffer::Messages::Base] | Riffer::Rig::Runtime::Blocked
+  def before_request: (Array[::Riffer::Messages::Base] messages) -> (Array[::Riffer::Messages::Base] | Riffer::Rig::Runtime::Blocked)
+
+  private
+
+  # @rbs name: Symbol
+  # @rbs payload: untyped
+  # @rbs accepts: ^(untyped) -> bool
+  # @rbs &: (untyped) -> Riffer::Rig::Events::_Event
+  # @rbs return: untyped
+  def veto: (Symbol name, untyped payload, ^(untyped) -> bool accepts) { (untyped) -> Riffer::Rig::Events::_Event } -> untyped
+
+  # @rbs outcome: untyped
+  # @rbs return: untyped
+  def announce: (untyped outcome) -> untyped
+
+  # @rbs name: Symbol
+  # @rbs hook: ^(Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base) -> untyped
+  # @rbs event: Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base
+  # @rbs return: untyped
+  def call: (Symbol name, ^(Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base) -> untyped hook, Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base event) -> untyped
+end

data/sig/generated/riffer/rig/runtime/request_guardrail.rbs

@@ -0,0 +1,16 @@
+# Generated from lib/riffer/rig/runtime/request_guardrail.rb with RBS::Inline
+
+# riffer runs its before guardrails once per run, just ahead of the first
+# request; the Runtime's on_message observer covers the requests after it.
+class Riffer::Rig::Runtime::RequestGuardrail < Riffer::Guardrail
+  @hooks: Riffer::Rig::Runtime::Hooks
+
+  # @rbs hooks: Riffer::Rig::Runtime::Hooks
+  # @rbs return: void
+  def initialize: (hooks: Riffer::Rig::Runtime::Hooks) -> void
+
+  # @rbs messages: Array[Riffer::Messages::Base]
+  # @rbs context: untyped
+  # @rbs return: Riffer::Guardrails::Result
+  def process_input: (Array[Riffer::Messages::Base] messages, context: untyped) -> Riffer::Guardrails::Result
+end

data/sig/generated/riffer/rig/runtime/tool_runtime.rbs

@@ -0,0 +1,23 @@
+# Generated from lib/riffer/rig/runtime/tool_runtime.rb with RBS::Inline
+
+class Riffer::Rig::Runtime::ToolRuntime < Riffer::Tools::Runtime
+  @hooks: Riffer::Rig::Runtime::Hooks
+
+  # @rbs hooks: Riffer::Rig::Runtime::Hooks
+  # @rbs return: void
+  def initialize: (Riffer::Rig::Runtime::Hooks hooks) -> void
+
+  private
+
+  # @rbs tool_call: Riffer::Messages::Assistant::ToolCall
+  # @rbs tools: Array[singleton(Riffer::Tool)]
+  # @rbs context: Riffer::Agent::Context?
+  # @rbs assistant_message: Riffer::Messages::Assistant?
+  # @rbs return: Riffer::Tools::Response
+  def dispatch_tool_call: (Riffer::Messages::Assistant::ToolCall tool_call, tools: Array[singleton(Riffer::Tool)], context: Riffer::Agent::Context?, ?assistant_message: Riffer::Messages::Assistant?) -> Riffer::Tools::Response
+
+  # @rbs tool_call: Riffer::Messages::Assistant::ToolCall
+  # @rbs args: Hash[Symbol, untyped]
+  # @rbs return: Riffer::Messages::Assistant::ToolCall
+  def replace_arguments: (Riffer::Messages::Assistant::ToolCall tool_call, Hash[Symbol, untyped] args) -> Riffer::Messages::Assistant::ToolCall
+end

data/sig/generated/riffer/rig/runtime.rbs

@@ -19,31 +19,53 @@ class Riffer::Rig::Runtime
 
   INTERRUPT_CANCELLED: Symbol
 
-  @agent: Riffer::Agent
+  @session_start_reason: Symbol
 
-  @base_prompt: String
+  @session_start_pending: bool
 
-  @cancel_flag: Riffer::Rig::Runtime::CancelFlag
+  @closed: bool
 
-  @credentials: Hash[Symbol, Hash[Symbol, String]]
+  @busy: bool
 
-  @cwd: String
+  @settings: Hash[Symbol, untyped]
+
+  @id: String
 
   @host: Riffer::Rig::Hosts::Mirror
 
-  @id: String
+  @cwd: String
 
-  @settings: Hash[Symbol, untyped]
+  @credentials: Hash[Symbol, Hash[Symbol, String]]
 
-  @busy: bool
+  @cancel_flag: Riffer::Rig::Runtime::CancelFlag
 
-  @closed: bool
+  @base_prompt: String
 
-  @session_start_pending: bool
+  @agent: Riffer::Agent
+
+  @model_override: String?
+
+  @message_observers: Array[^(Riffer::Messages::Base) -> void]
+
+  @prompts: Hash[Symbol, ^(Riffer::Rig::Runtime) -> String?]
+
+  @commands: Hash[String, Riffer::Rig::Command]
+
+  @declared_settings: Hash[String, Hash[Symbol, untyped]]
 
-  @registrar: Riffer::Rig::Registrar
+  @errors: Array[Riffer::Rig::Extension::Failure]
 
-  # @dynamic agent, credentials, cwd, host, id, settings
+  @hooks: Riffer::Rig::Runtime::Hooks
+
+  @tool_allowlist: Array[String]?
+
+  @mcp_registry: Riffer::Rig::Mcp::_Registry
+
+  @mcp_servers: Hash[String, Riffer::Rig::Mcp::Server]
+
+  @model_options: Hash[Symbol, untyped]
+
+  # @dynamic agent, credentials, cwd, host, id, settings, declared_settings
   attr_reader agent: Riffer::Agent
 
   attr_reader credentials: Hash[Symbol, Hash[Symbol, String]]
@@ -56,41 +78,155 @@ class Riffer::Rig::Runtime
 
   attr_reader settings: Hash[Symbol, untyped]
 
+  attr_reader declared_settings: Hash[String, Hash[Symbol, untyped]]
+
   # @rbs model: String
   # @rbs extensions: Array[Riffer::Rig::Extension]
   # @rbs tools: Array[String]?
   # @rbs settings: Hash[Symbol, untyped]
-  # @rbs host: Riffer::Rig::Hosts::Base
+  # @rbs host: Riffer::Rig::Hosts::_Host
   # @rbs cwd: String?
   # @rbs name: String
   # @rbs instructions: String?
   # @rbs credentials: Hash[Symbol, Hash[Symbol, String]]
   # @rbs pricing: Hash[String, Riffer::Rig::Settings::Pricing]
+  # @rbs riffer_config: Riffer::Config
+  # @rbs mcp_registry: Riffer::Rig::Mcp::_Registry
   # @rbs max_steps: Integer?
+  # @rbs model_options: Hash[Symbol, untyped]
   # @rbs snapshot: Hash[Symbol, untyped]?
   # @rbs return: void
-  def initialize: (String model, ?extensions: Array[Riffer::Rig::Extension], ?tools: Array[String]?, ?settings: Hash[Symbol, untyped], ?host: Riffer::Rig::Hosts::Base, ?cwd: String?, ?name: String, ?instructions: String?, ?credentials: Hash[Symbol, Hash[Symbol, String]], ?pricing: Hash[String, Riffer::Rig::Settings::Pricing], ?max_steps: Integer?, ?snapshot: Hash[Symbol, untyped]?) -> void
+  def initialize: (String model, ?extensions: Array[Riffer::Rig::Extension], ?tools: Array[String]?, ?settings: Hash[Symbol, untyped], ?host: Riffer::Rig::Hosts::_Host, ?cwd: String?, ?name: String, ?instructions: String?, ?credentials: Hash[Symbol, Hash[Symbol, String]], ?pricing: Hash[String, Riffer::Rig::Settings::Pricing], ?riffer_config: Riffer::Config, ?mcp_registry: Riffer::Rig::Mcp::_Registry, ?max_steps: Integer?, ?model_options: Hash[Symbol, untyped], ?snapshot: Hash[Symbol, untyped]?) -> void
 
   # @rbs text: String
-  # @rbs &block: ?(::Riffer::StreamEvents::Base | Riffer::Rig::Events::Event) -> void
-  # @rbs return: (nil | Enumerator[::Riffer::StreamEvents::Base | Riffer::Rig::Events::Event, Riffer::Agent::Response])
-  def prompt: (String text) ?{ (::Riffer::StreamEvents::Base | Riffer::Rig::Events::Event) -> void } -> (nil | Enumerator[::Riffer::StreamEvents::Base | Riffer::Rig::Events::Event, Riffer::Agent::Response])
+  # @rbs &block: ?(::Riffer::StreamEvents::Base | Riffer::Rig::Events::_Event) -> void
+  # @rbs return: (nil | Enumerator[::Riffer::StreamEvents::Base | Riffer::Rig::Events::_Event, Riffer::Agent::Response])
+  def prompt: (String text) ?{ (::Riffer::StreamEvents::Base | Riffer::Rig::Events::_Event) -> void } -> (nil | Enumerator[::Riffer::StreamEvents::Base | Riffer::Rig::Events::_Event, Riffer::Agent::Response])
 
   # @rbs text: String
   # @rbs return: Riffer::Agent::Response
   def ask: (String text) -> Riffer::Agent::Response
 
+  # @rbs return: Array[Riffer::Rig::Command]
+  def commands: () -> Array[Riffer::Rig::Command]
+
+  # @rbs name: String
+  # @rbs args: String
+  # @rbs &block: ?(::Riffer::StreamEvents::Base | Riffer::Rig::Events::_Event) -> void
+  # @rbs return: nil
+  def run_command: (String name, ?String args) ?{ (::Riffer::StreamEvents::Base | Riffer::Rig::Events::_Event) -> void } -> nil
+
+  # @rbs return: Array[Riffer::Rig::Extension::Failure]
+  def errors: () -> Array[Riffer::Rig::Extension::Failure]
+
+  # @rbs return: String
+  def model: () -> String
+
+  # @rbs model: String
+  # @rbs return: void
+  def model=: (String model) -> void
+
+  # @rbs extensions: Array[Riffer::Rig::Extension]
+  # @rbs settings: Hash[Symbol, untyped]
+  # @rbs return: nil
+  def rebuild: (extensions: Array[Riffer::Rig::Extension], settings: Hash[Symbol, untyped]) -> nil
+
+  # @rbs return: Hash[Symbol, untyped]
+  def to_h: () -> Hash[Symbol, untyped]
+
+  # @rbs &block: (Riffer::Messages::Base) -> void
+  # @rbs return: nil
+  def on_message: () { (Riffer::Messages::Base) -> void } -> nil
+
   # @rbs return: nil
   def cancel: () -> nil
 
+  # @rbs return: Riffer::Providers::TokenUsage?
+  def tally: () -> Riffer::Providers::TokenUsage?
+
   # @rbs return: void
   def close: () -> void
 
   private
 
-  # @rbs stream: Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
-  # @rbs return: Enumerator[::Riffer::StreamEvents::Base | Riffer::Rig::Events::Event, Riffer::Agent::Response]
-  def wrap_stream: (Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response] stream) -> Enumerator[::Riffer::StreamEvents::Base | Riffer::Rig::Events::Event, Riffer::Agent::Response]
+  # @rbs return: void
+  def claim: () -> void
+
+  # @rbs model: String
+  # @rbs config: Riffer::Agent::Config
+  # @rbs session: Riffer::Agent::Session?
+  # @rbs return: Riffer::Agent
+  def build_agent: (String model, Riffer::Agent::Config config, ?session: Riffer::Agent::Session?) -> Riffer::Agent
+
+  # @rbs model: String
+  # @rbs config: Riffer::Agent::Config
+  # @rbs return: Riffer::Agent
+  def successor: (String model, Riffer::Agent::Config config) -> Riffer::Agent
+
+  # @rbs registrars: Array[Riffer::Rig::Registrar]
+  # @rbs hooks: Riffer::Rig::Runtime::Hooks
+  # @rbs max_steps: Numeric?
+  # @rbs return: Riffer::Agent::Config
+  def agent_config: (Array[Riffer::Rig::Registrar] registrars, Riffer::Rig::Runtime::Hooks hooks, Numeric? max_steps) -> Riffer::Agent::Config
+
+  # @rbs sources: Array[^(Riffer::Rig::Runtime) -> Riffer::Skills::Backend]
+  # @rbs return: Riffer::Skills::Config?
+  def skills_config: (Array[^(Riffer::Rig::Runtime) -> Riffer::Skills::Backend] sources) -> Riffer::Skills::Config?
+
+  # @rbs registrars: Array[Riffer::Rig::Registrar]
+  # @rbs mcp_servers: Hash[String, Riffer::Rig::Mcp::Server]
+  # @rbs settings: Hash[Symbol, untyped]
+  # @rbs hooks: Riffer::Rig::Runtime::Hooks
+  # @rbs agent: Riffer::Agent
+  # @rbs return: void
+  def install: (Array[Riffer::Rig::Registrar] registrars, Hash[String, Riffer::Rig::Mcp::Server] mcp_servers, Hash[Symbol, untyped] settings, Riffer::Rig::Runtime::Hooks hooks, Riffer::Agent agent) -> void
+
+  # A session that has not started yet opens with session_start(:new) on its
+  # first turn instead.
+  # @rbs name: Symbol
+  # @rbs event: Riffer::Rig::Events::_Event
+  # @rbs return: void
+  def lifecycle: (Symbol name, Riffer::Rig::Events::_Event event) -> void
+
+  # @rbs text: String
+  # @rbs return: Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+  def start_turn: (String text) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+
+  # @rbs reason: String
+  # @rbs return: Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+  def blocked_turn: (String reason) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
+
+  # @rbs name: String
+  # @rbs args: String
+  # @rbs emit: ^(::Riffer::StreamEvents::Base | Riffer::Rig::Events::_Event) -> void
+  # @rbs return: void
+  def execute: (String name, String args, ^(::Riffer::StreamEvents::Base | Riffer::Rig::Events::_Event) -> void emit) -> void
+
+  # @rbs command: Riffer::Rig::Command
+  # @rbs args: String
+  # @rbs emit: ^(::Riffer::StreamEvents::Base | Riffer::Rig::Events::_Event) -> void
+  # @rbs return: Riffer::Rig::Command::Context
+  def command_context: (Riffer::Rig::Command command, String args, ^(::Riffer::StreamEvents::Base | Riffer::Rig::Events::_Event) -> void emit) -> Riffer::Rig::Command::Context
+
+  # @rbs text: String
+  # @rbs return: Enumerator[::Riffer::StreamEvents::Base | Riffer::Rig::Events::_Event, Riffer::Agent::Response]
+  def turn: (String text) -> Enumerator[::Riffer::StreamEvents::Base | Riffer::Rig::Events::_Event, Riffer::Agent::Response]
+
+  # @rbs yielder: Enumerator::Yielder
+  # @rbs event: ::Riffer::StreamEvents::Base
+  # @rbs return: void
+  def pass_through: (Enumerator::Yielder yielder, ::Riffer::StreamEvents::Base event) -> void
+
+  # @rbs message: Riffer::Messages::Base
+  # @rbs return: void
+  def observe_message: (Riffer::Messages::Base message) -> void
+
+  # @rbs message: Riffer::Messages::Base
+  # @rbs return: void
+  def deliver: (Riffer::Messages::Base message) -> void
+
+  # @rbs return: void
+  def before_next_request: () -> void
 
   # @rbs return: void
   def interrupt_if_cancelled: () -> void
@@ -99,9 +235,76 @@ class Riffer::Rig::Runtime
   # @rbs return: Symbol
   def stop_reason: (Riffer::Agent::Outcome outcome) -> Symbol
 
+  # @rbs snapshot: Hash[Symbol, untyped]
+  # @rbs model: String
+  # @rbs config: Riffer::Agent::Config
+  # @rbs return: Riffer::Agent
+  def restore: (Hash[Symbol, untyped] snapshot, String model, Riffer::Agent::Config config) -> Riffer::Agent
+
+  # @rbs saved: String?
+  # @rbs model: String
+  # @rbs return: String?
+  def restorable_model: (String? saved, String model) -> String?
+
+  # @rbs messages: Array[Riffer::Messages::Base]
+  # @rbs return: Riffer::Providers::TokenUsage?
+  def usage_of: (Array[Riffer::Messages::Base] messages) -> Riffer::Providers::TokenUsage?
+
+  # @rbs skills: Riffer::Skills::Context?
+  # @rbs names: Array[String]
+  # @rbs return: void
+  def reactivate: (Riffer::Skills::Context? skills, Array[String] names) -> void
+
+  # @rbs return: Array[String]
+  def activated_skills: () -> Array[String]
+
   # @rbs extensions: Array[Riffer::Rig::Extension]
-  # @rbs return: Riffer::Rig::Registrar
-  def build_registrar: (Array[Riffer::Rig::Extension] extensions) -> Riffer::Rig::Registrar
+  # @rbs settings: Hash[Symbol, untyped]
+  # @rbs &: (Riffer::Rig::Extension, StandardError) -> void
+  # @rbs return: Array[Riffer::Rig::Registrar]
+  def build_registrars: (Array[Riffer::Rig::Extension] extensions, Hash[Symbol, untyped] settings) { (Riffer::Rig::Extension, StandardError) -> void } -> Array[Riffer::Rig::Registrar]
+
+  # @rbs extension: Riffer::Rig::Extension
+  # @rbs registrar: Riffer::Rig::Registrar
+  # @rbs return: StandardError?
+  def load_extension: (Riffer::Rig::Extension extension, Riffer::Rig::Registrar registrar) -> StandardError?
+
+  # @rbs extension: Riffer::Rig::Extension
+  # @rbs error: StandardError
+  # @rbs return: void
+  def record_error: (Riffer::Rig::Extension extension, StandardError error) -> void
+
+  # @rbs registrars: Array[Riffer::Rig::Registrar]
+  # @rbs return: Array[String]
+  def overrides: (Array[Riffer::Rig::Registrar] registrars) -> Array[String]
+
+  # @rbs settings: Hash[Symbol, untyped]
+  # @rbs return: Hash[Symbol, untyped]
+  def with_declared_defaults: (Hash[Symbol, untyped] settings) -> Hash[Symbol, untyped]
+
+  # @rbs return: Hash[Symbol, Array[^(Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base) -> untyped]]
+  def merge_hooks: (untyped registrars) -> Hash[Symbol, Array[^(Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base) -> untyped]]
+
+  # Upstream candidate: riffer's MCP registry is process-wide and keyed by
+  # server name alone, so each Runtime tags its registrations, and two
+  # Runtimes declaring the same name replace each other's.
+  # @rbs return: Symbol
+  def mcp_tag: () -> Symbol
+
+  # @rbs registrars: Array[Riffer::Rig::Registrar]
+  # @rbs return: Hash[String, Riffer::Rig::Mcp::Server]
+  def register_mcp_servers: (Array[Riffer::Rig::Registrar] registrars) -> Hash[String, Riffer::Rig::Mcp::Server]
+
+  # @rbs name: String
+  # @rbs declaration: Riffer::Rig::Mcp::Declaration
+  # @rbs return: Riffer::Rig::Mcp::Server?
+  def register_mcp_server: (String name, Riffer::Rig::Mcp::Declaration declaration) -> Riffer::Rig::Mcp::Server?
+
+  # A retired registration was replaced under the same name, by another
+  # Runtime or a later declaration, and is no longer this Runtime's to remove.
+  # @rbs servers: Hash[String, Riffer::Rig::Mcp::Server]
+  # @rbs return: void
+  def unregister_mcp_servers: (Hash[String, Riffer::Rig::Mcp::Server] servers) -> void
 
   # @rbs registered: Array[singleton(Riffer::Tool)]
   # @rbs allowlist: Array[String]?