antigravity-sdk 0.3.0 → 0.4.2

data/lib/antigravity/message.rb

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

data/lib/antigravity/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/skill.rb

@@ -3,30 +3,78 @@
 require "yaml"
 
 module Antigravity
+  # 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)

data/lib/antigravity/skill_resolver.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Antigravity
+  # Resolves skill paths from various inputs: single skill dir, container dir,
+  # or GitHub URL. Returns expanded absolute paths to skill directories.
+  #
+  # Resolution logic:
+  #   1. Path contains SKILL.md -> single skill
+  #   2. Path has a skills/ subfolder -> discover children with SKILL.md
+  #   3. Path children have SKILL.md -> flat container discovery
+  #   4. GitHub URL -> clone/cache then resolve locally
+  #
+  # Spec compliance: https://agentskills.io/specification
+  class SkillResolver
+    GITHUB_URL_PATTERN = %r{\Ahttps?://github\.com/}i
+    CACHE_DIR = File.expand_path('~/.antigravity/cache/ruby-sdk/skills')
+
+    # Resolve a path or URL to an array of valid skill directory paths.
+    # @param path_or_url [String] local path or GitHub URL
+    # @return [Array<String>] expanded absolute paths to skill directories
+    def self.resolve(path_or_url)
+      path_or_url = path_or_url.to_s.strip
+
+      if github_url?(path_or_url)
+        resolve_github(path_or_url)
+      else
+        resolve_local(path_or_url)
+      end
+    end
+
+    # Discover all skill directories inside a container path.
+    # Checks for skills/ subfolder first, then scans children directly.
+    # @param container_path [String] path to scan for skills
+    # @return [Array<String>] sorted list of skill directory paths
+    def self.discover(container_path)
+      expanded = File.expand_path(container_path)
+      return [] unless File.directory?(expanded)
+
+      # Check for skills/ subfolder first (convention from agentskills.io)
+      skills_subdir = File.join(expanded, 'skills')
+      scan_dir = File.directory?(skills_subdir) ? skills_subdir : expanded
+
+      Dir.children(scan_dir)
+         .map { |child| File.join(scan_dir, child) }
+         .select { |child_path| skill_dir?(child_path) }
+         .sort
+    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)
+      File.directory?(path) && File.exist?(File.join(path, 'SKILL.md'))
+    end
+
+    # Check if a string looks like a GitHub URL.
+    # @param str [String]
+    # @return [Boolean]
+    def self.github_url?(str)
+      str.match?(GITHUB_URL_PATTERN)
+    end
+
+    class << self
+      private
+
+      def resolve_local(path)
+        expanded = File.expand_path(path)
+        raise ArgumentError, "Skill path does not exist: #{expanded}" unless File.exist?(expanded)
+        raise ArgumentError, "Skill path is not a directory: #{expanded}" unless File.directory?(expanded)
+
+        # Case 1: Direct skill dir (has SKILL.md)
+        return [expanded] if skill_dir?(expanded)
+
+        # Case 2 & 3: Container dir -- discover children
+        discovered = discover(expanded)
+        return discovered unless discovered.empty?
+
+        raise ArgumentError, "No skills found at #{expanded}. Expected SKILL.md or a skills/ subfolder."
+      end
+
+      # Parse a GitHub URL into components.
+      # Supports:
+      #   https://github.com/org/repo
+      #   https://github.com/org/repo/tree/main/skills/my-skill
+      #   https://github.com/org/repo/tree/main/skills
+      #
+      # Returns [org, repo, subpath_or_nil]
+      def parse_github_url(url)
+        # Strip trailing slash
+        url = url.chomp('/')
+
+        case url
+        when %r{github\.com/([^/]+)/([^/]+)/tree/[^/]+/(.+)}
+          # URL with tree/branch/subpath
+          [Regexp.last_match(1), Regexp.last_match(2), Regexp.last_match(3)]
+        when %r{github\.com/([^/]+)/([^/]+)(?:\.git)?/?$}
+          # Bare repo URL
+          [Regexp.last_match(1), Regexp.last_match(2), nil]
+        when %r{github\.com/([^/]+)/([^/]+)/(.+)}
+          # URL with subpath but no /tree/branch/ (e.g. from skill_name:)
+          [Regexp.last_match(1), Regexp.last_match(2), Regexp.last_match(3)]
+        else
+          raise ArgumentError, "Cannot parse GitHub URL: #{url}"
+        end
+      end
+
+      def resolve_github(url)
+        org, repo, subpath = parse_github_url(url)
+        local_repo = clone_or_update(org, repo)
+
+        # Resolve subpath within the cloned repo
+        target = subpath ? File.join(local_repo, subpath) : local_repo
+        resolve_local(target)
+      end
+
+      # Clone (or update) a GitHub repo into the cache.
+      # Returns the local path to the cloned repo.
+      def clone_or_update(org, repo)
+        cache_path = File.join(CACHE_DIR, org, repo)
+
+        if File.directory?(File.join(cache_path, '.git'))
+          # Already cloned -- pull latest
+          system('git', '-C', cache_path, 'pull', '--ff-only', '--quiet',
+                 out: File::NULL, err: File::NULL)
+        else
+          # Fresh clone
+          FileUtils.mkdir_p(File.dirname(cache_path))
+          clone_url = "https://github.com/#{org}/#{repo}.git"
+          success = system('git', 'clone', '--depth=1', '--quiet', clone_url, cache_path,
+                           out: File::NULL, err: File::NULL)
+          raise "Failed to clone #{clone_url}. Check the URL and your network." unless success
+        end
+
+        cache_path
+      end
+    end
+  end
+end

