superkick 0.1.0

data/lib/superkick/server.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Superkick
+  # Orchestrates server startup, signal handling, and shutdown.
+  #
+  # Usage:
+  #   Superkick::Server.start(daemonize: false)
+  class Server
+    def self.start(daemonize: false)
+      new(daemonize:).run
+    end
+
+    def initialize(daemonize: false)
+      @daemonize = daemonize
+    end
+
+    def run
+      check_already_running!
+
+      daemonize! if @daemonize
+
+      FileUtils.mkdir_p(Superkick.config.base_dir)
+      write_pid_file
+
+      Superkick.logger.info("server") { "Superkick server starting (v#{VERSION})" }
+
+      Superkick.load_config!
+      Superkick.logger.level = Superkick.config.log_level
+
+      store = AgentStore.new
+      buffer_client = Buffer.client_from(store:)
+      attach_relay_store = build_attach_relay_store
+      recover_agents(store, buffer_client)
+      notifier_state_store = NotifierStateStore::Memory.new
+      team_log_store = Team::LogStore.new
+      team_log_notifier = Team::LogNotifier.new(team_log_store:, state_store: notifier_state_store)
+      notification_dispatcher = NotificationDispatcher.new(
+        store:, state_store: notifier_state_store,
+        internal_notifiers: [[team_log_notifier, nil]]
+      )
+      injector = Injector.new(store:, notification_dispatcher:, buffer_client:)
+      team_artifact_store = Team::ArtifactStore.new
+      approval_store = Spawn::ApprovalStore.new
+      budget_checker = BudgetChecker.new(store:)
+      supervisor = Supervisor.new(
+        store:, injector:, buffer_client:,
+        approval_store:,
+        team_log_store:,
+        notification_dispatcher:
+      )
+      agent_spawner = Spawn::AgentSpawner.new(store:, notification_dispatcher:, supervisor:,
+        runtime: Superkick.config.agent_runtime)
+      supervisor.agent_spawner = agent_spawner
+      control_server = Control::Server.new(
+        store:,
+        injector:,
+        supervisor:,
+        buffer_client:,
+        agent_spawner:,
+        approval_store:,
+        budget_checker:,
+        team_log_store:,
+        team_artifact_store:,
+        notification_dispatcher:,
+        attach_relay_store:
+      )
+
+      validate_workflow_configs
+
+      supervisor.start
+      supervisor.restore_from_registry
+      supervisor.start_spawners
+
+      control_server.start
+      Superkick.logger.info("server") { "Control server listening on #{Superkick.config.socket_path}" }
+
+      wait_for_signals(control_server, supervisor)
+    rescue AlreadyRunning => e
+      warn "superkick: #{e.message}"
+      exit(1)
+    ensure
+      cleanup
+    end
+
+    private
+
+    AlreadyRunning = Class.new(StandardError)
+
+    def check_already_running!
+      return unless File.exist?(Superkick.config.pid_path)
+
+      pid = File.read(Superkick.config.pid_path).strip.to_i
+      return if pid <= 0
+
+      begin
+        Process.kill(0, pid)
+        raise AlreadyRunning, "Server already running (PID #{pid})"
+      rescue Errno::ESRCH
+        # Stale PID file — remove and continue
+        FileUtils.rm_f(Superkick.config.pid_path)
+      rescue Errno::EPERM
+        raise AlreadyRunning, "Server already running (PID #{pid})"
+      end
+    end
+
+    def write_pid_file
+      FileUtils.mkdir_p(File.dirname(Superkick.config.pid_path))
+      File.write(Superkick.config.pid_path, "#{Process.pid}\n")
+    end
+
+    def daemonize!
+      pid = fork
+      exit(0) if pid # parent exits
+
+      Process.setsid
+
+      pid = fork
+      exit(0) if pid # first child exits
+
+      FileUtils.mkdir_p(Superkick.config.base_dir)
+
+      $stdin.reopen(File::NULL)
+      $stdout.reopen(Superkick.config.log_path, "a")
+      $stderr.reopen(Superkick.config.log_path, "a")
+      $stdout.sync = true
+      $stderr.sync = true
+    end
+
+    def wait_for_signals(control_server, supervisor)
+      signal_queue = Queue.new
+      %w[TERM INT].each { |sig| Signal.trap(sig) { signal_queue << sig } }
+
+      Superkick.logger.info("server") { "Superkick server ready" }
+
+      loop do
+        break unless signal_queue.empty?
+        sleep 0.5
+      end
+
+      sig = signal_queue.pop
+      Superkick.logger.info("server") { "Received #{sig} — shutting down" }
+
+      control_server.stop
+      supervisor.stop
+    end
+
+    # Probe persisted buffer connections to check if agent processes survived
+    # a server restart. Keep live connections; detach and clean up stale ones.
+    def recover_agents(store, buffer_client)
+      store.each do |agent|
+        path = agent.buffer_socket_path
+        next unless path
+
+        if buffer_client.probe(agent.id)
+          Superkick.logger.info("server") { "Recovered buffer connection for agent #{agent.id}" }
+        else
+          Superkick.logger.info("server") { "Stale buffer connection for agent #{agent.id} — detaching" }
+          agent.detach_path(:buffer_socket_path)
+          FileUtils.rm_f(path)
+        end
+      end
+    end
+
+    def validate_workflow_configs
+      spawners = Superkick.config.spawners
+      return if spawners.empty?
+
+      cycles = Spawn::WorkflowValidator.validate(spawners)
+      cycles.each do |cycle|
+        names = cycle.map(&:to_s).join(" -> ")
+        involved = cycle.uniq
+
+        if involved.any? { |name| spawners.dig(name, :allow_cycles) }
+          Superkick.logger.warn("server") { "Workflow cycle detected (allowed): #{names}" }
+        else
+          Superkick.logger.error("server") { "Workflow cycle detected: #{names} — disabling involved spawners" }
+          involved.each { |name| spawners.delete(name) }
+        end
+      end
+
+      return if spawners.empty?
+
+      # Require max_iterations on cyclic spawners — without a limit, cycles recurse forever
+      missing = Spawn::WorkflowValidator.cyclic_spawners_without_iteration_limit(spawners)
+      missing.each do |name|
+        Superkick.logger.error("server") {
+          "Spawner #{name} has allow_cycles: true but no max_iterations — " \
+          "disabling to prevent infinite recursion. Set max_iterations on the spawner."
+        }
+        spawners.delete(name)
+      end
+    end
+
+    def build_attach_relay_store
+      config = {
+        replay_buffer_size: Superkick.config.attach_replay_buffer_size,
+        max_connections: Superkick.config.attach_max_connections,
+        rw_idle_timeout: Superkick.config.attach_rw_idle_timeout
+      }
+      Hosted::Attach::RelayStore.new(config:)
+    end
+
+    def cleanup
+      FileUtils.rm_f(Superkick.config.pid_path)
+      FileUtils.rm_f(Superkick.config.socket_path)
+      Superkick.logger.info("server") { "Superkick server stopped" }
+    end
+  end
+end

