ruby-claw 0.1.2 → 0.2.0

data/lib/claw/resources/binding_resource.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Claw
+  module Resources
+    # Reversible resource wrapping a Ruby Binding.
+    #
+    # Tracks all local variables by default. Uses binding diff to detect changes
+    # after each eval. Non-serializable variables are automatically excluded
+    # with a warning.
+    #
+    # Serialization: MarshalMd.dump for human-readable Markdown snapshots.
+    class BindingResource
+      include Claw::Resource
+
+      attr_reader :tracked, :excluded
+
+      # @param binding [Binding] the binding to track
+      # @param on_exclude [Proc, nil] called with (name, error) when a variable is excluded
+      def initialize(binding, on_exclude: nil)
+        @binding = binding
+        @tracked = {}    # name => last known Marshal blob
+        @excluded = {}   # name => reason string
+        @on_exclude = on_exclude
+        scan_binding
+      end
+
+      # Snapshot all tracked variables. Returns a frozen Hash of { name => Marshal blob }.
+      def snapshot!
+        scan_binding
+        @tracked.transform_values(&:dup).freeze
+      end
+
+      # Restore tracked variables from a snapshot token.
+      def rollback!(token)
+        token.each do |name, blob|
+          value = MarshalMd.load(blob)
+          @binding.local_variable_set(name, value)
+        end
+        # Remove variables that exist now but didn't exist in the snapshot
+        current_vars = @binding.local_variables.map(&:to_s)
+        snapshot_vars = token.keys.map(&:to_s)
+        (current_vars - snapshot_vars).each do |name|
+          # Can't remove local variables in Ruby, but we can set them to nil
+          @binding.local_variable_set(name.to_sym, nil) if @tracked.key?(name)
+        end
+        @tracked = token.transform_values(&:dup)
+      end
+
+      # Human-readable diff between two snapshot tokens.
+      def diff(token_a, token_b)
+        all_keys = (token_a.keys + token_b.keys).uniq
+        lines = []
+
+        all_keys.each do |name|
+          in_a = token_a.key?(name)
+          in_b = token_b.key?(name)
+
+          if in_a && in_b
+            if token_a[name] != token_b[name]
+              val_a = safe_inspect(MarshalMd.load(token_a[name]))
+              val_b = safe_inspect(MarshalMd.load(token_b[name]))
+              lines << "~ #{name}: #{val_a} → #{val_b}"
+            end
+          elsif in_b
+            val = safe_inspect(MarshalMd.load(token_b[name]))
+            lines << "+ #{name} = #{val}"
+          else
+            val = safe_inspect(MarshalMd.load(token_a[name]))
+            lines << "- #{name} = #{val}"
+          end
+        end
+
+        lines.empty? ? "(no changes)" : lines.join("\n")
+      end
+
+      # Render current tracked variables as Markdown.
+      def to_md
+        scan_binding
+        lines = []
+        lines << "#{@tracked.size} tracked, #{@excluded.size} excluded"
+        @tracked.each do |name, blob|
+          val = safe_inspect(MarshalMd.load(blob))
+          lines << "- `#{name}` = #{val}"
+        end
+        @excluded.each do |name, reason|
+          lines << "- `#{name}` (excluded: #{reason})"
+        end
+        lines.join("\n")
+      end
+
+      # Merge changed variables from another BindingResource into this one.
+      # Only variables that differ from the other's initial snapshot are merged.
+      def merge_from!(other)
+        other.tracked.each do |name, blob|
+          value = MarshalMd.load(blob)
+          @binding.local_variable_set(name.to_sym, value)
+          @tracked[name] = blob
+        end
+      end
+
+      # Scan the binding for new/changed variables.
+      # Call this after each eval to pick up changes.
+      def scan_binding
+        @binding.local_variables.each do |sym|
+          name = sym.to_s
+          next if @excluded.key?(name)
+
+          value = @binding.local_variable_get(sym)
+          begin
+            blob = MarshalMd.dump(value)
+            @tracked[name] = blob
+          rescue TypeError => e
+            @excluded[name] = e.message
+            @tracked.delete(name)
+            @on_exclude&.call(name, e)
+          end
+        end
+      end
+
+      private
+
+      def safe_inspect(value)
+        str = value.inspect
+        str.length > 80 ? "#{str[0, 77]}..." : str
+      end
+    end
+  end
+end

