antigravity-sdk 0.2.0 → 0.4.2

data/lib/antigravity/emojis.rb

@@ -2,8 +2,9 @@
 
 module Antigravity
   EMOJIS = {
+    antigravity: "🛰️",
     gem: "💎",
-    agent: "💎",
+    agent: "🕵️‍♂️",
     prompt: "💬",
     response: "🤖",
     thinking: "🤔",
@@ -13,35 +14,63 @@ module Antigravity
     sidecar: "🚗",
     logger: "🪵",
     skill: "📁",
+    check: "✅",
+    magnifying: "🔍",
+    workspace: "📂",
+    message: "💬",
     guard: "🛡️",
     test: "🧪",
-    success: "✅"
+    success: "✅",
+    unknown: "🤷"
+  }.freeze
+
+  # Name fragments we recognise in the class hierarchy
+  EMOJI_CLASS_MAP = {
+    "Agent" => :agent,
+    "Tool" => :tool,
+    "Sidecar" => :sidecar,
+    "Runner" => :sidecar,
+    "Skill" => :skill,
+    "Message" => :message,
+    "Chunk" => :message,
+    "Guard" => :guard,
+    "Logger" => :logger
   }.freeze
 
   class << self
     def emoji(key)
-      EMOJIS[key.to_sym] || "💎"
+      EMOJIS[key.to_sym] || EMOJIS[:unknown]
     end
 
     def emoji_for(target)
-      key = case target
-            when Message, Chunk
-              target.respond_to?(:role) && target.role == :user ? :prompt : :response
-            when Symbol, String
-              target
-            else
-              klass = target.is_a?(Class) || target.is_a?(Module) ? target : target.class
-              matched_part = klass.name&.split("::")&.reverse&.find do |part|
-                %w[Agent Tool Sidecar Skill Message Guard Logger].include?(part)
-              end
-              matched_part ? matched_part.downcase.to_sym : :gem
-            end
-
+      key = resolve_emoji_key(target)
       emoji(key)
     end
+
+    private
+
+    def resolve_emoji_key(target)
+      # Message/Chunk: role-aware
+      if target.is_a?(Message) || (defined?(Chunk) && target.is_a?(Chunk))
+        return target.respond_to?(:role) && target.role == :user ? :prompt : :response
+      end
+
+      # Direct symbol/string lookup
+      return target if target.is_a?(Symbol) || target.is_a?(String)
+
+      # Class hierarchy reflection
+      klass = target.is_a?(Class) || target.is_a?(Module) ? target : target.class
+      parts = klass.name&.split("::") || []
+      parts.reverse_each do |part|
+        return EMOJI_CLASS_MAP[part] if EMOJI_CLASS_MAP.key?(part)
+      end
+
+      :unknown
+    end
   end
 
-  # Mixin providing polymorphic .emoji class and instance methods
+  # Mixin providing polymorphic .emoji class and #emoji instance methods.
+  # Auto-included by Antigravity::Base via inherited hook.
   module Emojifiable
     def emoji
       Antigravity.emoji_for(self)

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/message.rb

@@ -1,24 +1,37 @@
 # frozen_string_literal: true
 
 module Antigravity
-  class Message
-    include Emojifiable
+  # 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/protocol.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require_relative 'version'
+
+module Antigravity
+  # Hand-rolled protobuf encoding/decoding for the 2 stdio handshake messages:
+  #   InputConfig  (SDK → localharness via stdin)
+  #   OutputConfig (localharness → SDK via stdout)
+  #
+  # Uses raw protobuf wire format to avoid the google-protobuf gem dependency.
+  # See: https://github.com/palladius/antigravity-ruby-sdk/issues/7
+  #
+  # Wire format reference: https://protobuf.dev/programming-guides/encoding/
+  #   Varint:           wire type 0, tag = (field_number << 3) | 0
+  #   Length-delimited: wire type 2, tag = (field_number << 3) | 2
+  class Protocol
+    # --- Encoding: InputConfig ---
+    # message InputConfig {
+    #   string storage_directory = 1;
+    #   uint32 port = 2;           # optional, we leave 0
+    #   string bind_address = 3;   # default "localhost"
+    #   ClientInfo client_info = 4;
+    #   map<string, string> env = 5;
+    # }
+    # message ClientInfo {
+    #   string language = 1;
+    #   string version = 2;
+    #   string language_version = 3;
+    #   string os = 4;
+    #   string os_version = 5;
+    # }
+    def self.encode_input_config(storage_directory:, bind_address: 'localhost', env: {})
+      buf = ''.b
+
+      # field 1: storage_directory (string)
+      buf << encode_string_field(1, storage_directory)
+
+      # field 3: bind_address (string, default "localhost")
+      buf << encode_string_field(3, bind_address)
+
+      # field 4: client_info (embedded message)
+      client_info = encode_client_info
+      buf << encode_bytes_field(4, client_info)
+
+      # field 5: env map entries (each is an embedded message with key=1, value=2)
+      env.each do |key, value|
+        entry = encode_string_field(1, key.to_s) + encode_string_field(2, value.to_s)
+        buf << encode_bytes_field(5, entry)
+      end
+
+      # Length-prefix: 4-byte little-endian uint32
+      [buf.bytesize].pack('V') + buf
+    end
+
+    # --- Decoding: OutputConfig ---
+    # message OutputConfig {
+    #   int32  port = 1;
+    #   string api_key = 2;
+    # }
+    def self.decode_output_config(data)
+      raise ProtocolError, 'Data too short for length prefix' if data.bytesize < 4
+
+      declared_len = data[0..3].unpack1('V')
+      payload = data[4..]
+
+      raise ProtocolError, "Truncated payload: expected #{declared_len}, got #{payload&.bytesize || 0}" if payload.nil? || payload.bytesize < declared_len
+
+      result = { port: 0, api_key: '' }
+      pos = 0
+
+      while pos < declared_len
+        tag_byte, new_pos = decode_varint(payload, pos)
+        pos = new_pos
+        field_number = tag_byte >> 3
+        wire_type = tag_byte & 0x07
+
+        case wire_type
+        when 0 # varint
+          value, pos = decode_varint(payload, pos)
+          result[:port] = value if field_number == 1
+        when 2 # length-delimited
+          length, pos = decode_varint(payload, pos)
+          value = payload[pos, length]
+          pos += length
+          result[:api_key] = value.force_encoding('UTF-8') if field_number == 2
+        else
+          raise ProtocolError, "Unsupported wire type #{wire_type} at position #{pos}"
+        end
+      end
+
+      result
+    end
+
+    # Read a length-prefixed frame from an IO (blocking).
+    # Returns the raw payload bytes.
+    def self.read_length_prefixed(io, timeout: 10)
+      len_bytes = read_exactly(io, 4, timeout: timeout)
+      raise ProtocolError, 'EOF reading length prefix' unless len_bytes&.bytesize == 4
+
+      payload_len = len_bytes.unpack1('V')
+      raise ProtocolError, "Unreasonable payload length: #{payload_len}" if payload_len > 1_000_000
+
+      frame = [payload_len].pack('V') + read_exactly(io, payload_len, timeout: timeout)
+      frame
+    end
+
+    class << self
+      private
+
+      def encode_client_info
+        buf = ''.b
+        buf << encode_string_field(1, 'ruby')
+        buf << encode_string_field(2, Antigravity::VERSION)
+        buf << encode_string_field(3, RUBY_VERSION)
+        buf << encode_string_field(4, ruby_platform_os)
+        buf << encode_string_field(5, RUBY_PLATFORM)
+        buf
+      end
+
+      def ruby_platform_os
+        case RUBY_PLATFORM
+        when /darwin/i then 'macos'
+        when /linux/i  then 'linux'
+        when /win/i    then 'windows'
+        else RUBY_PLATFORM
+        end
+      end
+
+      # Encode a string field: tag + varint length + UTF-8 bytes
+      def encode_string_field(field_number, value)
+        encode_bytes_field(field_number, value.to_s.encode('UTF-8').b)
+      end
+
+      # Encode a length-delimited field: tag + varint length + raw bytes
+      def encode_bytes_field(field_number, bytes)
+        tag = (field_number << 3) | 2 # wire type 2 = length-delimited
+        encode_varint_bytes(tag) + encode_varint_bytes(bytes.bytesize) + bytes
+      end
+
+      # Encode an integer as varint bytes
+      def encode_varint_bytes(value)
+        bytes = []
+        loop do
+          byte = value & 0x7F
+          value >>= 7
+          byte |= 0x80 if value > 0
+          bytes << byte
+          break if value == 0
+        end
+        bytes.pack('C*')
+      end
+
+      # Decode a varint starting at position, returns [value, new_position]
+      def decode_varint(data, pos)
+        result = 0
+        shift = 0
+        loop do
+          raise ProtocolError, "Varint extends past end of data at pos #{pos}" if pos >= data.bytesize
+
+          byte = data.getbyte(pos)
+          pos += 1
+          result |= (byte & 0x7F) << shift
+          break if (byte & 0x80) == 0
+
+          shift += 7
+          raise ProtocolError, 'Varint too long' if shift >= 64
+        end
+        [result, pos]
+      end
+
+      # Read exactly n bytes from IO with timeout
+      def read_exactly(io, n, timeout: 10)
+        buf = ''.b
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        while buf.bytesize < n
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise ProtocolError, "Timeout reading #{n} bytes from harness" if remaining <= 0
+
+          ready = IO.select([io], nil, nil, [remaining, 0.1].min)
+          if ready
+            chunk = io.read_nonblock(n - buf.bytesize, exception: false)
+            case chunk
+            when String then buf << chunk
+            when :wait_readable then next
+            when nil then raise ProtocolError, 'EOF while reading from harness'
+            end
+          end
+        end
+        buf
+      end
+    end
+  end
+end

