rubino-agent 0.3.0

data/lib/rubino/jobs/scheduler.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "rufus-scheduler"
+
+module Rubino
+  module Jobs
+    # In-process cron scheduler wrapping rufus-scheduler. Owns one rufus
+    # instance per process and is exposed as a process-wide singleton via
+    # +Scheduler.instance+; +load_all!+ is called once at server boot to
+    # register every enabled job. Resolves jobs from CronJobRepository,
+    # fires runs through Run::Executor, dispatches webhooks via
+    # WebhookDelivery.
+    #
+    # Because rufus lives in-process, this scheduler does NOT survive a
+    # multi-process scale-out: each worker would run every cron tick.
+    #
+    # Lifecycle:
+    #   scheduler = Scheduler.new
+    #   scheduler.load_all!          # on server boot
+    #   scheduler.schedule(job)      # after POST /v1/jobs
+    #   scheduler.unschedule(job_id) # after DELETE
+    #   scheduler.trigger(job_id)    # one-shot
+    #   scheduler.shutdown!
+    class Scheduler
+      # Per-process scheduler instance. The server boots one of these once;
+      # tests can inject their own via #instance= or call #reset! between examples.
+      class << self
+        def instance
+          @instance ||= new
+        end
+
+        attr_writer :instance
+
+        def reset!
+          @instance&.shutdown!
+        rescue StandardError
+          # best-effort during teardown
+        ensure
+          @instance = nil
+        end
+      end
+
+      def initialize(rufus: nil, cron_job_repository: nil, run_repository: nil, session_repository: nil, executor: nil,
+                     webhook: nil, logger: nil)
+        @rufus = rufus || Rufus::Scheduler.new
+        @cron_repo = cron_job_repository || CronJobRepository.new
+        @run_repo = run_repository || ::Rubino::Run::Repository.new
+        @session_repo = session_repository || ::Rubino::Session::Repository.new
+        @executor = executor || ::Rubino::Run::Executor.new
+        @webhook = webhook || WebhookDelivery.new
+        @logger = logger || Rubino.logger
+        @handles = {}
+        @mutex = Mutex.new
+      end
+
+      def load_all!
+        @cron_repo.list(include_disabled: false).each { |job| schedule(job) }
+      end
+
+      # Replays any +webhook_deliveries+ row left in +pending+ by a prior
+      # process. Boot-only hook; safe to call multiple times because each
+      # row's request_id is the dedup key.
+      def resume_pending_webhooks!
+        @webhook.resume_pending!
+      end
+
+      def schedule(job)
+        return unless job[:enabled]
+
+        unschedule(job[:id])
+        handle = @rufus.cron(job[:schedule]) { fire(job[:id]) }
+        @mutex.synchronize { @handles[job[:id]] = handle }
+      rescue ArgumentError => e
+        # A persisted row with a cron string rufus/fugit cannot parse (e.g.
+        # written by an older build before the API validated schedules, #164).
+        # Skip it and keep going: one poison row must never abort load_all!
+        # and take down server boot.
+        @logger.warn(event: "cron.invalid_schedule", job_id: job[:id], schedule: job[:schedule], error: e.message)
+        nil
+      end
+
+      def unschedule(job_id)
+        handle = @mutex.synchronize { @handles.delete(job_id) }
+        @rufus.unschedule(handle) if handle
+      end
+
+      # Run the job now without waiting for the next cron tick.
+      # @return [Hash, nil] the created run row, or nil on failure / unknown job.
+      def trigger(job_id)
+        fire(job_id)
+      end
+
+      def shutdown!
+        @rufus.shutdown
+        @mutex.synchronize { @handles.clear }
+      end
+
+      # Number of currently-registered cron handles. Reads @handles under
+      # @mutex so callers (e.g. the health probe) never touch private state.
+      def scheduled_count
+        @mutex.synchronize { @handles.size }
+      end
+
+      private
+
+      # Builds session + run for a cron tick, stamps cron_job_id on the run,
+      # and hands off to Executor with a webhook-delivery callback.
+      def fire(job_id)
+        job = @cron_repo.find(job_id)
+        return unless job
+
+        session = @session_repo.create(source: "cron", model: job[:model], provider: job[:provider], title: job[:name])
+        run = @run_repo.create(session_id: session[:id], input_text: job[:prompt], model: job[:model],
+                               provider: job[:provider], cron_job_id: job_id)
+        @cron_repo.record_run(job_id, run_id: run[:id])
+
+        @executor.start(run, on_complete: ->(payload) { deliver_if_needed(job, payload) })
+        Metrics.counter(:cron_fires_total, job: job[:name], outcome: "ok").increment
+        @logger.info(event: "cron.fired", job_id: job_id, run_id: run[:id], session_id: session[:id])
+        run
+      rescue StandardError => e
+        Metrics.counter(:cron_fires_total, job: job&.dig(:name) || "unknown", outcome: "error").increment
+        @logger.error(event: "cron.fire_failed", job_id: job_id, error: e.class.name, message: e.message)
+        nil
+      end
+
+      def deliver_if_needed(job, payload)
+        return unless job[:deliver] == "webhook"
+
+        @webhook.deliver(
+          payload.merge(job_id: job[:id], job_name: job[:name]),
+          job_id: job[:id],
+          run_id: payload[:run_id]
+        )
+      end
+    end
+  end
+end

