superkick 0.1.0

data/lib/superkick/pty_proxy.rb

@@ -0,0 +1,403 @@
+# frozen_string_literal: true
+
+require "pty"
+require "io/console"
+require "securerandom"
+
+module Superkick
+  # PtyProxy wraps an AI coding CLI in a pseudo-terminal so Superkick controls
+  # the terminal directly.  Three internal threads handle:
+  #   1. stdin proxy  — reads raw keystrokes, feeds InputBuffer, forwards to pty
+  #   2. output proxy — reads CLI output, writes to user stdout, tracks idle state
+  #   3. inject queue — drains @inject_queue, writes bytes to pty master
+  #
+  # An InjectionQueue drains rendered prompts from the server, checking
+  # preconditions (idle state, guards) locally before writing to the PTY.
+  #
+  # On startup it creates a Buffer::Server and registers both the agent and the
+  # buffer socket with the server (if running). In hosted mode, it also opens
+  # a persistent WebSocket to the server for receiving injection commands.
+  class PtyProxy
+    attr_reader :agent_id
+
+    def initialize(command:, idle_threshold:, inject_clear_delay:, args: [], agent_id: nil,
+      headless: false, team_id: nil, role: nil, team_log: true)
+      @command = command
+      @args = args
+      agent_id ||= "agent-#{SecureRandom.hex(4)}"
+      @agent_id = agent_id.to_s
+      @headless = headless
+      @team_id = team_id
+      @role = role
+      @team_log = team_log
+
+      @input_buffer = InputBuffer.new
+      @inject_queue = Queue.new
+      @output_mutex = Mutex.new
+      @last_output_at = nil
+      @at_prompt = false
+
+      @control_client = Control.client_from
+
+      @injection_queue = InjectionQueue.new(
+        pty_proxy: self, idle_threshold:, inject_clear_delay:, control_client: @control_client
+      )
+
+      @buffer_server = Buffer::Server.new(
+        agent_id: @agent_id,
+        input_buffer: @input_buffer,
+        pty_proxy: self,
+        injection_queue: @injection_queue
+      )
+      @buffer_bridge = nil
+      @attach_server = Attach::Server.new(
+        agent_id: @agent_id,
+        pty_proxy: self,
+        control_client: @control_client
+      )
+      @output_logger = OutputLogger.new(agent_id: @agent_id)
+      @session_recorder = if Superkick.config.session_recording_enabled
+        build_session_recorder
+      end
+    end
+
+    # Blocking — returns when the CLI process exits.
+    def run
+      @buffer_server.start
+      @injection_queue.start
+      @attach_server.start
+      @output_logger.start
+      @session_recorder&.start
+      auto_register
+      notify_server(:register_buffer)
+      notify_server(:register_attach)
+      start_buffer_bridge
+      start_attach_bridge
+
+      PTY.spawn({"SUPERKICK_AGENT_ID" => @agent_id}, @command, *@args) do |pty_out, pty_in, pid|
+        @pty_pid = pid
+        @pty_in = pty_in
+
+        unless @headless
+          # Match window size
+          rows, cols = begin
+            $stdout.winsize
+          rescue Errno::ENOTTY, Errno::EIO, IOError
+            [24, 80]
+          end
+          begin
+            pty_in.winsize = [rows, cols]
+          rescue Errno::ENOTTY, Errno::EIO, IOError
+            nil
+          end
+
+          Signal.trap("WINCH") do
+            r, c = begin
+              $stdout.winsize
+            rescue Errno::ENOTTY, Errno::EIO, IOError
+              [24, 80]
+            end
+            begin
+              pty_in.winsize = [r, c]
+            rescue Errno::ENOTTY, Errno::EIO, IOError
+              nil
+            end
+            @session_recorder&.resize(c, r)
+          end
+        end
+
+        threads = []
+        threads << Thread.new { proxy_stdin(pty_in) } unless @headless
+        threads << Thread.new { proxy_output(pty_out) }
+        threads << Thread.new { drain_inject_queue(pty_in) }
+
+        Process.wait(pid)
+        threads.each(&:kill)
+      end
+    rescue PTY::ChildExited
+      # Normal exit
+    ensure
+      @attach_bridge&.stop
+      @buffer_bridge&.stop
+      @injection_queue.stop
+      @attach_server.stop
+      @buffer_server.stop
+      @session_recorder&.close
+      @output_logger.close
+      notify_server(:unregister_attach)
+      notify_server(:unregister_buffer)
+      notify_server(:unregister)
+      @control_client.close
+    end
+
+    # Called by Buffer::Server on `idle_state` command, and by InjectionQueue.
+    def idle_state
+      @output_mutex.synchronize do
+        seconds_idle = @last_output_at ? (Time.now.to_f - @last_output_at) : nil
+        {seconds_idle:, at_prompt: @at_prompt}
+      end
+    end
+
+    # Called by Buffer::Server on `inject` command.
+    def enqueue_inject(bytes)
+      @inject_queue << bytes
+    end
+
+    # Called by InjectionQueue to check if guards are clear.
+    def guards_clear?
+      @input_buffer.guards.empty?
+    end
+
+    # Called by InjectionQueue to read partial user input for restoration.
+    def partial_input
+      @input_buffer.contents
+    end
+
+    # Called by Attach::Server when a read-write client sends a resize frame.
+    def resize(rows, cols)
+      return unless @pty_in
+
+      begin
+        @pty_in.winsize = [rows, cols]
+      rescue Errno::ENOTTY, Errno::EIO, IOError
+        nil
+      end
+      @session_recorder&.resize(cols, rows)
+    end
+
+    private
+
+    # ── Thread bodies ───────────────────────────────────────────────────────
+
+    def proxy_stdin(pty_in)
+      $stdin.raw do
+        loop do
+          chunk = $stdin.readpartial(4096)
+          @input_buffer.append(chunk)
+          pty_in.write(chunk)
+          pty_in.flush
+          @session_recorder&.record_input(chunk)
+        end
+      end
+    rescue IOError, Errno::EIO
+      # stdin closed
+    end
+
+    def proxy_output(pty_out)
+      loop do
+        begin
+          data = pty_out.read_nonblock(4096)
+        rescue IO::WaitReadable
+          IO.select([pty_out])
+          retry
+        end
+
+        unless @headless
+          $stdout.write(data)
+          $stdout.flush
+        end
+        @output_logger.write(data)
+        @session_recorder&.record_output(data)
+        @attach_server.broadcast(data)
+
+        stripped = strip_ansi(data)
+
+        @output_mutex.synchronize do
+          @last_output_at = Time.now.to_f
+          @at_prompt = prompt_match?(stripped)
+          update_guards(stripped)
+        end
+
+        # Cost extraction — runs outside the output mutex
+        extract_cost(stripped)
+      end
+    rescue IOError, Errno::EIO
+      # pty closed (CLI exited)
+    end
+
+    def drain_inject_queue(pty_in)
+      loop do
+        bytes = @inject_queue.pop
+        pty_in.write(bytes)
+        pty_in.flush
+        @session_recorder&.record_input(bytes)
+      end
+    rescue IOError, Errno::EIO
+      # pty closed
+    end
+
+    # ── Helpers ──────────────────────────────────────────────────────────
+
+    ANSI_CSI = /\e\[[0-9;]*[A-Za-z]/
+    ANSI_OSC = /\e\][^\a]*(?:\a|\e\\)/
+    ANSI_MISC = /\e./
+
+    def strip_ansi(text)
+      text.gsub(ANSI_CSI, "").gsub(ANSI_OSC, "").gsub(ANSI_MISC, "")
+    end
+
+    def prompt_match?(stripped_text)
+      return false unless Superkick.driver
+
+      patterns = Superkick.driver.prompt_patterns
+      return false if patterns.empty?
+
+      patterns.any? { it.match?(stripped_text) }
+    end
+
+    def update_guards(stripped_text)
+      return unless Superkick.driver
+
+      Superkick.driver.injection_guards.each do |guard|
+        if guard.match?(stripped_text)
+          @input_buffer.set_guard(guard.name, guard.reason,
+            clear_on_submit: guard.clear_on_submit)
+        end
+      end
+    end
+
+    def extract_cost(stripped_text)
+      return unless Superkick.driver
+
+      patterns = Superkick.driver.cost_patterns
+      return if patterns.empty?
+
+      @cost_extractor ||= CostExtractor.new(patterns:)
+      deltas = @cost_extractor.feed(stripped_text)
+      deltas.each { report_cost(it) }
+    end
+
+    def report_cost(data)
+      @control_client.request("report_cost",
+        agent_id: @agent_id,
+        **data,
+        source: :pty_scrape)
+    rescue Control::Client::ServerUnavailable
+      # Cost tracking is best-effort
+    end
+
+    def notify_server(command, **extra)
+      extras = extra
+      if command == :register_buffer
+        extras[:output_log_path] = @output_logger.path
+        extras[:recording_path] = @session_recorder.path if @session_recorder
+      end
+      @control_client.request(command.to_s, agent_id: @agent_id, **extras)
+    rescue Control::Client::ServerUnavailable
+      # Server not required for `superkick agent` to work
+    end
+
+    def auto_register
+      params = {agent_id: @agent_id, working_dir: Dir.pwd}
+      params[:team_id] = @team_id if @team_id
+      params[:role] = @role if @role
+      params[:team_log] = @team_log
+      result = @control_client.request("register", **params)
+
+      # Multi-step handshake: server responds with environment_request
+      if result.success? && result[:environment_request]
+        executor = EnvironmentExecutor.new(working_dir: Dir.pwd)
+        environment = executor.execute(result[:environment_request])
+        @control_client.request("register_environment",
+          agent_id: @agent_id, environment:)
+      end
+    rescue Control::Client::ServerUnavailable
+      Superkick.logger.info("pty:#{@agent_id}") { "Server not running — agent not registered" }
+    end
+
+    def build_session_recorder
+      store = if Superkick.config.server_type == :hosted
+        server_config = Superkick.config.server
+        SessionRecorder::Store::Http.new(
+          server_url: server_config[:url],
+          api_key: server_config[:api_key]
+        )
+      end
+
+      rows, cols = begin
+        $stdout.winsize
+      rescue Errno::ENOTTY, Errno::EIO, IOError
+        [40, 120]
+      end
+
+      SessionRecorder.new(
+        agent_id: @agent_id,
+        width: cols,
+        height: rows,
+        max_size: Superkick.config.session_recording_max_size,
+        store:
+      )
+    end
+
+    # In hosted mode, start the bridge that connects the local Buffer::Server
+    # to the hosted server over a persistent WebSocket. Buffer commands
+    # (enqueue_injection, idle_state, etc.) flow through this bridge. The local
+    # Buffer::Server still runs for local-mode compatibility.
+    def start_buffer_bridge
+      return unless Superkick.config.server_type == :hosted
+
+      server_config = Superkick.config.server
+      @buffer_bridge = Hosted::Buffer::Bridge.new(
+        agent_id: @agent_id,
+        server_url: server_config[:url],
+        api_key: server_config[:api_key],
+        command_handler: method(:handle_buffer_command)
+      )
+      @buffer_bridge.start
+      Superkick.logger.info("pty:#{@agent_id}") { "Buffer bridge started" }
+    end
+
+    # In hosted mode, start the bridge that connects the local Attach::Server
+    # to the hosted server over a persistent WebSocket. PTY output is
+    # forwarded to the relay; remote user input flows back.
+    def start_attach_bridge
+      return unless Superkick.config.server_type == :hosted
+
+      server_config = Superkick.config.server
+      @attach_bridge = Hosted::Attach::Bridge.new(
+        agent_id: @agent_id,
+        server_url: server_config[:url],
+        api_key: server_config[:api_key],
+        attach_server: @attach_server
+      )
+      @attach_bridge.start
+      Superkick.logger.info("pty:#{@agent_id}") { "Attach bridge started" }
+    end
+
+    # Dispatch a buffer command received over the bridge.
+    # Returns a response hash to send back to the server.
+    def handle_buffer_command(message)
+      case message[:command]
+      when "enqueue_injection"
+        @injection_queue.enqueue(
+          id: message[:id],
+          prompt: message[:prompt],
+          monitor_type: message[:monitor_type],
+          monitor_name: message[:monitor_name],
+          priority: message[:priority]&.to_sym || :normal,
+          ttl: message[:ttl] || InjectionQueue::DEFAULT_TTL,
+          supersede_key: message[:supersede_key]
+        )
+        {ok: true, status: "queued"}
+      when "idle_state"
+        idle_state.merge(ok: true)
+      when "guards_active"
+        guards = @input_buffer.guards
+        {ok: true, active: !guards.empty?, guards: guards}
+      when "get"
+        contents = @input_buffer.contents
+        {ok: true, contents: contents.empty? ? nil : contents}
+      when "inject"
+        bytes = Base64.decode64(message[:data].to_s)
+        enqueue_inject(bytes)
+        {ok: true}
+      when "ping"
+        {ok: true}
+      else
+        {ok: false, error: "unknown command: #{message[:command]}"}
+      end
+    rescue => e
+      {ok: false, error: e.message}
+    end
+  end
+end