data/lib/superkick/session_recorder.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Records complete, timestamped agent sessions (input + output) in the
+  # asciicast v2 format. Recordings enable audit logging and visual playback
+  # via asciinema-player or `asciinema play`.
+  #
+  # Thread-safe — three PtyProxy threads (proxy_stdin, proxy_output,
+  # drain_inject_queue) write concurrently via Mutex.
+  #
+  # Lifecycle follows OutputLogger: create → start → record_* → close.
+  class SessionRecorder
+    MAX_SIZE = 100 * 1024 * 1024 # 100 MB default
+
+    def initialize(agent_id:, width: 120, height: 40, max_size: MAX_SIZE,
+      recordings_dir: Superkick.config.recordings_dir, store: nil)
+      @path = File.join(recordings_dir, "#{agent_id}.cast")
+      @agent_id = agent_id
+      @width = width
+      @height = height
+      @max_size = max_size
+      @store = store
+      @file = nil
+      @bytes_written = 0
+      @start_time = nil
+      @mutex = Mutex.new
+    end
+
+    def start
+      FileUtils.mkdir_p(File.dirname(@path))
+      @file = File.open(@path, "ab")
+      @file.sync = true
+      @bytes_written = @file.size
+      @start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      write_header
+      self
+    end
+
+    def record_output(data)
+      record_event("o", data)
+    end
+
+    def record_input(data)
+      record_event("i", data)
+    end
+
+    def resize(width, height)
+      @mutex.synchronize do
+        return unless @file
+
+        @width = width
+        @height = height
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @start_time
+        line = JSON.generate([elapsed.round(6), "r", "#{width}x#{height}"]) + "\n"
+        rotate! if @bytes_written + line.bytesize > @max_size
+        @file.write(line)
+        @bytes_written += line.bytesize
+      end
+    end
+
+    def close
+      @mutex.synchronize do
+        @file&.close
+        @file = nil
+      end
+      @store&.upload(agent_id: @agent_id, path: @path)
+    end
+
+    attr_reader :path
+
+    private
+
+    def write_header
+      header = {
+        version: 2,
+        width: @width,
+        height: @height,
+        timestamp: Time.now.to_i,
+        env: {"TERM" => ENV.fetch("TERM", "xterm-256color")}
+      }
+      line = JSON.generate(header) + "\n"
+      @file.write(line)
+      @bytes_written += line.bytesize
+    end
+
+    def record_event(type, data)
+      @mutex.synchronize do
+        return unless @file
+
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @start_time
+        line = JSON.generate([elapsed.round(6), type, data.b.force_encoding("UTF-8")]) + "\n"
+        rotate! if @bytes_written + line.bytesize > @max_size
+        @file.write(line)
+        @bytes_written += line.bytesize
+      end
+    end
+
+    def rotate!
+      @file.close
+      rotated = "#{@path}.1"
+      FileUtils.rm_f(rotated)
+      File.rename(@path, rotated)
+      @file = File.open(@path, "ab")
+      @file.sync = true
+      @bytes_written = 0
+    end
+
+    # Abstract upload interface for completed recordings.
+    # Local mode uses Noop; hosted mode uses an HTTP implementation.
+    class Store
+      def upload(agent_id:, path:)
+        raise NotImplementedError, "#{self.class}#upload not implemented"
+      end
+    end
+
+    # Local mode — recordings stay on disk, no upload.
+    class Store::Noop < Store
+      def upload(agent_id:, path:) = nil
+    end
+
+    # Hosted mode — uploads the completed .cast file to the hosted server
+    # via multipart POST. Uses faraday-multipart to stream the file without
+    # loading it entirely into memory.
+    class Store::Http < Store
+      def initialize(server_url:, api_key:, connection: nil)
+        @server_url = server_url
+        @api_key = api_key
+        @connection = connection || build_connection
+      end
+
+      def upload(agent_id:, path:)
+        return unless File.exist?(path)
+
+        payload = {
+          file: Faraday::Multipart::FilePart.new(path, "application/x-asciicast")
+        }
+        @connection.post("/api/v1/agents/#{agent_id}/recording", payload)
+      rescue => e
+        Superkick.logger.warn("session_recorder") { "Recording upload failed for #{agent_id}: #{e.message}" }
+        nil
+      end
+
+      private
+
+      def build_connection
+        Faraday.new(url: @server_url) do |f|
+          f.request :authorization, "Bearer", @api_key
+          f.request :multipart
+          f.adapter Faraday.default_adapter
+        end
+      end
+    end
+  end
+end

