antigravity-sdk 0.3.0 → 0.5.0

data/lib/antigravity/errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Antigravity
+  # Base error for all Antigravity SDK errors
+  class Error < StandardError; end
+
+  # Raised when the localharness binary cannot be found
+  class HarnessNotFoundError < Error; end
+
+  # Raised when the stdio handshake with localharness fails
+  class HarnessHandshakeError < Error; end
+
+  # Raised when protobuf encoding/decoding fails
+  class ProtocolError < Error; end
+
+  # Raised when a tool callback fails
+  class ToolError < Error; end
+
+  # Raised when trying to execute an unregistered tool
+  class ToolNotFoundError < ToolError; end
+
+  # Raised when WebSocket connection fails
+  class ConnectionError < Error; end
+
+  # Raised when required configuration (e.g., GEMINI_API_KEY) is missing
+  class ConfigError < Error; end
+end

data/lib/antigravity/guards.rb

@@ -1,31 +1,48 @@
 # frozen_string_literal: true
 
-require "logger"
+require "json"
 require "fileutils"
 
 module Antigravity
   module Guards
-    # Configurable opt-in logger guard supporting file loggers and Rails.logger
+    # Dual-output logger guard:
+    #   1. JSONL (log/antigravity.jsonl) — structured, machine-parseable, full data
+    #   2. Compact log (log/antigravity.log) — human-readable one-liners with byte sizes
+    # Falls back to Rails.logger for both if available.
     class AgentLogger
-      attr_reader :logger, :target_description
+      attr_reader :target_description
 
-      def initialize(log_target = nil, level: Logger::INFO, silent_notice: false)
-        resolved_target = resolve_log_target(log_target)
+      def initialize(log_target = nil, level: :info, silent_notice: false)
+        resolved = resolve_log_target(log_target)
 
-        if resolved_target.is_a?(String)
-          dir = File.dirname(resolved_target)
+        if resolved.is_a?(String)
+          dir = File.dirname(resolved)
           FileUtils.mkdir_p(dir) unless Dir.exist?(dir)
-          @logger = ::Logger.new(resolved_target)
-          @target_description = resolved_target
-        elsif resolved_target.respond_to?(:info)
-          @logger = resolved_target
+
+          # Fat JSONL log
+          @jsonl = File.open(resolved, 'a')
+          @jsonl.sync = true
+
+          # Skinny compact log (same dir, .log extension)
+          compact_path = resolved.sub(/\.jsonl$/, '.log')
+          @compact = File.open(compact_path, 'a')
+          @compact.sync = true
+
+          @rails_logger = nil
+          @target_description = resolved
+        elsif resolved.respond_to?(:info)
+          @jsonl = nil
+          @compact = nil
+          @rails_logger = resolved
           @target_description = "Rails.logger"
         else
-          @logger = ::Logger.new($stdout)
+          @jsonl = $stdout
+          @compact = nil
+          @rails_logger = nil
           @target_description = "$stdout"
         end
 
-        @logger.level = level if @logger.respond_to?(:level=)
+        @level = level
 
         unless silent_notice
           puts "#{Antigravity.emoji(:logger)} Logging to #{@target_description}"
@@ -33,25 +50,49 @@ module Antigravity
       end
 
       def before_prompt(prompt_text)
-        @logger.info("#{Antigravity.emoji(:prompt)} [Antigravity::Prompt] User: '#{prompt_text}'")
+        size = prompt_text.to_s.bytesize
+        log_jsonl('prompt', { user_input: prompt_text })
+        log_compact("#{Antigravity.emoji(:prompt)} PROMPT #{size}B | #{prompt_text.to_s[0, 80]}")
       end
 
       def after_response(response)
-        @logger.info("#{Antigravity.emoji(:response)} [Antigravity::Response] Assistant (#{response.model_id}): #{response.content.strip}")
+        content = response.content&.strip || ''
+        log_jsonl('response', {
+          model: response.model_id,
+          content: content,
+          tokens: response.usage[:total_token_count],
+          tool_calls: response.tool_calls_count,
+          steps: response.steps&.length
+        })
+        log_compact("#{Antigravity.emoji(:response)} RESPONSE #{content.bytesize}B | " \
+                    "tokens=#{response.usage[:total_token_count]} " \
+                    "tools=#{response.tool_calls_count} " \
+                    "steps=#{response.steps&.length} " \
+                    "model=#{response.model_id}")
       end
 
       def before_tool_call(tool_name, params)
-        @logger.info("#{Antigravity.emoji(:tool)} [Antigravity::Tool] Executing '#{tool_name}' with params: #{params.inspect}")
+        params_size = params.to_s.bytesize
+        log_jsonl('tool_call', { tool: tool_name, params: params })
+        log_compact("#{Antigravity.emoji(:tool)} TOOL_CALL #{tool_name} params=#{params_size}B")
       end
 
       def after_tool_call(tool_name, params, result)
-        prefix = result.to_s.include?("TOOL BLOCKED") ? Antigravity.emoji(:tool_blocked) : Antigravity.emoji(:tool_result)
-        @logger.info("#{prefix} [Antigravity::Tool] Result for '#{tool_name}': #{result}")
+        blocked = result.to_s.include?("TOOL BLOCKED")
+        result_size = result.to_s.bytesize
+        log_jsonl('tool_result', {
+          tool: tool_name,
+          result: result.to_s[0, 500],
+          blocked: blocked
+        })
+        status = blocked ? 'BLOCKED' : 'OK'
+        log_compact("#{blocked ? Antigravity.emoji(:tool_blocked) : Antigravity.emoji(:tool_result)} TOOL_RESULT #{tool_name} #{status} result=#{result_size}B")
         result
       end
 
       def sidecar_event(event_type, payload)
-        @logger.info("#{Antigravity.emoji(:sidecar)} [Antigravity::Sidecar] Event :#{event_type} payload: #{payload.inspect}")
+        log_jsonl('sidecar', { type: event_type.to_s, payload: payload })
+        log_compact("#{Antigravity.emoji(:sidecar)} SIDECAR :#{event_type}")
       end
 
       def attach_to(agent)
@@ -64,17 +105,36 @@ module Antigravity
 
       private
 
+      def ts
+        Time.now.utc.strftime('%Y-%m-%dT%H:%M:%S.%3NZ')
+      end
+
+      def log_jsonl(event, data)
+        if @rails_logger
+          @rails_logger.info("[Antigravity] #{event}: #{data.inspect}")
+        elsif @jsonl
+          entry = { ts: ts, event: event, pid: Process.pid }.merge(data.compact)
+          @jsonl.puts(JSON.generate(entry))
+        end
+      end
+
+      def log_compact(line)
+        if @compact
+          @compact.puts("#{ts} #{line}")
+        end
+      end
+
       def resolve_log_target(target)
         return target if target
 
         if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
           Rails.logger
         elsif ENV["RAILS_ENV"] && !ENV["RAILS_ENV"].empty?
-          "log/#{ENV['RAILS_ENV']}.log"
+          "log/#{ENV['RAILS_ENV']}.jsonl"
         elsif ENV["RACK_ENV"] && !ENV["RACK_ENV"].empty?
-          "log/#{ENV['RACK_ENV']}.log"
+          "log/#{ENV['RACK_ENV']}.jsonl"
         else
-          "log/antigravity.log"
+          "log/antigravity.jsonl"
         end
       end
     end

data/lib/antigravity/hooks.rb

@@ -9,6 +9,7 @@ module Antigravity
       @post_response_hooks = []
       @pre_tool_hooks = []
       @post_tool_hooks = []
+      @listeners = Hash.new { |h, k| h[k] = [] }
     end
 
     def before_prompt(&block)
@@ -29,6 +30,17 @@ module Antigravity
       @post_tool_hooks << block if block_given?
     end
 
+    # Generic event system — subscribe to any named event.
+    # Usage: hooks.on(:ws_message) { |msg| puts msg.keys }
+    def on(event, &block)
+      @listeners[event.to_sym] << block if block_given?
+    end
+
+    # Emit a named event to all subscribers.
+    def emit(event, *args)
+      @listeners[event.to_sym].each { |cb| cb.call(*args) }
+    end
+
     def run_pre_prompt(prompt_text)
       @pre_prompt_hooks.each { |hook| hook.call(prompt_text) }
     end

