rubino-agent 0.3.0

data/lib/rubino/api/operations/tasks/serializer.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Rubino
+  module API
+    module Operations
+      module Tasks
+        # Wire shapes for background-subagent (`task`) entries.
+        #
+        # #summary powers the list endpoint — id/subagent/prompt/status/timing
+        # plus a short result preview, never the full body. #detail adds the
+        # complete result (success) or error (failure). The Entry struct carries
+        # Time objects and a live Thread/Runner; only the serializable fields are
+        # surfaced.
+        module Serializer
+          module_function
+
+          RESULT_PREVIEW = 200
+
+          def summary(entry)
+            {
+              id: entry.id,
+              subagent: entry.subagent,
+              prompt: entry.prompt,
+              status: entry.status.to_s,
+              started_at: iso(entry.started_at),
+              elapsed_seconds: elapsed(entry),
+              result_summary: preview(entry.result)
+            }
+          end
+
+          def detail(entry)
+            summary(entry).merge(
+              finished_at: iso(entry.finished_at),
+              result: entry.result,
+              error: entry.error
+            )
+          end
+
+          def iso(time)
+            time&.utc&.iso8601
+          end
+
+          # Wall-clock seconds: to finish if done, else to now for a live task.
+          def elapsed(entry)
+            return nil unless entry.started_at
+
+            ((entry.finished_at || Time.now) - entry.started_at).round(3)
+          end
+
+          def preview(result)
+            return nil if result.nil?
+
+            str = result.to_s
+            str.length > RESULT_PREVIEW ? "#{str[0, RESULT_PREVIEW]}…" : str
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubino/api/operations/tasks/show_operation.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Rubino
+  module API
+    module Operations
+      module Tasks
+        # GET /v1/tasks/:id
+        # Full detail for one background subagent, including its complete result
+        # (on success) or error (on failure).
+        #
+        # @raise [Rubino::NotFoundError] when no task has the id.
+        class ShowOperation
+          def self.call(request)
+            new.call(request)
+          end
+
+          # Accepts an alternate registry for tests.
+          def initialize(registry: nil)
+            @registry = registry || ::Rubino::Tools::BackgroundTasks.instance
+          end
+
+          def call(request)
+            id = request.params.fetch("id")
+            entry = @registry.find(id)
+            raise NotFoundError.new("task", id) unless entry
+
+            [200, Serializer.detail(entry)]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubino/api/operations/tasks/stop_operation.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Rubino
+  module API
+    module Operations
+      module Tasks
+        # POST /v1/tasks/:id/stop
+        # Cancels a running background subagent — the HTTP twin of the `task_stop`
+        # tool. Flips the child Runner's CancelToken (the same mechanism the
+        # top-level run stop-watcher uses), which unwinds the child loop
+        # cooperatively at its next cancel checkpoint.
+        #
+        # Cancellation is asynchronous: this returns the entry's CURRENT snapshot,
+        # so `status` may still read "running" until the worker thread reaches a
+        # checkpoint and records its terminal (cancelled/failed) state. Poll
+        # GET /v1/tasks/:id to observe the transition.
+        #
+        # @raise [Rubino::NotFoundError]   when no task has the id.
+        # @raise [Rubino::ConflictError]   when the task is already finished.
+        class StopOperation
+          def self.call(request)
+            new.call(request)
+          end
+
+          # Accepts an alternate registry for tests.
+          def initialize(registry: nil)
+            @registry = registry || ::Rubino::Tools::BackgroundTasks.instance
+          end
+
+          def call(request)
+            id = request.params.fetch("id")
+            entry = @registry.find(id)
+            raise NotFoundError.new("task", id) unless entry
+
+            raise ConflictError, "task #{id} already #{entry.status} — nothing to stop" unless entry.status == :running
+
+            entry.runner&.cancel!
+            # Stop-cascade (S5a): wake any descendant parked on a blocking
+            # ask_parent so the whole subtree unwinds at once.
+            @registry.cancel_descendant_ask_gates(id)
+            [202, Serializer.detail(entry)]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubino/api/request.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Rubino
+  module API
+    # Operation-facing view over the Rack env: URL captures, parsed JSON body,
+    # query string, headers, and a dry-schema validation helper.
+    #
+    # Body comes from env["rubino.json"] (set by JsonParser middleware),
+    # so operations never touch rack.input directly.
+    #
+    #   request.params              # URL captures (e.g. { "id" => "abc" })
+    #   request.body                # parsed JSON body (Hash)
+    #   request.validate!(schema)   # runs dry-schema, raises ValidationError on fail
+    #   request.header("X-Foo")     # case-insensitive header lookup
+    class Request
+      # @param env [Hash] Rack env
+      # @param params [Hash{String=>String}] captures from the matched route
+      def initialize(env, params)
+        @env = env
+        @params = params
+      end
+
+      attr_reader :env, :params
+
+      # @return [Hash] parsed JSON body, or {} when none
+      def body
+        @env.fetch("rubino.json", {})
+      end
+
+      # Case-insensitive header lookup; "X-Foo" becomes HTTP_X_FOO.
+      def header(name)
+        key = "HTTP_#{name.upcase.tr("-", "_")}"
+        @env[key]
+      end
+
+      def query
+        @query ||= Rack::Utils.parse_nested_query(@env["QUERY_STRING"].to_s)
+      end
+
+      # Runs the body through a dry-schema and returns the coerced hash.
+      # dry-schema is used only at the HTTP boundary; internals trust their types.
+      #
+      # @param schema [Dry::Schema::Processor]
+      # @return [Hash] coerced, validated payload
+      # @raise [ValidationError] when the schema rejects the body (mapped to 422 by ErrorHandler)
+      def validate!(schema)
+        result = schema.call(body)
+        raise ValidationError.new("invalid request body", details: { errors: result.errors.to_h }) if result.failure?
+
+        result.to_h
+      end
+    end
+  end
+end

