superkick 0.1.0

data/exe/superkick

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/superkick"
+
+Superkick::CLI.start(ARGV)

data/lib/superkick/agent/runtime.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Superkick
+  class Agent
+    # Runtime — abstract base class for agent process runtimes.
+    #
+    # A runtime knows how to provision a compute environment for an agent
+    # process, terminate it, and check whether it's still alive. The
+    # AgentSpawner delegates to a Runtime instead of calling Process.spawn
+    # directly.
+    #
+    # Subclass contract:
+    #   self.type                       → unique Symbol (e.g. :local, :docker)
+    #   provision(agent_id:, config:)   → Handle (opaque lifecycle handle)
+    #   terminate(handle:)              → nil
+    #   alive?(handle:)                 → Boolean
+    #   metadata(handle:)               → Hash (optional, default {})
+    #
+    # Subclasses register themselves:
+    #   Superkick::Agent::Runtime.register(MyRuntime)
+    class Runtime
+      # ── Registry (stores classes, keyed by type) ─────────────────────────
+      @registry = {}
+
+      class << self
+        include Superkick::Registry
+
+        def register(runtime_class)
+          key = runtime_class.type
+          raise ArgumentError, "Agent::Runtime :#{key} already registered" if @registry.key?(key)
+          @registry[key] = runtime_class
+        end
+
+        def lookup(name)
+          @registry[name.to_sym] or raise ArgumentError, "Unknown agent runtime: #{name.inspect}"
+        end
+
+        def registered
+          @registry.dup.freeze
+        end
+      end
+
+      # ── Instance interface ───────────────────────────────────────────────
+
+      def self.type
+        raise NotImplementedError, "#{self}.type not implemented"
+      end
+
+      # Provision a compute environment and start an agent process in it.
+      #
+      # @param agent_id [String]
+      # @param config [Hash] { env:, command:, working_dir: }
+      # @return [Object] opaque handle for lifecycle management
+      def provision(agent_id:, config:)
+        raise NotImplementedError, "#{self.class}#provision not implemented"
+      end
+
+      # Terminate the agent's compute environment.
+      #
+      # @param handle [Object] handle returned by #provision
+      def terminate(handle:)
+        raise NotImplementedError, "#{self.class}#terminate not implemented"
+      end
+
+      # Check if the agent's compute environment is still running.
+      #
+      # @param handle [Object] handle returned by #provision
+      # @return [Boolean]
+      def alive?(handle:)
+        raise NotImplementedError, "#{self.class}#alive? not implemented"
+      end
+
+      # Return runtime-specific metadata for the agent.
+      #
+      # @param handle [Object] handle returned by #provision
+      # @return [Hash]
+      def metadata(handle:)
+        {}
+      end
+    end
+  end
+end

data/lib/superkick/agent/runtimes/local.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Superkick
+  class Agent
+    class Runtime
+      # Local runtime — spawns agent processes on the same machine via
+      # Process.spawn. This is the default runtime for local and on-prem
+      # deployments.
+      class Local < Runtime
+        Handle = Data.define(:pid)
+
+        def self.type = :local
+
+        def initialize(**) = nil
+
+        # Spawn a local process.
+        #
+        # @param agent_id [String]
+        # @param config [Hash] { env: Hash, command: Array, working_dir: String }
+        # @return [Handle]
+        def provision(agent_id:, config:)
+          pid = Process.spawn(
+            config[:env] || {},
+            *config[:command],
+            chdir: config[:working_dir],
+            in: File::NULL,
+            out: File::NULL,
+            err: File::NULL
+          )
+          Process.detach(pid)
+
+          Superkick.logger.info("runtime:local") { "Started agent PID #{pid} for #{agent_id} in #{config[:working_dir]}" }
+          Handle.new(pid:)
+        end
+
+        # Send SIGTERM, then SIGKILL after 10 seconds if still alive.
+        #
+        # @param handle [Handle]
+        def terminate(handle:)
+          Process.kill("TERM", handle.pid)
+          Thread.new do
+            sleep 10
+            begin
+              Process.kill("KILL", handle.pid)
+            rescue Errno::ESRCH
+              nil
+            end
+          end
+        rescue Errno::ESRCH
+          nil
+        end
+
+        # Check if the process is still running via signal 0.
+        #
+        # @param handle [Handle]
+        # @return [Boolean]
+        def alive?(handle:)
+          Process.kill(0, handle.pid)
+          true
+        rescue Errno::ESRCH
+          false
+        end
+
+        # @param handle [Handle]
+        # @return [Hash]
+        def metadata(handle:)
+          {pid: handle.pid}
+        end
+      end
+    end
+  end
+end
+
+Superkick::Agent::Runtime.register(Superkick::Agent::Runtime::Local)

