riffer-rig 0.6.0 → 0.7.0

data/lib/riffer/rig/prompts/agents_md.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Riffer::Rig::Prompts::AgentsMd
+  extend self
+
+  FRAMING = 'The user wrote the following instructions in AGENTS.md files, ordered from the most general to ' \
+            'the one closest to the working directory. Follow them; where they conflict with the guidance ' \
+            'above, they take precedence, and where they conflict with each other, the later file wins.' #: String
+
+  # @rbs cwd: String
+  # @rbs return: Array[String]
+  def paths(cwd)
+    global  = File.join(Dir.home, '.riffer', 'AGENTS.md')
+    project = Riffer::Rig::Directories.ancestors(File.expand_path(cwd)).reverse.map { |dir| File.join(dir, 'AGENTS.md') }
+    [global, *project].uniq.select { |path| File.file?(path) }
+  end
+
+  # @rbs cwd: String
+  # @rbs return: String?
+  def section(cwd)
+    blocks = paths(cwd).map { |path| block(path) }
+    [FRAMING, *blocks].join("\n\n") unless blocks.empty?
+  end
+
+  private
+
+  # @rbs path: String
+  # @rbs return: String
+  def block(path)
+    "<project_instructions path=\"#{path}\">\n#{File.read(path)}\n</project_instructions>"
+  end
+end

data/lib/riffer/rig/prompts.rb

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

data/lib/riffer/rig/registrar.rb

@@ -1,19 +1,55 @@
 # frozen_string_literal: true
 
 class Riffer::Rig::Registrar
-  # @rbs @tools: Array[singleton(Riffer::Tool)]
+  class NameCollisionError < StandardError; end
+
+  CORE_SETTINGS_KEYS = %w[model reasoning models reload extensions sessions providers tools].freeze #: Array[String]
+
+  EVENTS = %i[
+    session_start session_end
+    before_prompt before_tool_call before_request
+    after_tool_call after_response turn_end
+    stream
+  ].freeze #: Array[Symbol]
+
+  # @rbs @tools: Hash[String, singleton(Riffer::Tool)]
   # @rbs @prompts: Hash[Symbol, ^(Riffer::Rig::Runtime) -> String?]
+  # @rbs @commands: Hash[String, Riffer::Rig::Command]
+  # @rbs @skill_sources: Array[^(Riffer::Rig::Runtime) -> Riffer::Skills::Backend]
+  # @rbs @declared_settings: Hash[Symbol, untyped]
+  # @rbs @given_settings: Hash[Symbol, untyped]
+  # @rbs @mcp_servers: Hash[String, Riffer::Rig::Mcp::Declaration]
+  # @rbs @hooks: Hash[Symbol, Array[^(Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base) -> untyped]]
 
+  # @dynamic extension
+  attr_reader :extension #: String
+
+  # @rbs extension: String
+  # @rbs settings: Hash[Symbol, untyped]
   # @rbs return: void
-  def initialize
-    @tools = []
+  def initialize(extension, settings = {})
+    @extension = extension
+    @tools = {}
     @prompts = {}
+    @commands = {}
+    @skill_sources = []
+    @declared_settings = {}
+    @given_settings = settings
+    @mcp_servers = {}
+    @hooks = EVENTS.to_h { |event| [event, []] }
+  end
+
+  # @rbs return: NameCollisionError?
+  def collision
+    return unless CORE_SETTINGS_KEYS.include?(@extension)
+
+    NameCollisionError.new("extension name #{@extension} collides with a core settings key")
   end
 
   # @rbs klass: singleton(Riffer::Tool)
   # @rbs return: void
   def tool(klass)
-    @tools << klass
+    @tools[klass.identifier] = klass
   end
 
   # @rbs name: Symbol
@@ -23,7 +59,46 @@ class Riffer::Rig::Registrar
     @prompts[name] = block
   end
 
-  # @rbs return: Array[singleton(Riffer::Tool)]
+  # @rbs name: String
+  # @rbs description: String
+  # @rbs &block: (Riffer::Rig::Command::Context) -> void
+  # @rbs return: void
+  def command(name, description:, &)
+    @commands[name] = Riffer::Rig::Command.new(name, description: description, extension: @extension, &)
+  end
+
+  # @rbs &block: (Riffer::Rig::Runtime) -> Riffer::Skills::Backend
+  # @rbs return: void
+  def skills(&block)
+    @skill_sources << block
+  end
+
+  # @rbs key: Symbol
+  # @rbs default: untyped
+  # @rbs return: void
+  def setting(key, default:)
+    @declared_settings[key] = default
+  end
+
+  # @rbs name: String
+  # @rbs url: String
+  # @rbs headers: Hash[String, String]
+  # @rbs return: void
+  def mcp(name, url:, headers: {})
+    @mcp_servers[name] = Riffer::Rig::Mcp::Declaration.new(url: url, headers: headers)
+  end
+
+  # @rbs event: Symbol
+  # @rbs &block: (Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base) -> untyped
+  # @rbs return: void
+  def on(event, &block)
+    hooks = @hooks.fetch(event) do
+      raise Riffer::ArgumentError, "unknown event #{event.inspect}; expected one of #{EVENTS.join(', ')}"
+    end
+    hooks << block
+  end
+
+  # @rbs return: Hash[String, singleton(Riffer::Tool)]
   def tools
     @tools.dup
   end
@@ -32,4 +107,44 @@ class Riffer::Rig::Registrar
   def prompts
     @prompts.dup
   end
+
+  # @rbs return: Hash[String, Riffer::Rig::Command]
+  def commands
+    @commands.dup
+  end
+
+  # @rbs return: Array[^(Riffer::Rig::Runtime) -> Riffer::Skills::Backend]
+  def skill_sources
+    @skill_sources.dup
+  end
+
+  # @rbs return: Hash[Symbol, untyped]
+  def settings
+    @declared_settings.merge(@given_settings)
+  end
+
+  # @rbs return: Hash[Symbol, untyped]
+  def declared_settings
+    @declared_settings.dup
+  end
+
+  # @rbs return: Hash[String, Riffer::Rig::Mcp::Declaration]
+  def mcp_servers
+    @mcp_servers.dup
+  end
+
+  # @rbs return: Array[String]
+  def registrations
+    [
+      *@tools.keys.map { |identifier| "tool #{identifier}" },
+      *@prompts.keys.map { |name| "prompt section #{name}" },
+      *@commands.keys.map { |name| "command #{name}" },
+      *@mcp_servers.keys.map { |name| "MCP server #{name}" }
+    ]
+  end
+
+  # @rbs return: Hash[Symbol, Array[^(Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base) -> untyped]]
+  def hooks
+    @hooks.transform_values(&:dup)
+  end
 end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Runtime::Blocked
+  # @dynamic reason
+  attr_reader :reason #: String
+
+  # @rbs reason: String
+  # @rbs return: void
+  def initialize(reason)
+    @reason = reason
+    freeze
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Runtime::Hooks
+  # @rbs @hooks: Hash[Symbol, Array[^(Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base) -> untyped]]
+  # @rbs @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(hooks, host)
+    @hooks = hooks
+    @host = host
+  end
+
+  # @rbs name: Symbol
+  # @rbs event: Riffer::Rig::Events::_Event | ::Riffer::StreamEvents::Base
+  # @rbs return: void
+  def observe(name, event)
+    @hooks.fetch(name).each { |hook| call(name, hook, event) }
+  end
+
+  # @rbs text: String
+  # @rbs return: String | Riffer::Rig::Runtime::Blocked
+  def before_prompt(text)
+    accepts = ->(value) { value.is_a?(String) }
+    announce(veto(:before_prompt, text, accepts) { |current| Riffer::Rig::Events::BeforePrompt.new(current) })
+  end
+
+  # @rbs tool: String
+  # @rbs args: Hash[Symbol, untyped]
+  # @rbs return: Hash[Symbol, untyped] | Riffer::Rig::Runtime::Blocked
+  def before_tool_call(tool, args)
+    accepts = ->(value) { value.is_a?(Hash) }
+    veto(:before_tool_call, args, accepts) { |current| Riffer::Rig::Events::BeforeToolCall.new(tool, current) }
+  end
+
+  # @rbs messages: Array[::Riffer::Messages::Base]
+  # @rbs return: Array[::Riffer::Messages::Base] | Riffer::Rig::Runtime::Blocked
+  def before_request(messages)
+    accepts = ->(value) { value.is_a?(Array) && value.all?(::Riffer::Messages::Base) }
+    announce(veto(:before_request, messages, accepts) { |current| Riffer::Rig::Events::BeforeRequest.new(current) })
+  end
+
+  private
+
+  # @rbs name: Symbol
+  # @rbs payload: untyped
+  # @rbs accepts: ^(untyped) -> bool
+  # @rbs &: (untyped) -> Riffer::Rig::Events::_Event
+  # @rbs return: untyped
+  def veto(name, payload, accepts)
+    @hooks.fetch(name).reduce(payload) do |current, hook|
+      result = call(name, hook, yield(current))
+      verdict, reason = result
+      break Riffer::Rig::Runtime::Blocked.new(reason&.to_s || "blocked by a #{name} hook") if verdict == :block
+
+      accepts.call(result) ? result : current
+    end
+  end
+
+  # @rbs outcome: untyped
+  # @rbs return: untyped
+  def announce(outcome)
+    @host.notify(outcome.reason, level: :warning) if outcome.is_a?(Riffer::Rig::Runtime::Blocked)
+    outcome
+  end
+
+  # @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(name, hook, event)
+    hook.call(event)
+  rescue StandardError => e
+    @host.notify("#{name} hook failed: #{e.message}", level: :error)
+    nil
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# 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
+  # @rbs @hooks: Riffer::Rig::Runtime::Hooks
+
+  # @rbs hooks: Riffer::Rig::Runtime::Hooks
+  # @rbs return: void
+  def initialize(hooks:)
+    super()
+    @hooks = hooks
+  end
+
+  # @rbs messages: Array[Riffer::Messages::Base]
+  # @rbs context: untyped
+  # @rbs return: Riffer::Guardrails::Result
+  def process_input(messages, context:)
+    verdict = @hooks.before_request(messages)
+    return block(verdict.reason) if verdict.is_a?(Riffer::Rig::Runtime::Blocked)
+
+    verdict.equal?(messages) ? pass(messages) : transform(verdict.dup)
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'json'
+
+class Riffer::Rig::Runtime::ToolRuntime < Riffer::Tools::Runtime
+  # @rbs @hooks: Riffer::Rig::Runtime::Hooks
+
+  # @rbs hooks: Riffer::Rig::Runtime::Hooks
+  # @rbs return: void
+  def initialize(hooks)
+    # Sequential, so hooks never run concurrently.
+    super(runner: Riffer::Runner::Sequential.new)
+    @hooks = hooks
+  end
+
+  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(tool_call, tools:, context:, assistant_message: nil)
+    args = parse_arguments(tool_call.arguments)
+    return super unless args.is_a?(Hash)
+
+    verdict = @hooks.before_tool_call(tool_call.name, args)
+    return Riffer::Tools::Response.error(verdict.reason, type: :blocked) if verdict.is_a?(Riffer::Rig::Runtime::Blocked)
+
+    call = verdict.equal?(args) ? tool_call : replace_arguments(tool_call, verdict)
+    response = super(call, tools: tools, context: context, assistant_message: assistant_message)
+    @hooks.observe(:after_tool_call, Riffer::Rig::Events::AfterToolCall.new(tool_call.name, verdict, response))
+    response
+  rescue JSON::ParserError
+    super
+  end
+
+  # @rbs tool_call: Riffer::Messages::Assistant::ToolCall
+  # @rbs args: Hash[Symbol, untyped]
+  # @rbs return: Riffer::Messages::Assistant::ToolCall
+  def replace_arguments(tool_call, args)
+    Riffer::Messages::Assistant::ToolCall.new(call_id: tool_call.call_id, name: tool_call.name, arguments: args.to_json)
+  end
+end