data/lib/rubino/api/responses.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rubino
+  module API
+    # Coerces Operation return values into Rack response triples.
+    # Lets operations return whatever shape is most convenient (a plain Hash for
+    # 200, a [status, body] pair for other codes, or a full Rack triple for
+    # streaming/binary), while the router always hands Rack a valid triple.
+    module Responses
+      module_function
+
+      # Builds a JSON response triple with content-type set.
+      #
+      # @return [Array(Integer, Hash, Array<String>)]
+      def json(status, payload)
+        [status, { "content-type" => "application/json" }, [JSON.generate(payload)]]
+      end
+
+      # @return [Array(Integer, Hash, Array)] empty 204 response triple
+      def no_content
+        [204, {}, []]
+      end
+
+      # Normalize an operation result. See Router class comment for the contract.
+      #
+      # @param value [Hash, Array, #to_rack]
+      # @return [Array(Integer, Hash, Array<String>)] Rack triple
+      # @raise [ArgumentError] when value doesn't match any supported shape
+      def coerce(value)
+        case value
+        when Array
+          coerce_array(value)
+        when Hash
+          json(200, value)
+        else
+          return value.to_rack if value.respond_to?(:to_rack)
+
+          raise ArgumentError, "operation returned unsupported value: #{value.class}"
+        end
+      end
+
+      # Disambiguates [status, body] (length 2, JSON-encoded) from a raw
+      # [status, headers, body] Rack triple (length 3, passed through).
+      def coerce_array(value)
+        case value.length
+        when 2
+          status, body = value
+          # RFC 7231 §6.3.5: a 204 response MUST NOT have a message body. We
+          # force the body to "" regardless of what the operation returned so
+          # we never emit `null\n` (a 4-byte JSON literal) for a No Content.
+          return [status, {}, [""]] if status == 204
+
+          json(status, body)
+        when 3
+          value
+        else
+          raise ArgumentError, "operation returned array of length #{value.length}; expected 2 or 3"
+        end
+      end
+    end
+  end
+end