data/lib/claw/resources/context_resource.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Claw
+  module Resources
+    # Reversible resource wrapping Mana::Context (messages + summaries).
+    # Snapshots are deep copies of the messages and summaries arrays.
+    class ContextResource
+      include Claw::Resource
+
+      def initialize(context)
+        @context = context
+      end
+
+      # Deep-copy messages and summaries arrays.
+      def snapshot!
+        {
+          messages: deep_copy(@context.messages),
+          summaries: deep_copy(@context.summaries)
+        }
+      end
+
+      # Replace messages and summaries with the snapshot's copies.
+      def rollback!(token)
+        @context.messages.replace(deep_copy(token[:messages]))
+        @context.summaries.replace(deep_copy(token[:summaries]))
+      end
+
+      # Human-readable diff between two snapshots.
+      def diff(token_a, token_b)
+        msgs_a = token_a[:messages].size
+        msgs_b = token_b[:messages].size
+        sums_a = token_a[:summaries].size
+        sums_b = token_b[:summaries].size
+
+        lines = []
+        lines << "messages: #{msgs_a} → #{msgs_b}" if msgs_a != msgs_b
+
+        # Show added messages
+        if msgs_b > msgs_a
+          token_b[:messages][msgs_a..].each do |msg|
+            role = msg[:role] || msg["role"]
+            content = msg[:content] || msg["content"]
+            preview = content.is_a?(String) ? content[0, 80] : "(#{content.size} blocks)"
+            lines << "  + [#{role}] #{preview}"
+          end
+        end
+
+        lines << "summaries: #{sums_a} → #{sums_b}" if sums_a != sums_b
+        lines.empty? ? "(no changes)" : lines.join("\n")
+      end
+
+      # Render current context state as Markdown.
+      def to_md
+        msgs = @context.messages.size
+        sums = @context.summaries.size
+        "#{msgs} messages, #{sums} summaries"
+      end
+
+      # Merge context from another ContextResource.
+      # Generally a no-op — child conversation history is rarely useful for parent.
+      # If called, appends the other's summaries to this context.
+      def merge_from!(other)
+        # no-op by default; child context is independent
+      end
+
+      private
+
+      def deep_copy(obj)
+        MarshalMd.load(MarshalMd.dump(obj))
+      end
+    end
+  end
+end

data/lib/claw/resources/filesystem_resource.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+
+module Claw
+  module Resources
+    # Reversible resource for the .ruby-claw/ directory using git.
+    # Each snapshot is a git commit; rollback checks out a previous commit.
+    # Tracks the entire directory — no exclusions.
+    class FilesystemResource
+      include Claw::Resource
+
+      attr_reader :path
+
+      def initialize(path)
+        @path = File.expand_path(path)
+        init_git_repo unless git_initialized?
+      end
+
+      # Create a git commit capturing the current state. Returns the commit SHA.
+      def snapshot!
+        git("add", "-A")
+        # Check if there are staged changes
+        status = git("status", "--porcelain")
+        if status.strip.empty?
+          # Nothing to commit — return current HEAD
+          git("rev-parse", "HEAD").strip
+        else
+          git("commit", "-m", "snapshot #{Time.now.iso8601}", "--allow-empty-message")
+          git("rev-parse", "HEAD").strip
+        end
+      end
+
+      # Restore directory to a previous commit.
+      def rollback!(token)
+        # Remove all tracked files, then restore from target commit.
+        # Either step may have nothing to do (empty tree), so we allow failures.
+        git_try("rm", "-rf", "--quiet", ".")
+        git_try("checkout", token, "--", ".")
+        git("clean", "-fd")
+        git("reset", "HEAD")
+      end
+
+      # Git diff between two commits.
+      def diff(token_a, token_b)
+        result = git("diff", "--stat", token_a, token_b)
+        result.strip.empty? ? "(no changes)" : result.strip
+      end
+
+      # Summary of recent git history.
+      def to_md
+        log = git("log", "--oneline", "-10")
+        log.strip.empty? ? "(no commits)" : log.strip
+      end
+
+      # Merge changes from another FilesystemResource (e.g., child worktree).
+      # Performs a git merge from the other's current HEAD.
+      def merge_from!(other)
+        other_path = other.respond_to?(:path) ? other.path : nil
+        raise "Cannot determine path for merge source" unless other_path
+
+        # Determine the branch name to merge
+        other_branch = if other.is_a?(Resources::WorktreeResource)
+          other.branch_name
+        else
+          other.instance_eval { git("rev-parse", "--abbrev-ref", "HEAD").strip }
+        end
+
+        remote_name = "child_#{object_id}"
+        git_try("remote", "add", remote_name, other_path)
+        git("fetch", remote_name)
+        git_try("merge", "#{remote_name}/#{other_branch}", "--no-edit", "-m", "merge from child")
+        git_try("remote", "remove", remote_name)
+      end
+
+      private
+
+      def git_initialized?
+        File.directory?(File.join(@path, ".git"))
+      end
+
+      def init_git_repo
+        FileUtils.mkdir_p(@path)
+        git("init")
+        # Create initial empty commit so HEAD exists
+        git("commit", "--allow-empty", "-m", "init")
+      end
+
+      def git(*args)
+        cmd = ["git", "-C", @path] + args
+        stdout, stderr, status = Open3.capture3(*cmd)
+        unless status.success?
+          raise "git #{args.first} failed: #{stderr.strip}"
+        end
+        stdout
+      end
+
+      # Like git() but ignores failures (for operations that may have nothing to do).
+      def git_try(*args)
+        git(*args)
+      rescue RuntimeError
+        # intentionally swallowed
+      end
+    end
+  end
+end

data/lib/claw/resources/memory_resource.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Claw
+  module Resources
+    # Reversible resource wrapping Claw::Memory's long_term array.
+    # On rollback, restores the in-memory array and syncs to MEMORY.md.
+    class MemoryResource
+      include Claw::Resource
+
+      def initialize(memory)
+        @memory = memory
+      end
+
+      # Deep-copy the long_term array.
+      def snapshot!
+        MarshalMd.load(MarshalMd.dump(@memory.long_term))
+      end
+
+      # Restore long_term array and sync to disk.
+      def rollback!(token)
+        restored = MarshalMd.load(MarshalMd.dump(token))
+        @memory.long_term.replace(restored)
+        # Sync to MEMORY.md so file matches in-memory state
+        store = @memory.send(:store)
+        ns = @memory.send(:namespace)
+        store.write(ns, @memory.long_term)
+      end
+
+      # Human-readable diff between two snapshots.
+      def diff(token_a, token_b)
+        ids_a = token_a.map { |m| m[:id] }.to_set
+        ids_b = token_b.map { |m| m[:id] }.to_set
+
+        added = token_b.select { |m| !ids_a.include?(m[:id]) }
+        removed = token_a.select { |m| !ids_b.include?(m[:id]) }
+
+        lines = []
+        added.each { |m| lines << "+ [#{m[:id]}] #{m[:content]}" }
+        removed.each { |m| lines << "- [#{m[:id]}] #{m[:content]}" }
+        lines.empty? ? "(no changes)" : lines.join("\n")
+      end
+
+      # Merge new memories from another MemoryResource.
+      # Appends facts from other that don't already exist (by id) in this memory.
+      def merge_from!(other)
+        existing_ids = @memory.long_term.map { |m| m[:id] }.to_set
+        other_memory = other.instance_variable_get(:@memory)
+        other_memory.long_term.each do |m|
+          unless existing_ids.include?(m[:id])
+            @memory.long_term << MarshalMd.load(MarshalMd.dump(m))
+          end
+        end
+        # Sync to disk
+        store = @memory.send(:store)
+        ns = @memory.send(:namespace)
+        store.write(ns, @memory.long_term)
+      end
+
+      # Render current memory state as Markdown.
+      def to_md
+        count = @memory.long_term.size
+        if count == 0
+          "(empty)"
+        else
+          lines = ["#{count} memories:"]
+          @memory.long_term.each do |m|
+            lines << "- [#{m[:id]}] #{m[:content]}"
+          end
+          lines.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/claw/resources/worktree_resource.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "open3"
+require "fileutils"
+
+module Claw
+  module Resources
+    # Git worktree-based filesystem resource for child agent isolation.
+    # Creates a separate worktree from the parent repo so the child can
+    # make changes without affecting the parent's working directory.
+    class WorktreeResource
+      include Claw::Resource
+
+      attr_reader :path, :branch_name
+
+      def initialize(parent_path:, branch_name:)
+        @parent_path = File.expand_path(parent_path)
+        @branch_name = branch_name
+        @path = "#{@parent_path}-#{branch_name}"
+        @cleaned_up = false
+
+        create_worktree!
+      end
+
+      # Snapshot via git commit in the worktree.
+      def snapshot!
+        git("add", "-A")
+        status = git("status", "--porcelain")
+        if status.strip.empty?
+          git("rev-parse", "HEAD").strip
+        else
+          git("commit", "-m", "snapshot #{Time.now.iso8601}", "--allow-empty-message")
+          git("rev-parse", "HEAD").strip
+        end
+      end
+
+      # Rollback to a previous commit in the worktree.
+      def rollback!(token)
+        git_try("rm", "-rf", "--quiet", ".")
+        git_try("checkout", token, "--", ".")
+        git("clean", "-fd")
+        git("reset", "HEAD")
+      end
+
+      # Git diff between two commits.
+      def diff(token_a, token_b)
+        result = git("diff", "--stat", token_a, token_b)
+        result.strip.empty? ? "(no changes)" : result.strip
+      end
+
+      # Summary of recent history.
+      def to_md
+        log = git("log", "--oneline", "-10")
+        log.strip.empty? ? "(no commits)" : log.strip
+      end
+
+      # Merge from another worktree or filesystem resource.
+      def merge_from!(other)
+        other_path = other.respond_to?(:path) ? other.path : nil
+        raise "Cannot determine path for merge source" unless other_path
+
+        # Determine the branch name to merge
+        other_branch = if other.is_a?(WorktreeResource)
+          other.branch_name
+        else
+          # For FilesystemResource, get the current branch name
+          other.instance_eval { git("rev-parse", "--abbrev-ref", "HEAD").strip }
+        end
+
+        remote_name = "merge_#{other.object_id}"
+        git_try("remote", "add", remote_name, other_path)
+        git("fetch", remote_name)
+        git_try("merge", "#{remote_name}/#{other_branch}", "--no-edit", "-m", "merge from #{other.class.name}")
+        git_try("remote", "remove", remote_name)
+      end
+
+      # Remove the worktree and delete the branch.
+      def cleanup!
+        return if @cleaned_up
+        @cleaned_up = true
+
+        # Remove worktree
+        parent_git("worktree", "remove", @path, "--force")
+
+        # Delete branch
+        parent_git_try("branch", "-D", @branch_name)
+      rescue => e
+        # Best effort cleanup
+        FileUtils.rm_rf(@path) if Dir.exist?(@path)
+      end
+
+      private
+
+      def create_worktree!
+        # Ensure parent has a commit (needed for worktree)
+        parent_git_try("rev-parse", "HEAD")
+
+        # Create worktree with a new branch
+        parent_git("worktree", "add", @path, "-b", @branch_name)
+      end
+
+      def git(*args)
+        cmd = ["git", "-C", @path] + args
+        stdout, stderr, status = Open3.capture3(*cmd)
+        unless status.success?
+          raise "git #{args.first} failed in worktree: #{stderr.strip}"
+        end
+        stdout
+      end
+
+      def git_try(*args)
+        git(*args)
+      rescue RuntimeError
+        # intentionally swallowed
+      end
+
+      def parent_git(*args)
+        cmd = ["git", "-C", @parent_path] + args
+        stdout, stderr, status = Open3.capture3(*cmd)
+        unless status.success?
+          raise "git #{args.first} failed in parent: #{stderr.strip}"
+        end
+        stdout
+      end
+
+      def parent_git_try(*args)
+        parent_git(*args)
+      rescue RuntimeError
+        # intentionally swallowed
+      end
+    end
+  end
+end