data/lib/antigravity/sidecar.rb

@@ -6,9 +6,9 @@ require "fileutils"
 
 module Antigravity
   module Sidecar
-    # Base class for non-blocking agent sidecars
-    class Base
-      include Emojifiable
+    # Abstract runner for non-blocking agent sidecars.
+    # Subclass and implement #process_event.
+    class Runner < Antigravity::Base
 
       attr_reader :name, :queue, :worker_thread
 
@@ -52,7 +52,7 @@ module Antigravity
     end
 
     # Async Audit Logger Sidecar
-    class AuditLogger < Base
+    class AuditLogger < Runner
       attr_reader :log_file
 
       def initialize(log_file = "log/agent_audit.jsonl")
@@ -72,7 +72,7 @@ module Antigravity
     end
 
     # Async Vulnerability & Code Quality Scanner Sidecar
-    class VulnerabilityScanner < Base
+    class VulnerabilityScanner < Runner
       attr_reader :scanned_events
 
       def initialize
@@ -90,5 +90,7 @@ module Antigravity
         @scanned_events << { tool: tool_name, params: params, verified: true }
       end
     end
+    # Backward-compatible alias
+    Base = Runner
   end
 end

data/lib/antigravity/skill.rb

@@ -3,31 +3,78 @@
 require "yaml"
 
 module Antigravity
-  class Skill
-    include Emojifiable
+  # Represents an Agent Skill loaded from a SKILL.md file or defined inline.
+  # Spec: https://agentskills.io/specification
+  #
+  # A skill directory must contain a SKILL.md with YAML frontmatter:
+  #   ---
+  #   name: my-skill
+  #   description: What this skill does
+  #   ---
+  #   # Instructions in markdown...
+  class Skill < Base
 
-    attr_reader :name, :description, :instructions, :path
+    attr_reader :name, :description, :instructions, :path, :metadata
 
+    # Load a skill from a directory containing SKILL.md.
+    # @param path [String] path to skill directory
     def initialize(path)
       @path = File.expand_path(path)
+      @metadata = {}
       parse_skill_file
     end
 
+    # Factory: load from directory path.
     def self.load(path)
       new(path)
     end
 
+    # Factory: create an inline skill (no file needed).
+    # @param name [String] skill name (lowercase, hyphenated)
+    # @param description [String] what the skill does
+    # @param instructions [String] the skill instructions (markdown)
+    # @return [Skill] an inline skill instance
+    def self.inline(name:, description:, instructions:)
+      skill = allocate
+      skill.send(:init_inline, name: name, description: description, instructions: instructions)
+      skill
+    end
+
+    # Check if a directory is a valid skill (contains SKILL.md).
+    # @param path [String] directory path to check
+    # @return [Boolean]
+    def self.skill_dir?(path)
+      SkillResolver.skill_dir?(path)
+    end
+
+    def to_s
+      "#<Skill name=#{@name.inspect} path=#{@path.inspect}>"
+    end
+
+    def inspect
+      "#<Antigravity::Skill name=#{@name.inspect} description=#{@description.inspect} path=#{@path.inspect}>"
+    end
+
     private
 
+    def init_inline(name:, description:, instructions:)
+      @name = name
+      @description = description
+      @instructions = instructions
+      @path = nil  # inline skills have no path
+      @metadata = {}
+    end
+
     def parse_skill_file
       skill_file = File.join(@path, "SKILL.md")
       raise ArgumentError, "SKILL.md not found at #{@path}" unless File.exist?(skill_file)
 
-      content = File.read(skill_file)
+      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))
-        @name = front_matter["name"]
-        @description = front_matter["description"]
+        front_matter = YAML.safe_load(Regexp.last_match(1)) || {}
+        @name = front_matter["name"] || File.basename(@path)
+        @description = front_matter["description"] || ""
+        @metadata = front_matter.fetch("metadata", {})
         @instructions = Regexp.last_match.post_match.strip
       else
         @name = File.basename(@path)