data/lib/rubino/jobs/webhook_delivery.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+require "securerandom"
+require "digest"
+require "openssl"
+require "time"
+
+module Rubino
+  module Jobs
+    # POSTs cron-job results to a configured webhook URL with idempotency
+    # and persistence guarantees.
+    #
+    # Every #deliver call is recorded as a row in +webhook_deliveries+ before
+    # the HTTP request fires; the row's +request_id+ doubles as the
+    # +X-Rubino-Delivery-Id+ header receivers MUST treat as the dedup
+    # key. The body is signed with HMAC-SHA256 under +RUBINO_WEBHOOK_SECRET+
+    # (or a per-job secret passed via +secret:+) and sent as
+    # +X-Rubino-Signature+. When no secret is configured the header is
+    # omitted; the receiver is then on its own.
+    #
+    # Failures retry up to 3 attempts total with exponential backoff
+    # (5s, 30s, 5min) using lightweight Thread.new sleeps. The current
+    # trade-off is that an agent crash mid-backoff loses the in-flight
+    # retry timer, but the persisted row stays +pending+ and #resume_pending!
+    # at boot picks it up. A real job queue is overkill for the expected
+    # webhook volume; revisit if backlog grows.
+    #
+    # URL resolution: constructor arg > +RUBINO_WEBHOOK_URL+ env. There
+    # is no per-job override yet (alpha).
+    class WebhookDelivery
+      DEFAULT_TIMEOUT = 10
+      # Backoff schedule (seconds) BEFORE attempt N+1. attempt_count after a
+      # successful schedule is N; index into BACKOFF_SCHEDULE[N-1] for the
+      # delay before the next attempt. After 3 entries we give up.
+      BACKOFF_SCHEDULE = [5, 30, 300].freeze
+      MAX_ATTEMPTS = 3
+      RESUME_SCAN_LIMIT = 1000
+
+      def initialize(url: nil, logger: nil, timeout: DEFAULT_TIMEOUT, conn: nil, db: nil, secret: nil, clock: nil,
+                     sleeper: nil)
+        @url = url || ENV.fetch("RUBINO_WEBHOOK_URL", nil)
+        @logger = logger || Rubino.logger
+        @conn = conn || build_conn(timeout)
+        @db = db
+        @secret = secret || ENV.fetch("RUBINO_WEBHOOK_SECRET", nil)
+        @clock = clock || -> { Time.now.utc }
+        # Tests inject a synchronous sleeper so backoff doesn't burn wall time.
+        @sleeper = sleeper || ->(s) { sleep(s) }
+      end
+
+      # @param payload [Hash] JSON-serialisable body POSTed as-is.
+      # @param job_id [String, nil] persisted on the delivery row.
+      # @param run_id [String, nil] persisted on the delivery row.
+      # @return [Boolean] true if delivered on this call, false otherwise.
+      def deliver(payload, job_id: nil, run_id: nil)
+        return false if @url.nil? || @url.empty?
+
+        body = JSON.generate(payload)
+        row_id = persist_pending(body: body, job_id: job_id, run_id: run_id)
+        attempt_with_retries(row_id: row_id, body: body)
+      end
+
+      # Resume hook called at agent boot. Scans up to RESUME_SCAN_LIMIT
+      # pending rows whose scheduled_at has passed and replays them in a
+      # background thread. Cap exists to avoid replay storms after a long
+      # outage — older entries stay in the table for ops to inspect.
+      def resume_pending!
+        return 0 unless db
+
+        now = @clock.call.iso8601
+        rows = db[:webhook_deliveries]
+               .where(status: "pending")
+               .where { scheduled_at <= now }
+               .order(:scheduled_at)
+               .limit(RESUME_SCAN_LIMIT)
+               .all
+        rows.each do |row|
+          Thread.new { attempt_with_retries(row_id: row[:id], body: row[:payload_json]) }
+        end
+        rows.size
+      end
+
+      private
+
+      def attempt_with_retries(row_id:, body:)
+        row = db[:webhook_deliveries].where(id: row_id).first if db && row_id
+        attempts_done = row ? row[:attempt_count] : 0
+        # Without a persisted row we can't ack/idempotently dedupe retries,
+        # so we degrade to a single attempt to preserve the pre-persistence
+        # contract (one POST, return success bool).
+        max = row_id ? MAX_ATTEMPTS : 1
+
+        loop do
+          attempts_done += 1
+          ok = post_once(row_id: row_id, body: body, attempt_count: attempts_done)
+          return true if ok
+
+          if attempts_done >= max
+            mark_dead(row_id) if row_id
+            return false
+          end
+
+          @sleeper.call(BACKOFF_SCHEDULE[attempts_done - 1])
+        end
+      end
+
+      def post_once(row_id:, body:, attempt_count:)
+        request_id = row_request_id(row_id) || SecureRandom.uuid
+        response = @conn.post(@url) do |req|
+          req.headers["content-type"] = "application/json"
+          req.headers["X-Rubino-Delivery-Id"] = request_id
+          req.headers["X-Rubino-Signature"] = "sha256=#{sign(body)}" if @secret && !@secret.empty?
+          req.body = body
+        end
+        success = response.success?
+        outcome = success ? "ok" : "http_error"
+        Metrics.counter(:webhook_deliveries_total, outcome: outcome).increment
+        if success
+          mark_delivered(row_id, attempt_count: attempt_count)
+          @logger.info(event: "webhook.delivered", url: @url, status: response.status, request_id: request_id)
+        else
+          mark_failed(row_id, attempt_count: attempt_count, error: "http_#{response.status}")
+          @logger.error(event: "webhook.http_error", url: @url, status: response.status, request_id: request_id)
+        end
+        success
+      rescue Faraday::Error => e
+        Metrics.counter(:webhook_deliveries_total, outcome: "error").increment
+        mark_failed(row_id, attempt_count: attempt_count, error: "#{e.class.name}: #{e.message}")
+        @logger.error(event: "webhook.failed", url: @url, error: e.class.name, message: e.message)
+        false
+      end
+
+      def sign(body)
+        OpenSSL::HMAC.hexdigest("SHA256", @secret, body)
+      end
+
+      def persist_pending(body:, job_id:, run_id:)
+        return nil unless db
+
+        now = @clock.call.iso8601
+        id = SecureRandom.uuid
+        db[:webhook_deliveries].insert(
+          id: id,
+          job_id: job_id,
+          run_id: run_id,
+          target_url: @url,
+          request_id: SecureRandom.uuid,
+          payload_sha256: Digest::SHA256.hexdigest(body),
+          payload_json: body,
+          attempt_count: 0,
+          status: "pending",
+          scheduled_at: now,
+          created_at: now,
+          updated_at: now
+        )
+        id
+      rescue Sequel::DatabaseError, Sequel::Error => e
+        # No webhook_deliveries table → fall back to fire-and-forget so the
+        # legacy contract (deliver returns true on 2xx, no persistence) still
+        # works in installs that have not migrated yet.
+        @logger.warn(event: "webhook.persist_skipped", error: e.class.name, message: e.message)
+        nil
+      end
+
+      def row_request_id(row_id)
+        return nil unless db && row_id
+
+        db[:webhook_deliveries].where(id: row_id).get(:request_id)
+      end
+
+      def mark_delivered(row_id, attempt_count:)
+        return unless db && row_id
+
+        now = @clock.call.iso8601
+        db[:webhook_deliveries].where(id: row_id).update(
+          status: "delivered",
+          attempt_count: attempt_count,
+          delivered_at: now,
+          updated_at: now
+        )
+      end
+
+      def mark_failed(row_id, attempt_count:, error:)
+        return unless db && row_id
+
+        db[:webhook_deliveries].where(id: row_id).update(
+          status: "failed",
+          attempt_count: attempt_count,
+          last_error: error,
+          updated_at: @clock.call.iso8601
+        )
+      end
+
+      def mark_dead(row_id)
+        return unless db && row_id
+
+        db[:webhook_deliveries].where(id: row_id).update(
+          status: "dead",
+          updated_at: @clock.call.iso8601
+        )
+      end
+
+      def db
+        return @db if defined?(@db_resolved) && @db_resolved
+
+        @db_resolved = true
+        @db ||= begin
+          Rubino.database.db
+        rescue StandardError
+          nil
+        end
+      end
+
+      def build_conn(timeout)
+        Faraday.new do |f|
+          f.options.timeout = timeout
+          f.adapter Faraday.default_adapter
+        end
+      end
+    end
+  end
+end