data/lib/superkick/registry.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Registry — shared test isolation for class-level plugin registries.
+  #
+  # Include this module in the singleton class of any registry host that
+  # stores plugins in `@registry`.  It provides `with_registry` for
+  # snapshot/restore scoping in tests, replacing ad-hoc deregister/restore
+  # patterns.
+  #
+  # Usage in a registry host:
+  #
+  #   class MyPlugin
+  #     @registry = {}
+  #     class << self
+  #       include Superkick::Registry
+  #       # ... register, lookup, registered, etc.
+  #     end
+  #   end
+  #
+  # Block-scoped usage in tests (preferred):
+  #
+  #   MyPlugin.with_registry do
+  #     MyPlugin.register(StubPlugin)
+  #     # StubPlugin visible here, cleaned up automatically
+  #   end
+  #
+  # Optionally pre-seed the isolated registry:
+  #
+  #   MyPlugin.with_registry(stub: StubPlugin) do
+  #     assert_equal StubPlugin, MyPlugin.lookup(:stub)
+  #   end
+  #
+  # Paired save/restore for Minitest before/after hooks:
+  #
+  #   before do
+  #     @saved = MyPlugin.snapshot_registry
+  #     MyPlugin.register(StubPlugin)
+  #   end
+  #
+  #   after do
+  #     MyPlugin.restore_registry(@saved)
+  #   end
+  #
+  module Registry
+    # Snapshot the current registry, optionally replace it, yield, then
+    # restore.  Thread-safe per block scope (the snapshot is local).
+    #
+    # @param entries [Hash] optional entries to seed the isolated registry with
+    # @yield block runs with the isolated registry
+    # @return the block's return value
+    def with_registry(**entries, &block)
+      saved = @registry.dup
+      @registry = entries.any? ? entries.dup : saved.dup
+      block.call
+    ensure
+      @registry = saved
+    end
+
+    # Take a snapshot of the current registry for later restoration.
+    # Use with `restore_registry` in Minitest before/after hooks.
+    #
+    # @return [Hash] frozen snapshot of the registry
+    def snapshot_registry
+      @registry.dup.freeze
+    end
+
+    # Restore the registry from a previous snapshot.
+    #
+    # @param snapshot [Hash] a snapshot from `snapshot_registry`
+    def restore_registry(snapshot)
+      @registry = snapshot.dup
+    end
+  end
+end