data/lib/rubino/api/router.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Rubino
+  module API
+    # Minimal pattern-matching router mapping HTTP verb + path to an Operation class.
+    #
+    # Path patterns support `:name` captures (e.g. "/v1/sessions/:id"), compiled to
+    # a `[^/]+` regex group. On a match the captures become Request#params, the
+    # original pattern is stashed on env["rubino.route"] (low-cardinality label
+    # for Observability), and the operation's return value is coerced via Responses.
+    #
+    # Operation contract: `.call(request)` returning one of:
+    #   - Hash                                  → 200 JSON
+    #   - [status, body_hash]                   → status + JSON body
+    #   - [status, headers, body_iterable]      → raw Rack triple
+    #   - object responding to #to_rack         → delegated
+    #
+    #   router = Router.new
+    #   router.get  "/v1/health",        to: HealthOperation
+    #   router.post "/v1/sessions",      to: Sessions::CreateOperation
+    #   router.get  "/v1/sessions/:id",  to: Sessions::ShowOperation
+    class Router
+      Route = Struct.new(:method, :pattern, :keys, :operation, :original_path)
+
+      HTTP_METHODS = %i[get post put patch delete].freeze
+
+      def initialize
+        @routes = []
+      end
+
+      HTTP_METHODS.each do |verb|
+        define_method(verb) do |path, to:|
+          add(verb.to_s.upcase, path, to)
+        end
+      end
+
+      # Rack entry point. Matches in registration order; first match wins.
+      # Returns a 404 JSON response when nothing matches.
+      #
+      # @return [Array(Integer, Hash, Array<String>)] Rack response triple
+      def call(env)
+        rack_method = env["REQUEST_METHOD"]
+        path = env["PATH_INFO"]
+
+        @routes.each do |route|
+          next unless route.method == rack_method
+
+          match = route.pattern.match(path)
+          next unless match
+
+          params = route.keys.zip(match.captures).to_h
+          env["rubino.route"] = route.original_path
+          request = Request.new(env, params)
+          return Responses.coerce(route.operation.call(request))
+        end
+
+        Responses.json(404, error: { code: "not_found", message: "route not found: #{rack_method} #{path}" })
+      end
+
+      private
+
+      def add(method, path, operation)
+        keys = []
+        pattern = path.gsub(/:([a-z_]+)/) do
+          keys << ::Regexp.last_match(1)
+          "([^/]+)"
+        end
+        @routes << Route.new(method, /\A#{pattern}\z/, keys, operation, path)
+      end
+    end
+  end
+end

data/lib/rubino/api/schemas.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "dry-schema"
+
+Dry::Schema.load_extensions(:json_schema)
+
+module Rubino
+  module API
+    # dry-schema definitions for HTTP request bodies. Validation runs only at
+    # the HTTP boundary (via Request#validate!); domain code downstream assumes
+    # types are already coerced. Each constant maps to a single endpoint.
+    module Schemas
+      # POST /v1/sessions
+      CreateSession = Dry::Schema.JSON do
+        optional(:title).maybe(:string)
+        optional(:parent_id).maybe(:string)
+      end
+
+      # POST /v1/sessions/:id/runs
+      # `input` is optional at the schema level so an image-only run (a file
+      # with no accompanying text) is accepted: the executor substitutes a
+      # default prompt when the text is blank but an image is attached. The
+      # "input present OR attachments present" rule is enforced in
+      # Operations::Runs::CreateOperation (dry-schema has no cross-field rule
+      # and we don't pull in dry-validation just for this).
+      CreateRun = Dry::Schema.JSON do
+        optional(:input).maybe(:string)
+        optional(:attachments).array(:string)
+        optional(:skills).array(:string)
+        optional(:model).maybe(:string)
+        optional(:provider).maybe(:string)
+      end
+
+      # POST /v1/runs/:run_id/approvals/:approval_id
+      # Keep in sync with UI::API::APPROVE_DECISIONS — the approve values plus
+      # the explicit "deny" (one-off) and "deny_always" (persists a
+      # permissions:deny rule) forms the closed set of decisions the gate
+      # understands. `always` is a BACK-COMPAT ALIAS for `always_command`
+      # (existing web clients post `always`); `always_prefix`/`always_command`
+      # are the explicit forms. New values are additive — old clients keep working.
+      DecideApproval = Dry::Schema.JSON do
+        required(:decision).filled(
+          :string,
+          included_in?: %w[once session always always_prefix always_command deny deny_always]
+        )
+      end
+
+      # POST /v1/runs/:run_id/clarifications/:clarify_id
+      DecideClarification = Dry::Schema.JSON do
+        required(:response).filled(:string)
+      end
+
+      # PUT /v1/skills/:name
+      ToggleSkill = Dry::Schema.JSON do
+        required(:enabled).filled(:bool)
+      end
+
+      # PUT /v1/mode — string instead of symbol because JSON has no symbol
+      # type; the operation normalises via Modes.set.
+      UpdateMode = Dry::Schema.JSON do
+        required(:mode).filled(:string, included_in?: Rubino::Modes::ALL.map(&:to_s))
+      end
+
+      # POST /v1/jobs
+      CreateCronJob = Dry::Schema.JSON do
+        required(:name).filled(:string)
+        required(:schedule).filled(:string)
+        required(:prompt).filled(:string)
+        optional(:skills).array(:string)
+        optional(:model).maybe(:string)
+        optional(:provider).maybe(:string)
+        optional(:deliver).filled(:string, included_in?: %w[local webhook])
+      end
+
+      # PATCH /v1/jobs/:id
+      UpdateCronJob = Dry::Schema.JSON do
+        optional(:name).filled(:string)
+        optional(:schedule).filled(:string)
+        optional(:prompt).filled(:string)
+        optional(:skills).array(:string)
+        optional(:model).maybe(:string)
+        optional(:provider).maybe(:string)
+        optional(:deliver).filled(:string, included_in?: %w[local webhook])
+        optional(:enabled).filled(:bool)
+      end
+
+      # POST /v1/oauth/providers/:id/connect
+      ConnectProvider = Dry::Schema.JSON do
+        required(:redirect_uri).filled(:string)
+        optional(:scopes).array(:string)
+      end
+
+      # POST /v1/oauth/providers/:id/callback
+      CallbackProvider = Dry::Schema.JSON do
+        required(:code).filled(:string)
+        required(:state).filled(:string)
+        required(:expected_state).filled(:string)
+        required(:code_verifier).filled(:string)
+        required(:redirect_uri).filled(:string)
+      end
+    end
+  end
+end

data/lib/rubino/api/server.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "rack"
+require "uri"
+require "puma"
+require "puma/configuration"
+require "puma/launcher"
+require "puma/events"
+
+module Rubino
+  module API
+    # Rack app entry point. Wires the middleware stack + router and runs it under Puma.
+    #
+    # Reads RUBINO_API_KEY from the environment when no key is passed explicitly;
+    # start! refuses to boot without one so the bearer-auth middleware is never bypassed.
+    # The pure Rack app (no Puma) is exposed via .build_app for tests and embedding.
+    #
+    #   server = Rubino::API::Server.new(port: 4820)
+    #   server.start!
+    class Server
+      DEFAULT_PORT = 4820
+      # Loopback by default (#69): the server speaks to a shell tool, so a
+      # routable bind is opt-in (--host 0.0.0.0 / RUBINO_API_HOST).
+      DEFAULT_HOST = "127.0.0.1"
+
+      # @param port [Integer] TCP port (default 4820, or pass via constructor)
+      # @param host [String] bind address (default 127.0.0.1)
+      # @param api_key [String, nil] bearer token; falls back to ENV["RUBINO_API_KEY"]
+      # @param tls_cert [String, nil] path to a TLS cert PEM; when set (with
+      #   tls_key) the listener serves HTTPS via ssl_bind instead of plain TCP
+      # @param tls_key [String, nil] path to the matching private-key PEM
+      def initialize(port: DEFAULT_PORT, host: DEFAULT_HOST, api_key: nil, router: nil, logger: nil,
+                     tls_cert: nil, tls_key: nil)
+        @port = port
+        @host = host
+        @api_key = api_key || ENV.fetch("RUBINO_API_KEY", nil)
+        @router = router || Router.new
+        @logger = logger || Rubino.logger
+        @tls_cert = tls_cert
+        @tls_key = tls_key
+      end
+
+      # @return [Boolean] whether this server will serve over TLS
+      def tls?
+        !@tls_cert.nil? && !@tls_key.nil?
+      end
+
+      # Boots Puma and blocks. Fails fast if no API key is configured.
+      #
+      # @raise [ConfigurationError] if RUBINO_API_KEY is missing/empty
+      def start!
+        if @api_key.nil? || @api_key.empty?
+          raise ConfigurationError,
+                "RUBINO_API_KEY must be set to start the API server"
+        end
+
+        app = self.class.build_app(router: @router, api_key: @api_key, logger: @logger)
+        @logger.info(event: "api.server.starting", host: @host, port: @port, tls: tls?)
+
+        bind_url = self.class.bind_url(host: @host, port: @port, tls_cert: @tls_cert, tls_key: @tls_key)
+        config = Puma::Configuration.new do |c|
+          c.bind(bind_url)
+          c.app(app)
+          c.quiet
+        end
+        Puma::Launcher.new(config).run
+      end
+
+      # Composes the Rack middleware stack around the router. Order matters:
+      # Observability is outermost (sees every status, including 500s from
+      # ErrorHandler), then ErrorHandler, then RateLimit (so /v1/health and
+      # /v1/metrics also get a per-IP ceiling before Auth waves them through),
+      # then JsonParser, then Auth closest to the router so unauthorized
+      # requests never reach operations.
+      #
+      # @return [#call] a Rack-compatible app
+      # Builds the Puma bind URL. When a TLS cert+key are configured it returns
+      # an ssl:// bind so Puma terminates TLS with the self-signed cert; the web
+      # client pins that cert (see Rubino::API::TLS).
+      # Otherwise it returns a plain tcp:// bind (local dev / fake stay HTTP).
+      #
+      # @return [String] a Puma bind URL ("tcp://..." or "ssl://...")
+      def self.bind_url(host:, port:, tls_cert: nil, tls_key: nil)
+        return "tcp://#{host}:#{port}" if tls_cert.nil? || tls_key.nil?
+
+        query = URI.encode_www_form(cert: tls_cert, key: tls_key)
+        "ssl://#{host}:#{port}?#{query}"
+      end
+
+      def self.build_app(router:, api_key:, logger: Rubino.logger)
+        Rack::Builder.new do
+          use Middleware::Observability, logger: logger
+          use Middleware::ErrorHandler, logger: logger
+          use Middleware::RateLimit
+          use Middleware::JsonParser
+          use Middleware::Auth, api_key: api_key
+          run router
+        end.to_app
+      end
+    end
+  end
+end

data/lib/rubino/api/tls.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "fileutils"
+require "ipaddr"
+
+module Rubino
+  module API
+    # Self-signed TLS for the app→app hop (web client → agent API).
+    #
+    # The hop is server→server (Ruby Net::HTTP, not a browser), so there is no
+    # DNS / Let's Encrypt: the agent generates a long-lived self-signed cert on
+    # first boot and the web client PINS it. The operator provisions the PEM out
+    # of band over an already-trusted channel, so there is no trust-on-first-use
+    # gap on the untrusted HTTP hop.
+    #
+    # Cert + key live under RUBINO_HOME/tls and are reused across boots.
+    module TLS
+      DIR_NAME  = "tls"
+      CERT_NAME = "cert.pem"
+      KEY_NAME  = "key.pem"
+
+      # ~10 years — this is a pinned, app→app cert, not a browser-facing one, so
+      # a long lifetime avoids needless re-provisioning churn.
+      VALIDITY_SECONDS = 10 * 365 * 24 * 60 * 60
+
+      module_function
+
+      # TLS is enabled when explicitly toggled (RUBINO_TLS=1) or when a cert
+      # already exists under the home dir. Local dev (bin/dev / fake) leaves the
+      # toggle unset and ships no cert, so it stays plain HTTP.
+      def enabled?(home: Rubino.home_path)
+        return true if ENV["RUBINO_TLS"].to_s.strip == "1"
+
+        File.exist?(cert_path(home: home))
+      end
+
+      def dir(home: Rubino.home_path)
+        File.join(home, DIR_NAME)
+      end
+
+      def cert_path(home: Rubino.home_path)
+        File.join(dir(home: home), CERT_NAME)
+      end
+
+      def key_path(home: Rubino.home_path)
+        File.join(dir(home: home), KEY_NAME)
+      end
+
+      # Returns the cert PEM string, generating the cert+key on first call and
+      # reusing them on every subsequent call (idempotent across boots). The
+      # cert's CN/SAN is set to +host+ so a pinning client that also checks the
+      # subject is satisfied; for IP binds the SAN carries the IP.
+      #
+      # @param host [String] the host/IP the agent is reachable at
+      # @return [String] the certificate PEM
+      def ensure_cert!(host: nil, home: Rubino.home_path)
+        cert = cert_path(home: home)
+        key  = key_path(home: home)
+        return File.read(cert) if File.exist?(cert) && File.exist?(key)
+
+        FileUtils.mkdir_p(dir(home: home))
+        pem_cert, pem_key = generate(host: host)
+        # 0600 the key; the cert PEM is public (it gets shipped to the client).
+        File.write(key, pem_key)
+        File.chmod(0o600, key)
+        File.write(cert, pem_cert)
+        File.chmod(0o644, cert)
+        pem_cert
+      end
+
+      # Generates a fresh self-signed RSA-2048 cert+key for +host+. Returns
+      # [cert_pem, key_pem]. Not persisted — callers persist via ensure_cert!.
+      def generate(host: nil)
+        cn = host.nil? || host.empty? || host == "0.0.0.0" ? "rubino" : host
+        key = OpenSSL::PKey::RSA.new(2048)
+
+        cert = OpenSSL::X509::Certificate.new
+        cert.version    = 2
+        cert.serial     = OpenSSL::BN.rand(159)
+        cert.subject    = OpenSSL::X509::Name.new([["CN", cn]])
+        cert.issuer     = cert.subject
+        cert.public_key = key.public_key
+        cert.not_before = Time.now - 60
+        cert.not_after  = Time.now + VALIDITY_SECONDS
+
+        ef = OpenSSL::X509::ExtensionFactory.new
+        ef.subject_certificate = cert
+        ef.issuer_certificate  = cert
+        cert.add_extension(ef.create_extension("basicConstraints", "CA:TRUE", true))
+        cert.add_extension(ef.create_extension("subjectAltName", san_for(cn), false))
+        cert.sign(key, OpenSSL::Digest.new("SHA256"))
+
+        [cert.to_pem, key.to_pem]
+      end
+
+      # Builds a SAN string. An IP literal goes in as IP:, a hostname as DNS:.
+      def san_for(name)
+        ip = begin
+          IPAddr.new(name)
+        rescue StandardError
+          nil
+        end
+        ip ? "IP:#{name}" : "DNS:#{name}"
+      end
+    end
+  end
+end

data/lib/rubino/attachments/classification.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Attachments
+    # Result of Attachments::Classify.call. Pure data; no behaviour.
+    #   path:       frozen realpath captured once (TOCTOU), or original if unsafe
+    #   kind:       :image | :text | :document | :archive | :binary
+    #   mime:       Marcel content-sniffed type
+    #   safe:       false => safety pipeline rejected it; caller skips + warns
+    #   reason:     human-readable why-unsafe / how-classified
+    Classification = Struct.new(
+      :path, :kind, :mime, :size_bytes, :safe, :reason,
+      keyword_init: true
+    )
+  end
+end