data/lib/rubino/jobs/worker.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Jobs
+    # Background worker that polls the job queue and executes available jobs.
+    # Runs in a loop until interrupted.
+    class Worker
+      def initialize(config: nil)
+        @config = config || Rubino.configuration
+        @poll_interval = @config.jobs_poll_interval
+        @running = false
+        @worker_id = "worker-#{Process.pid}-#{Thread.current.object_id}"
+      end
+
+      # Starts the worker loop
+      def start
+        @running = true
+        setup_signal_handlers
+
+        while @running
+          processed = process_batch
+          sleep(@poll_interval) if processed.zero?
+        end
+      end
+
+      # Stops the worker gracefully
+      def stop
+        @running = false
+      end
+
+      def running?
+        @running
+      end
+
+      private
+
+      def process_batch
+        queue = Queue.new
+        processed = 0
+
+        loop do
+          job = queue.dequeue(worker_id: @worker_id)
+          break unless job
+
+          runner = Runner.new
+          runner.run_job(job[:id])
+          processed += 1
+        end
+
+        processed
+      end
+
+      def setup_signal_handlers
+        trap("INT") { stop }
+        trap("TERM") { stop }
+      end
+    end
+  end
+end

data/lib/rubino/llm/adapter_factory.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "ruby_llm_adapter"
+require_relative "fake_provider"
+require_relative "provider_resolver"
+
+module Rubino
+  module LLM
+    # Single seam where Lifecycle (and tests) decide which LLM adapter to
+    # instantiate. Keeps the "fake provider" branch out of RubyLLMAdapter
+    # so the real adapter stays focused on ruby_llm wiring.
+    #
+    # Routing:
+    #   - explicit `provider: "fake"`        → FakeProvider
+    #   - model_id matches the "fake" regex  → FakeProvider
+    #   - everything else                    → RubyLLMAdapter
+    class AdapterFactory
+      def self.build(model_id: nil, provider: nil, config: nil, ui: nil, event_bus: nil,
+                     tool_executor: nil, cancel_token: nil, isolate_config: false)
+        # Resolve the provider ONCE here (the single seam) and pass the concrete
+        # value down. The caller's provider may be nil/"auto"; fall back to the
+        # config default and let ProviderResolver interpret "auto" (including the
+        # Bedrock-bearer override) in one place. RubyLLMAdapter then trusts the
+        # value it receives and no longer re-runs resolution.
+        explicit = provider
+        explicit = config&.model_provider if explicit.nil?
+        resolved = ProviderResolver.resolve(model_id, explicit_provider: explicit)
+
+        klass = resolved == "fake" ? FakeProvider : RubyLLMAdapter
+        kwargs = {
+          model_id: model_id,
+          provider: resolved,
+          config: config,
+          ui: ui,
+          event_bus: event_bus,
+          tool_executor: tool_executor,
+          cancel_token: cancel_token
+        }
+        # SLICE-7: only the real adapter understands per-call config isolation
+        # (RubyLLM::Context). FakeProvider has no global to protect, so it never
+        # receives the flag — keeps its constructor signature untouched.
+        kwargs[:isolate_config] = isolate_config if klass == RubyLLMAdapter
+        klass.new(**kwargs)
+      end
+    end
+  end
+end

