antigravity-sdk 0.2.0 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbeafe860899a22961b7c19a418337cb456594d683708d49b06b293711429c57
-  data.tar.gz: 7e0caad86e9aa6dd49e2f541ddb041ee9fc0518a21575bfe634b43cb3e879e94
+  metadata.gz: b2a5cad1edda5eb5efaa58d7d5104ba433f8469a923bb5f862b9f1bcb4219021
+  data.tar.gz: 75c9924910ef8aab407444abfecfa0f7e989473d8be251691e4e07c9d04499aa
 SHA512:
-  metadata.gz: 624c1c92b64d248113fd1ef0bd02367c84097666a873b0cecda4063107719406533861faa4cd9baf401afe91ae91e7f2fe185d811027adc7521a09e4e51fa1ae
-  data.tar.gz: def792e62ad5f0c2b0c7198022453c5d28ccdf7b9c70668ce79207b81589e778310cd0779a58d13301902663b6c0b59e2db15ef57fcb99cc92105b41c505dbb8
+  metadata.gz: ac637d9792051869f94b4a8ebc716fd604b2db18886e19b105190a9636c7e7bce418aeece52a360b139b1c534e560605b0dc578fab10b3e06ac913dc454663eb
+  data.tar.gz: c8b6e4bee541853abd1f993d5423cc3426c830a24aba58f6790ec30e093279163b83e258a824811380ac5a603cba749dd7a099dee5ad4a2160fe25a7373c6e51

data/lib/antigravity/agent.rb

@@ -1,31 +1,125 @@
 # frozen_string_literal: true
 
 module Antigravity
-  class Agent
-    include Emojifiable
+  class Agent < Base
 
     attr_accessor :model, :system_instruction, :api_key
-    attr_reader :tools, :skills, :hooks, :sidecars, :client, :logger_guard
+    attr_reader :tools, :skills, :hooks, :sidecars, :client, :logger_guard,
+                :workspace, :connection, :conversation
 
-    def initialize(model: nil, auto_logger: true, &block)
+    def initialize(model: nil, system_instruction: nil, tools: [],
+                   skills: [], workspace: nil, auto_logger: true, log_file: nil, &block)
       @model = model || Antigravity.config.default_model
       @api_key = Antigravity.config.api_key
-      @system_instruction = nil
-      @tools = []
+      @system_instruction = system_instruction
+      @workspace = workspace ? File.expand_path(workspace) : nil
+      @tools = tools.dup
       @skills = []
       @sidecars = []
       @hooks = Hooks.new
       @client = Client.new
       @logger_guard = nil
+      @connection = nil
+      @conversation = nil
+      @connected = false
+
+      # Register pre-provided tools into the tool runner
+      @tool_runner = ToolRunner.new
+      @tools.each { |t| @tool_runner.register(t) }
+
+      # Load skills provided at construction (local paths or GitHub URLs)
+      add_skills(skills) unless Array(skills).empty?
 
       # Automagic Logger attachment unless disabled via ENV["ANTIGRAVITY_LOGGER"]=false or auto_logger: false
       if auto_logger && logger_enabled?
-        attach_logger
+        attach_logger(log_file)
       end
 
       yield(self) if block_given?
     end
 
+    # --- Class Methods ---
+
+    # Block form: opens connection, yields agent, auto-closes.
+    def self.open(**kwargs, &block)
+      agent = new(**kwargs)
+      agent.connect!
+      begin
+        block.call(agent)
+      ensure
+        agent.close!
+      end
+    end
+
+    # --- Connection Lifecycle ---
+
+    def connect!
+      return self if @connected
+
+      @connection = Connection::LocalConnection.new
+      @connection.connect!
+
+      @conversation = Conversation.new(
+        ws_client: @connection.ws_client,
+        tool_runner: @tool_runner,
+        hooks: @hooks
+      )
+
+      harness_config = build_harness_config
+      @conversation.initialize_session!(harness_config: harness_config)
+      @connected = true
+      self
+    end
+
+    def connected?
+      @connected && @connection&.connected?
+    end
+
+    def close!
+      @connected = false
+      @connection&.disconnect!
+      @connection = nil
+      @conversation = nil
+    end
+
+    # --- Chat ---
+
+    def prompt(message, timeout: Antigravity.config.timeout_llm, &block)
+      emit_sidecar_event(:prompt_started, prompt: message)
+      hooks.run_pre_prompt(message)
+
+      if @connected && @conversation
+        response = @conversation.chat(message, timeout: timeout, &block)
+      else
+        # Legacy mock-client path (unit tests, pre-connection)
+        response = client.send_turn(self, message, &block)
+      end
+
+      hooks.run_post_response(response)
+      emit_sidecar_event(:turn_completed, response: response.content, model: model)
+
+      response
+    end
+    alias ask prompt
+
+    # --- Metadata Accessors (mirrors Python SDK) ---
+
+    def conversation_id
+      @conversation&.conversation_id
+    end
+
+    def turn_count
+      @conversation&.turn_count || 0
+    end
+
+    def session_summary
+      return {} unless @conversation
+
+      @conversation.session_summary(model: @model)
+    end
+
+    # --- Tool Registration ---
+
     def register_tool(tool_or_name = nil, description: "", &block)
       if block_given? && tool_or_name
         tool = Tool::Dynamic.new(tool_or_name, description: description, &block)
@@ -35,6 +129,7 @@ module Antigravity
         raise ArgumentError, "Invalid tool definition"
       end
       @tools << tool
+      @tool_runner.register(tool) if @tool_runner
       tool
     end
 
@@ -43,18 +138,61 @@ module Antigravity
       sidecar
     end
 
-    def attach_logger(log_target = nil, level: ::Logger::INFO, silent_notice: false)
+    def attach_logger(log_target = nil, level: :info, silent_notice: false)
       @logger_guard = Guards::AgentLogger.new(log_target, level: level, silent_notice: silent_notice)
       @logger_guard.attach_to(self)
       @logger_guard
     end
 
-    def load_skill(skill_path)
-      skill = Skill.load(skill_path)
-      @skills << skill
+    # Add a single skill by path or GitHub URL.
+    # Raises if the path resolves to multiple skills (use add_skills instead).
+    # @param path_or_url [String] local path or GitHub URL
+    # @param skill_name [String, nil] optional specific skill name within a repo
+    # @return [Skill] the loaded skill
+    def add_skill(path_or_url, skill_name: nil)
+      target = skill_name ? "#{path_or_url.to_s.chomp('/')}/#{skill_name}" : path_or_url.to_s
+      paths = SkillResolver.resolve(target)
+      if paths.size > 1
+        raise ArgumentError,
+              "add_skill resolved to #{paths.size} skills. Use add_skills instead, " \
+              "or specify skill_name: to pick one."
+      end
+      raise ArgumentError, "No skill found at #{target}" if paths.empty?
+
+      load_single_skill(paths.first)
+    end
+
+    # Add one or more skills by path or GitHub URL.
+    # Accepts a single string or an array. Each entry is resolved (may expand to multiple).
+    # @param paths_or_urls [String, Array<String>] local paths or GitHub URLs
+    # @return [Array<Skill>] all loaded skills
+    def add_skills(paths_or_urls)
+      Array(paths_or_urls).flat_map do |p|
+        SkillResolver.resolve(p).map { |skill_path| load_single_skill(skill_path) }
+      end
+    end
+
+    # Create and add an inline skill (no file needed).
+    # @param name [String] skill name
+    # @param description [String] what the skill does
+    # @param instructions [String] the skill body (markdown)
+    # @return [Skill] the inline skill
+    def add_inline_skill(name:, description:, instructions:)
+      skill = Skill.inline(name: name, description: description, instructions: instructions)
+      @skills << skill unless @skills.any? { |s| s.name == skill.name }
       skill
     end
 
+    # List discovered skills in a container path (without loading them).
+    # @param path_or_url [String] local path or GitHub URL
+    # @return [Array<String>] skill directory paths
+    def self.list_skills(path_or_url)
+      SkillResolver.resolve(path_or_url)
+    end
+
+    # Legacy alias
+    alias_method :load_skill, :add_skill
+
     def before_prompt(&block)
       hooks.before_prompt(&block)
     end
@@ -76,19 +214,6 @@ module Antigravity
       @sidecars.each { |sidecar| sidecar.emit(event_type, payload) }
     end
 
-    def prompt(message, &block)
-      emit_sidecar_event(:prompt_started, prompt: message)
-      hooks.run_pre_prompt(message)
-
-      response = client.send_turn(self, message, &block)
-
-      hooks.run_post_response(response)
-      emit_sidecar_event(:turn_completed, response: response.content, model: model)
-
-      response
-    end
-    alias ask prompt
-
     private
 
     def logger_enabled?
@@ -97,5 +222,91 @@ module Antigravity
 
       true
     end
+
+    def build_harness_config
+      api_key = ENV.fetch('GEMINI_API_KEY') {
+        raise ConfigError, 'GEMINI_API_KEY environment variable is required'
+      }
+
+      config = {
+        config: {
+          models: [
+            {
+              name: @model,
+              geminiApiEndpoint: {
+                apiKey: api_key
+              }
+            }
+          ]
+        }
+      }
+
+      # Add workspaces if specified
+      if @workspace
+        expanded = File.expand_path(@workspace)
+        $stderr.puts "\u231B Indexing workspace: #{expanded} — this may take a moment..."
+        config[:config][:workspaces] = [
+          {
+            filesystemWorkspace: {
+              directory: expanded
+            }
+          }
+        ]
+      end
+
+      # Add system instructions if specified (protobuf: SystemInstructions.custom.part[])
+      effective_instructions = @system_instruction || ''
+
+      # Auto-append workspace tool hints — models (esp. flash-lite) won't use tools unless told
+      if @workspace && !effective_instructions.match?(/list_dir|view_file|tools/i)
+        tool_hint = 'You have access to the workspace filesystem. Use the available tools (list_dir, view_file, grep_search) to explore it.'
+        effective_instructions = effective_instructions.empty? ? tool_hint : "#{effective_instructions}\n#{tool_hint}"
+      end
+
+      unless effective_instructions.empty?
+        config[:config][:systemInstructions] = {
+          custom: {
+            part: [{ text: effective_instructions }]
+          }
+        }
+      end
+
+      # Add custom tools
+      if @tool_runner && !@tool_runner.empty?
+        config[:config][:tools] = @tool_runner.to_harness_tools
+      end
+
+      # Enable harness-side built-in tools by default (list_dir, view_file, grep_search, etc.)
+      config[:config][:harnessSideTools] = {
+        listDir: { enabled: true },
+        viewFile: { enabled: true },
+        grepSearch: { enabled: true },
+        find: { enabled: true },
+        writeToFile: { enabled: true },
+        fileEdit: { enabled: true },
+        readUrlContent: { enabled: true },
+        searchWeb: { enabled: true }
+      }
+
+      # Wire skills paths for harness (proto field: skills_paths)
+      unless @skills.empty?
+        skill_paths = @skills.select(&:path).map(&:path)
+        config[:config][:skillsPaths] = skill_paths unless skill_paths.empty?
+      end
+
+      # App data dir
+      config[:config][:appDataDir] = File.expand_path('~/.gemini/antigravity')
+
+      config
+    end
+
+    def load_single_skill(skill_path)
+      # Dedup by path
+      return @skills.find { |s| s.path == skill_path } if @skills.any? { |s| s.path == skill_path }
+
+      skill = Skill.load(skill_path)
+      @skills << skill
+      skill
+    end
   end
 end

data/lib/antigravity/base.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Antigravity
+  # Base class for all Antigravity domain objects.
+  # Subclasses automagically get .emoji / #emoji via Emojifiable.
+  #
+  # ⚠️  Keep this class SUPER thin!
+  # Every SDK class inherits from it, so any weight here
+  # is carried by Agent, Tool, Skill, Message, Sidecar::Runner, etc.
+  class Base
+    include Emojifiable
+
+    def self.inherited(subclass)
+      super
+      subclass.include(Emojifiable) unless subclass < Emojifiable
+    end
+  end
+end

