ruby-claw 0.1.2 → 0.2.0

data/lib/claw/forge.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Claw
+  # Promotes eval-defined methods into formal Claw::Tool classes.
+  # `/forge method_name` reads the method source, uses LLM to generate
+  # a tool class, and writes it to `.ruby-claw/tools/`.
+  module Forge
+    TEMPLATE_PROMPT = <<~PROMPT
+      Convert this Ruby method into a Claw::Tool class.
+
+      Method source:
+      ```ruby
+      %{source}
+      ```
+
+      Output ONLY a complete Ruby file with this exact structure (no explanation):
+      ```ruby
+      class ClassName
+        include Claw::Tool
+        tool_name   "tool_name_here"
+        description "One-line description of what this tool does"
+        parameter   :param1, type: "String", required: true, desc: "..."
+        # Add more parameters as needed
+
+        def call(param1:)
+          # Implementation (adapted from the method source above)
+        end
+      end
+      ```
+
+      Rules:
+      - tool_name should be the method name in snake_case
+      - Extract method parameters as tool parameters with appropriate types
+      - The call method should have keyword arguments matching the parameters
+      - Return a meaningful result (string or data structure)
+    PROMPT
+
+    class << self
+      # Promote an eval-defined method to a formal tool class file.
+      #
+      # @param method_name [String] name of the method to promote
+      # @param binding [Binding] caller's binding (to read definitions)
+      # @param claw_dir [String] path to .ruby-claw/ directory
+      # @return [Hash] { success: bool, path: String, message: String }
+      def promote(method_name, binding:, claw_dir: nil)
+        claw_dir ||= File.join(Dir.pwd, ".ruby-claw")
+        tools_dir = File.join(claw_dir, "tools")
+        FileUtils.mkdir_p(tools_dir)
+
+        # 1. Read method source from tracked definitions
+        source = find_source(method_name, binding)
+        unless source
+          return { success: false, message: "Method '#{method_name}' not found in definitions" }
+        end
+
+        # 2. Generate tool class via LLM (direct API call, no tools)
+        prompt = format(TEMPLATE_PROMPT, source: source)
+        backend = Mana::Backends::Base.for(Mana.config)
+        response = backend.chat(
+          system: "You are a Ruby code generator. Output only code, no explanations.",
+          messages: [{ role: "user", content: prompt }],
+          tools: [],
+          model: Mana.config.model,
+          max_tokens: 2048
+        )
+        raw = response.dig(:content, 0, :text) || response[:content]&.map { |c| c[:text] }&.compact&.join
+
+        # 3. Extract Ruby code from response
+        code = extract_ruby_code(raw.to_s)
+        unless code
+          return { success: false, message: "LLM did not generate valid Ruby code" }
+        end
+
+        # 4. Write to tools directory
+        filename = "#{method_name.downcase.gsub(/[^a-z0-9_]/, '_')}.rb"
+        path = File.join(tools_dir, filename)
+        File.write(path, code)
+
+        # 5. Refresh tool index if registry exists
+        Claw.tool_registry&.index&.scan!
+
+        { success: true, path: path, message: "Tool '#{method_name}' forged at #{path}" }
+      rescue => e
+        { success: false, message: "Forge failed: #{e.class}: #{e.message}" }
+      end
+
+      private
+
+      def find_source(method_name, binding)
+        receiver = binding.receiver
+        defs = if receiver.instance_variable_defined?(:@__claw_definitions__)
+                 receiver.instance_variable_get(:@__claw_definitions__)
+               else
+                 {}
+               end
+
+        # Try tracked definitions first
+        source = defs[method_name.to_s] || defs[method_name.to_sym]
+        return source if source
+
+        # Try source_location as fallback
+        meth = begin
+          receiver.method(method_name.to_sym)
+        rescue NameError
+          nil
+        end
+
+        if meth&.source_location
+          file, line = meth.source_location
+          return nil unless file && File.exist?(file)
+          lines = File.readlines(file)
+          # Read from def line until matching end
+          start = line - 1
+          depth = 0
+          result_lines = []
+          lines[start..].each do |l|
+            result_lines << l
+            depth += 1 if l.match?(/\b(def|class|module|do|begin|if|unless|while|until|for|case)\b/)
+            depth -= 1 if l.match?(/\bend\b/)
+            break if depth <= 0 && result_lines.size > 1
+          end
+          result_lines.join
+        end
+      end
+
+      def extract_ruby_code(text)
+        # Extract code from ```ruby ... ``` blocks
+        if text.match?(/```ruby\s*\n/)
+          match = text.match(/```ruby\s*\n(.*?)```/m)
+          return match[1].strip if match
+        end
+
+        # If the entire response looks like Ruby code
+        if text.strip.match?(/\Aclass\s/)
+          return text.strip
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/claw/hub.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Claw
+  # Client for the ruby-claw-toolhub community tool repository.
+  # Provides search and download of community-contributed tools.
+  class Hub
+    attr_reader :url
+
+    def initialize(url:)
+      @url = url.chomp("/")
+    end
+
+    # Search hub for tools matching a keyword.
+    #
+    # @param keyword [String]
+    # @return [Array<Hash>] [{name:, description:, version:, url:}]
+    def search(keyword)
+      uri = URI("#{@url}/api/search?q=#{URI.encode_www_form_component(keyword)}")
+      response = http_get(uri)
+      return [] unless response
+
+      results = JSON.parse(response, symbolize_names: true)
+      results.map do |r|
+        { name: r[:name], description: r[:description] || "",
+          version: r[:version], url: r[:url] }
+      end
+    rescue JSON::ParserError
+      []
+    end
+
+    # Download a tool file from the hub.
+    #
+    # @param name [String] tool name
+    # @param target_dir [String] directory to write the file
+    # @return [String] path to the downloaded file
+    def download(name, target_dir:)
+      uri = URI("#{@url}/api/tools/#{URI.encode_www_form_component(name)}")
+      content = http_get(uri)
+      raise "Tool '#{name}' not found on hub" unless content
+
+      safe_name = File.basename(name).gsub(/[^a-zA-Z0-9_\-]/, "_")
+      path = File.join(target_dir, "#{safe_name}.rb")
+      File.write(path, content)
+      path
+    end
+
+    private
+
+    def http_get(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = 10
+      http.read_timeout = 10
+
+      req = Net::HTTP::Get.new(uri)
+      res = http.request(req)
+
+      res.is_a?(Net::HTTPSuccess) ? res.body : nil
+    rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED, SocketError
+      nil
+    end
+  end
+end

data/lib/claw/init.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+
+module Claw
+  # Scaffolds a new Claw project in the current directory.
+  #
+  # Creates .ruby-claw/ with:
+  #   gems/         — cloned ruby-claw and ruby-mana source (editable)
+  #   system_prompt.md — default agent personality (customizable)
+  #   MEMORY.md     — empty long-term memory
+  #   .git/         — git repo for filesystem snapshots
+  #
+  # Also generates a project-root Gemfile pointing to local gem copies.
+  module Init
+    GITHUB_CLAW = "https://github.com/twokidsCarl/ruby-claw.git"
+    GITHUB_MANA = "https://github.com/twokidsCarl/ruby-mana.git"
+
+    class << self
+      # Run the full init sequence.
+      #
+      # @param dir [String] project root (defaults to pwd)
+      # @param stdout [IO] output stream for progress messages
+      def run(dir: Dir.pwd, stdout: $stdout)
+        claw_dir = File.join(dir, ".ruby-claw")
+
+        if File.directory?(claw_dir) && !Dir.empty?(claw_dir)
+          stdout.puts "  ⚠ .ruby-claw/ already exists — skipping init"
+          return false
+        end
+
+        FileUtils.mkdir_p(claw_dir)
+
+        clone_gems(claw_dir, stdout)
+        write_gemfile(dir, stdout)
+        write_system_prompt(claw_dir, stdout)
+        write_memory(claw_dir, stdout)
+        create_roles(claw_dir, stdout)
+        create_tools_dir(claw_dir, stdout)
+        git_init(claw_dir, stdout)
+
+        stdout.puts "  ✓ claw init complete"
+        stdout.puts "  Run `bundle install` to use local gem copies"
+        true
+      end
+
+      private
+
+      # Clone ruby-claw and ruby-mana into .ruby-claw/gems/
+      def clone_gems(claw_dir, stdout)
+        gems_dir = File.join(claw_dir, "gems")
+        FileUtils.mkdir_p(gems_dir)
+
+        [
+          ["ruby-claw", GITHUB_CLAW],
+          ["ruby-mana", GITHUB_MANA]
+        ].each do |name, url|
+          target = File.join(gems_dir, name)
+          if Dir.exist?(target)
+            stdout.puts "  · #{name} already cloned"
+            next
+          end
+          stdout.puts "  ↓ cloning #{name}..."
+          out, status = Open3.capture2e("git", "clone", "--depth=1", url, target)
+          unless status.success?
+            raise "Failed to clone #{name}: #{out}"
+          end
+        end
+      end
+
+      # Generate a Gemfile in the project root with path references to local gems.
+      def write_gemfile(dir, stdout)
+        path = File.join(dir, "Gemfile")
+        if File.exist?(path)
+          stdout.puts "  · Gemfile already exists — skipping"
+          stdout.puts "    Add these lines manually:"
+          stdout.puts '    gem "ruby-claw", path: ".ruby-claw/gems/ruby-claw"'
+          stdout.puts '    gem "ruby-mana", path: ".ruby-claw/gems/ruby-mana"'
+          return
+        end
+
+        content = <<~RUBY
+          source "https://rubygems.org"
+
+          gem "ruby-claw", path: ".ruby-claw/gems/ruby-claw"
+          gem "ruby-mana", path: ".ruby-claw/gems/ruby-mana"
+          gem "dotenv"
+        RUBY
+
+        File.write(path, content)
+        stdout.puts "  ✓ Gemfile created"
+      end
+
+      # Write the default system prompt template.
+      def write_system_prompt(claw_dir, stdout)
+        path = File.join(claw_dir, "system_prompt.md")
+        File.write(path, default_system_prompt)
+        stdout.puts "  ✓ system_prompt.md created"
+      end
+
+      # Create an empty MEMORY.md.
+      def write_memory(claw_dir, stdout)
+        path = File.join(claw_dir, "MEMORY.md")
+        File.write(path, "# Long-term Memory\n")
+        stdout.puts "  ✓ MEMORY.md created"
+      end
+
+      # Create roles/ directory with a default role.
+      def create_roles(claw_dir, stdout)
+        roles_dir = File.join(claw_dir, "roles")
+        FileUtils.mkdir_p(roles_dir)
+        default_path = File.join(roles_dir, "default.md")
+        File.write(default_path, <<~ROLE)
+          # Default Role
+
+          You are a helpful Ruby assistant with access to the runtime binding.
+          Help the user analyze data, write code, and manage their Ruby environment.
+        ROLE
+        stdout.puts "  ✓ roles/ directory created"
+      end
+
+      # Create tools/ directory for project tools.
+      def create_tools_dir(claw_dir, stdout)
+        tools_dir = File.join(claw_dir, "tools")
+        FileUtils.mkdir_p(tools_dir)
+        readme = File.join(tools_dir, "README.md")
+        File.write(readme, <<~MD) unless File.exist?(readme)
+          # Project Tools
+
+          Place `Claw::Tool` class files here. They will be indexed at startup
+          and available via `search_tools` / `load_tool`.
+
+          Example:
+          ```ruby
+          class MyTool
+            include Claw::Tool
+            tool_name   "my_tool"
+            description "Does something useful"
+            parameter   :input, type: "String", required: true, desc: "The input"
+
+            def call(input:)
+              "Result: \#{input}"
+            end
+          end
+          ```
+        MD
+        stdout.puts "  ✓ tools/ directory created"
+      end
+
+      # Initialize a git repo in .ruby-claw/ with an initial commit.
+      def git_init(claw_dir, stdout)
+        if Dir.exist?(File.join(claw_dir, ".git"))
+          stdout.puts "  · git already initialized"
+          return
+        end
+
+        run_git(claw_dir, "init")
+        run_git(claw_dir, "add", "-A")
+        run_git(claw_dir, "commit", "-m", "claw init", "--allow-empty")
+        stdout.puts "  ✓ git initialized with initial snapshot"
+      end
+
+      def run_git(dir, *args)
+        out, status = Open3.capture2e("git", "-C", dir, *args)
+        raise "git #{args.first} failed: #{out}" unless status.success?
+        out
+      end
+
+      def default_system_prompt
+        <<~MD
+          # System Prompt
+
+          You are a helpful AI assistant embedded in a Ruby runtime.
+          You have full access to the Ruby environment through tools.
+
+          ## Personality
+
+          - Be concise and direct
+          - Show code when helpful
+          - Explain your reasoning when the task is non-trivial
+          - Match the user's language (Chinese → Chinese, English → English)
+
+          ## Guidelines
+
+          - Use read_var/write_var for variable access
+          - Use call_func for calling Ruby methods
+          - Use eval only for defining new methods or requiring libraries
+          - Always return a result via the done tool
+          - Use the knowledge tool when unsure about your capabilities
+
+          ## Custom Instructions
+
+          Add your project-specific instructions here.
+        MD
+      end
+    end
+  end
+end

data/lib/claw/knowledge.rb

@@ -25,7 +25,11 @@ module Claw
           "compaction"    => compaction,
           "session"       => session,
           "serializer"    => serializer,
-          "persistence"   => session
+          "persistence"   => session,
+          "tools"         => tools_section,
+          "search_tools"  => tools_section,
+          "load_tool"     => tools_section,
+          "forge"         => tools_section
         }
       end
 
@@ -69,13 +73,43 @@ module Claw
         TEXT
       end
 
+      def tools_section
+        <<~TEXT
+          Tool system in Claw (three layers):
+
+          1. Core tools (always loaded): read_var, write_var, call_func, eval, etc. + remember
+          2. Project tools (on-demand): .ruby-claw/tools/*.rb — indexed at startup, loaded via load_tool
+          3. Hub tools (remote): community tools from ruby-claw-toolhub, downloaded on demand
+
+          Key tools for discovery:
+          - search_tools: search available project/hub tools by keyword
+          - load_tool: load a discovered tool into the current session
+
+          Creating tools:
+          - Write a class including Claw::Tool with tool_name, description, parameter DSL
+          - Place in .ruby-claw/tools/
+          - Or use /forge to promote an eval-defined method to a formal tool
+
+          Tool class structure:
+            class MyTool
+              include Claw::Tool
+              tool_name   "my_tool"
+              description "What it does"
+              parameter   :input, type: "String", required: true, desc: "..."
+              def call(input:)
+                # logic
+              end
+            end
+        TEXT
+      end
+
       def serializer
         <<~TEXT
           Runtime state serialization in Claw:
           Claw::Serializer can save and restore local variables and method definitions.
           - Claw::Serializer.save(binding, dir) — saves values.json + definitions.rb
           - Claw::Serializer.restore(binding, dir) — restores from saved files
-          - Values: Marshal.dump (hex encoded) with JSON fallback
+          - Values: MarshalMd.dump (human-readable Markdown) with JSON fallback
           - Definitions: tracked via @__claw_definitions__ on the receiver
         TEXT
       end

data/lib/claw/memory_store.rb

@@ -7,7 +7,7 @@ module Claw
   # Replaces JSON memory/session files with human-readable Markdown.
   #
   # Directory layout:
-  #   .mana/
+  #   .ruby-claw/
   #     MEMORY.md      — long-term memory
   #     session.md     — session summary
   #     values.json    — kept as-is (Marshal data)
@@ -72,7 +72,7 @@ module Claw
     private
 
     def base_dir
-      @base_path || Mana.config.memory_path || File.join(Dir.pwd, ".mana")
+      @base_path || Mana.config.memory_path || File.join(Dir.pwd, ".ruby-claw")
     end
 
     def memory_md_path

data/lib/claw/plan_mode.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Claw
+  # Plan Mode: two-phase plan-then-execute workflow.
+  #
+  # Phase 1 (plan): LLM outputs a step-by-step plan without executing tools.
+  # Phase 2 (execute): After user confirmation, execute inside a fork for safety.
+  class PlanMode
+    STATES = %i[inactive ready planning reviewing executing].freeze
+
+    attr_reader :pending_plan, :state
+
+    def initialize(runtime)
+      @runtime = runtime
+      @state = :inactive
+      @pending_plan = nil
+    end
+
+    def active? = @state != :inactive
+    def pending? = @state == :reviewing
+
+    def toggle!
+      if @state == :inactive
+        @state = :ready  # activated, waiting for plan! call
+        true
+      else
+        discard!
+        false
+      end
+    end
+
+    # Phase 1: Generate a plan (no tool execution).
+    #
+    # @param prompt [String] user's task description
+    # @param caller_binding [Binding] for binding context
+    # @param on_text [Proc, nil] streaming callback
+    # @return [String] the plan text
+    def plan!(prompt, caller_binding, &on_text)
+      @state = :planning
+
+      binding_md = @runtime&.resources&.dig("binding")&.to_md || "(no binding)"
+      memory_md = @runtime&.resources&.dig("memory")&.to_md || "(no memory)"
+
+      planning_prompt = <<~PROMPT
+        The user wants: #{prompt}
+
+        Current binding state:
+        #{binding_md}
+
+        Current memory:
+        #{memory_md}
+
+        Output ONLY a step-by-step plan describing what tools you would use and in what order.
+        Do NOT call any tools. Do NOT execute anything.
+        Format as a numbered list. For each step, specify:
+        - Which tool to use
+        - On what target (variable/method/etc.)
+        - Expected result
+      PROMPT
+
+      engine = Mana::Engine.new(caller_binding)
+      # Execute with empty tools array so LLM cannot call any tools
+      plan_text = engine.execute(planning_prompt, &on_text)
+
+      @pending_plan = {
+        prompt: prompt,
+        plan_text: plan_text.to_s,
+        created_at: Time.now
+      }
+      @state = :reviewing
+      @pending_plan[:plan_text]
+    end
+
+    # Phase 2: Execute the approved plan inside a fork for safety.
+    #
+    # @param caller_binding [Binding]
+    # @param edited_plan [String, nil] user-edited plan text (optional)
+    # @param on_text [Proc, nil] streaming callback
+    # @return [Array] [success, result] from Runtime#fork
+    def execute!(caller_binding, edited_plan: nil, &on_text)
+      raise "No pending plan" unless @state == :reviewing
+
+      @state = :executing
+      plan_text = edited_plan || @pending_plan[:plan_text]
+      prompt = @pending_plan[:prompt]
+      @pending_plan = nil
+
+      result = @runtime.fork(label: "plan_execution") do
+        engine = Mana::Engine.new(caller_binding)
+        engine.execute(<<~EXEC, &on_text)
+          Execute this task: #{prompt}
+
+          Your approved plan:
+          #{plan_text}
+
+          Follow the plan step by step. Use the available tools to complete each step.
+        EXEC
+      end
+
+      @state = :inactive
+      result
+    end
+
+    # Discard the pending plan.
+    def discard!
+      @pending_plan = nil
+      @state = :inactive
+    end
+  end
+end

data/lib/claw/resource.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Claw
+  # Interface for reversible resources managed by Claw::Runtime.
+  # All resources that participate in snapshot/rollback must include this module
+  # and implement the required methods.
+  module Resource
+    # Capture current state. Returns an opaque token for later rollback.
+    def snapshot!
+      raise NotImplementedError, "#{self.class}#snapshot! not implemented"
+    end
+
+    # Restore state to a previous snapshot token.
+    # Implementations must guarantee success — partial rollback is not acceptable.
+    def rollback!(token)
+      raise NotImplementedError, "#{self.class}#rollback! not implemented"
+    end
+
+    # Compare two snapshot tokens. Returns a human-readable diff string.
+    def diff(token_a, token_b)
+      raise NotImplementedError, "#{self.class}#diff not implemented"
+    end
+
+    # Render current state as Markdown for human/LLM consumption.
+    def to_md
+      raise NotImplementedError, "#{self.class}#to_md not implemented"
+    end
+
+    # Merge changes from another resource instance (e.g., child → parent).
+    # Used by V8 Multi-Agent to selectively merge child results back.
+    def merge_from!(other)
+      raise NotImplementedError, "#{self.class}#merge_from! not implemented"
+    end
+  end
+end