rubino-agent 0.3.0

data/lib/rubino/agent/truncation_continuation.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Agent
+    # Stitches a response truncated by the output-token limit back together.
+    #
+    # Faithful port of the reference finish_reason=="length" continuation
+    # (the per-turn loop plus the boosted output budget). When a model call comes back with
+    # stop_reason==:length and NO tool calls, the answer was cut mid-sentence by
+    # max_tokens. Rather than surface the fragment as the final turn, we:
+    #
+    #   1. keep the interim partial as an assistant message in the history,
+    #   2. append a "[System: …continue exactly where you left off…]" user nudge,
+    #   3. re-issue the SAME request with a progressively BOOSTED output budget
+    #      (base × (retry+1), capped at 32 768), and
+    #   4. concatenate the partial pieces into the final answer.
+    #
+    # Up to MAX_RETRIES (3, matching the reference `length_continue_retries < 3`)
+    # continuations are attempted; if it is still truncated after that, the
+    # stitched-together partial is returned as-is (the reference returns it with
+    # partial=True / "remained truncated after 3 continuation attempts").
+    #
+    # The class is transport-agnostic: it issues each continuation through a
+    # +boundary+ callable (`boundary.call(request) -> AdapterResponse`) so it
+    # unit-tests against fixtures with no network. The caller (Loop) builds the
+    # first request and passes the first response in.
+    class TruncationContinuation
+      # The `length_continue_retries < 3` ceiling.
+      MAX_RETRIES = 3
+      # Fallback base when agent.max_tokens is unset.
+      DEFAULT_BASE = 4096
+      # Boost cap.
+      BOOST_CAP = 32_768
+
+      # The continuation nudge for an ordinary output-length truncation
+      # (the `else` branch of the continuation-prompt builder). The
+      # partial-stream-stub variants don't apply here — a dropped stream surfaces
+      # as AdapterResponse#interrupted?, handled separately by the Loop.
+      CONTINUATION_NUDGE =
+        "[System: Your previous response was truncated by the output " \
+        "length limit. Continue exactly where you left off. Do not " \
+        "restart or repeat prior text. Finish the answer directly.]"
+
+      # +boundary+    : responds to #call(request, &block) → AdapterResponse.
+      # +base_tokens+ : the configured agent.max_tokens (nil ⇒ DEFAULT_BASE).
+      # +ui+          : optional, gets #note on each continuation attempt.
+      def initialize(boundary:, base_tokens: nil, ui: nil)
+        @boundary    = boundary
+        @base_tokens = base_tokens
+        @ui          = ui
+      end
+
+      # True iff +response+ is a length-truncated turn that warrants continuation:
+      # stopped on the output limit AND carries no tool calls (a truncated
+      # tool-call turn is a different repair path — out of scope here, as in
+      # the reference's separate truncated_tool_call branch).
+      def applicable?(response)
+        response&.stop_reason == :length && !response.has_tool_calls?
+      end
+
+      # Drive the continuation loop. +request+ is the LLM::Request that produced
+      # +first_response+; +first_response+ is the truncated AdapterResponse.
+      # Re-issues with a boosted budget until the model stops cleanly or
+      # MAX_RETRIES is hit, then returns ONE AdapterResponse whose content is the
+      # stitched-together answer. A passed block forwards stream chunks straight
+      # through to the boundary on each continuation call.
+      #
+      # If +first_response+ is not applicable? this returns it untouched, so the
+      # Loop can call #continue unconditionally.
+      def continue(request, first_response, &)
+        return first_response unless applicable?(first_response)
+
+        parts    = collect_part(first_response)
+        response = first_response
+        retries  = 0
+
+        while applicable?(response) && retries < MAX_RETRIES
+          retries += 1
+          @ui&.note("↻ Requesting continuation (#{retries}/#{MAX_RETRIES})…")
+
+          # Keep the interim partial in history, then nudge the model to resume.
+          messages = request.messages.dup
+          messages << { role: "assistant", content: response.content.to_s }
+          messages << { role: "user", content: CONTINUATION_NUDGE }
+
+          request  = reissue(request, messages, retries)
+          response = @boundary.call(request, &)
+          parts.concat(collect_part(response))
+        end
+
+        stitch(response, parts)
+      end
+
+      private
+
+      # Build the next request: same shape, continued history, boosted budget.
+      def reissue(request, messages, retries)
+        LLM::Request.new(
+          messages: messages,
+          tools: request.tools,
+          temperature: request.temperature,
+          max_tokens: boosted_max_tokens(retries),
+          thinking: request.thinking,
+          prefill: request.prefill,
+          image_paths: request.image_paths,
+          stream: request.stream?
+        )
+      end
+
+      # Progressive boost: base × (retries+1), capped. On the
+      # first continuation (retries==1) the budget is 2× base, then 3×, …
+      def boosted_max_tokens(retries)
+        base = @base_tokens && @base_tokens.positive? ? @base_tokens : DEFAULT_BASE
+        [base * (retries + 1), BOOST_CAP].min
+      end
+
+      def collect_part(response)
+        text = response.content.to_s
+        text.empty? ? [] : [text]
+      end
+
+      # Final stitched response: concatenated content, carrying the LAST call's
+      # token usage / model id / stop_reason (the spend already happened, and the
+      # final stop_reason tells the caller whether it ever completed cleanly).
+      def stitch(last_response, parts)
+        LLM::AdapterResponse.new(
+          content: parts.join,
+          tool_calls: last_response.tool_calls,
+          input_tokens: last_response.input_tokens,
+          output_tokens: last_response.output_tokens,
+          model_id: last_response.model_id,
+          stop_reason: last_response.stop_reason
+        )
+      end
+    end
+  end
+end

data/lib/rubino/api/middleware/auth.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "rack/utils"
+
+module Rubino
+  module API
+    module Middleware
+      # Bearer-token auth middleware. Sits between JsonParser and the router so
+      # unauthorized requests never reach an operation; raises UnauthorizedError
+      # which ErrorHandler (one layer up) maps to a 401 JSON response.
+      #
+      # Token comparison uses Rack::Utils.secure_compare to avoid timing leaks.
+      # SKIP_PATHS allows unauthenticated access to liveness/metrics endpoints
+      # so external probes don't need to carry the API key.
+      class Auth
+        SKIP_PATHS = %w[/v1/health /v1/metrics].freeze
+
+        def initialize(app, api_key:)
+          @app = app
+          @api_key = api_key
+        end
+
+        def call(env)
+          return @app.call(env) if SKIP_PATHS.include?(env["PATH_INFO"])
+
+          header = env["HTTP_AUTHORIZATION"].to_s
+          # RFC 6750: scheme is case-insensitive, separated from the token by a
+          # single space. Match explicitly so a raw token without the "Bearer "
+          # prefix is rejected instead of being silently accepted (which is what
+          # String#sub would do when the pattern doesn't match).
+          match = header.match(/\ABearer (.*)\z/i)
+          raise UnauthorizedError, "missing bearer scheme" if match.nil?
+
+          token = match[1]
+          raise UnauthorizedError, "missing bearer token" if token.empty?
+          raise UnauthorizedError, "invalid bearer token" unless Rack::Utils.secure_compare(token, @api_key)
+
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/rubino/api/middleware/error_handler.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rubino
+  module API
+    module Middleware
+      # Catches typed Rubino errors and renders them as JSON with the right
+      # HTTP status (see STATUS_MAP). Anything else becomes a generic 500 while
+      # the full class/message/backtrace are sent to the structured logger,
+      # so unhandled crashes never leak internals to clients.
+      #
+      # Stack position: second from outermost, just inside Observability, so
+      # Observability still sees the final status code on the way out.
+      class ErrorHandler
+        STATUS_MAP = {
+          Rubino::NotFoundError => 404,
+          Rubino::ValidationError => 422,
+          Rubino::UnauthorizedError => 401,
+          Rubino::ConflictError => 409,
+          Rubino::PayloadTooLargeError => 413,
+          Rubino::UpstreamError => 502
+        }.freeze
+
+        def initialize(app, logger:)
+          @app = app
+          @logger = logger
+        end
+
+        def call(env)
+          @app.call(env)
+        rescue *STATUS_MAP.keys => e
+          base = STATUS_MAP.find { |klass, _| e.is_a?(klass) }
+          status = base.last
+          render(status, code(e, base.first), e.message, details(e))
+        rescue StandardError => e
+          @logger.error(event: "api.error.unhandled", error: e.class.name, message: e.message,
+                        backtrace: e.backtrace&.first(10))
+          render(500, "internal_error", "internal server error")
+        end
+
+        private
+
+        def render(status, code, message, details = nil)
+          body = { error: { code: code, message: message } }
+          body[:error][:details] = details if details && !details.empty?
+          [status, { "content-type" => "application/json" }, [JSON.generate(body)]]
+        end
+
+        # Derives a snake_case error code. Subclasses of typed errors (e.g.
+        # Workspace::PathTraversal < ValidationError) collapse to the parent's
+        # code so clients see a stable enum keyed off STATUS_MAP, not internal
+        # subclass names.
+        def code(error, base_class = nil)
+          source = (base_class || error.class).name
+          source.split("::").last.sub(/Error\z/, "").gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase
+        end
+
+        def details(error)
+          error.respond_to?(:details) ? error.details : nil
+        end
+      end
+    end
+  end
+end

