superkick 0.1.0

data/lib/superkick/buffer/server.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "socket"
+require "base64"
+require "fileutils"
+
+module Superkick
+  module Buffer
+    # Per-agent Unix socket server running inside the `superkick agent` process.
+    # The server's Injector and other components send buffer commands here.
+    #
+    # Supported commands (newline-delimited JSON):
+    #   get                → { ok: true, contents: String | nil }
+    #   clear              → { ok: true }
+    #   guards_active      → { ok: true, active: bool, guards: { name => reason } }
+    #   idle_state         → { ok: true, seconds_idle: Float|nil, at_prompt: bool }
+    #   inject             → enqueues base64-decoded bytes onto PtyProxy's inject queue
+    #   enqueue_injection  → enqueues a rendered prompt onto the InjectionQueue
+    #   ping               → { ok: true }
+    class Server
+      def initialize(agent_id:, input_buffer:, pty_proxy:, injection_queue: nil, socket_path: nil)
+        @agent_id = agent_id
+        @input_buffer = input_buffer
+        @pty_proxy = pty_proxy
+        @injection_queue = injection_queue
+        @socket_path = socket_path || Superkick.config.buffer_socket_path(agent_id)
+        @server = nil
+        @thread = nil
+      end
+
+      def start
+        FileUtils.mkdir_p(File.dirname(@socket_path))
+        FileUtils.rm_f(@socket_path)
+        @server = UNIXServer.new(@socket_path)
+        @thread = Thread.new { serve }
+        self
+      end
+
+      def stop
+        begin
+          @server&.close
+        rescue IOError, Errno::EBADF
+          nil
+        end
+        begin
+          @thread&.kill
+        rescue ThreadError
+          nil
+        end
+        FileUtils.rm_f(@socket_path)
+      end
+
+      attr_reader :socket_path
+      attr_writer :injection_queue
+
+      private
+
+      def serve
+        loop do
+          client = @server.accept
+          Thread.new(client) { handle(it) }
+        rescue IOError, Errno::EBADF
+          break
+        rescue => e
+          Superkick.logger.error("buffer:#{@agent_id}") { "Buffer::Server accept error: #{e.message}\n#{e.backtrace.first(5).join("\n")}" }
+          break
+        end
+      end
+
+      def handle(raw_connection)
+        connection = Superkick::Connection.new(raw_connection)
+        request = connection.receive_message
+        return unless request
+
+        case request[:command]
+        when "get"
+          contents = @input_buffer.contents
+          connection.reply(contents: contents.empty? ? nil : contents)
+
+        when "clear"
+          @input_buffer.clear
+          connection.reply
+
+        when "guards_active"
+          guards = @input_buffer.guards
+          connection.reply(active: !guards.empty?, guards: guards)
+
+        when "idle_state"
+          connection.reply(@pty_proxy.idle_state)
+
+        when "inject"
+          bytes = Base64.decode64(request[:data].to_s)
+          @pty_proxy.enqueue_inject(bytes)
+          connection.reply
+
+        when "enqueue_injection"
+          raise "No injection queue available" unless @injection_queue
+
+          @injection_queue.enqueue(
+            id: request[:id],
+            prompt: request[:prompt],
+            monitor_type: request[:monitor_type],
+            monitor_name: request[:monitor_name],
+            priority: request[:priority]&.to_sym || :normal,
+            ttl: request[:ttl] || InjectionQueue::DEFAULT_TTL,
+            supersede_key: request[:supersede_key]
+          )
+          connection.reply(status: "queued")
+
+        when "ping"
+          connection.reply
+
+        else
+          raise "unknown command: #{request[:command]}"
+        end
+      rescue => e
+        begin
+          connection&.error(e.message)
+        rescue IOError, Errno::EPIPE, Errno::ENOTCONN
+          nil
+        end
+      ensure
+        connection&.close
+      end
+    end
+  end
+end

