antigravity-sdk 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2a5cad1edda5eb5efaa58d7d5104ba433f8469a923bb5f862b9f1bcb4219021
-  data.tar.gz: 75c9924910ef8aab407444abfecfa0f7e989473d8be251691e4e07c9d04499aa
+  metadata.gz: effdabdb0588788c4b168749a2578e2e1f07aa877a54bfd80fe1969d42f497d2
+  data.tar.gz: 3debe5e4295f8c2e2bcd4c37ec7ea52ea11a77d034370320d4064b52aa08cc29
 SHA512:
-  metadata.gz: ac637d9792051869f94b4a8ebc716fd604b2db18886e19b105190a9636c7e7bce418aeece52a360b139b1c534e560605b0dc578fab10b3e06ac913dc454663eb
-  data.tar.gz: c8b6e4bee541853abd1f993d5423cc3426c830a24aba58f6790ec30e093279163b83e258a824811380ac5a603cba749dd7a099dee5ad4a2160fe25a7373c6e51
+  metadata.gz: 4123cbc798ddbfaa82ea0f854e89adb122491d9a99b52f501c15350401e660109be3ca778b6142720f0259256992dbbb73d4d2371d8bdefcda266bd4d98591cf
+  data.tar.gz: d80349e13c564c74bb81c5c8ba14887f39af36507d03b3c6a5883ed3a885359570210d10b9fc1f8cc3e8a0c193408de176f3316129a58e1d6303352c5527ed01

data/lib/antigravity/agent.rb

@@ -8,13 +8,14 @@ module Antigravity
                 :workspace, :connection, :conversation
 
     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
       @tools = tools.dup
       @skills = []
+      @policies = []
       @sidecars = []
       @hooks = Hooks.new
       @client = Client.new
@@ -30,6 +31,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 +48,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.
@@ -56,6 +73,12 @@ module Antigravity
     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!
 
@@ -68,6 +91,16 @@ module Antigravity
       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
 
@@ -76,6 +109,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 +126,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)
 
@@ -223,6 +265,16 @@ 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'
@@ -308,5 +360,9 @@ module Antigravity
       @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/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
 
@@ -144,20 +166,31 @@ 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
         if (usage = msg[:usageUpdate])
           update_usage(usage)
+          seen_any_step = true
         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 FIX: Only honor FULLY_IDLE if we've seen at least one stepUpdate/toolCall/usageUpdate
+        # from this turn, OR if enough time has elapsed (1s) 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 zero steps/text.
         if (traj = msg[:trajectoryStateUpdate])
+          elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - turn_started_at
           if traj[:state].to_s =~ /FULLY_IDLE|CANCELLED/
-            finished = true
-            finished_at = Time.now
+            if seen_any_step || elapsed > 1.0
+              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', elapsed: elapsed.round(3) })
+            end
           end
         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/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.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.0
 platform: ruby
 authors:
 - Riccardo Carlesso
@@ -63,6 +63,7 @@ files:
 - 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 +74,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