data/lib/claw/roles.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Claw
+  # Agent role management. Roles are Markdown files in .ruby-claw/roles/
+  # that define the agent's system prompt identity.
+  #
+  # Single-agent: /role data_analyst to switch identity.
+  # Multi-agent (V8): child agents reference roles via role: parameter.
+  module Roles
+    # List available role names.
+    #
+    # @param claw_dir [String] path to .ruby-claw/
+    # @return [Array<String>] role names (without extension)
+    def self.list(claw_dir = ".ruby-claw")
+      roles_dir = File.join(claw_dir, "roles")
+      return [] unless Dir.exist?(roles_dir)
+
+      Dir.glob(File.join(roles_dir, "*.md")).map { |f| File.basename(f, ".md") }.sort
+    end
+
+    # Load a role's content by name.
+    #
+    # @param name [String] role name (e.g., "data_analyst")
+    # @param claw_dir [String] path to .ruby-claw/
+    # @return [String] role file content
+    # @raise [RuntimeError] if role file not found
+    def self.load(name, claw_dir = ".ruby-claw")
+      normalized = name.tr(" ", "_").downcase
+      path = File.join(claw_dir, "roles", "#{normalized}.md")
+      raise "Role not found: #{name} (expected #{path})" unless File.exist?(path)
+
+      File.read(path)
+    end
+
+    # Switch the current agent's role (thread-local).
+    #
+    # @param name [String] role name
+    # @param claw_dir [String] path to .ruby-claw/
+    def self.switch!(name, claw_dir = ".ruby-claw")
+      content = load(name, claw_dir)
+      Thread.current[:claw_role] = { name: name, content: content }
+    end
+
+    # Get the current role.
+    #
+    # @return [Hash, nil] { name:, content: } or nil
+    def self.current
+      Thread.current[:claw_role]
+    end
+
+    # Clear the current role.
+    def self.clear!
+      Thread.current[:claw_role] = nil
+    end
+  end
+end