antigravity-sdk 0.2.0 → 0.4.2

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

@@ -1,18 +1,21 @@
 # frozen_string_literal: true
 
 module Antigravity
-  class Tool
-    include Emojifiable
-
+  class Tool < Base
     class << self
       def inherited(subclass)
+        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
-      include Emojifiable::ClassMethods
-
       def name(val = nil, desc: nil)
         if val
           @tool_name = val.to_s
@@ -75,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
 
@@ -88,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

@@ -8,15 +8,24 @@ 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.2.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
@@ -61,16 +61,25 @@ extra_rdoc_files: []
 files:
 - lib/antigravity.rb
 - lib/antigravity/agent.rb
+- 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: