antigravity-sdk 0.4.2 → 0.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2a5cad1edda5eb5efaa58d7d5104ba433f8469a923bb5f862b9f1bcb4219021
-  data.tar.gz: 75c9924910ef8aab407444abfecfa0f7e989473d8be251691e4e07c9d04499aa
+  metadata.gz: 25e15da1171b05a2bcc0be36f79e4f1f6e6e0e6135d520d3776282007071ee05
+  data.tar.gz: 3ddfcb833bb6d1339573b81e5910f33c37cd4113bfb28c753367386f0d67d88e
 SHA512:
-  metadata.gz: ac637d9792051869f94b4a8ebc716fd604b2db18886e19b105190a9636c7e7bce418aeece52a360b139b1c534e560605b0dc578fab10b3e06ac913dc454663eb
-  data.tar.gz: c8b6e4bee541853abd1f993d5423cc3426c830a24aba58f6790ec30e093279163b83e258a824811380ac5a603cba749dd7a099dee5ad4a2160fe25a7373c6e51
+  metadata.gz: 70112ba04d101d659b82372f4f49f03a301d9d1e8fb4c89de871ccf2abdee7bed7017b3fe8440eff5c935902f0c545238081d2439e7aff1e4ca5a63d76f87e83
+  data.tar.gz: feb64a14685fefe355772238556f05e27a08aad6f9ad44ae74db4fd0c16e1821eda88f78dbcc24cf990cb90d744139697b06eb883da4fe1f447d67a9d486de7c

data/VERSION

@@ -0,0 +1 @@
+0.5.4

data/lib/antigravity/agent.rb

@@ -5,16 +5,17 @@ module Antigravity
 
     attr_accessor :model, :system_instruction, :api_key
     attr_reader :tools, :skills, :hooks, :sidecars, :client, :logger_guard,
-                :workspace, :connection, :conversation
+                :workspace, :connection, :conversation, :policy, :policies, :born_at
 
     def initialize(model: nil, system_instruction: nil, tools: [],
-                   skills: [], workspace: nil, auto_logger: true, log_file: nil, &block)
+                   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 = system_instruction
-      @workspace = workspace ? File.expand_path(workspace) : nil
+      @workspace = resolve_workspace(workspace)
       @tools = tools.dup
       @skills = []
+      @policies = []
       @sidecars = []
       @hooks = Hooks.new
       @client = Client.new
@@ -22,6 +23,7 @@ module Antigravity
       @connection = nil
       @conversation = nil
       @connected = false
+      @born_at = Time.now
 
       # Register pre-provided tools into the tool runner
       @tool_runner = ToolRunner.new
@@ -30,6 +32,15 @@ module Antigravity
       # 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(log_file)
@@ -38,6 +49,13 @@ module Antigravity
       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.
@@ -51,11 +69,21 @@ module Antigravity
       end
     end
 
+    def workspace=(path)
+      @workspace = resolve_workspace(path)
+    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!
 
@@ -66,8 +94,28 @@ module Antigravity
       )
 
       harness_config = build_harness_config
+
+      # Emit indexing hooks — workspace indexing happens during session init
+      index_t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC) if @workspace
+      hooks.emit(:indexing_start, { workspace: @workspace }) if @workspace
+
       @conversation.initialize_session!(harness_config: harness_config)
       @connected = true
+
+      if @workspace
+        index_elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - index_t0
+        hooks.emit(:indexing_done, { workspace: @workspace, elapsed: index_elapsed.round(2) })
+      end
+
+      # 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
 
@@ -76,6 +124,14 @@ module Antigravity
     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
@@ -85,6 +141,7 @@ module Antigravity
     # --- 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)
 
@@ -118,6 +175,21 @@ module Antigravity
       @conversation.session_summary(model: @model)
     end
 
+    # Seconds since agent was created
+    def uptime
+      Time.now - @born_at
+    end
+
+    # Human-readable uptime: "1m 23.4s", "7.3s"
+    def uptime_human
+      secs = uptime
+      if secs >= 60
+        "#{(secs / 60).to_i}m #{(secs % 60).round(1)}s"
+      else
+        "#{secs.round(1)}s"
+      end
+    end
+
     # --- Tool Registration ---
 
     def register_tool(tool_or_name = nil, description: "", &block)