data/lib/antigravity/tool.rb

@@ -7,6 +7,12 @@ module Antigravity
         super
         subclass.extend(ClassMethods)
       end
+
+      # Factory method: define a tool inline with a block.
+      #   Tool.define(:name, desc: '...', params: { city: { type: :string } }) { |city:| ... }
+      def define(name, desc: '', params: {}, &block)
+        Dynamic.new(name, description: desc, params: params, &block)
+      end
     end
 
     module ClassMethods
@@ -72,12 +78,13 @@ module Antigravity
 
     # Factory for dynamic Proc-based tools
     class Dynamic < Tool
-      attr_reader :block
+      attr_reader :block, :params
 
-      def initialize(name, description: "", &block)
+      def initialize(name, description: '', params: {}, &block)
         super()
         @dynamic_name = name.to_s
         @dynamic_description = description
+        @params = params
         @block = block
       end
 
@@ -85,17 +92,37 @@ module Antigravity
         @dynamic_name
       end
 
-      def call(params)
-        @block.call(params)
+      def call(params = nil, **kwargs)
+        return nil unless @block
+
+        if params && kwargs.empty?
+          # Old-style: tool.call({key: value})
+          @block.call(params)
+        else
+          # New-style: tool.call(key: value)
+          @block.call(**kwargs)
+        end
       end
 
       def to_json_schema
+        properties = {}
+        required_params = []
+
+        @params.each do |param_name, spec|
+          properties[param_name] = {
+            type: (spec[:type] || :string).to_s,
+            description: spec[:description] || spec[:desc] || ''
+          }
+          required_params << param_name.to_s unless spec[:required] == false
+        end
+
         {
           name: @dynamic_name,
           description: @dynamic_description,
           parameters: {
-            type: "object",
-            properties: {}
+            type: 'object',
+            properties: properties,
+            required: required_params
           }
         }
       end

data/lib/antigravity/tool_runner.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Antigravity
+  # Registers, resolves, and executes custom tools for agent callbacks.
+  # Tools are invoked by the harness when the model decides to call them.
+  class ToolRunner < Base
+    def initialize
+      @tools = {}
+    end
+
+    # Register a tool (Tool::Dynamic or any Tool subclass)
+    def register(tool)
+      name = tool.respond_to?(:tool_name) ? tool.tool_name : tool.to_s
+      raise ToolError, "Tool '#{name}' is already registered" if @tools.key?(name)
+
+      @tools[name] = tool
+    end
+
+    # Check if a tool is registered
+    def registered?(name)
+      @tools.key?(name.to_s)
+    end
+
+    # Execute a tool by name with keyword args.
+    # Returns the result or a { error: "..." } hash on failure.
+    def execute(name, **kwargs)
+      tool = @tools[name.to_s]
+      raise ToolNotFoundError, "Tool '#{name}' not found" unless tool
+
+      tool.call(**kwargs)
+    rescue ToolNotFoundError
+      raise
+    rescue => e
+      { error: e.message }
+    end
+
+    # Generate harness-compatible tool definitions for HarnessConfig
+    def to_harness_tools
+      @tools.values.map do |tool|
+        schema = tool.to_json_schema
+        {
+          name: schema[:name],
+          description: schema[:description],
+          parametersJsonSchema: JSON.generate(schema[:parameters])
+        }
+      end
+    end
+
+    def size
+      @tools.size
+    end
+
+    def empty?
+      @tools.empty?
+    end
+  end
+end

data/lib/antigravity.rb

@@ -9,15 +9,23 @@ end
 require_relative "antigravity/version"
 require_relative "antigravity/emojis"
 require_relative "antigravity/base"
+require_relative "antigravity/errors"
 require_relative "antigravity/config"
 require_relative "antigravity/message"
+require_relative "antigravity/protocol"
 require_relative "antigravity/harness"
 require_relative "antigravity/hooks"
 require_relative "antigravity/guards"
 require_relative "antigravity/sidecar"
 require_relative "antigravity/tool"
+require_relative "antigravity/tool_runner"
+require_relative "antigravity/skill_resolver"
 require_relative "antigravity/skill"
 require_relative "antigravity/client"
+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/agent"
 
 module Antigravity

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: antigravity-sdk
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.2
 platform: ruby
 authors:
 - Riccardo Carlesso
@@ -10,19 +10,19 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: faye-websocket
+  name: websocket
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.11'
+        version: '1.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.11'
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
@@ -64,14 +64,22 @@ files:
 - lib/antigravity/base.rb
 - lib/antigravity/client.rb
 - lib/antigravity/config.rb
+- lib/antigravity/connection/binary_fetcher.rb
+- lib/antigravity/connection/local_connection.rb
+- lib/antigravity/connection/websocket_client.rb
+- lib/antigravity/conversation.rb
 - lib/antigravity/emojis.rb
+- lib/antigravity/errors.rb
 - lib/antigravity/guards.rb
 - lib/antigravity/harness.rb
 - lib/antigravity/hooks.rb
 - lib/antigravity/message.rb
+- lib/antigravity/protocol.rb
 - lib/antigravity/sidecar.rb
 - lib/antigravity/skill.rb
+- lib/antigravity/skill_resolver.rb
 - lib/antigravity/tool.rb
+- lib/antigravity/tool_runner.rb
 - lib/antigravity/version.rb
 homepage: https://github.com/palladius/antigravity-ruby-sdk
 licenses: