antigravity-sdk 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 665ab001fa484b0bc5ba97c2e7feb960712b0f8e5070ed521f0caf5ad0f16a58
-  data.tar.gz: 3f556321b1083daadea10792632ac216ba168abb26708fc5cc3a81824301d460
+  metadata.gz: effdabdb0588788c4b168749a2578e2e1f07aa877a54bfd80fe1969d42f497d2
+  data.tar.gz: 3debe5e4295f8c2e2bcd4c37ec7ea52ea11a77d034370320d4064b52aa08cc29
 SHA512:
-  metadata.gz: d60ff58a66fec4ed17a85ad51015568e743363f313eb1a27b9e6512a767ae5a7abca062796ae0bc19edbe59545202828415b693f6551b77a22d8a1ff5cca99ea
-  data.tar.gz: 9e09ed8b23e59d29f644d10f421b73d70f357c7d9fd601ba67ba429df8c2814768d0264084e5e6439cd9161d2f8c13313f6890bcd11faf6f66f7e43e3ea2578f
+  metadata.gz: 4123cbc798ddbfaa82ea0f854e89adb122491d9a99b52f501c15350401e660109be3ca778b6142720f0259256992dbbb73d4d2371d8bdefcda266bd4d98591cf
+  data.tar.gz: d80349e13c564c74bb81c5c8ba14887f39af36507d03b3c6a5883ed3a885359570210d10b9fc1f8cc3e8a0c193408de176f3316129a58e1d6303352c5527ed01

data/lib/antigravity/agent.rb

@@ -4,27 +4,164 @@ module Antigravity
   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: [], policies: [], policy: nil, 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 = []
+      @policies = []
       @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?
+
+      # Resolve policy: sugar (symbol → preset, Policy object → use directly)
+      if policy
+        resolved = policy.is_a?(Symbol) ? Policy.preset(policy) : policy
+        enforce(resolved)
+      end
+
+      # Load policies
+      policies.each { |p| enforce(p) }
 
       # 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
 
+    def enforce(policy)
+      @policies << policy
+      before_tool_call do |tool_name, args|
+        policy.evaluate(tool_name, args)
+      end
+    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
+
+      # Auto-attach lifecycle logger if enabled via env
+      if lifecycle_logger_enabled? && !@lifecycle_attached
+        LifecycleLogger.attach!(self, verbose: ENV['ANTIGRAVITY_LIFECYCLE_VERBOSE'] == '1')
+        @lifecycle_attached = true
+      end
+
+      @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
+
+      # Emit session_start hook
+      hooks.emit(:session_start, {
+        model: @model,
+        conversation_id: conversation_id,
+        workspace: @workspace,
+        skills_count: @skills.length,
+        tools_count: @tools.length,
+      })
+
+      self
+    end
+
+    def connected?
+      @connected && @connection&.connected?
+    end
+
+    def close!
+      # Emit session_end hook before teardown
+      if @connected
+        hooks.emit(:session_end, {
+          turn_count: turn_count,
+          conversation_id: conversation_id,
+        })
+      end
+
+      @connected = false
+      @connection&.disconnect!
+      @connection = nil
+      @conversation = nil
+    end
+
+    # --- Chat ---
+
+    def prompt(message, timeout: Antigravity.config.timeout_llm, &block)
+      connect! unless @connected
+      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)
@@ -34,6 +171,7 @@ module Antigravity
         raise ArgumentError, "Invalid tool definition"
       end
       @tools << tool
+      @tool_runner.register(tool) if @tool_runner
       tool
     end
 
@@ -42,18 +180,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
@@ -75,19 +256,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?
@@ -96,5 +264,105 @@ module Antigravity
 
       true
     end
+
+    def lifecycle_logger_enabled?
+      # Explicit opt-in
+      return true if ENV['ANTIGRAVITY_LIFECYCLE'] == '1'
+      # Rails/Rack test or development
+      return true if %w[test development].include?(ENV['RAILS_ENV']&.downcase)
+      return true if %w[test development].include?(ENV['RACK_ENV']&.downcase)
+      # Explicit opt-out
+      false
+    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
+
+    def lifecycle_logger_enabled?
+      ENV['ANTIGRAVITY_LIFECYCLE'] == '1'
+    end
   end
 end

data/lib/antigravity/colors.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Lightweight ANSI color helpers for terminal output.
+# No external dependencies. Safe for piped/non-TTY output.
+module Antigravity
+  module Colors
+    CODES = {
+      reset:     "\e[0m",
+      bold:      "\e[1m",
+      dim:       "\e[2m",
+      italic:    "\e[3m",
+      # Foreground
+      gray:      "\e[90m",
+      red:       "\e[31m",
+      green:     "\e[32m",
+      yellow:    "\e[33m",
+      blue:      "\e[34m",
+      magenta:   "\e[35m",
+      cyan:      "\e[36m",
+      white:     "\e[37m",
+      # Bright
+      bright_green:  "\e[92m",
+      bright_yellow: "\e[93m",
+      bright_cyan:   "\e[96m",
+    }.freeze
+
+    def self.colorize(text, *styles)
+      return text.to_s unless $stdout.tty?
+      prefix = styles.map { |s| CODES[s] || "" }.join
+      "#{prefix}#{text}#{CODES[:reset]}"
+    end
+
+    def self.gray(text)    = colorize(text, :gray)
+    def self.dim(text)     = colorize(text, :dim)
+    def self.green(text)   = colorize(text, :green)
+    def self.yellow(text)  = colorize(text, :yellow)
+    def self.red(text)     = colorize(text, :red)
+    def self.cyan(text)    = colorize(text, :cyan)
+    def self.blue(text)    = colorize(text, :blue)
+    def self.magenta(text) = colorize(text, :magenta)
+    def self.bold(text)    = colorize(text, :bold)
+  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