data/lib/rubino/api/middleware/json_parser.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rubino
+  module API
+    module Middleware
+      # Parses JSON request bodies once and stashes the result on
+      # env["rubino.json"] for Request#body to read. Only POST/PUT/PATCH
+      # with an application/json content-type are parsed; everything else
+      # gets an empty Hash so operations can rely on the key always existing.
+      #
+      # Malformed JSON raises ValidationError, which ErrorHandler turns into 422.
+      #
+      # Body size is capped at api.max_body_bytes (default 5 MiB). Requests
+      # that advertise a larger Content-Length, or whose body turns out to
+      # exceed the cap mid-read (i.e. Content-Length lied or was absent),
+      # are short-circuited to 413 here — ErrorHandler is bypassed because
+      # 413 is not part of the typed-error map.
+      class JsonParser
+        APPLICABLE_METHODS = %w[POST PUT PATCH].freeze
+        DEFAULT_MAX_BODY_BYTES = 5 * 1024 * 1024
+
+        def initialize(app)
+          @app = app
+        end
+
+        def call(env)
+          if APPLICABLE_METHODS.include?(env["REQUEST_METHOD"]) && json_content?(env)
+            limit = max_body_bytes
+            return too_large(limit) if content_length_over_limit?(env, limit)
+
+            body, overflowed = read_capped(env, limit)
+            return too_large(limit) if overflowed
+
+            env["rubino.json"] = parse(body)
+          else
+            env["rubino.json"] = {}
+          end
+          @app.call(env)
+        end
+
+        private
+
+        def json_content?(env)
+          env["CONTENT_TYPE"].to_s.start_with?("application/json")
+        end
+
+        def content_length_over_limit?(env, limit)
+          declared = env["CONTENT_LENGTH"]
+          return false if declared.nil? || declared.empty?
+
+          declared.to_i > limit
+        end
+
+        # Reads up to limit+1 bytes so we can detect the case where the
+        # actual body is larger than Content-Length advertised (or there
+        # was no Content-Length at all). The +1 marker is dropped before
+        # parsing.
+        def read_capped(env, limit)
+          input = env["rack.input"]
+          return ["", false] if input.nil?
+
+          buf = input.read(limit + 1)
+          return ["", false] if buf.nil?
+
+          if buf.bytesize > limit
+            [nil, true]
+          else
+            [buf, false]
+          end
+        end
+
+        def parse(body)
+          return {} if body.nil? || body.empty?
+
+          JSON.parse(body)
+        rescue JSON::ParserError => e
+          raise ValidationError.new("malformed JSON body", details: { parse_error: e.message })
+        end
+
+        def max_body_bytes
+          value = Rubino.configuration.dig("api", "max_body_bytes")
+          value.is_a?(Integer) && value.positive? ? value : DEFAULT_MAX_BODY_BYTES
+        end
+
+        def too_large(limit)
+          payload = {
+            error: {
+              code: "validation",
+              message: "request body too large (max #{limit} bytes)",
+              details: { max_bytes: limit }
+            }
+          }
+          [413, { "content-type" => "application/json" }, [JSON.generate(payload)]]
+        end
+      end
+    end
+  end
+end

data/lib/rubino/api/middleware/observability.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Rubino
+  module API
+    module Middleware
+      # Outermost middleware. Wraps every request to:
+      #   - record http_requests_total{method,path,status} + http_request_duration_seconds
+      #   - emit one JSON log line (event="api.request") with method, path, status, duration_ms
+      #
+      # Status comes from the response tuple after ErrorHandler has done its
+      # mapping; on a fully unhandled raise we still record status=500 and
+      # re-raise so Puma can render whatever it wants. The `path` metric label
+      # uses env["rubino.route"] (the matched pattern) when present, to
+      # keep Prometheus label cardinality bounded.
+      class Observability
+        def initialize(app, logger: nil)
+          @app = app
+          @logger = logger || Rubino.logger
+        end
+
+        def call(env)
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          status, headers, body = @app.call(env)
+          observe(env, status, start)
+          [status, headers, body]
+        rescue StandardError
+          observe(env, 500, start)
+          raise
+        end
+
+        private
+
+        def observe(env, status, start)
+          duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+          method = env["REQUEST_METHOD"]
+          path = path_for(env)
+
+          Metrics.counter(:http_requests_total, method: method, path: path, status: status).increment
+          Metrics.histogram(:http_request_duration_seconds, method: method, path: path).observe(duration)
+
+          @logger.info(
+            event: "api.request",
+            method: method,
+            path: env["PATH_INFO"],
+            status: status,
+            duration_ms: (duration * 1000).round(2)
+          )
+        end
+
+        # Use the matched route pattern when the router set it (low-cardinality);
+        # fall back to the raw path otherwise (might balloon labels, but is
+        # better than nothing for unmatched paths logged as 404).
+        def path_for(env)
+          env["rubino.route"] || env["PATH_INFO"]
+        end
+      end
+    end
+  end
+end