data/lib/superkick/agent/runtimes.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "runtime"
+require_relative "runtimes/local"

data/lib/superkick/agent.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Canonical, live agent object.  Holds its own state and writes it to its
+  # own JSON file on every mutation.  Monitor thread lifecycle is managed by
+  # Supervisor — Agent is a pure state + persistence object.
+  class Agent
+    TRANSIENT_PATH_KEYS = %i[buffer_socket_path output_log_path attach_socket_path recording_path].freeze
+
+    attr_reader :id, :registered_at, :last_notified_at, :monitors, :notifiers, :spawn_info,
+      :goal_status, :goal_summary, :claimed_at, :cost, :team_id, :team_role, :role, :working_dir,
+      :environment
+    attr_writer :spawn_info
+
+    def initialize(id:, registered_at:, last_notified_at: nil, monitors: {}, notifiers: {},
+      transient_paths: {}, spawn_info: nil, goal_status: nil, goal_summary: nil, claimed_at: nil,
+      team_id: nil, team_role: nil, role: nil, working_dir: nil, environment: nil, file_path: nil)
+      @id = id
+      @registered_at = registered_at
+      @last_notified_at = last_notified_at
+      @monitors = monitors
+      @notifiers = notifiers
+      @file_path = file_path
+      @persist_mutex = Mutex.new
+      @transient_paths = transient_paths
+      @spawn_info = spawn_info
+      @goal_status = goal_status
+      @goal_summary = goal_summary
+      @claimed_at = claimed_at
+      @team_id = team_id
+      @team_role = team_role&.to_sym
+      @role = role
+      @working_dir = working_dir
+      @environment = environment
+      @cost = CostAccumulator.new
+    end
+
+    # Transient resource paths (buffer socket, output log, attach socket).
+    # Attached/detached by the agent process over IPC, persisted to JSON.
+
+    def attach_path(key, value)
+      @transient_paths[key] = value
+      persist
+    end
+
+    def detach_path(key)
+      @transient_paths.delete(key)
+      persist
+    end
+
+    def path(key)
+      @transient_paths[key]
+    end
+
+    # Convenience readers — keep call sites concise.
+    def buffer_socket_path = path(:buffer_socket_path)
+
+    def output_log_path = path(:output_log_path)
+
+    def attach_socket_path = path(:attach_socket_path)
+
+    def recording_path = path(:recording_path)
+
+    # Returns the config hash for a single named monitor, or nil.
+    def monitor_config(name)
+      @monitors[name.to_sym]
+    end
+
+    # Returns the config hash for a single named notifier, or nil.
+    def notifier_config(name)
+      @notifiers[name.to_sym]
+    end
+
+    # --- Mutations -----------------------------------------------------------
+
+    def set_monitor_config(name, config)
+      @monitors[name.to_sym] = config
+      persist
+    end
+
+    def set_monitor_field(name, key, value)
+      (@monitors[name.to_sym] ||= {})[key.to_sym] = value
+      persist
+    end
+
+    def remove_monitor(name)
+      @monitors.delete(name.to_sym)
+      persist
+    end
+
+    def set_notifier_config(name, config)
+      @notifiers[name.to_sym] = config
+      persist
+    end
+
+    def remove_notifier(name)
+      @notifiers.delete(name.to_sym)
+      persist
+    end
+
+    def set_last_notified
+      @last_notified_at = Time.now.iso8601
+      persist
+    end
+
+    def set_goal_status(status)
+      @goal_status = status
+      persist
+    end
+
+    def set_goal_summary(summary)
+      @goal_summary = summary
+      persist
+    end
+
+    def claim!
+      @claimed_at = Time.now.iso8601
+      persist
+    end
+
+    def unclaim!
+      @claimed_at = nil
+      persist
+    end
+
+    def claimed?
+      !@claimed_at.nil?
+    end
+
+    def set_team(team_id:, team_role:)
+      @team_id = team_id
+      @team_role = team_role&.to_sym
+      persist
+    end
+
+    def set_role(role)
+      @role = role
+      persist
+    end
+
+    def set_working_dir(dir)
+      @working_dir = dir
+      persist
+    end
+
+    def set_environment(env)
+      @environment = env
+      persist
+    end
+
+    # Write current state to disk atomically.  No-op when file_path is nil.
+    def persist
+      return unless @file_path
+
+      @persist_mutex.synchronize do
+        tmp = "#{@file_path}.tmp"
+        File.write(tmp, JSON.pretty_generate(to_h))
+        File.rename(tmp, @file_path)
+      end
+    end
+
+    # Serialize to the plain-hash form stored in the JSON file.
+    def to_h
+      h = {
+        registered_at: @registered_at,
+        last_notified_at: @last_notified_at,
+        monitors: @monitors,
+        notifiers: @notifiers
+      }
+      TRANSIENT_PATH_KEYS.each { |k| h[k] = @transient_paths[k] if @transient_paths[k] }
+      h[:spawn_info] = @spawn_info if @spawn_info
+      h[:goal_status] = @goal_status if @goal_status
+      h[:goal_summary] = @goal_summary if @goal_summary
+      h[:claimed_at] = @claimed_at if @claimed_at
+      h[:team_id] = @team_id if @team_id
+      h[:team_role] = @team_role if @team_role
+      h[:role] = @role if @role
+      h[:working_dir] = @working_dir if @working_dir
+      h[:environment] = @environment if @environment
+      cost_data = @cost.to_h
+      h[:cost] = cost_data if cost_data[:total_tokens_in] > 0 || cost_data[:total_cost_usd] > 0
+      h
+    end
+
+    def self.from_h(id, hash, file_path: nil)
+      paths = {}
+      TRANSIENT_PATH_KEYS.each { |k| paths[k] = hash[k] if hash[k] }
+
+      new(
+        id:,
+        registered_at: hash[:registered_at],
+        last_notified_at: hash[:last_notified_at],
+        monitors: hash[:monitors] || {},
+        notifiers: hash[:notifiers] || {},
+        transient_paths: paths,
+        spawn_info: hash[:spawn_info],
+        goal_status: hash[:goal_status],
+        goal_summary: hash[:goal_summary],
+        claimed_at: hash[:claimed_at],
+        team_id: hash[:team_id],
+        team_role: hash[:team_role],
+        role: hash[:role],
+        working_dir: hash[:working_dir],
+        environment: hash[:environment],
+        file_path:
+      )
+    end
+  end
+end