@@ -223,6 +295,16 @@ module Antigravity
       true
     end
 
+    def lifecycle_logger_enabled?
+      # Explicit opt-in (strip handles trailing spaces in .env files)
+      return true if ENV['ANTIGRAVITY_LIFECYCLE']&.strip == '1'
+      # Rails/Rack test or development
+      return true if %w[test development].include?(ENV['RAILS_ENV']&.strip&.downcase)
+      return true if %w[test development].include?(ENV['RACK_ENV']&.strip&.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'
@@ -308,5 +390,22 @@ module Antigravity
       @skills << skill
       skill
     end
+
+    def resolve_workspace(val)
+      return nil if val.nil? || val == false
+
+      raw_path = case val
+                 when :here, :current, true, '.'
+                   '.'
+                 else
+                   val.to_s
+                 end
+
+      expanded = File.expand_path(raw_path)
+      expanded += '/' unless expanded.end_with?('/')
+
+      $stderr.puts "📁 Setting workspace to \e[34m#{expanded}\e[0m" rescue nil
+      expanded
+    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/connection/binary_fetcher.rb

@@ -87,7 +87,7 @@ module Antigravity
 
           unless wheel
             # Try all versions for the platform
-            versions = data['releases']&.keys&.sort_by { |v| Gem::Version.new(v) rescue v }&.reverse
+            versions = data['releases']&.keys&.sort_by { |v| Gem::Version.correct?(v) ? Gem::Version.new(v) : Gem::Version.new('0') }&.reverse
             versions&.each do |ver|
               files = data.dig('releases', ver) || []
               wheel = files.find { |u| u['filename']&.include?(platform) && u['filename']&.end_with?('.whl') }
@@ -134,7 +134,11 @@ module Antigravity
           # 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)
+          success = system('unzip', '-q', '-o', wheel_path, '-d', extract_dir)
+          unless success
+            FileUtils.rm_rf(extract_dir)
+            raise HarnessNotFoundError, "Failed to extract wheel using unzip command"
+          end
 
           # Search for the binary inside (prefer localharness over language_server)
           candidates = Dir.glob("#{extract_dir}/**/localharness") +

data/lib/antigravity/connection/local_connection.rb

@@ -121,8 +121,7 @@ module Antigravity
       end
 
       def perform_handshake!
-        storage_dir = File.join(Dir.tmpdir, "antigravity-ruby-#{$$}")
-        FileUtils.mkdir_p(storage_dir)
+        storage_dir = Dir.mktmpdir('antigravity-ruby-')
 
         # Send InputConfig via stdin
         input_config = Protocol.encode_input_config(

data/lib/antigravity/conversation.rb

@@ -59,6 +59,11 @@ module Antigravity
       @turn_count += 1
       @last_turn_usage = empty_usage
 
+      # GHI #18: Drain any stale messages from the WebSocket buffer before sending
+      # a new prompt. This prevents leftover FULLY_IDLE from previous turns or init
+      # from being consumed by collect_response.
+      drain_stale_messages
+
       # Send user input (protobuf InputEvent with user_input string field)
       input_event = {
         userInput: prompt
@@ -87,6 +92,20 @@ module Antigravity
 
     private
 
+    # GHI #18: Non-blocking drain of stale WebSocket messages (FULLY_IDLE leftovers).
+    # During gaps between turns (e.g. voice transcription taking 5-10s), the harness
+    # may send trajectory updates that would confuse the next collect_response call.
+    def drain_stale_messages
+      drained = 0
+      loop do
+        msg = @ws.receive_json(timeout: 0.05, idle_timeout: 0.05) rescue nil
+        break unless msg
+        drained += 1
+        @hooks&.emit(:ws_message, { _debug: 'drained_stale_message', message_keys: msg.keys, drained_count: drained })
+      end
+      @hooks&.emit(:ws_message, { _debug: 'drain_complete', count: drained }) if drained > 0
+    end
+
     def collect_response(timeout: Antigravity.config.timeout_llm, &block)
       text_parts = []
       thinking_parts = []
@@ -94,11 +113,14 @@ module Antigravity
       tool_calls_count = 0
       finished = false
       finished_at = nil
+      seen_any_step = false          # GHI #18: track if we've seen real work from this turn
+      turn_started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
       @ws.each_message(timeout: timeout) do |msg|
         @hooks&.emit(:ws_message, msg)
 
         if (step = msg[:stepUpdate])
+          seen_any_step = true
           step_record = parse_step(step)
           steps << step_record
 
@@ -109,10 +131,9 @@ module Antigravity
 
           if step[:textDelta] && !step[:textDelta].empty? && is_model_step && is_target_user && !is_error_step
             text_parts << step[:textDelta]
-            chunk = Message.new(
+            chunk = Chunk.new(
               content: step[:textDelta],
-              role: :assistant,
-              delta: true
+              role: :assistant
             )
             block&.call(chunk)
           end
@@ -144,30 +165,48 @@ module Antigravity
         # Top-level tool call (custom tools are sent as separate messages, not in stepUpdate)
         if (tool_call = msg[:toolCall])
           tool_calls_count += 1
+          seen_any_step = true
           handle_tool_call(tool_call)
         end
 
-        # Usage update
+        # Usage update — do NOT set seen_any_step here!
+        # usageUpdate can leak from the previous turn and trick the GHI #18
+        # stale-FULLY_IDLE guard into accepting a stale FULLY_IDLE as real.
         if (usage = msg[:usageUpdate])
           update_usage(usage)
         end
 
         # Trajectory state: STATE_FULLY_IDLE / STATE_CANCELLED = turn complete (authoritative signal from harness)
-        # This is the MOST authoritative signal — always stop, even with empty text.
+        # GHI #18 + #24 FIX: Only honor FULLY_IDLE if we've seen at least one stepUpdate or toolCall
+        # (NOT usageUpdate — it leaks across turns) from this turn, OR if enough time has elapsed
+        # (2s) that this can't be a stale leftover. A stale FULLY_IDLE from a previous turn sitting
+        # in the WebSocket buffer was causing collect_response to return immediately with 0B text.
         if (traj = msg[:trajectoryStateUpdate])
           if traj[:state].to_s =~ /FULLY_IDLE|CANCELLED/
-            finished = true
-            finished_at = Time.now
+            if seen_any_step
+              finished = true
+              finished_at = Time.now
+            else
+              # Stale FULLY_IDLE — skip it (likely leftover from previous turn or init)
+              @hooks&.emit(:ws_message, { _debug: 'skipped_stale_fully_idle', seen_any_step: seen_any_step })
+            end
           end
         end
 
         # Stop conditions (in priority order):
-        # 1. Session end — always stop
-        # 2. Model response DONE or trajectory FULLY_IDLE / CANCELLED — turn complete
-        if msg.key?(:sessionEndResponse) || finished
+        # 1. Session end — always hard-stop immediately
+        # 2. Finished (DONE or FULLY_IDLE) WITH text — short drain for trailing usage
+        # 3. Finished WITHOUT text but with steps — model was working (thinking),
+        #    text is likely still in-flight. Drain longer (3s) to catch it. (GHI #24)
+        # 4. Not finished but text started — idle timeout for more text
+        if msg.key?(:sessionEndResponse)
           :stop
+        elsif finished && !text_parts.empty?
+          [:idle_timeout, 0.5]
+        elsif finished && text_parts.empty?
+          # FULLY_IDLE arrived but no text yet — wait longer for trailing text
+          [:idle_timeout, 3.0]
         elsif !text_parts.empty?
-          # If assistant has sent text response, allow 3s idle timeout for trailing metadata
           [:idle_timeout, 3.0]
         end
       end
@@ -208,10 +247,40 @@ module Antigravity
       # Symbolize keys for Ruby kwargs
       kwargs = args.transform_keys(&:to_sym)
 
-      begin
-        result = @tool_runner.execute(tool_name, **kwargs)
-      rescue ToolNotFoundError => e
-        result = { error: e.message }
+      # Emit tool_call hook BEFORE execution
+      @hooks&.emit(:tool_call, { tool_name: tool_name, params: args, tool_id: tool_id })
+
+      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      policy_check = @hooks ? @hooks.run_pre_tool(tool_name, args) : { allowed: true }
+
+      if !policy_check[:allowed]
+        reason = policy_check[:reason]
+        # Same format as client.rb sidecar emission
+        @hooks&.emit(:tool_blocked, { tool: tool_name, reason: reason })
+        result = "❌ TOOL BLOCKED: #{reason}"
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+        
+        # We run the post_tool hook here as well to satisfy AgentLogger's pairing
+        result = @hooks ? @hooks.run_post_tool(tool_name, args, result) : result
+        @hooks&.emit(:tool_result, { tool_name: tool_name, result: result.to_s, duration: duration, tool_id: tool_id })
+      else
+        begin
+          raw_result = @tool_runner.execute(tool_name, **kwargs)
+          
+          # Run post_tool filters/maskers
+          result = @hooks ? @hooks.run_post_tool(tool_name, args, raw_result) : raw_result
+          
+          duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+
+          # Emit tool_result hook AFTER execution
+          @hooks&.emit(:tool_result, { tool_name: tool_name, result: result.to_s, duration: duration, tool_id: tool_id })
+        rescue ToolNotFoundError => e
+          duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+          result = { error: e.message }
+
+          # Emit tool_error hook on failure
+          @hooks&.emit(:tool_error, { tool_name: tool_name, error: e.message, duration: duration, tool_id: tool_id })
+        end
       end
 
       # Send tool response back (protobuf InputEvent.tool_response format)

data/lib/antigravity/harness.rb

@@ -22,8 +22,7 @@ module Antigravity
         return true
       end
 
-      cmd = "#{@bin_path} --port=#{@port}"
-      @stdin, @stdout, @stderr, wait_thr = Open3.popen3(cmd)
+      @stdin, @stdout, @stderr, wait_thr = Open3.popen3(@bin_path, "--port=#{@port}")
       @pid = wait_thr.pid
 
       at_exit { stop! }

data/lib/antigravity/lifecycle_logger.rb

@@ -0,0 +1,161 @@
+# 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[:total_tokens] || 0
+      tok_str  = tokens > 999 ? "#{(tokens / 1000.0).round(1)}k" : tokens.to_s
+      tok_str  = "🪙#{tok_str}"
+      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("\n🪝🟢 #{C.dim("session_start")} | model=#{C.cyan(model)} | conv=#{C.cyan(conv_id)}")
+      end
+
+      agent.hooks.on(:indexing_start) do |info|
+        ws = info[:workspace] || '?'
+        puts C.gray("🪝 📂 #{C.dim("indexing")}       | #{C.blue(ws)}")
+      end
+
+      agent.hooks.on(:indexing_done) do |info|
+        ws = info[:workspace] || '?'
+        elapsed = info[:elapsed] ? "#{info[:elapsed]}s" : '?'
+        puts C.gray("🪝 ✅ #{C.dim("indexed")}        | #{C.blue(ws)} | #{C.green(elapsed)}")
+      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[:total_tokens] || 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} | #{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}B")} #{C.dim("#{lines}L")}"]
+        parts << "#{C.magenta("#{thinking_len}B")} think" if thinking_len > 0
+        parts << "#{C.cyan("#{tool_count}")} tools" if tool_count > 0
+        parts << "#{C.blue("#{elapsed}s")}"
+
+        puts C.gray("\n🪝 ⬅️  #{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_str = info[:result].to_s
+        result_len = result_str.bytesize rescue 0
+        preview = result_str[0..120].gsub("\n", ' ')
+        preview += '...' if result_str.length > 120
+        duration = info[:duration] ? "#{info[:duration].round(2)}s" : nil
+        parts = [C.cyan(name), "#{result_len}B"]
+        parts << duration if duration
+        puts C.gray("  🪝 ✅ #{C.dim("tool_done")}  | #{parts.join(' | ')}")
+        puts C.dim("     → #{C.yellow(preview)}") if result_len > 0
+      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/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

data/lib/antigravity/policy.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require_relative 'policy/constants'
+
+module Antigravity
+  # ==========================================================================
+  # Antigravity::Policy — Declarative tool-access control for agents.
+  #
+  # ⚠️  ORDER DOES NOT MATTER!
+  #
+  # The DSL is declarative, like SQL — not imperative like a script.
+  # Rules are evaluated by PRECEDENCE, not by insertion order.
+  # You can write `allow` before `deny` or vice versa — same result.
+  #
+  # Precedence (highest wins):
+  #   1. Tool specificity:    specific tool > wildcard (nil)
+  #   2. Condition specificity: has `when:` > no `when:`
+  #   3. Restrictiveness:      deny > confirm > allow
+  #
+  # Example — these two policies behave identically:
+  #
+  #   Policy.define do          Policy.define do
+  #     allow :run_command        deny :run_command, when: cmd('rm')
+  #     deny :run_command,        allow :run_command
+  #       when: cmd('rm')       end
+  #   end
+  #
+  # In both cases, `rm` is denied (conditional deny beats unconditional
+  # allow), and everything else is allowed.
+  #
+  # See policy/constants.rb for curated command/file/tool lists.
+  # ==========================================================================
+  class Policy
+
+    # ------------------------------------------------------------------
+    # Rule — a single allow/deny/confirm entry in a policy.
+    # ------------------------------------------------------------------
+    class Rule
+      attr_reader :action, :tool_name, :condition, :handler
+
+      def initialize(action, tool_name = nil, condition: nil, handler: nil)
+        @action = action
+        @tool_name = tool_name
+        @condition = condition
+        @handler = handler
+      end
+
+      def matches?(tool, args)
+        return false if @tool_name && @tool_name.to_sym != tool.to_sym
+        return false if @condition && !@condition.call(name: tool, args: args)
+        true
+      end
+
+      # Precedence order (higher = wins):
+      # 1. Tool specificity: Specific tool > Wildcard (nil)
+      # 2. Condition specificity: Has predicate > No predicate
+      # 3. Action restrictiveness: Deny > Confirm > Allow
+      def precedence
+        specificity = @tool_name ? 1 : 0
+        condition_score = @condition ? 1 : 0
+        action_score = case @action
+                       when :deny then 3
+                       when :confirm then 2
+                       when :allow then 1
+                       else 0
+                       end
+        [specificity, condition_score, action_score]
+      end
+    end
+
+    # ------------------------------------------------------------------
+    # Constructor & factory methods
+    # ------------------------------------------------------------------
+
+    def initialize(&block)
+      @rules = []
+      @confirm_handler = nil
+      instance_eval(&block) if block_given?
+    end
+
+    def self.define(&block)
+      new(&block)
+    end
+
+    def self.allow_all
+      new { allow_all }
+    end
+
+    def self.deny_all
+      new { deny_all }
+    end
+
+    # ------------------------------------------------------------------
+    # Built-in presets
+    # ------------------------------------------------------------------
+
+    # Resolve a preset by name (symbol).
+    # @param name [Symbol] :cautious, :default, :turbo, :test, or :auto
+    # @return [Policy]
+    def self.preset(name)
+      case name.to_sym
+      when :cautious then cautious
+      when :default  then default
+      when :turbo    then turbo
+      when :test     then test
+      when :auto     then auto
+      else
+        raise ArgumentError, "Unknown preset :#{name}. Choose from: #{PRESET_NAMES.map { |n| ":#{n}" }.join(', ')}"
+      end
+    end
+
+    # 🔒 Cautious — read-only free, confirm everything else, hard-deny destructive.
+    # Best for: untrusted environments, production agents.
+    # NOTE: cat/head/tail/ls NOT in safe list — they can bypass view_file deny rules.
+    def self.cautious
+      define do
+        deny_all
+        READONLY_TOOLS.each { |t| allow t }
+        allow :run_command, when: cmd(*SAFE_CMDS, *SAFE_GIT_CMDS)
+        deny :run_command, when: cmd(*CATASTROPHIC_CMDS)
+        deny :run_command, when: cmd(*RISKY_CMDS)
+        deny :run_command, when: cmd(*DESTRUCTIVE_GIT_CMDS)
+        WRITE_TOOLS.each { |t| confirm t }
+        # 📂 Sandbox dirs: always writable, even in production
+        WRITE_TOOLS.each { |t| allow t, when: path(*SANDBOX_DIRS) }
+        confirm :run_command
+      end
+    end
+
+    # ⚖️ Default — balanced: allow reads + writes, confirm dangerous shell, protect sensitive files.
+    # Best for: day-to-day development, pair programming with an agent.
+    def self.default
+      define do
+        deny_all
+        READONLY_TOOLS.each { |t| allow t }
+        WRITE_TOOLS.each { |t| allow t }
+        WRITE_TOOLS.each { |t| confirm t, when: path(*SENSITIVE_FILES) }
+        allow :run_command
+        deny :run_command, when: cmd(*CATASTROPHIC_CMDS)
+        confirm :run_command, when: cmd(*RISKY_CMDS)
+        confirm :run_command, when: cmd(*DESTRUCTIVE_GIT_CMDS)
+      end
+    end
+
+    # 🚀 Turbo — wide open with seatbelts: allow everything, only hard-deny catastrophic.
+    # Best for: trusted dev environments, rapid prototyping.
+    def self.turbo
+      define do
+        allow_all
+        deny :run_command, when: cmd(*CATASTROPHIC_CMDS)
+        confirm :run_command, when: cmd(*DESTRUCTIVE_GIT_CMDS)
+        WRITE_TOOLS.each { |t| confirm t, when: path(*SENSITIVE_FILES) }
+      end
+    end
+
+    # 🧪 Test — permissive for test runners, but sandboxed.
+    # Best for: CI, test suites, RAILS_ENV=test.
+    def self.test
+      define do
+        allow_all
+        deny :run_command, when: cmd(*CATASTROPHIC_CMDS)
+        deny :run_command, when: cmd(*DESTRUCTIVE_GIT_CMDS)
+        confirm :run_command, when: cmd(*RISKY_CMDS)
+        WRITE_TOOLS.each { |t| confirm t, when: path(*SENSITIVE_FILES) }
+      end
+    end
+
+    # 🔮 Auto — reads RAILS_ENV, RACK_ENV, or ANTIGRAVITY_ENV and picks a preset.
+    # Falls back to :default if unrecognized or unset.
+    def self.auto
+      env = ENV['ANTIGRAVITY_ENV'] || ENV['RAILS_ENV'] || ENV['RACK_ENV']
+      preset_name = ENV_MAP.fetch(env.to_s.downcase, :default)
+      send(preset_name)
+    end
+
+    # ------------------------------------------------------------------
+    # DSL methods
+    # ------------------------------------------------------------------
+
+    def allow(tool_name = nil, **kwargs)
+      @rules << Rule.new(:allow, tool_name, condition: kwargs[:when])
+    end
+
+    def deny(tool_name = nil, **kwargs)
+      @rules << Rule.new(:deny, tool_name, condition: kwargs[:when])
+    end
+
+    def confirm(tool_name = nil, **kwargs, &block)
+      @rules << Rule.new(:confirm, tool_name, condition: kwargs[:when], handler: block)
+    end
+
+    def allow_all
+      allow(nil)
+    end
+
+    def deny_all
+      deny(nil)
+    end
+
+    def on_confirm(&block)
+      @confirm_handler = block
+    end
+
+    # ------------------------------------------------------------------
+    # Predicate helpers
+    # ------------------------------------------------------------------
+
+    def cmd(*patterns)
+      ->(ctx) do
+        args = ctx[:args]
+        cmd_arg = args[:command_line] || args['command_line'] || args[:CommandLine] || args['CommandLine']
+        return false unless cmd_arg
+
+        cmd_arg = cmd_arg.to_s
+        patterns.any? { |p| cmd_arg.include?(p.to_s) }
+      end
+    end
+
+    def path(*globs)
+      ->(ctx) do
+        args = ctx[:args]
+        path_arg = args[:path] || args['path'] ||
+                   args[:file] || args['file'] ||
+                   args[:target] || args['target'] ||
+                   args[:file_path] || args['file_path'] ||
+                   args[:target_file] || args['target_file']
+        return false unless path_arg
+
+        path_arg = path_arg.to_s
+        globs.any? { |g| File.fnmatch?(g.to_s, path_arg) }
+      end
+    end
+
+    def args_match(**matchers)
+      ->(ctx) do
+        args = ctx[:args]
+        matchers.any? do |k, v|
+          val = args[k.to_sym] || args[k.to_s]
+          val && v.match?(val.to_s)
+        end
+      end
+    end
+
+    # ------------------------------------------------------------------
+    # Evaluation engine
+    # ------------------------------------------------------------------
+
+    def evaluate(tool_name, args = {})
+      matching_rules = @rules.select { |r| r.matches?(tool_name, args) }
+      best_rule = matching_rules.max_by(&:precedence)
+
+      if best_rule
+        if best_rule.action == :confirm
+          handler = best_rule.handler || @confirm_handler
+          if handler
+            ctx = { name: tool_name, args: args }
+            result = handler.call(ctx)
+            { status: result ? :allow : :deny }
+          else
+            { status: :deny }
+          end
+        elsif best_rule.action == :deny
+          { status: :deny, reason: "Denied by policy" }
+        else
+          { status: :allow }
+        end
+      else
+        { status: :deny } # Default to deny if no rules match
+      end
+    end
+  end
+end

data/lib/antigravity/skill.rb

@@ -71,7 +71,11 @@ module Antigravity
 
       content = File.read(skill_file, encoding: 'UTF-8')
       if content =~ /\A(---\s*\n.*?\n?)^(---\s*$\n?)/m
-        front_matter = YAML.safe_load(Regexp.last_match(1)) || {}
+        front_matter = begin
+                         YAML.safe_load(Regexp.last_match(1)) || {}
+                       rescue Psych::SyntaxError => e
+                         raise ArgumentError, "Invalid YAML frontmatter in #{skill_file}: #{e.message}"
+                       end
         @name = front_matter["name"] || File.basename(@path)
         @description = front_matter["description"] || ""
         @metadata = front_matter.fetch("metadata", {})

data/lib/antigravity/version.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
 module Antigravity
-  VERSION = File.read(File.expand_path("../../VERSION", __dir__)).strip rescue "0.1.0"
+  VERSION = begin
+    version_file = [
+      File.expand_path("../../VERSION", __dir__),
+      File.expand_path("../VERSION", __dir__)
+    ].find { |f| File.exist?(f) }
+    version_file ? File.read(version_file).strip : "0.5.0"
+  end
 end

data/lib/antigravity.rb

@@ -14,6 +14,7 @@ require_relative "antigravity/config"
 require_relative "antigravity/message"
 require_relative "antigravity/protocol"
 require_relative "antigravity/harness"
+require_relative "antigravity/policy"
 require_relative "antigravity/hooks"
 require_relative "antigravity/guards"
 require_relative "antigravity/sidecar"
@@ -26,6 +27,8 @@ require_relative "antigravity/connection/binary_fetcher"
 require_relative "antigravity/connection/websocket_client"
 require_relative "antigravity/connection/local_connection"
 require_relative "antigravity/conversation"
+require_relative "antigravity/colors"
+require_relative "antigravity/lifecycle_logger"
 require_relative "antigravity/agent"
 
 module Antigravity

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: antigravity-sdk
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.4
 platform: ruby
 authors:
 - Riccardo Carlesso
@@ -51,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 description: An elegant, Ruby-like SDK for building autonomous AI agents with Google
   Antigravity.
 email:
@@ -59,10 +73,12 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- VERSION
 - lib/antigravity.rb
 - lib/antigravity/agent.rb
 - lib/antigravity/base.rb
 - lib/antigravity/client.rb
+- lib/antigravity/colors.rb
 - lib/antigravity/config.rb
 - lib/antigravity/connection/binary_fetcher.rb
 - lib/antigravity/connection/local_connection.rb
@@ -73,7 +89,10 @@ files:
 - lib/antigravity/guards.rb
 - lib/antigravity/harness.rb
 - lib/antigravity/hooks.rb
+- lib/antigravity/lifecycle_logger.rb
 - lib/antigravity/message.rb
+- lib/antigravity/policy.rb
+- lib/antigravity/policy/constants.rb
 - lib/antigravity/protocol.rb
 - lib/antigravity/sidecar.rb
 - lib/antigravity/skill.rb