data/lib/rubino/api/middleware/rate_limit.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rubino
+  module API
+    module Middleware
+      # Token-bucket rate limiter, applied BEFORE Auth so that the open
+      # endpoints (/v1/health, /v1/metrics) get their own per-IP ceiling and
+      # cannot be flooded by an unauthenticated client. Authenticated requests
+      # are keyed by the bearer token so a single API key cannot saturate the
+      # process by spraying connections from many IPs.
+      #
+      # Buckets refill linearly over a 60-second window. Storage is a single
+      # in-memory hash with monotonic timestamps; safe for a single-process
+      # deployment. Multi-process / multi-host needs a shared backend
+      # (Redis, etc.) — defer until we actually scale out.
+      #
+      # On exceed: 429 with the canonical error envelope
+      #   { error: { code: "rate_limited", message: "...",
+      #              details: { retry_after_seconds: N } } }
+      # and a Retry-After header so well-behaved clients can back off without
+      # parsing the body.
+      class RateLimit
+        DEFAULT_UNAUTH_PER_MINUTE = 60
+        DEFAULT_AUTH_PER_MINUTE   = 600
+        WINDOW_SECONDS            = 60.0
+
+        def initialize(app, clock: nil)
+          @app = app
+          @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+          @buckets = {}
+          @mutex = Mutex.new
+        end
+
+        def call(env)
+          return @app.call(env) unless enabled?
+
+          key, capacity = bucket_for(env)
+          allowed, retry_after = consume(key, capacity)
+          return too_many(retry_after) unless allowed
+
+          @app.call(env)
+        end
+
+        private
+
+        # Authenticated buckets are keyed by the bearer token (so the same key
+        # used from many IPs still hits one ceiling); unauthenticated buckets
+        # are keyed by remote IP. The auth/unauth split is decided by whether
+        # the request advertised a Bearer token at all — Auth itself validates
+        # the token later, so an invalid token still gets the unauth bucket
+        # via REMOTE_ADDR if we cannot extract one.
+        def bucket_for(env)
+          token = bearer_token(env)
+          if token
+            ["auth:#{token}", auth_limit]
+          else
+            ["ip:#{env["REMOTE_ADDR"] || "unknown"}", unauth_limit]
+          end
+        end
+
+        def bearer_token(env)
+          header = env["HTTP_AUTHORIZATION"].to_s
+          match = header.match(/\ABearer (.+)\z/i)
+          match && match[1]
+        end
+
+        # Refill is continuous: tokens accumulate at capacity/window per second,
+        # capped at capacity. Each request costs 1 token. Returns
+        # [allowed?, retry_after_seconds_when_denied].
+        def consume(key, capacity)
+          now = @clock.call
+          @mutex.synchronize do
+            bucket = @buckets[key] ||= { tokens: capacity.to_f, updated_at: now }
+            elapsed = now - bucket[:updated_at]
+            refill_rate = capacity / WINDOW_SECONDS
+            bucket[:tokens] = [bucket[:tokens] + (elapsed * refill_rate), capacity.to_f].min
+            bucket[:updated_at] = now
+
+            if bucket[:tokens] >= 1
+              bucket[:tokens] -= 1
+              [true, 0]
+            else
+              # Time until one full token is available again.
+              deficit = 1 - bucket[:tokens]
+              retry_after = (deficit / refill_rate).ceil
+              [false, [retry_after, 1].max]
+            end
+          end
+        end
+
+        def too_many(retry_after)
+          payload = {
+            error: {
+              code: "rate_limited",
+              message: "rate limit exceeded",
+              details: { retry_after_seconds: retry_after }
+            }
+          }
+          [
+            429,
+            {
+              "content-type" => "application/json",
+              "retry-after" => retry_after.to_s
+            },
+            [JSON.generate(payload)]
+          ]
+        end
+
+        def enabled?
+          value = config_dig("api", "rate_limit_enabled")
+          value.nil? || value == true
+        end
+
+        def unauth_limit
+          int_or(config_dig("api", "rate_limit_unauth_per_minute"), DEFAULT_UNAUTH_PER_MINUTE)
+        end
+
+        def auth_limit
+          int_or(config_dig("api", "rate_limit_auth_per_minute"), DEFAULT_AUTH_PER_MINUTE)
+        end
+
+        def int_or(value, fallback)
+          value.is_a?(Integer) && value.positive? ? value : fallback
+        end
+
+        def config_dig(*keys)
+          Rubino.configuration.dig(*keys)
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/rubino/api/operations/approvals/decide_operation.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Rubino
+  module API
+    module Operations
+      module Approvals
+        # POST /v1/runs/:run_id/approvals/:approval_id
+        # Resolves a pending approval gate on a paused run by posting the
+        # operator's decision through the in-process GateRegistry.
+        #
+        # @raise [Rubino::NotFoundError] when the run does not exist.
+        # @raise [Rubino::ValidationError] when the body fails Schemas::DecideApproval.
+        # @raise [Rubino::ConflictError] when the run has no pending gate (already decided or never opened).
+        class DecideOperation
+          def self.call(request)
+            new.call(request)
+          end
+
+          # Accepts an alternate run repository and gate registry for tests.
+          def initialize(repository: nil, registry: nil)
+            @repository = repository || ::Rubino::Run::Repository.new
+            @registry = registry || ::Rubino::Run::GateRegistry
+          end
+
+          def call(request)
+            run_id = request.params.fetch("run_id")
+            approval_id = request.params.fetch("approval_id")
+
+            raise NotFoundError.new("run", run_id) unless @repository.find(run_id)
+
+            attrs = request.validate!(Schemas::DecideApproval)
+            gate = @registry.fetch(run_id)
+            raise ConflictError, "no pending decisions for run #{run_id}" if gate.nil?
+
+            # Wrong-run (or replayed) approval_id: the gate never issued it,
+            # so refuse — never let an arbitrary id unblock an unrelated await.
+            # Duplicate posts return the originally-resolved decision so
+            # retries are idempotent (no double-unblock of the run loop).
+            status = gate.decide(approval_id, attrs[:decision])
+            raise NotFoundError.new("approval", approval_id) if status == :unknown
+
+            resolved = status == :duplicate ? gate.decision_for(approval_id) : attrs[:decision]
+            [200, { approval_id: approval_id, decision: resolved }]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubino/api/operations/clarifications/decide_operation.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Rubino
+  module API
+    module Operations
+      module Clarifications
+        # POST /v1/runs/:run_id/clarifications/:clarify_id
+        # Delivers the user's response to a clarification gate that paused the run,
+        # using the same in-process GateRegistry as approvals.
+        #
+        # @raise [Rubino::NotFoundError] when the run does not exist.
+        # @raise [Rubino::ValidationError] when the body fails Schemas::DecideClarification.
+        # @raise [Rubino::ConflictError] when the run has no pending gate.
+        class DecideOperation
+          def self.call(request)
+            new.call(request)
+          end
+
+          # Accepts an alternate run repository and gate registry for tests.
+          def initialize(repository: nil, registry: nil)
+            @repository = repository || ::Rubino::Run::Repository.new
+            @registry = registry || ::Rubino::Run::GateRegistry
+          end
+
+          def call(request)
+            run_id = request.params.fetch("run_id")
+            clarify_id = request.params.fetch("clarify_id")
+
+            raise NotFoundError.new("run", run_id) unless @repository.find(run_id)
+
+            attrs = request.validate!(Schemas::DecideClarification)
+            gate = @registry.fetch(run_id)
+            raise ConflictError, "no pending decisions for run #{run_id}" if gate.nil?
+
+            status = gate.decide(clarify_id, attrs[:response])
+            raise NotFoundError.new("clarification", clarify_id) if status == :unknown
+
+            [200, { clarify_id: clarify_id, accepted: true }]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubino/api/operations/cron_jobs/create_operation.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Rubino
+  module API
+    module Operations
+      module CronJobs
+        # POST /v1/jobs
+        # Creates a cron job row and registers it with the in-process scheduler.
+        # New jobs default to deliver="local" when the client omits it.
+        #
+        # @return [[Integer, Hash]] 201 + serialized job.
+        # @raise [Rubino::ValidationError] when the body fails Schemas::CreateCronJob
+        #   or carries a cron schedule Fugit cannot parse (#164).
+        class CreateOperation
+          include ScheduleValidation
+
+          def self.call(request)
+            new.call(request)
+          end
+
+          # Accepts an alternate repository and scheduler for tests.
+          def initialize(repository: nil, scheduler: nil)
+            @repository = repository || ::Rubino::Jobs::CronJobRepository.new
+            @scheduler = scheduler || ::Rubino::Jobs::Scheduler.instance
+          end
+
+          def call(request)
+            attrs = request.validate!(Schemas::CreateCronJob)
+            validate_schedule!(attrs[:schedule])
+            job = @repository.create(
+              name: attrs[:name],
+              schedule: attrs[:schedule],
+              prompt: attrs[:prompt],
+              skills: attrs[:skills] || [],
+              model: attrs[:model],
+              provider: attrs[:provider],
+              deliver: attrs[:deliver] || "local"
+            )
+            @scheduler.schedule(job)
+            [201, Serializer.call(job)]
+          end
+        end
+      end
+    end
+  end
+end