data/lib/superkick/agent_store.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "time"
+
+module Superkick
+  # Thread-safe agent registry backed by a per-agent JSON file under
+  # agents_dir.  Holds live Agent objects; mutations on an Agent
+  # write directly to that agent's file with no involvement from the store.
+  class AgentStore
+    include Enumerable
+
+    def initialize(dir = Superkick.config.agents_dir)
+      @dir = dir
+      @mutex = Mutex.new
+      FileUtils.mkdir_p(dir)
+      @data = load_from_disk
+    end
+
+    # --- Agent lifecycle -------------------------------------------------
+
+    def add(agent_id, monitors: {})
+      id = agent_id.to_s
+      raise ArgumentError, "Agent ID '#{id}' already exists" if @mutex.synchronize { @data.key?(id) }
+      agent = Agent.new(
+        id:,
+        registered_at: Time.now.iso8601,
+        monitors:,
+        file_path: agent_file(id)
+      )
+      @mutex.synchronize { @data[id] = agent }
+      agent.persist
+      agent
+    end
+
+    def remove(agent_id)
+      id = agent_id.to_s
+      agent = @mutex.synchronize { @data.delete(id) }
+      FileUtils.rm_f(agent_file(id))
+      agent
+    end
+
+    def has?(agent_id)
+      @mutex.synchronize { @data.key?(agent_id.to_s) }
+    end
+
+    # Returns the live Agent for the given id, or nil.
+    def get(agent_id)
+      @mutex.synchronize { @data[agent_id.to_s] }
+    end
+
+    # Yields each Agent; Enumerable methods (map, select, …) come free.
+    def each
+      agents = @mutex.synchronize { @data.values.dup }
+      agents.each { yield it }
+    end
+
+    # Returns all agents belonging to the given team.
+    def team(team_id)
+      select { it.team_id == team_id }
+    end
+
+    # Returns true if any agent belongs to the given team.
+    def team_exists?(team_id)
+      any? { it.team_id == team_id }
+    end
+
+    private
+
+    def agent_file(id)
+      File.join(@dir, "#{id}.json")
+    end
+
+    def load_from_disk
+      Dir.glob(File.join(@dir, "*.json")).each_with_object({}) do |path, h|
+        id = File.basename(path, ".json")
+        raw = JSON.parse(File.read(path), symbolize_names: true)
+        h[id] = Agent.from_h(id, raw, file_path: path)
+      rescue JSON::ParserError
+        Superkick.logger.warn("agent_store") { "Corrupt agent file — skipping: #{path}" }
+      end
+    end
+  end
+end