data/lib/rubino/llm/adapter_response.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Rubino
+  module LLM
+    # Structured response returned by all LLM adapters — the normalized shape the
+    # conversation loop and its recovery layers read, never ruby_llm internals.
+    # This is the Ruby side of the reference normalize_response seam:
+    # the loop branches only on content / thinking /
+    # tool_calls / stop_reason / interrupted?, never on provider types.
+    #
+    # All recovery-layer fields (thinking, stop_reason, usage, raw) default
+    # nil-safely so existing callers that construct only the core fields keep
+    # working unchanged.
+    class AdapterResponse
+      attr_reader :content, :tool_calls, :input_tokens, :output_tokens, :model_id,
+                  :thinking, :stop_reason, :raw
+
+      def initialize(content:, tool_calls:, input_tokens:, output_tokens:, model_id:,
+                     interrupted: false, thinking: nil, stop_reason: nil, raw: nil)
+        @content       = content
+        @tool_calls    = tool_calls || []
+        @input_tokens  = input_tokens || 0
+        @output_tokens = output_tokens || 0
+        @model_id      = model_id
+        # True when this response holds only a buffered partial from a stream that
+        # was cut before a clean completion (no finish_reason / [DONE]). The Loop
+        # must treat it as a turn failure, never as a final answer.
+        @interrupted   = interrupted
+        # Reasoning text/summary if the provider surfaced it (think blocks are
+        # already split out of +content+). nil when not surfaced on this path.
+        @thinking      = thinking
+        # Normalized finish reason: :stop | :length | :tool_calls | nil. Drives
+        # truncation continuation (later slice). Left nil where unreachable —
+        # never fabricated.
+        @stop_reason   = stop_reason
+        # Escape hatch to the underlying provider response. The loop must NOT
+        # branch on it; it exists for diagnostics / later-slice needs only.
+        @raw           = raw
+      end
+
+      # Token usage as a nil-safe Hash, the shape the recovery layers read.
+      def usage
+        { input_tokens: @input_tokens, output_tokens: @output_tokens }
+      end
+
+      # The stream was truncated; +content+ is an incomplete partial, not a
+      # finished turn. See AdapterResponse#initialize and Loop#run.
+      def interrupted?
+        @interrupted
+      end
+
+      def has_tool_calls?
+        !@tool_calls.empty?
+      end
+
+      def text_only?
+        !has_tool_calls? && !@content.nil? && !@content.empty?
+      end
+
+      def total_tokens
+        @input_tokens + @output_tokens
+      end
+    end
+  end
+end