data/lib/antigravity/config.rb

@@ -4,11 +4,22 @@ module Antigravity
   class Config
     attr_accessor :api_key, :default_model, :harness_path, :log_level
 
+    # Timeouts (seconds) — aggressive for dev, override via ENV for prod.
+    #   ANTIGRAVITY_TIMEOUT_LLM       — per-message wait for LLM response (default: 20s)
+    #   ANTIGRAVITY_TIMEOUT_WS        — WebSocket connect/handshake (default: 3s)
+    #   ANTIGRAVITY_TIMEOUT_HANDSHAKE — stdio binary handshake (default: 5s)
+    attr_accessor :timeout_llm, :timeout_ws, :timeout_handshake
+
     def initialize
       @api_key = ENV["GEMINI_API_KEY"]
-      @default_model = "gemini-flash-latest"
+      @default_model = ENV["GEMINI_MODEL"] || ENV["ANTIGRAVITY_MODEL"] || "gemini-3.6-flash"
       @harness_path = ENV["ANTIGRAVITY_HARNESS_PATH"] || File.expand_path("~/.antigravity/bin/localharness")
       @log_level = :info
+
+      # Timeouts: aggressive for dev, relax via ENV for production
+      @timeout_llm       = (ENV["ANTIGRAVITY_TIMEOUT_LLM"]       || 40).to_i
+      @timeout_ws        = (ENV["ANTIGRAVITY_TIMEOUT_WS"]        || 3).to_i
+      @timeout_handshake = (ENV["ANTIGRAVITY_TIMEOUT_HANDSHAKE"] || 5).to_i
     end
 
     def api_key?

data/lib/antigravity/connection/binary_fetcher.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'fileutils'
+require 'tmpdir'
+require 'net/http'
+require 'json'
+require 'uri'
+
+module Antigravity
+  module Connection
+    # Downloads and extracts the localharness binary from the official
+    # google-antigravity PyPI wheel. Used when the binary isn't already
+    # installed via Antigravity.app or a manual setup.
+    module BinaryFetcher
+      PYPI_PACKAGE = 'google-antigravity'
+      INSTALL_DIR  = File.expand_path('~/.antigravity/bin')
+      BINARY_NAME  = 'localharness'
+
+      # Platform mapping: Ruby's RUBY_PLATFORM -> PyPI wheel platform tag
+      PLATFORM_MAP = {
+        /darwin.*arm/i   => 'macosx_11_0_arm64',
+        /darwin.*x86/i   => 'macosx_10_15_x86_64',
+        /darwin/i        => 'macosx_11_0_arm64',    # default macOS = ARM
+        /linux.*x86_64/i => 'manylinux2014_x86_64',
+        /linux.*aarch/i  => 'manylinux2014_aarch64',
+      }.freeze
+
+      class << self
+        # Fetch and install the binary. Returns the installed path.
+        # @param quiet [Boolean] suppress progress output
+        # @return [String] path to the installed binary
+        def fetch!(quiet: false)
+          platform = detect_platform
+          say("🔍 Detecting platform: #{platform}", quiet: quiet)
+
+          # Step 1: Find the wheel URL from PyPI
+          say("📡 Querying PyPI for #{PYPI_PACKAGE}...", quiet: quiet)
+          wheel_url = find_wheel_url(platform)
+
+          # Step 2: Download the wheel
+          say("⏳ Downloading binary... this will take some time (~50MB wheel)", quiet: quiet)
+          wheel_path = download_wheel(wheel_url, quiet: quiet)
+
+          # Step 3: Extract the binary
+          say("📦 Extracting localharness binary...", quiet: quiet)
+          binary_path = extract_binary(wheel_path)
+
+          # Step 4: Make executable
+          FileUtils.chmod(0o755, binary_path)
+          say("✅ Installed localharness at #{binary_path}", quiet: quiet)
+
+          binary_path
+        ensure
+          # Clean up temp wheel
+          FileUtils.rm_f(wheel_path) if wheel_path && File.exist?(wheel_path.to_s)
+        end
+
+        # Check if the binary is already installed via fetch
+        def installed?
+          path = File.join(INSTALL_DIR, BINARY_NAME)
+          File.executable?(path)
+        end
+
+        def installed_path
+          File.join(INSTALL_DIR, BINARY_NAME)
+        end
+
+        private
+
+        def detect_platform
+          PLATFORM_MAP.each do |pattern, tag|
+            return tag if RUBY_PLATFORM.match?(pattern)
+          end
+          raise HarnessNotFoundError,
+            "Unsupported platform: #{RUBY_PLATFORM}. Cannot auto-download localharness."
+        end
+
+        def find_wheel_url(platform)
+          uri = URI("https://pypi.org/pypi/#{PYPI_PACKAGE}/json")
+          response = Net::HTTP.get(uri)
+          data = JSON.parse(response)
+
+          # Find latest version's wheel for our platform
+          urls = data['urls'] || []
+          wheel = urls.find { |u| u['filename']&.include?(platform) && u['filename']&.end_with?('.whl') }
+
+          unless wheel
+            # Try all versions for the platform
+            versions = data['releases']&.keys&.sort_by { |v| Gem::Version.new(v) rescue v }&.reverse
+            versions&.each do |ver|
+              files = data.dig('releases', ver) || []
+              wheel = files.find { |u| u['filename']&.include?(platform) && u['filename']&.end_with?('.whl') }
+              break if wheel
+            end
+          end
+
+          raise HarnessNotFoundError,
+            "No wheel found for platform #{platform} on PyPI. Install Antigravity.app manually." unless wheel
+
+          wheel['url']
+        end
+
+        def download_wheel(url, quiet: false)
+          dest = File.join(Dir.tmpdir, "antigravity-wheel-#{$$}.whl")
+          uri = URI(url)
+
+          Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
+            request = Net::HTTP::Get.new(uri)
+            http.request(request) do |response|
+              total = response['content-length']&.to_i
+              downloaded = 0
+
+              File.open(dest, 'wb') do |f|
+                response.read_body do |chunk|
+                  f.write(chunk)
+                  downloaded += chunk.bytesize
+                  if total && total > 0 && !quiet
+                    pct = (downloaded * 100.0 / total).round(1)
+                    print "\r  ⏳ #{pct}% (#{(downloaded / 1024.0 / 1024).round(1)} MB / #{(total / 1024.0 / 1024).round(1)} MB)"
+                  end
+                end
+              end
+              puts unless quiet
+            end
+          end
+
+          dest
+        end
+
+        def extract_binary(wheel_path)
+          FileUtils.mkdir_p(INSTALL_DIR)
+
+          # Wheels are just ZIP files. Extract the binary.
+          # Look for: google/antigravity/bin/localharness (or language_server)
+          extract_dir = Dir.mktmpdir('agy-extract-')
+          system('unzip', '-q', '-o', wheel_path, '-d', extract_dir)
+
+          # Search for the binary inside (prefer localharness over language_server)
+          candidates = Dir.glob("#{extract_dir}/**/localharness") +
+                       Dir.glob("#{extract_dir}/**/language_server")
+
+          binary = candidates.find { |f| File.file?(f) && !File.directory?(f) }
+
+          unless binary
+            FileUtils.rm_rf(extract_dir)
+            raise HarnessNotFoundError,
+              "Could not find localharness binary inside the wheel. Contents: #{Dir.glob("#{extract_dir}/**/*").join(', ')}"
+          end
+
+          dest_path = File.join(INSTALL_DIR, BINARY_NAME)
+          FileUtils.cp(binary, dest_path)
+          FileUtils.rm_rf(extract_dir)
+          dest_path
+        end
+
+        def say(msg, quiet: false)
+          $stderr.puts msg unless quiet
+        end
+      end
+    end
+  end
+end