data/lib/superkick/attach/client.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "io/console"
+require "socket"
+
+module Superkick
+  module Attach
+    @clients = {}
+    extend ClientRegistry
+
+    # CLI-side attach session.  Connects to an agent, enters raw terminal
+    # mode, and streams output to the user's terminal.
+    # In read-write mode, keystrokes are forwarded to the PTY.
+    #
+    # The default implementation uses a Unix socket. In hosted mode, a
+    # subclass (Hosted::Attach::Client) uses a WebSocket.
+    #
+    # Use Attach.client_from to construct the right implementation for the
+    # configured server type.
+    #
+    # Escape sequences (default prefix: Ctrl-A):
+    #   d — detach
+    #   c — claim agent (pause autonomous operation)
+    #   u — unclaim agent (resume autonomous operation)
+    #   w — request RW promotion (only if slot is vacant)
+    #   W — forced RW promotion (demotes existing RW holder)
+    #   r — voluntary demotion to read-only
+    class Client
+      CTRL_KEY_NAMES = Hash.new { |_, byte| "0x#{byte.to_s(16).rjust(2, "0")}" }.tap do |h|
+        (1..26).each { |i| h[i] = "Ctrl-#{(i + 64).chr}" }
+      end.freeze
+
+      def self.from(agent_id:, config: Superkick.config, mode: :ro, escape_key: "\x01", force: false)
+        socket_path = File.join(config.run_dir, "attach-#{agent_id}.sock")
+        new(socket_path:, mode:, escape_key:, force:)
+      end
+
+      def initialize(socket_path: nil, mode: :ro, escape_key: "\x01", force: false)
+        @mode = mode
+        @escape_key = escape_key.ord
+        @force = force
+        @prev_escape_byte = nil
+
+        if socket_path
+          @socket = UNIXSocket.new(socket_path)
+        end
+      end
+
+      # Blocking — returns exit code (0 on clean detach, 1 on error).
+      def run
+        # Send hello
+        hello = {mode: @mode.to_s}
+        hello[:force] = true if @force && @mode == :rw
+        write_json_frame(Protocol::HELLO, hello)
+
+        # Read meta (or error)
+        frame = read_frame
+        if frame && frame[0] == Protocol::ERROR
+          err = Protocol.decode_json(frame[1])
+          warn "attach: #{err[:message]}"
+          return 1
+        end
+
+        if frame && frame[0] == Protocol::META
+          meta = Protocol.decode_json(frame[1])
+          print_banner(meta)
+        end
+
+        # Read history
+        frame = read_frame
+        if frame && frame[0] == Protocol::HISTORY
+          $stdout.write(frame[1])
+          $stdout.flush
+        end
+
+        # Start output reader thread
+        output_thread = Thread.new { read_output }
+
+        # All clients use the same input forwarding loop.
+        # RO clients' keystrokes are discarded server-side (except COMMAND frames).
+        forward_stdin
+
+        output_thread.kill
+        0
+      rescue Errno::ENOENT, Errno::ECONNREFUSED
+        warn "attach: Cannot connect to agent (is it running?)"
+        1
+      ensure
+        close
+        restore_terminal
+      end
+
+      # Transport methods — default implementation uses Unix socket with Protocol framing.
+
+      def read_frame
+        Protocol.read_frame(@socket)
+      end
+
+      def write_frame(type, data)
+        Protocol.write_frame(@socket, type, data)
+      end
+
+      def write_json_frame(type, hash)
+        Protocol.write_json_frame(@socket, type, hash)
+      end
+
+      def close
+        @socket&.close
+      rescue IOError
+        nil
+      end
+
+      private
+
+      def print_banner(meta)
+        prefix = CTRL_KEY_NAMES[@escape_key]
+        warn "Attached to agent #{meta[:agent_id]} " \
+             "[#{(@mode == :rw) ? "read-write" : "read-only"}]"
+        warn "Detach: #{prefix}, d | RW: #{prefix}, w | " \
+             "Force RW: #{prefix}, W | RO: #{prefix}, r | " \
+             "Claim: #{prefix}, c | Unclaim: #{prefix}, u"
+      end
+
+      def read_output
+        loop do
+          frame = read_frame
+          break unless frame
+
+          type, payload = frame
+          case type
+          when Protocol::OUTPUT
+            $stdout.write(payload)
+            $stdout.flush
+          when Protocol::META
+            # Updated metadata (future use)
+          when Protocol::NOTIFY
+            msg = Protocol.decode_json(payload)
+            warn "\nattach: #{msg[:message]}"
+          when Protocol::ERROR
+            err = Protocol.decode_json(payload)
+            warn "\nattach: #{err[:message]}"
+            break
+          end
+        end
+      rescue IOError, Errno::EPIPE, Errno::ECONNRESET
+        warn "\nSession disconnected."
+      end
+
+      def forward_stdin
+        @prev_escape_byte = nil
+
+        setup_winch_handler
+
+        $stdin.raw do
+          loop do
+            chunk = $stdin.readpartial(4096)
+
+            action = detect_escape(chunk)
+            case action
+            when :detach
+              warn "\nDetached."
+              break
+            when :claim
+              send_command("claim")
+              warn "\nClaim requested."
+              next
+            when :unclaim
+              send_command("unclaim")
+              warn "\nUnclaim requested."
+              next
+            when :promote_rw
+              send_command("promote_rw")
+              next
+            when :force_promote_rw
+              send_command("force_promote_rw")
+              next
+            when :demote_ro
+              send_command("demote_ro")
+              next
+            end
+
+            write_frame(Protocol::INPUT, chunk)
+          end
+        end
+      rescue IOError, Errno::EIO
+        # stdin closed or agent ended
+      end
+
+      # Detect escape sequences: Ctrl-A prefix followed by a command byte.
+      def detect_escape(chunk)
+        chunk.each_byte do |b|
+          if @prev_escape_byte == @escape_key
+            @prev_escape_byte = nil
+            case b
+            when 0x64 then return :detach          # 'd'
+            when 0x63 then return :claim           # 'c'
+            when 0x75 then return :unclaim         # 'u'
+            when 0x77 then return :promote_rw      # 'w'
+            when 0x57 then return :force_promote_rw # 'W'
+            when 0x72 then return :demote_ro       # 'r'
+              # else: not a recognized escape — fall through
+            end
+          else
+            @prev_escape_byte = (b == @escape_key) ? b : nil
+          end
+        end
+        nil
+      end
+
+      # For backwards compatibility — tests may call this directly
+      def detect_detach(chunk)
+        detect_escape(chunk) == :detach
+      end
+
+      def send_command(action)
+        write_json_frame(Protocol::COMMAND, {action:})
+      rescue IOError, Errno::EPIPE
+        nil
+      end
+
+      def setup_winch_handler
+        Signal.trap("WINCH") do
+          rows, cols = begin
+            $stdout.winsize
+          rescue Errno::ENOTTY, Errno::EIO, IOError
+            [24, 80]
+          end
+          begin
+            write_json_frame(Protocol::RESIZE, {rows:, cols:})
+          rescue IOError, Errno::EPIPE
+            nil
+          end
+        end
+      end
+
+      def restore_terminal
+        return unless $stdin.tty?
+
+        $stdin.cooked!
+      rescue Errno::ENOTTY, Errno::EIO, IOError
+        nil
+      end
+    end
+  end
+end