data/lib/superkick/repository_source.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module Superkick
+  # Repository — metadata for a single repository in the catalog.
+  class Repository
+    attr_reader :name, :path, :url, :dependencies,
+      :version_control, :context_documents
+
+    # Well-known context document patterns — glob relative to repo root.
+    CONTEXT_DOCUMENT_PATTERNS = {
+      readme: "README*",
+      claude_md: "CLAUDE.md",
+      agents_md: "AGENTS.md",
+      contributing: "CONTRIBUTING*",
+      conventions: "CONVENTIONS*",
+      cursorrules: ".cursorrules"
+    }.freeze
+
+    def initialize(name:, path: nil, url: nil, dependencies: [],
+      version_control: nil, context_documents: {})
+      @name = name.to_sym
+      @path = path && File.expand_path(path)
+      @url = url
+      @dependencies = dependencies.map(&:to_s)
+      @context_documents = (context_documents || {}).dup
+      @version_control = version_control&.to_sym
+    end
+
+    # Convenience accessor — returns the :readme context document content.
+    def readme_content
+      @context_documents[:readme]
+    end
+
+    # Convenience writer — sets the :readme context document.
+    # Used by OrganizationRepositorySource to pre-populate fetched content.
+    def readme_content=(content)
+      @context_documents[:readme] = content
+    end
+
+    # Set a named context document. Used by sources to populate documents
+    # after construction.
+    def set_context_document(name, content)
+      @context_documents[name.to_sym] = content
+    end
+
+    def to_h
+      h = {name: @name}
+      h[:path] = @path if @path
+      h[:url] = @url if @url
+      h[:version_control] = @version_control if @version_control
+      h[:dependencies] = @dependencies if @dependencies.any?
+      h[:context_documents] = @context_documents.keys if @context_documents.any?
+      h
+    end
+  end
+
+  # RepositorySource — abstract base class for repository sources.
+  #
+  # A repository source knows how to discover and describe repositories.
+  # It provides metadata (name, path, url, etc.) but does not handle
+  # workspace preparation — that's the job of VersionControl adapters.
+  #
+  # Subclass contract:
+  #   self.type          → unique Symbol (e.g. :local, :github_organization)
+  #   repositories       → Hash of { name_sym => Repository }
+  #   find_by_name(n)    → Repository or nil
+  #   to_prompt_context  → String for planning agent prompt
+  #   empty? / size      → catalog stats
+  #
+  # Built-in implementations:
+  #   Local::RepositorySource                           — scans a local directory
+  #   Integrations::Git::RepositorySource               — single URL-based git repo
+  #   Integrations::GitHub::OrganizationRepositorySource — lists repos from a GitHub org
+  #   CompositeRepositorySource                         — unions multiple sources
+  class RepositorySource
+    # ── Registry (stores classes, keyed by type) ─────────────────────────
+    @registry = {}
+
+    class << self
+      include Superkick::Registry
+
+      def register(source_class)
+        key = source_class.type
+        raise ArgumentError, "RepositorySource :#{key} already registered" if @registry.key?(key)
+        @registry[key] = source_class
+      end
+
+      def lookup(name)
+        @registry[name.to_sym] or raise ArgumentError, "Unknown repository source type: #{name.inspect}"
+      end
+
+      def registered
+        @registry.dup.freeze
+      end
+
+      # Build a source from config.
+      #
+      # Accepts a Hash where each key is a user-chosen name and each value is either:
+      #   - a typed source config (has :type key) → built as its own typed source
+      #   - an untyped entry with :path → wrapped as a Local::RepositorySource (depth 0)
+      #
+      # Entries without :type and without :path are silently skipped.
+      #
+      # When the result is a single source, returns it directly.
+      # When there are multiple, composites them.
+      def build(config)
+        config = {} if config.nil?
+        return Local::RepositorySource.new({}) if config.empty?
+
+        sources = []
+
+        config.each do |name, entry_config|
+          next unless entry_config.is_a?(Hash)
+
+          if entry_config.key?(:type)
+            klass = lookup(entry_config[:type].to_sym)
+            sources << klass.new(entry_config.merge(name:))
+          elsif entry_config[:path]
+            sources << Local::RepositorySource.new(path: entry_config[:path], depth: 0, name:)
+          end
+        end
+
+        case sources.size
+        when 0 then Local::RepositorySource.new({})
+        when 1 then sources.first
+        else CompositeRepositorySource.new(sources)
+        end
+      end
+    end
+
+    def self.type
+      raise NotImplementedError, "#{self}.type not implemented"
+    end
+
+    # Setup wizard metadata. Override in subclasses that should appear in `superkick setup`.
+    def self.setup_label = nil
+    def self.setup_config = nil
+
+    def repositories
+      raise NotImplementedError, "#{self.class}#repositories not implemented"
+    end
+
+    def find_by_name(name)
+      repositories[name.to_sym]
+    end
+
+    def to_prompt_context
+      return "No repositories configured." if repositories.empty?
+
+      repositories.map do |name, repository|
+        lines = ["### #{name}"]
+        lines << "Dependencies: #{repository.dependencies.join(", ")}" if repository.dependencies.any?
+        repository.context_documents.each do |doc_name, content|
+          excerpt = content.lines.first(30).join
+          lines << ""
+          lines << "#{doc_name.to_s.tr("_", " ").capitalize} (excerpt):"
+          lines << excerpt
+        end
+        lines.join("\n")
+      end.join("\n\n")
+    end
+
+    def empty?
+      repositories.empty?
+    end
+
+    def size
+      repositories.size
+    end
+  end
+
+  # CompositeRepositorySource — unions multiple sources into one.
+  #
+  # Built automatically by RepositorySource.build when the config contains
+  # multiple sources. Earlier entries win on name collisions
+  # (first-found precedence).
+  class CompositeRepositorySource < RepositorySource
+    def self.type = :composite
+
+    def initialize(children = [])
+      @children = children
+      @repositories = children
+        .each_with_object({}) do |child, merged|
+          child.repositories.each do |name, repository|
+            merged[name] ||= repository
+          end
+        end
+        .freeze
+    end
+
+    attr_reader :repositories, :children
+  end
+
+  RepositorySource.register(CompositeRepositorySource)
+end