rubino-agent 0.3.0

data/lib/rubino/api/operations/runs/events_operation.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rubino
+  module API
+    module Operations
+      module Runs
+        # GET /v1/runs/:id/events — Server-Sent Events stream.
+        #
+        # Replays persisted events (honoring the `Last-Event-ID` header for
+        # resume), then polls for new ones at POLL_INTERVAL until the run
+        # reaches a terminal status (completed/failed/stopped) or disappears.
+        # Puma handles the chunked transfer transparently.
+        #
+        # @return [[Integer, Hash, Enumerable]] 200 + SSE headers + lazy streamer.
+        # @raise [Rubino::NotFoundError] when the run does not exist.
+        class EventsOperation
+          TERMINAL_STATUSES = %w[completed failed stopped].freeze
+          POLL_INTERVAL = 0.25
+          # Proxies (nginx, caddy, ALB) close idle connections around 30–60s;
+          # 15s leaves margin and also exercises the write path so we notice
+          # client disconnects (EPIPE/ECONNRESET) without waiting for a real event.
+          HEARTBEAT_INTERVAL = 15.0
+          HEARTBEAT_FRAME = ": heartbeat\n\n"
+          # Watchdog: if the run is still "running" but no new event has been
+          # written for this many seconds, give up and mark it failed. Covers
+          # cases the Executor's rescue can't (model in an infinite tool loop,
+          # provider stream silently stalled, OS thread killed by a signal we
+          # never saw). Generous enough to outlast a slow tool call but well
+          # under the SSE consumer's job timeout. Tunable via config so an op can dial
+          # it down for short tasks or up for legit long-running computations.
+          DEFAULT_IDLE_EVENT_TIMEOUT = 300.0
+          # Writes to a closed/aborted socket surface as one of these; we treat
+          # them all as "client gone" and stop polling so the thread doesn't
+          # leak until the run reaches a terminal status.
+          DISCONNECT_ERRORS = [Errno::EPIPE, Errno::ECONNRESET, IOError].freeze
+
+          def self.call(request)
+            new.call(request)
+          end
+
+          # Accepts an alternate run repository and event store for tests.
+          # `clock` and `sleeper` are seams so heartbeat/disconnect specs can
+          # drive virtual time without sleeping in real wall-clock seconds.
+          # `idle_event_timeout` overrides the watchdog window (defaults from
+          # config so ops can dial without code changes; nil disables it).
+          def initialize(repository: nil, event_store: nil, clock: nil, sleeper: nil, idle_event_timeout: :default)
+            @repository = repository || ::Rubino::Run::Repository.new
+            @store = event_store || ::Rubino::Run::EventStore.new
+            @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+            @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+            @idle_event_timeout = idle_event_timeout == :default ? configured_idle_timeout : idle_event_timeout
+          end
+
+          def call(request)
+            id = request.params.fetch("id")
+            run = @repository.find(id)
+            raise NotFoundError.new("run", id) unless run
+
+            after_seq = parse_last_event_id(request.header("Last-Event-ID"))
+            headers = {
+              "content-type" => "text/event-stream",
+              "cache-control" => "no-cache",
+              "x-accel-buffering" => "no"
+            }
+            [200, headers, build_stream(id, after_seq)]
+          end
+
+          private
+
+          def parse_last_event_id(header_value)
+            return nil if header_value.nil? || header_value.empty?
+
+            Integer(header_value, 10)
+          rescue ArgumentError
+            nil
+          end
+
+          def build_stream(run_id, after_seq)
+            store = @store
+            repo = @repository
+            clock = @clock
+            sleeper = @sleeper
+            idle_timeout = @idle_event_timeout
+            Enumerator.new do |y|
+              cursor = after_seq
+              now = clock.call
+              last_write_at = now
+              last_real_event_at = now
+              begin
+                # Replay persisted events first.
+                store.for_run(run_id, after_seq: cursor).each do |event|
+                  cursor = event[:seq]
+                  y << format_event(event)
+                  last_write_at = clock.call
+                  last_real_event_at = last_write_at
+                end
+                # Then poll for new events until terminal.
+                loop do
+                  fresh = store.for_run(run_id, after_seq: cursor)
+                  fresh.each do |event|
+                    cursor = event[:seq]
+                    y << format_event(event)
+                    last_write_at = clock.call
+                    last_real_event_at = last_write_at
+                  end
+                  run = repo.find(run_id)
+                  break if run.nil? || TERMINAL_STATUSES.include?(run[:status])
+
+                  # A run parked on a human approval/clarification is NOT idle —
+                  # it is deliberately waiting. Suspend the watchdog while the
+                  # run's gate has a pending decision and keep the clock fresh so
+                  # the timer doesn't fire the instant the answer arrives.
+                  last_real_event_at = clock.call if gate_pending?(run_id)
+
+                  # Watchdog: if the run says "running" but the executor has
+                  # gone silent for too long, escalate. Marks the row as
+                  # failed (so the next /v1/runs query reflects truth) and
+                  # appends a synthetic run.failed event so SSE consumers
+                  # observe a proper terminal frame and can stop polling.
+                  if idle_timeout && (clock.call - last_real_event_at) >= idle_timeout
+
+                    handle_idle_timeout(repo, store, run_id, idle_timeout)
+                    fresh = store.for_run(run_id, after_seq: cursor)
+                    fresh.each do |event|
+                      cursor = event[:seq]
+                      y << format_event(event)
+                    end
+                    break
+                  end
+
+                  if clock.call - last_write_at >= HEARTBEAT_INTERVAL
+                    y << HEARTBEAT_FRAME
+                    last_write_at = clock.call
+                  end
+
+                  sleeper.call(POLL_INTERVAL)
+                end
+              rescue *DISCONNECT_ERRORS
+                # Client (or proxy) closed the connection. Nothing to clean up:
+                # falling out of the Enumerator block ends the stream and lets
+                # Puma reclaim the thread.
+                nil
+              end
+            end
+          end
+
+          # True when this run is currently blocked on a human approval or
+          # clarification. The gate lives in the in-process GateRegistry; a nil
+          # gate (run finished, or another worker) is simply "not pending".
+          def gate_pending?(run_id)
+            gate = ::Rubino::Run::GateRegistry.fetch(run_id)
+            gate.respond_to?(:pending?) && gate.pending?
+          rescue StandardError
+            false
+          end
+
+          def configured_idle_timeout
+            cfg = Rubino.configuration if defined?(Rubino) && Rubino.respond_to?(:configuration)
+            value = cfg && cfg.respond_to?(:run_idle_event_timeout) ? cfg.run_idle_event_timeout : nil
+            value.nil? ? DEFAULT_IDLE_EVENT_TIMEOUT : value
+          rescue StandardError
+            DEFAULT_IDLE_EVENT_TIMEOUT
+          end
+
+          # When the watchdog fires the run is, by definition, in an
+          # inconsistent state — the worker thread is alive long enough that
+          # systemd thinks the process is healthy but isn't emitting anymore.
+          # We update the DB row first (authoritative) then append the
+          # terminal event (best-effort; failure leaves the row consistent).
+          def handle_idle_timeout(repo, store, run_id, timeout_seconds)
+            error_message = "run idle: no new events for #{timeout_seconds.to_i}s"
+            Rubino.logger.warn(event: "run.idle_timeout", run_id: run_id, timeout_s: timeout_seconds)
+            repo.mark_failed!(run_id, error: error_message)
+            run = repo.find(run_id)
+            store.append(
+              session_id: run && run[:session_id],
+              run_id: run_id,
+              type: "run.failed",
+              payload: { error: error_message, reason: "idle_timeout" }
+            )
+          rescue StandardError => e
+            Rubino.logger.error(event: "run.idle_timeout_error", run_id: run_id, error: e.class.name,
+                                message: e.message)
+          end
+
+          def format_event(event)
+            "id: #{event[:seq]}\nevent: #{event[:type]}\ndata: #{event[:payload_json]}\n\n"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Rubino
+  module API
+    module Operations
+      module Runs
+        # POST /v1/runs/:id/stop
+        # Cooperative stop: flags the run for cancellation; the executor checks
+        # between turns and exits cleanly. Returns 200 immediately — the run may
+        # still take a turn to wind down.
+        #
+        # @raise [Rubino::NotFoundError] when the run does not exist.
+        class StopOperation
+          def self.call(request)
+            new.call(request)
+          end
+
+          # Accepts an alternate repository for tests.
+          def initialize(repository: nil)
+            @repository = repository || ::Rubino::Run::Repository.new
+          end
+
+          def call(request)
+            id = request.params.fetch("id")
+            raise NotFoundError.new("run", id) unless @repository.find(id)
+
+            @repository.request_stop!(id)
+            [200, { id: id, status: "stop_requested" }]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Rubino
+  module API
+    module Operations
+      module Sessions
+        # POST /v1/sessions
+        # Creates a session row (source="api") and returns its serialized form.
+        #
+        # @return [[Integer, Hash]] 201 + session payload.
+        # @raise [Rubino::ValidationError] when the body fails Schemas::CreateSession.
+        class CreateOperation
+          def self.call(request)
+            new.call(request)
+          end
+
+          # Accepts an alternate repository for tests.
+          def initialize(repository: nil)
+            @repository = repository || ::Rubino::Session::Repository.new
+          end
+
+          def call(request)
+            attrs = request.validate!(Schemas::CreateSession)
+            session = @repository.create(
+              source: "api",
+              title: attrs[:title],
+              parent_session_id: attrs[:parent_id]
+            )
+            [201, serialize(session)]
+          end
+
+          private
+
+          def serialize(session)
+            {
+              id: session[:id],
+              title: session[:title],
+              parent_id: session[:parent_session_id],
+              created_at: session[:created_at]
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubino/api/operations/sessions/delete_operation.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Rubino
+  module API
+    module Operations
+      module Sessions
+        # DELETE /v1/sessions/:id
+        # Cascade-deletes the session and its messages/runs/events.
+        #
+        # @return [[Integer, Hash]] 204 No Content.
+        # @raise [Rubino::NotFoundError] when the session does not exist.
+        class DeleteOperation
+          def self.call(request)
+            new.call(request)
+          end
+
+          # Accepts an alternate repository for tests.
+          def initialize(repository: nil)
+            @repository = repository || ::Rubino::Session::Repository.new
+          end
+
+          def call(request)
+            id = request.params.fetch("id")
+            raise NotFoundError.new("session", id) unless @repository.find(id)
+
+            @repository.destroy!(id)
+            Responses.no_content
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubino/api/operations/sessions/index_operation.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Rubino
+  module API
+    module Operations
+      module Sessions
+        # GET /v1/sessions
+        # Lists recent sessions. When `?q=` is present, switches to FTS5 mode
+        # and returns the sessions whose messages match the query, ordered by
+        # the most-recent matching message. Reusing the same route keeps the
+        # client surface small — clients only need to learn one endpoint.
+        class IndexOperation
+          DEFAULT_LIMIT = 20
+          MAX_LIMIT     = 100
+
+          def self.call(request)
+            new.call(request)
+          end
+
+          # Accepts alternate dependencies for tests.
+          def initialize(repository: nil, message_store: nil)
+            @repository = repository || ::Rubino::Session::Repository.new
+            @message_store = message_store || ::Rubino::Session::Store.new
+          end
+
+          def call(request)
+            limit = clamp_limit(request.query["limit"])
+            q = request.query["q"].to_s.strip
+
+            sessions = q.empty? ? list_recent(limit) : search(q, limit)
+            [200, { sessions: sessions.map { |s| serialize(s) } }]
+          end
+
+          private
+
+          def list_recent(limit)
+            @repository.list(limit: limit)
+          end
+
+          # Search mode: group FTS5 hits by session, ordered by the latest hit.
+          # The store gives us per-message rows; we collapse them down to one
+          # entry per session and look up the session row to keep the wire
+          # shape identical to list mode.
+          def search(q, limit)
+            hits = @message_store.search(query: q, limit: MAX_LIMIT)
+            ordered_ids = []
+            seen = {}
+            hits.each do |hit|
+              sid = hit[:session_id]
+              next if seen[sid]
+
+              seen[sid] = true
+              ordered_ids << sid
+              break if ordered_ids.size >= limit
+            end
+
+            ordered_ids.filter_map { |id| @repository.find(id) }
+          end
+
+          def clamp_limit(raw)
+            n = raw.to_i
+            return DEFAULT_LIMIT if n <= 0
+
+            [n, MAX_LIMIT].min
+          end
+
+          def serialize(session)
+            {
+              id: session[:id],
+              title: session[:title],
+              status: session[:status],
+              created_at: session[:created_at],
+              updated_at: session[:updated_at],
+              message_count: session[:message_count],
+              token_count: session[:token_count]
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubino/api/operations/sessions/retry_operation.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Rubino
+  module API
+    module Operations
+      module Sessions
+        # POST /v1/sessions/:id/retry
+        # Deletes the last user message and everything after it, then enqueues a
+        # fresh run with the same input. Returns 202 with the new run id.
+        #
+        # @return [[Integer, Hash]] 202 + { run_id, session_id, status: "running" }.
+        # @raise [Rubino::NotFoundError] when the session does not exist.
+        # @raise [Rubino::ConflictError] when the session has no user message to retry.
+        class RetryOperation
+          def self.call(request)
+            new.call(request)
+          end
+
+          # Accepts alternate collaborators (session repo, message store, run repo, executor) for tests.
+          def initialize(session_repository: nil, message_store: nil, run_repository: nil, executor: nil)
+            @session_repo = session_repository || ::Rubino::Session::Repository.new
+            @message_store = message_store || ::Rubino::Session::Store.new
+            @run_repo = run_repository || ::Rubino::Run::Repository.new
+            @executor = executor || ::Rubino::Run::Executor.new
+          end
+
+          def call(request)
+            session_id = request.params.fetch("id")
+            raise NotFoundError.new("session", session_id) unless @session_repo.find(session_id)
+
+            last_user = @message_store.last_for_role(session_id, "user")
+            raise ConflictError, "no user message to retry" unless last_user
+
+            @message_store.delete_from_inclusive(session_id, from_id: last_user.id)
+
+            run = @run_repo.create(session_id: session_id, input_text: last_user.content)
+            @executor.start(run)
+
+            [202, { run_id: run[:id], session_id: session_id, status: "running" }]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Rubino
+  module API
+    module Operations
+      module Sessions
+        # GET /v1/sessions/:id
+        # Returns the session with its message timeline inlined.
+        #
+        # @raise [Rubino::NotFoundError] when the session does not exist.
+        class ShowOperation
+          def self.call(request)
+            new.call(request)
+          end
+
+          # Accepts an alternate repository and message store for tests.
+          def initialize(repository: nil, message_store: nil)
+            @repository = repository || ::Rubino::Session::Repository.new
+            @message_store = message_store || ::Rubino::Session::Store.new
+          end
+
+          def call(request)
+            id = request.params.fetch("id")
+            session = @repository.find(id)
+            raise NotFoundError.new("session", id) unless session
+
+            [200, serialize(session)]
+          end
+
+          private
+
+          def serialize(session)
+            {
+              id: session[:id],
+              title: session[:title],
+              instructions: nil,
+              created_at: session[:created_at],
+              status: session[:status],
+              messages: messages_for(session[:id])
+            }
+          end
+
+          def messages_for(session_id)
+            @message_store.for_session(session_id).map do |m|
+              {
+                id: m.id,
+                role: m.role,
+                content: m.content,
+                created_at: m.created_at
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubino/api/operations/sessions/undo_operation.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Rubino
+  module API
+    module Operations
+      module Sessions
+        # POST /v1/sessions/:id/undo
+        # Removes the last user message and everything after it (no re-run).
+        # Returns the number of messages deleted.
+        #
+        # @raise [Rubino::NotFoundError] when the session does not exist.
+        # @raise [Rubino::ConflictError] when the session has no user message to undo.
+        class UndoOperation
+          def self.call(request)
+            new.call(request)
+          end
+
+          # Accepts an alternate session repository and message store for tests.
+          def initialize(session_repository: nil, message_store: nil)
+            @session_repo = session_repository || ::Rubino::Session::Repository.new
+            @message_store = message_store || ::Rubino::Session::Store.new
+          end
+
+          def call(request)
+            session_id = request.params.fetch("id")
+            raise NotFoundError.new("session", session_id) unless @session_repo.find(session_id)
+
+            last_user = @message_store.last_for_role(session_id, "user")
+            raise ConflictError, "nothing to undo" unless last_user
+
+            removed = @message_store.delete_from_inclusive(session_id, from_id: last_user.id)
+            [200, { removed_messages: removed }]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubino/api/operations/skills/list_operation.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Rubino
+  module API
+    module Operations
+      module Skills
+        # GET /v1/skills
+        # Lists every registered skill annotated with its persisted enabled flag.
+        class ListOperation
+          def self.call(request)
+            new.call(request)
+          end
+
+          # Accepts an alternate skills registry and state repository for tests.
+          def initialize(registry: nil, state_repository: nil)
+            @registry = registry || ::Rubino::Skills::Registry.new
+            @state_repository = state_repository || ::Rubino::Skills::StateRepository.new
+          end
+
+          def call(_request)
+            skills = @registry.all.map do |skill|
+              {
+                name: skill.name,
+                description: skill.description,
+                enabled: @state_repository.enabled?(skill.name)
+              }
+            end
+            [200, skills]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubino/api/operations/skills/toggle_operation.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Rubino
+  module API
+    module Operations
+      module Skills
+        # PUT /v1/skills/:name
+        # Persists the enable/disable flag for a single registered skill.
+        #
+        # @raise [Rubino::NotFoundError] when no skill is registered under +name+.
+        # @raise [Rubino::ValidationError] when the body fails Schemas::ToggleSkill.
+        class ToggleOperation
+          def self.call(request)
+            new.call(request)
+          end
+
+          # Accepts an alternate skills registry and state repository for tests.
+          def initialize(registry: nil, state_repository: nil)
+            @registry = registry || ::Rubino::Skills::Registry.new
+            @state_repository = state_repository || ::Rubino::Skills::StateRepository.new
+          end
+
+          def call(request)
+            name = request.params.fetch("name")
+            raise NotFoundError.new("skill", name) unless @registry.find(name)
+
+            attrs = request.validate!(Schemas::ToggleSkill)
+            # The shared toggle write path (Skills::Toggle, #188) — the same
+            # registry-validated StateRepository write the in-chat
+            # `/skills enable|disable` and the `rubino skills` CLI verbs run.
+            ::Rubino::Skills::Toggle.set(name, enabled: attrs[:enabled],
+                                               registry: @registry,
+                                               state_repository: @state_repository)
+            [200, { name: name, enabled: attrs[:enabled] }]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Rubino
+  module API
+    module Operations
+      module Tasks
+        # GET /v1/tasks
+        # Lists background subagents started by the `task` tool, newest first.
+        # Each row is the summary shape (no full result body — see the show
+        # endpoint for that). The registry is process-local and not persisted,
+        # so this reflects only the current server process's children.
+        class IndexOperation
+          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)
+            tasks = @registry.list.map { |entry| Serializer.summary(entry) }
+            [200, { tasks: tasks }]
+          end
+        end
+      end
+    end
+  end
+end