data/lib/superkick/cli/agent.rb

@@ -0,0 +1,524 @@
+# frozen_string_literal: true
+
+module Superkick
+  class CLI < Thor
+    class Agent < Thor
+      package_name "superkick agent"
+
+      desc "start [-- ARGS]", "Start an AI coding CLI as a Superkick agent"
+      long_desc <<~DESC
+        Wrap an AI coding CLI (Claude Code, Copilot, Codex, Gemini, Goose) in a
+        PTY proxy that enables context injection from monitors. The Superkick
+        server must be running for injection to work, but the agent starts fine
+        without it.
+
+        The driver is auto-detected from config.yml or can be set with --driver.
+        Any arguments after -- are forwarded to the underlying CLI.
+
+        Use --team to join an existing agent team as a human member. Team members
+        receive digest injections of teammate activity and can communicate via the
+        team log. Use --no-log to disable digest injections while remaining on the
+        team.
+
+        Examples:
+
+          superkick agent start
+
+          superkick agent start -d copilot -- --workspace ~/projects/api
+
+          superkick agent start --team my-team --role "Code reviewer"
+      DESC
+      option :driver, type: :string, aliases: "-d",
+        desc: "Driver name (claude_code, copilot, codex, gemini)"
+      option :driver_config_dir, type: :string, desc: "Override driver config/settings directory"
+      option :driver_command, type: :string, desc: "Override driver CLI executable"
+      option :team, type: :string, desc: "Join an existing team by team ID"
+      option :role, type: :string, desc: "Human-readable role label (e.g. 'Code reviewer')"
+      option :no_log, type: :boolean, default: false, desc: "Disable team log digest injections"
+      option :agent_id, type: :string, hide: true
+      option :headless, type: :boolean, default: false, hide: true
+      def start(*args)
+        Superkick.load_config!
+
+        driver_opts = {}
+        driver_opts[:cli_command] = options[:driver_command] if options[:driver_command]
+        driver_opts[:config_dir] = options[:driver_config_dir] if options[:driver_config_dir]
+
+        if options[:driver]
+          Superkick.use(options[:driver].to_sym, **driver_opts)
+        elsif driver_opts.any? && Superkick.driver
+          # Re-initialize current driver with overrides
+          Superkick.use(Superkick.driver.driver_name, **driver_opts)
+        end
+
+        unless Superkick.driver
+          warn "No CLI command configured. Use --driver or set `driver:` in config.yml."
+          exit(1)
+        end
+
+        config = Superkick.config
+        proxy_opts = {
+          command: Superkick.driver.cli_command, args: args,
+          idle_threshold: config.idle_threshold,
+          inject_clear_delay: config.inject_clear_delay
+        }
+        proxy_opts[:agent_id] = options[:agent_id] if options[:agent_id]
+        proxy_opts[:headless] = true if options[:headless]
+        proxy_opts[:team_id] = options[:team] if options[:team]
+        proxy_opts[:role] = options[:role] if options[:role]
+        proxy_opts[:team_log] = !options[:no_log] if options[:team]
+
+        pty_proxy = PtyProxy.new(**proxy_opts)
+        pty_proxy.run
+      end
+
+      desc "list", "List all active agents"
+      option :json, type: :boolean, default: false, desc: "Output as JSON"
+      def list
+        client = Control.client_from
+
+        unless client.alive?
+          $stdout.puts "Superkick server is not running."
+          return
+        end
+
+        result = client.request("list_agents")
+        agents = result[:agents] || []
+
+        if options[:json]
+          $stdout.puts JSON.pretty_generate(agents)
+          return
+        end
+
+        if agents.empty?
+          $stdout.puts "No active agents."
+          return
+        end
+
+        agents.each do |s|
+          status_parts = []
+          status_parts << "pty-connected" if s[:has_buffer]
+          status_parts << "output-log" if s[:has_output_log]
+          status = status_parts.any? ? status_parts.join(", ") : "no-pty"
+
+          $stdout.puts s[:agent_id].to_s
+          $stdout.puts "  Status:        #{status}"
+          $stdout.puts "  Monitors:      #{s[:monitor_count]}"
+          $stdout.puts "  Registered:    #{s[:registered_at]}"
+          $stdout.puts "  Last notified: #{s[:last_notified] || "never"}"
+
+          if s[:output_log_path]
+            size = File.exist?(s[:output_log_path]) ? File.size(s[:output_log_path]) : 0
+            $stdout.puts "  Output log:    #{s[:output_log_path]} (#{human_size(size)})"
+          end
+
+          if s[:spawn_info]
+            si = s[:spawn_info]
+            $stdout.puts "  Spawned by:    #{si[:spawner_name]} (#{si[:event_type]})"
+            $stdout.puts "  Spawned at:    #{si[:spawned_at]}"
+            $stdout.puts "  Duration:      #{human_duration(si[:spawned_at])}" if si[:spawned_at]
+            if si[:parent_agent_id]
+              $stdout.puts "  Workflow from:  #{si[:parent_agent_id]}"
+              $stdout.puts "  Workflow depth: #{si[:workflow_depth]}" if si[:workflow_depth]
+              if si[:workflow_iterations]&.any?
+                iterations = si[:workflow_iterations].map { |k, v| "#{k}:#{v}" }.join(", ")
+                $stdout.puts "  Iterations:     #{iterations}"
+              end
+            end
+          end
+
+          if s[:goal_status]
+            $stdout.puts "  Goal status:   #{s[:goal_status]}"
+          end
+
+          if s[:claimed_at]
+            $stdout.puts "  Claimed at:    #{s[:claimed_at]}"
+          end
+
+          if s[:cost]
+            c = s[:cost]
+            cost_str = "$#{c[:total_cost_usd]}"
+            tokens = "#{c[:total_tokens_in]} in / #{c[:total_tokens_out]} out"
+            $stdout.puts "  Cost:          #{cost_str} (#{tokens})"
+          end
+          $stdout.puts ""
+        end
+      rescue Control::Client::ServerUnavailable
+        $stdout.puts "Superkick server is not running."
+      end
+
+      desc "cost [AGENT_ID]", "Show cost tracking for an agent or all agents"
+      option :json, type: :boolean, default: false, desc: "Output as JSON"
+      def cost(agent_id = nil)
+        client = Control.client_from
+
+        if agent_id
+          result = client.request("get_agent_cost", agent_id:)
+          if options[:json]
+            $stdout.puts JSON.pretty_generate(result)
+          else
+            $stdout.puts agent_id.to_s
+            $stdout.puts "  Cost:       $#{result[:total_cost_usd]}"
+            $stdout.puts "  Tokens in:  #{result[:total_tokens_in]}"
+            $stdout.puts "  Tokens out: #{result[:total_tokens_out]}"
+            $stdout.puts "  Samples:    #{result[:sample_count]}"
+          end
+        else
+          result = client.request("get_cost_summary")
+          agents = result[:agents] || []
+
+          if options[:json]
+            $stdout.puts JSON.pretty_generate(agents)
+            return
+          end
+
+          if agents.empty?
+            $stdout.puts "No cost data recorded."
+            return
+          end
+
+          total_cost = 0.0
+          agents.each do |a|
+            c = a[:cost]
+            total_cost += c[:total_cost_usd]
+            $stdout.puts "#{a[:agent_id]}: $#{c[:total_cost_usd]} " \
+                         "(#{c[:total_tokens_in]} in / #{c[:total_tokens_out]} out)"
+          end
+          $stdout.puts "Total: $#{total_cost.round(4)}"
+        end
+      rescue Control::Client::ServerUnavailable
+        $stdout.puts "Superkick server is not running."
+      end
+
+      desc "log AGENT_ID", "Tail an agent's output log"
+      option :lines, type: :numeric, aliases: "-n", default: 50,
+        desc: "Number of lines to show"
+      option :follow, type: :boolean, aliases: "-f", default: true,
+        desc: "Follow output in real time"
+      def log(agent_id)
+        client = Control.client_from
+        result = client.request("get_output_log_path", agent_id: agent_id)
+        path = result[:path]
+
+        unless path && File.exist?(path)
+          warn "No output log for agent #{agent_id}"
+          warn "(Agent may not be running or output capture is not active)"
+          exit(1)
+        end
+
+        args = ["-n", options[:lines].to_s]
+        args << "-f" if options[:follow]
+        system("tail", *args, path)
+      rescue Control::Client::ServerUnavailable
+        # Fall back to checking the file directly on disk
+        path = File.join(Superkick.config.output_logs_dir, "#{agent_id}.log")
+        unless File.exist?(path)
+          warn "No output log for agent #{agent_id}"
+          exit(1)
+        end
+        args = ["-n", options[:lines].to_s]
+        args << "-f" if options[:follow]
+        system("tail", *args, path)
+      end
+
+      desc "stop AGENT_ID", "Stop a spawned agent"
+      def stop(agent_id)
+        client = Control.client_from
+        reply = client.request("terminate_agent", agent_id: agent_id)
+
+        if reply.success?
+          $stdout.puts "Stopping agent #{agent_id}."
+        else
+          warn "Error: #{reply.error_message}"
+          exit(1)
+        end
+      rescue Control::Client::ServerUnavailable
+        warn "Superkick server is not running."
+        exit(1)
+      end
+
+      desc "attach AGENT_ID", "Attach to a running agent"
+      long_desc <<~DESC
+        Open a live terminal session to a running agent. By default, attaches in
+        read-only mode — you can see the agent's output but cannot type.
+
+        Use -i for read-write mode, which forwards your keystrokes to the agent.
+        Only one client can be read-write at a time. Use -f to force-takeover
+        read-write from another client.
+
+        The escape key (default Ctrl-A) provides session controls:
+
+          Ctrl-A d   Detach from the session
+
+          Ctrl-A r   Request read-write mode (from read-only)
+
+          Ctrl-A o   Demote yourself to read-only
+
+        Read-write sessions auto-demote to read-only after 5 minutes of
+        inactivity (configurable via attach_rw_idle_timeout in config.yml).
+      DESC
+      option :interactive, type: :boolean, aliases: "-i", default: false,
+        desc: "Read-write mode (forward keystrokes to agent)"
+      option :force, type: :boolean, aliases: "-f", default: false,
+        desc: "Force-takeover read-write mode from another client"
+      def attach(agent_id)
+        Superkick.load_config!
+        config = Superkick.config
+        mode = (options[:interactive] || options[:force]) ? :rw : :ro
+        force = options[:force]
+        escape_key = config.attach_escape_key
+
+        if config.server_type == :local
+          socket_path = File.join(config.run_dir, "attach-#{agent_id}.sock")
+
+          unless File.exist?(socket_path)
+            warn "No attach socket for agent #{agent_id}."
+            warn "The agent may not be running, or attach may not be supported."
+            exit(1)
+          end
+        end
+
+        client = Attach.client_from(agent_id:, config:, mode:, escape_key:, force:)
+        exit(client.run)
+      end
+
+      desc "claim AGENT_ID", "Claim a spawned agent (pause autonomous operation)"
+      def claim(agent_id)
+        client = Control.client_from
+        reply = client.request("claim_agent", agent_id:)
+
+        if reply.success?
+          $stdout.puts "Claimed agent #{agent_id}. Goal checking paused."
+        else
+          warn "Error: #{reply.error_message}"
+          exit(1)
+        end
+      rescue Control::Client::ServerUnavailable
+        warn "Superkick server is not running."
+        exit(1)
+      end
+
+      desc "unclaim AGENT_ID", "Release a claimed agent back to autonomous operation"
+      def unclaim(agent_id)
+        client = Control.client_from
+        reply = client.request("unclaim_agent", agent_id:)
+
+        if reply.success?
+          $stdout.puts "Released agent #{agent_id}. Goal checking resumed."
+        else
+          warn "Error: #{reply.error_message}"
+          exit(1)
+        end
+      rescue Control::Client::ServerUnavailable
+        warn "Superkick server is not running."
+        exit(1)
+      end
+
+      desc "report-cost AGENT_ID", "Report cost data for an agent"
+      option :tokens_in, type: :numeric, desc: "Total input tokens"
+      option :tokens_out, type: :numeric, desc: "Total output tokens"
+      option :cost_usd, type: :numeric, desc: "Total cost in USD"
+      def report_cost(agent_id)
+        unless options[:tokens_in] || options[:tokens_out] || options[:cost_usd]
+          warn "At least one of --tokens_in, --tokens_out, or --cost_usd is required."
+          exit(1)
+        end
+
+        client = Control.client_from
+        result = client.request("report_cost",
+          agent_id:,
+          tokens_in: options[:tokens_in],
+          tokens_out: options[:tokens_out],
+          cost_usd: options[:cost_usd],
+          source: :cli_report)
+
+        if result.success?
+          $stdout.puts "Cost recorded for agent #{agent_id}."
+        else
+          warn "Error: #{result.error_message}"
+          exit(1)
+        end
+      rescue Control::Client::ServerUnavailable
+        warn "Superkick server is not running."
+        exit(1)
+      end
+
+      desc "add-monitor AGENT_ID MONITOR_NAME", "Add a monitor to a running agent"
+      long_desc <<~DESC
+        Dynamically add a monitor to a running agent. The monitor type is inferred
+        from the name unless --type is given (e.g. two shell monitors can coexist
+        under different names like "disk_check" and "mem_check").
+
+        Config can be passed as inline JSON/YAML or loaded from a file with the
+        @ prefix:
+
+          superkick agent add-monitor agent-1 disk_check -t shell \\
+            -c '{"command": "./check.sh", "timeout": 30}'
+
+          superkick agent add-monitor agent-1 disk_check \\
+            -c @monitors/disk_check.yml
+
+        Privileged monitor types (configured via privileged_types in config.yml)
+        cannot be added by the AI agent or via this command.
+      DESC
+      option :type, type: :string, aliases: "-t",
+        desc: "Monitor class type (e.g. 'shell'). Inferred from name if omitted."
+      option :config, type: :string, aliases: "-c",
+        desc: "JSON/YAML config string or @filepath"
+      def add_monitor(agent_id, monitor_name)
+        config = parse_config(options[:config])
+        config[:type] = options[:type] if options[:type]
+
+        client = Control.client_from
+        result = client.request("add_monitor",
+          agent_id:,
+          monitor_name:,
+          config:)
+
+        if result.success?
+          $stdout.puts "Monitor #{monitor_name} added to agent #{agent_id}."
+        else
+          warn "Error: #{result.error_message}"
+          exit(1)
+        end
+      rescue Control::Client::ServerUnavailable
+        warn "Superkick server is not running."
+        exit(1)
+      end
+
+      desc "remove-monitor AGENT_ID MONITOR_NAME", "Remove a monitor from a running agent"
+      def remove_monitor(agent_id, monitor_name)
+        client = Control.client_from
+        result = client.request("remove_monitor",
+          agent_id:,
+          monitor_name:)
+
+        if result.success?
+          $stdout.puts "Monitor #{monitor_name} removed from agent #{agent_id}."
+        else
+          warn "Error: #{result.error_message}"
+          exit(1)
+        end
+      rescue Control::Client::ServerUnavailable
+        warn "Superkick server is not running."
+        exit(1)
+      end
+
+      desc "add-notifier AGENT_ID NOTIFIER_NAME", "Add a notifier to a running agent"
+      long_desc <<~DESC
+        Dynamically add a per-agent notifier to a running agent. Per-agent
+        notifiers fire alongside global notifiers for that agent's events only.
+
+        Config can be passed as inline JSON/YAML or loaded from a file with the
+        @ prefix:
+
+          superkick agent add-notifier agent-1 slack_ops -t slack \\
+            -c '{"channel": "#ops"}'
+
+          superkick agent add-notifier agent-1 slack_ops \\
+            -c @notifiers/slack_ops.yml
+
+        Privileged notifier types (configured via notification_privileged_types in
+        config.yml) cannot be added by the AI agent or via this command.
+      DESC
+      option :type, type: :string, aliases: "-t",
+        desc: "Notifier class type (e.g. 'slack'). Inferred from name if omitted."
+      option :config, type: :string, aliases: "-c",
+        desc: "JSON/YAML config string or @filepath"
+      def add_notifier(agent_id, notifier_name)
+        config = parse_config(options[:config])
+        config[:type] = options[:type] if options[:type]
+
+        client = Control.client_from
+        result = client.request("add_notifier",
+          agent_id:,
+          notifier_name:,
+          config:)
+
+        if result.success?
+          $stdout.puts "Notifier #{notifier_name} added to agent #{agent_id}."
+        else
+          warn "Error: #{result.error_message}"
+          exit(1)
+        end
+      rescue Control::Client::ServerUnavailable
+        warn "Superkick server is not running."
+        exit(1)
+      end
+
+      desc "remove-notifier AGENT_ID NOTIFIER_NAME", "Remove a notifier from a running agent"
+      def remove_notifier(agent_id, notifier_name)
+        client = Control.client_from
+        result = client.request("remove_notifier",
+          agent_id:,
+          notifier_name:)
+
+        if result.success?
+          $stdout.puts "Notifier #{notifier_name} removed from agent #{agent_id}."
+        else
+          warn "Error: #{result.error_message}"
+          exit(1)
+        end
+      rescue Control::Client::ServerUnavailable
+        warn "Superkick server is not running."
+        exit(1)
+      end
+
+      default_command :start
+
+      private
+
+      def parse_config(value)
+        return {} unless value
+
+        raw = if value.start_with?("@")
+          path = File.expand_path(value[1..])
+          unless File.exist?(path)
+            warn "Config file not found: #{path}"
+            exit(1)
+          end
+          File.read(path)
+        else
+          value
+        end
+
+        parsed = YAML.safe_load(raw, symbolize_names: true)
+        unless parsed.is_a?(Hash)
+          warn "Config must be a YAML/JSON object, got: #{parsed.class}"
+          exit(1)
+        end
+        parsed
+      rescue Psych::SyntaxError => e
+        warn "Invalid YAML/JSON config: #{e.message}"
+        exit(1)
+      end
+
+      def human_size(bytes)
+        if bytes < 1024
+          "#{bytes} B"
+        elsif bytes < 1024 * 1024
+          "#{(bytes / 1024.0).round(1)} KB"
+        else
+          "#{(bytes / (1024.0 * 1024)).round(1)} MB"
+        end
+      end
+
+      def human_duration(iso8601_start)
+        elapsed = Time.now - Time.iso8601(iso8601_start)
+        return "just now" if elapsed < 1
+
+        parts = []
+        hours = (elapsed / 3600).to_i
+        minutes = ((elapsed % 3600) / 60).to_i
+        seconds = (elapsed % 60).to_i
+
+        parts << "#{hours}h" if hours > 0
+        parts << "#{minutes}m" if minutes > 0
+        parts << "#{seconds}s" if parts.empty?
+        parts.join(" ")
+      rescue
+        "unknown"
+      end
+    end
+  end
+end