data/lib/antigravity/lifecycle_logger.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+# Auto-attachable lifecycle logger that prints colorful, compact status lines
+# on every hook event. Inspired by Cloud Code's status bar.
+#
+# Usage:
+#   agent = Antigravity::Agent.new
+#   Antigravity::LifecycleLogger.attach!(agent)
+#
+# Or auto-attach via env:
+#   ANTIGRAVITY_LIFECYCLE=1
+#   RAILS_ENV=test (auto-attaches in test/development)
+#
+module Antigravity
+  class LifecycleLogger
+    C = Antigravity::Colors
+
+    # Compact status string — the "Cloud Code status bar" equivalent.
+    # Example: "T3 | 1.2k tok | 4 tools | 2.3s"
+    def self.status_line(agent)
+      turns    = agent.turn_count rescue 0
+      summary  = agent.session_summary rescue {}
+      tokens   = summary.dig(:tokens, :total) || 0
+      tok_str  = tokens > 999 ? "#{(tokens / 1000.0).round(1)}k" : tokens.to_s
+      model    = summary[:model] || agent.model || '?'
+      conv_id  = (summary[:conversation_id] || '?')[0..7]
+
+      C.dim("T#{turns} | #{tok_str} tok | #{model} | #{conv_id}")
+    end
+
+    def self.attach!(agent, verbose: false)
+      new(verbose: verbose).attach(agent)
+    end
+
+    def initialize(verbose: false)
+      @verbose = verbose
+      @session_start_time = nil
+      @turn_start_time = nil
+      @turn_count = 0
+    end
+
+    def attach(agent)
+      attach_session_hooks(agent)
+      attach_turn_hooks(agent)
+      attach_tool_hooks(agent)
+    end
+
+    private
+
+    def attach_session_hooks(agent)
+      logger = self
+
+      agent.hooks.on(:session_start) do |info|
+        logger.instance_variable_set(:@session_start_time, Process.clock_gettime(Process::CLOCK_MONOTONIC))
+        model = info[:model] || agent.model || '?'
+        conv_id = (info[:conversation_id] || '?')[0..11]
+        puts C.gray("🟢 #{C.dim("session_start")} | model=#{C.cyan(model)} | conv=#{C.cyan(conv_id)}")
+      end
+
+      agent.hooks.on(:session_end) do |info|
+        elapsed = if logger.instance_variable_get(:@session_start_time)
+                    (Process.clock_gettime(Process::CLOCK_MONOTONIC) - logger.instance_variable_get(:@session_start_time)).round(1)
+                  else
+                    '?'
+                  end
+        turns = info[:turn_count] || agent.turn_count rescue 0
+        summary = agent.session_summary rescue {}
+        tokens = summary.dig(:tokens, :total) || 0
+        tok_str = tokens > 999 ? "#{(tokens / 1000.0).round(1)}k" : tokens.to_s
+        puts C.gray("🔴 #{C.dim("session_end")}   | #{C.bold("#{turns} turns")} | #{tok_str} tok | #{elapsed}s")
+      end
+    end
+
+    def attach_turn_hooks(agent)
+      logger = self
+
+      agent.hooks.before_prompt do |text|
+        logger.instance_variable_set(:@turn_start_time, Process.clock_gettime(Process::CLOCK_MONOTONIC))
+        count = logger.instance_variable_get(:@turn_count) + 1
+        logger.instance_variable_set(:@turn_count, count)
+        preview = text.to_s[0..60].gsub("\n", ' ')
+        preview += '...' if text.to_s.length > 60
+        status = self.class.status_line(agent) rescue C.dim("T#{count}")
+        puts C.gray("  ➡️  #{C.dim("pre_turn")}  T#{count} | #{C.yellow("\"#{preview}\"")} | #{status}")
+      end
+
+      agent.hooks.after_response do |response|
+        elapsed = if logger.instance_variable_get(:@turn_start_time)
+                    (Process.clock_gettime(Process::CLOCK_MONOTONIC) - logger.instance_variable_get(:@turn_start_time)).round(2)
+                  else
+                    '?'
+                  end
+        content = response.respond_to?(:content) ? response.content.to_s : response.to_s
+        chars = content.length
+        lines = content.count("\n") + 1
+        preview = content[0..60]&.gsub("\n", ' ') || '(empty)'
+        preview += '...' if chars > 60
+        thinking_len = response.respond_to?(:thinking) ? (response.thinking&.length || 0) : 0
+        tool_count = response.respond_to?(:tool_calls_count) ? (response.tool_calls_count || 0) : 0
+        status = self.class.status_line(agent) rescue ''
+
+        parts = ["#{C.green("#{chars}ch")} #{C.dim("#{lines}L")}"]
+        parts << "#{C.magenta("#{thinking_len}ch")} think" if thinking_len > 0
+        parts << "#{C.cyan("#{tool_count}")} tools" if tool_count > 0
+        parts << "#{C.blue("#{elapsed}s")}"
+
+        puts C.gray("  ⬅️  #{C.dim("post_turn")} T#{logger.instance_variable_get(:@turn_count)} | #{parts.join(' | ')} | #{status}")
+        if logger.instance_variable_get(:@verbose)
+          puts C.dim("     \"#{preview}\"")
+        end
+      end
+    end
+
+    def attach_tool_hooks(agent)
+      logger = self
+
+      agent.hooks.on(:tool_call) do |info|
+        name = info[:tool_name] || info[:name] || '?'
+        params_preview = (info[:params] || {}).keys.join(', ')
+        puts C.gray("    🔧 #{C.dim("tool_call")}  | #{C.cyan(name)}(#{C.dim(params_preview)})")
+      end
+
+      agent.hooks.on(:tool_result) do |info|
+        name = info[:tool_name] || info[:name] || '?'
+        result_len = info[:result].to_s.length rescue 0
+        duration = info[:duration] ? "#{info[:duration].round(2)}s" : nil
+        parts = [C.cyan(name), "#{result_len}ch"]
+        parts << duration if duration
+        puts C.gray("    ✅ #{C.dim("tool_done")}  | #{parts.join(' | ')}")
+      end
+
+      agent.hooks.on(:tool_blocked) do |info|
+        name = info[:tool] || '?'
+        reason = info[:reason] || 'policy'
+        puts C.red("    🚫 #{C.dim("tool_deny")}  | #{C.red(name)} — #{reason}")
+      end
+
+      agent.hooks.on(:tool_error) do |info|
+        name = info[:tool_name] || info[:name] || '?'
+        error = info[:error] || info[:message] || '?'
+        puts C.red("    💥 #{C.dim("tool_error")} | #{C.red(name)} — #{error.to_s[0..80]}")
+      end
+    end
+  end
+end

data/lib/antigravity/message.rb

@@ -1,23 +1,37 @@
 # frozen_string_literal: true
 
 module Antigravity
+  # Represents a response message from the agent.
+  # Mirrors Python SDK's ChatResponse with metadata.
   class Message < Base
+    attr_accessor :role, :content, :thinking, :tool_calls, :model_id, :tokens,
+                  :steps, :tool_calls_count, :usage, :delta
 
-    attr_accessor :role, :content, :thinking, :tool_calls, :model_id, :tokens
-
-    def initialize(role: :assistant, content: "", thinking: "", tool_calls: [], model_id: nil)
+    def initialize(role: :assistant, content: '', thinking: '', tool_calls: [],
+                   model_id: nil, steps: [], tool_calls_count: 0, usage: nil,
+                   delta: false)
       @role = role
       @content = content
       @thinking = thinking
       @tool_calls = tool_calls
       @model_id = model_id
       @tokens = { input: 0, output: 0 }
+      @steps = steps
+      @tool_calls_count = tool_calls_count
+      @usage = usage || { prompt_token_count: 0, candidates_token_count: 0, total_token_count: 0 }
+      @delta = delta
+    end
+
+    # Is this a streaming delta (partial) or a complete response?
+    def delta?
+      @delta
     end
   end
 
+  # Backward-compatible alias for streaming chunks
   class Chunk < Message
-    def initialize(role: :assistant, content: "", thinking: "", tool_calls: [], model_id: nil)
-      super(role: role, content: content, thinking: thinking, tool_calls: tool_calls, model_id: model_id)
+    def initialize(**kwargs)
+      super(**kwargs, delta: true)
     end
   end
 end

data/lib/antigravity/policy/constants.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+# ==========================================================================
+# Policy Constants — curated lists of commands, tools, and file patterns.
+#
+# 🛠️  MAINTAINER NOTES:
+#   - One entry per line for easy review in PRs.
+#   - Add new entries alphabetically within each group.
+#   - Multi-word commands use explicit quotes (no backslash escapes!).
+#   - Run `bundle exec rspec spec/antigravity/policy_spec.rb` after edits.
+# ==========================================================================
+
+module Antigravity
+  class Policy
+
+    # ------------------------------------------------------------------
+    # 💀 Catastrophic commands — hard-denied in ALL presets, no exceptions.
+    # ------------------------------------------------------------------
+    CATASTROPHIC_CMDS = [
+      'dd if=/dev/urandom',
+      'dd if=/dev/zero',
+      '> /dev/sd',
+      'halt',
+      'mkfs',
+      'reboot',
+      'rm -rf /*',
+      'rm -rf /',
+      'rm -rf ~',
+      'shutdown',
+    ].freeze
+
+    # ------------------------------------------------------------------
+    # ⚠️  Risky commands — confirmed in :default, hard-denied in :cautious.
+    # Single-word or short patterns that match substring in command_line.
+    # ------------------------------------------------------------------
+    RISKY_CMDS = [
+      'chmod -R 777',
+      'chown -R',
+      'kill -9',
+      'killall',
+      'pkill',
+      'rm',
+      'xargs',
+    ].freeze
+
+    # ------------------------------------------------------------------
+    # 🔥 Destructive git — nuke local changes, rewrite history.
+    # Confirmed in :default/:turbo, hard-denied in :cautious/:test.
+    # ------------------------------------------------------------------
+    DESTRUCTIVE_GIT_CMDS = [
+      'git checkout .',
+      'git checkout -- .',
+      'git clean -fd',
+      'git clean -fdx',
+      'git push --force',
+      'git push -f',
+      'git reset --hard',
+      'git stash drop',
+    ].freeze
+
+    # ------------------------------------------------------------------
+    # ✅ Safe read-only shell commands — allowed even in :cautious.
+    # ------------------------------------------------------------------
+    SAFE_CMDS = %i[
+      cd
+      date
+      echo
+      hostname
+      ls
+      md5
+      md5sum
+      pwd
+      uname
+      wc
+      which
+      whoami
+    ].freeze
+
+    # ⚠️  File-reading shell commands — can bypass view_file deny rules!
+    # Allowed in :default/:turbo/:test, but NOT in :cautious.
+    # If you deny `view_file` for a path, `cat` can circumvent it.
+    READ_CMDS = %i[
+      cat
+      head
+      strings
+      tail
+    ].freeze
+
+    # Safe git subcommands (read-only, no mutations)
+    SAFE_GIT_CMDS = [
+      'git branch',
+      'git diff',
+      'git log',
+      'git remote',
+      'git status',
+    ].freeze
+
+    # ------------------------------------------------------------------
+    # 🔐 Sensitive file globs — writes to these require confirmation.
+    # ------------------------------------------------------------------
+    SENSITIVE_FILES = [
+      '.env',
+      '.env.*',
+      '*.key',
+      '*.pem',
+      '*.secret',
+      'id_rsa*',
+    ].freeze
+
+    # ------------------------------------------------------------------
+    # 📂 Sandbox directories — always writable, even in production.
+    # Throwaway / output dirs where agents can freely write.
+    # ------------------------------------------------------------------
+    SANDBOX_DIRS = [
+      'out/*',
+      'scratch/*',
+    ].freeze
+
+    # ------------------------------------------------------------------
+    # 🔧 Tool classifications
+    # ------------------------------------------------------------------
+
+    # Read-only harness tools (always safe)
+    READONLY_TOOLS = %i[
+      find
+      grep_search
+      list_dir
+      read_url_content
+      search_web
+      view_file
+    ].freeze
+
+    # Write harness tools
+    WRITE_TOOLS = %i[
+      file_edit
+      write_to_file
+    ].freeze
+
+    # ------------------------------------------------------------------
+    # 🗺️  Environment → preset mapping (for Policy.auto)
+    # ------------------------------------------------------------------
+    PRESET_NAMES = %i[auto cautious default test turbo].freeze
+
+    ENV_MAP = {
+      'dev'         => :turbo,
+      'development' => :turbo,
+      'prod'        => :cautious,
+      'production'  => :cautious,
+      'staging'     => :default,
+      'test'        => :test,
+    }.freeze
+
+  end
+end