data/lib/rubino/llm/auxiliary_client.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "adapter_factory"
+
+module Rubino
+  module LLM
+    # Routes per-task auxiliary LLM calls (vision, compression, approval, …)
+    # through AdapterFactory based on the `auxiliary.<task>` config block.
+    #
+    # Pattern lifted from the reference `call_llm(task: …)`: instead of a
+    # single "secondary model" slot, each task has its own block with
+    # provider/model/base_url/timeout independently overridable. The
+    # `provider: "main"` sentinel reuses the primary's provider so simple
+    # setups don't repeat themselves.
+    #
+    # Returns an AdapterResponse — the caller reads `.content` for text-only
+    # delegations (vision tool) or inspects `.tool_calls` if the aux model
+    # itself can use tools (compression doesn't, but we don't preclude it).
+    class AuxiliaryClient
+      def initialize(config: Rubino.configuration)
+        @config = config
+      end
+
+      def call(task:, messages:, **opts)
+        cfg = @config.auxiliary_config(task)
+        raise ArgumentError, "No auxiliary config for task=#{task}" if cfg.empty?
+
+        adapter = build_adapter(cfg)
+        adapter.chat(messages: messages, **opts.slice(:tools, :response_format, :image_paths))
+      end
+
+      private
+
+      def build_adapter(cfg)
+        provider = cfg["provider"].to_s
+        resolved_provider = provider.empty? || provider == "main" ? @config.model_provider : provider
+
+        AdapterFactory.build(
+          model_id: cfg["model"].to_s.empty? ? @config.model_default : cfg["model"],
+          provider: resolved_provider,
+          config: build_overlay_config(cfg, resolved_provider)
+        )
+      end
+
+      # When the aux task pins a base_url, push it into a shallow config
+      # overlay so the adapter sees it. We don't mutate the real configuration
+      # — provider_config is read by RubyLLMAdapter.configure_ruby_llm! on
+      # construction, so a transient overlay is enough.
+      def build_overlay_config(cfg, resolved_provider)
+        base_url = cfg["base_url"].to_s
+        return @config if base_url.empty?
+
+        raw = Marshal.load(Marshal.dump(@config.raw))
+        raw["providers"] ||= {}
+        raw["providers"][resolved_provider] ||= {}
+        raw["providers"][resolved_provider]["base_url"] = base_url
+        Config::Configuration.new(raw: raw)
+      end
+    end
+  end
+end