data/lib/superkick/setup.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Setup — generates a well-documented config.yml from user selections.
+  #
+  # Encapsulates config generation logic separate from the Thor command
+  # so it can be tested independently.
+  class Setup
+    HEADER = <<~YAML
+      # Superkick configuration
+      # Generated by `superkick setup` on %<date>s
+      # Docs: https://github.com/admtnnr/superkick
+    YAML
+
+    SETTINGS_SECTION = <<~YAML
+      # ── Settings ─────────────────────────────────────────────
+      # Uncomment to customize. Defaults are shown.
+      # superkick:
+      #   poll_interval: 30        # seconds between monitor ticks
+      #   idle_threshold: 5.0      # seconds CLI must be idle before injection
+      #   log_level: info          # debug, info, warn, error
+    YAML
+
+    def initialize(base_dir: nil)
+      @base_dir = base_dir || Superkick.config.base_dir
+    end
+
+    # Returns Array of { name:, cli_command:, installed: } for each registered driver.
+    def detect_drivers
+      Driver.registered.map do |name, klass|
+        instance = klass.new
+        cli_command = instance.cli_command
+        installed = command_installed?(cli_command)
+        {name:, cli_command:, installed:}
+      end
+    end
+
+    # Returns Array of { type:, label:, description: } for each monitor with setup_label.
+    def available_monitors
+      collect_available(Monitor.registered)
+    end
+
+    # Returns Array of { type:, label:, description: } for each spawner with setup_label.
+    def available_spawners
+      collect_available(Spawner.registered)
+    end
+
+    # Returns Array of { type:, label:, description: } for each notifier with setup_label.
+    def available_notifiers
+      collect_available(Notifier.registered)
+    end
+
+    # Returns Array of { type:, label:, description: } for each repository source with setup_label.
+    def available_repository_sources
+      collect_available(RepositorySource.registered)
+    end
+
+    # Assembles the final config.yml string from selected components.
+    def generate_config(driver:, monitors: [], spawners: [], notifiers: [], repository_sources: [])
+      parts = []
+      parts << format(HEADER, date: Date.today.iso8601)
+      parts << "driver: #{driver}\n"
+
+      append_monitors_section(parts, monitors)
+      append_spawners_section(parts, spawners)
+      append_notifications_section(parts, notifiers)
+      append_repositories_section(parts, repository_sources)
+      parts << SETTINGS_SECTION
+
+      parts.join("\n")
+    end
+
+    private
+
+    def collect_available(registry)
+      registry.filter_map do |type, klass|
+        label = klass.setup_label
+        next unless label
+
+        description = klass.respond_to?(:description) ? klass.description : nil
+        {type:, label:, description:}
+      end
+    end
+
+    def command_installed?(command)
+      system("which", command, out: File::NULL, err: File::NULL)
+    end
+
+    def append_monitors_section(parts, monitor_types)
+      return if monitor_types.empty?
+
+      snippets = monitor_types.filter_map { lookup_setup_config(Monitor, it) }
+      return if snippets.empty?
+
+      parts << <<~YAML
+        # ── Monitors ─────────────────────────────────────────────
+        # Monitors watch external services and inject context into your AI CLI.
+        # Config values like repo and branch are auto-detected at runtime.
+        monitors:
+      YAML
+      snippets.each { parts << indent(it, 2) }
+    end
+
+    def append_spawners_section(parts, spawner_types)
+      return if spawner_types.empty?
+
+      snippets = spawner_types.filter_map { lookup_setup_config(Spawner, it) }
+      return if snippets.empty?
+
+      parts << <<~YAML
+        # ── Spawners ─────────────────────────────────────────────
+        # Spawners watch external services and spawn new agents automatically.
+        spawners:
+      YAML
+      snippets.each { parts << indent(it, 2) }
+    end
+
+    def append_notifications_section(parts, notifier_types)
+      return if notifier_types.empty?
+
+      snippets = notifier_types.filter_map { lookup_setup_config(Notifier, it) }
+      return if snippets.empty?
+
+      parts << <<~YAML
+        # ── Notifications ────────────────────────────────────────
+        # Notifications fire after injections and agent lifecycle events.
+        notifications:
+      YAML
+      snippets.each { parts << indent(it, 2) }
+    end
+
+    def append_repositories_section(parts, source_types)
+      return if source_types.empty?
+
+      snippets = source_types.filter_map { lookup_setup_config(RepositorySource, it) }
+      return if snippets.empty?
+
+      parts << <<~YAML
+        # ── Repositories ─────────────────────────────────────────
+        # Repository sources for team planning and spawned agent workspaces.
+        repositories:
+      YAML
+      snippets.each { parts << indent(it, 2) }
+    end
+
+    def lookup_setup_config(registry_class, type)
+      klass = registry_class.lookup(type)
+      klass.setup_config
+    rescue ArgumentError
+      nil
+    end
+
+    def indent(text, spaces)
+      prefix = " " * spaces
+      text.lines.map { |line|
+        line.strip.empty? ? "\n" : "#{prefix}#{line}"
+      }.join
+    end
+  end
+end