ruby-claw 0.1.2 → 0.2.0

data/lib/claw/runtime.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module Claw
+  # Reversible Runtime — manages resources and provides atomic snapshot/rollback.
+  #
+  # All registered resources are snapshot/rolled-back together. A snapshot captures
+  # the state of every resource at a point in time; rollback restores all of them
+  # atomically.
+  #
+  # Resources must be registered at startup. Dynamic registration during execution
+  # is not allowed — it would break snapshot consistency.
+  class Runtime
+    Snapshot = Struct.new(:id, :label, :tokens, :timestamp, keyword_init: true)
+    Step = Struct.new(:number, :tool_name, :target, :elapsed_ms, keyword_init: true)
+
+    STATES = %i[idle thinking executing_tool failed].freeze
+
+    attr_reader :resources, :snapshots, :events, :state, :current_step, :children
+
+    def initialize
+      @resources = {}       # name => resource instance
+      @snapshot_data = {}   # snapshot_id => { name => token }
+      @snapshots = []       # ordered list of Snapshot metadata
+      @next_id = 1
+      @locked = false
+      @events = []          # append-only event log
+      @state = :idle
+      @current_step = nil
+      @state_callbacks = []
+      @children = {}        # id => ChildRuntime (V8)
+    end
+
+    # Transition the runtime execution state.
+    # Fires registered callbacks with (old_state, new_state, step).
+    def transition!(new_state, step: nil)
+      raise ArgumentError, "Invalid state: #{new_state}" unless STATES.include?(new_state)
+
+      old = @state
+      @state = new_state
+      @current_step = step
+      @state_callbacks.each { |cb| cb.call(old, new_state, step) }
+    end
+
+    # Register an observer for state transitions.
+    def on_state_change(&block)
+      @state_callbacks << block
+    end
+
+    # Register a named resource. Must be called before any snapshot.
+    # Raises if called after the first snapshot (resources are locked).
+    def register(name, resource)
+      raise "Cannot register resources after first snapshot" if @locked
+      raise ArgumentError, "Resource must include Claw::Resource" unless resource.is_a?(Claw::Resource)
+      raise ArgumentError, "Resource '#{name}' already registered" if @resources.key?(name)
+
+      @resources[name] = resource
+    end
+
+    # Atomic snapshot: captures all registered resources.
+    # Returns the snapshot id.
+    def snapshot!(label: nil)
+      @locked = true
+      tokens = {}
+      @resources.each do |name, resource|
+        tokens[name] = resource.snapshot!
+      end
+
+      snap = Snapshot.new(
+        id: @next_id,
+        label: label,
+        tokens: tokens.values.sum { |t| t.respond_to?(:size) ? t.size : 0 },
+        timestamp: Time.now.iso8601
+      )
+      @snapshot_data[@next_id] = tokens
+      @snapshots << snap
+      record_event(action: "snapshot", target: "runtime", detail: "id=#{@next_id} label=#{label}")
+      @next_id += 1
+      snap.id
+    end
+
+    # Atomic rollback: restores all resources to a previous snapshot.
+    def rollback!(snap_id)
+      tokens = @snapshot_data[snap_id]
+      raise ArgumentError, "Unknown snapshot id: #{snap_id}" unless tokens
+
+      @resources.each do |name, resource|
+        resource.rollback!(tokens[name])
+      end
+      record_event(action: "rollback", target: "runtime", detail: "to snapshot id=#{snap_id}")
+    end
+
+    # Compare two snapshots across all resources.
+    # Returns a Hash { resource_name => diff_string }.
+    def diff(snap_id_a, snap_id_b)
+      tokens_a = @snapshot_data[snap_id_a]
+      tokens_b = @snapshot_data[snap_id_b]
+      raise ArgumentError, "Unknown snapshot id: #{snap_id_a}" unless tokens_a
+      raise ArgumentError, "Unknown snapshot id: #{snap_id_b}" unless tokens_b
+
+      result = {}
+      @resources.each do |name, resource|
+        result[name] = resource.diff(tokens_a[name], tokens_b[name])
+      end
+      result
+    end
+
+    # Fork: snapshot → execute block → rollback on failure.
+    # Returns [success, result] tuple.
+    def fork(label: nil)
+      snap_id = snapshot!(label: label || "fork")
+      begin
+        result = yield
+        [true, result]
+      rescue => e
+        rollback!(snap_id)
+        record_event(action: "fork_rollback", target: "runtime", detail: "#{e.class}: #{e.message}")
+        [false, e]
+      end
+    end
+
+    # Append an event to the log.
+    def record_event(action:, target:, detail: nil)
+      @events << {
+        timestamp: Time.now.iso8601,
+        action: action,
+        target: target,
+        detail: detail
+      }
+    end
+
+    # Fork a child agent that runs in a separate thread with isolated resources.
+    # The child can later be merged back via child.merge!
+    #
+    # @param prompt [String] the task for the child to execute
+    # @param vars [Hash] variables to inject into the child's binding
+    # @param role [String, nil] optional role name for the child
+    # @param model [String, nil] optional model override
+    # @return [ChildRuntime]
+    def fork_async(prompt:, vars: {}, role: nil, model: nil)
+      child = ChildRuntime.new(
+        parent: self,
+        prompt: prompt,
+        vars: vars,
+        role: role,
+        model: model
+      )
+      @children[child.id] = child
+      child.start!
+      record_event(action: "fork_async", target: child.id, detail: prompt[0..80])
+      child
+    end
+
+    # Render runtime state as Markdown.
+    def to_md
+      lines = ["# Runtime State\n"]
+
+      lines << "## Status"
+      lines << "- state: #{@state}"
+      if @current_step
+        lines << "- step: ##{@current_step.number} #{@current_step.tool_name} (#{@current_step.target})"
+      end
+      lines << ""
+
+      lines << "## Resources"
+      @resources.each do |name, resource|
+        lines << "### #{name}"
+        lines << resource.to_md
+        lines << ""
+      end
+
+      lines << "## Snapshots"
+      if @snapshots.empty?
+        lines << "(none)"
+      else
+        @snapshots.each do |snap|
+          lines << "- **##{snap.id}** #{snap.label || '(unlabeled)'} — #{snap.timestamp}"
+        end
+      end
+      lines << ""
+
+      lines << "## Events (last 20)"
+      @events.last(20).each do |ev|
+        lines << "- `#{ev[:timestamp]}` #{ev[:action]} #{ev[:target]} #{ev[:detail]}"
+      end
+
+      lines.join("\n")
+    end
+  end
+end

data/lib/claw/serializer.rb

@@ -61,14 +61,14 @@ module Claw
         # Corrupted file — skip
       end
 
-      # Encode a value for JSON storage.
-      # Strategy: try Marshal (hex-encoded), fall back to JSON, skip unserializable.
+      # Encode a value for storage.
+      # Strategy: try MarshalMd (human-readable Markdown), fall back to JSON, skip unserializable.
       def encode_value(val)
-        # Try Marshal first for full Ruby fidelity
-        marshalled = Marshal.dump(val)
-        { "type" => "marshal", "data" => marshalled.unpack1("H*") }
+        # Try MarshalMd first for full Ruby fidelity + human readability
+        md = MarshalMd.dump(val)
+        { "type" => "marshal_md", "data" => md }
       rescue TypeError
-        # Marshal failed — try JSON for simple types
+        # MarshalMd failed — try JSON for simple types
         begin
           json = JSON.generate(val)
           { "type" => "json", "data" => json }
@@ -80,7 +80,10 @@ module Claw
       # Decode a value from its stored representation.
       def decode_value(entry)
         case entry["type"]
+        when "marshal_md"
+          MarshalMd.load(entry["data"])
         when "marshal"
+          # Backward compatibility: load old binary Marshal data
           Marshal.load([entry["data"]].pack("H*")) # rubocop:disable Security/MarshalLoad
         when "json"
           JSON.parse(entry["data"])
@@ -111,7 +114,7 @@ module Claw
         return if source.strip.empty?
 
         bind.eval(source)
-      rescue => e
+      rescue Exception => e # rubocop:disable Lint/RescueException — SyntaxError is not a StandardError
         $stderr.puts "Claw::Serializer restore error: #{e.message}" if $DEBUG
       end
     end

data/lib/claw/tool.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Claw
+  # Mixin for defining project tools as classes with a declarative DSL.
+  #
+  # Usage:
+  #   class FormatReport
+  #     include Claw::Tool
+  #     tool_name   "format_report"
+  #     description "Format raw data into a readable report"
+  #     parameter   :data,  type: "Hash",   required: true,  desc: "Raw data"
+  #     parameter   :style, type: "String", required: false, desc: "brief or detailed"
+  #
+  #     def call(data:, style: "brief")
+  #       # ...
+  #     end
+  #   end
+  module Tool
+    @tool_classes = []
+
+    def self.tool_classes
+      @tool_classes
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.instance_variable_set(:@tool_parameters, [])
+      @tool_classes << base unless @tool_classes.include?(base)
+    end
+
+    module ClassMethods
+      def tool_name(name = nil)
+        if name
+          @tool_name = name
+        else
+          @tool_name || self.name&.split("::")&.last&.gsub(/([a-z])([A-Z])/, '\1_\2')&.downcase
+        end
+      end
+
+      def description(desc = nil)
+        if desc
+          @tool_description = desc
+        else
+          @tool_description || ""
+        end
+      end
+
+      def parameter(name, type: "String", required: false, desc: "")
+        @tool_parameters ||= []
+        @tool_parameters << { name: name, type: type, required: required, desc: desc }
+      end
+
+      def tool_parameters
+        @tool_parameters || []
+      end
+
+      # Generate a Mana-compatible tool definition hash.
+      def to_tool_definition
+        props = {}
+        required = []
+
+        tool_parameters.each do |p|
+          json_type = ruby_type_to_json(p[:type])
+          props[p[:name].to_s] = { type: json_type, description: p[:desc] }
+          required << p[:name].to_s if p[:required]
+        end
+
+        {
+          name: tool_name,
+          description: description,
+          input_schema: {
+            type: "object",
+            properties: props,
+            required: required
+          }
+        }
+      end
+
+      private
+
+      def ruby_type_to_json(type)
+        case type.to_s
+        when "String"  then "string"
+        when "Integer", "Fixnum", "Bignum" then "integer"
+        when "Float", "Numeric" then "number"
+        when "Hash"    then "object"
+        when "Array"   then "array"
+        when "Boolean", "TrueClass", "FalseClass" then "boolean"
+        else "string"
+        end
+      end
+    end
+
+    # Subclasses must implement #call with keyword args matching parameters.
+    def call(**kwargs)
+      raise NotImplementedError, "#{self.class}#call not implemented"
+    end
+  end
+end

data/lib/claw/tool_index.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Claw
+  # Lightweight index of project tools in `.ruby-claw/tools/`.
+  # Scans files via regex to extract tool_name and description without requiring them.
+  class ToolIndex
+    Entry = Struct.new(:name, :description, :path, keyword_init: true)
+
+    attr_reader :entries
+
+    def initialize(tools_dir)
+      @tools_dir = tools_dir
+      @entries = []
+      scan! if tools_dir && Dir.exist?(tools_dir)
+    end
+
+    # Rebuild the index by scanning the tools directory.
+    def scan!
+      @entries = []
+      return unless @tools_dir && Dir.exist?(@tools_dir)
+
+      Dir.glob(File.join(@tools_dir, "*.rb")).each do |path|
+        entry = extract_metadata(path)
+        @entries << entry if entry
+      end
+    end
+
+    # Search for tools matching a keyword (case-insensitive substring match).
+    #
+    # @param keyword [String]
+    # @return [Array<Entry>]
+    def search(keyword)
+      return @entries if keyword.nil? || keyword.empty?
+
+      pattern = keyword.downcase
+      @entries.select do |e|
+        e.name.downcase.include?(pattern) || e.description.downcase.include?(pattern)
+      end
+    end
+
+    # Find an entry by exact name.
+    #
+    # @param name [String]
+    # @return [Entry, nil]
+    def find(name)
+      @entries.find { |e| e.name == name }
+    end
+
+    # Load a tool class from its file. Returns the class or nil.
+    #
+    # @param name [String] tool name
+    # @return [Class, nil] the class including Claw::Tool
+    def load_tool(name)
+      entry = find(name)
+      return nil unless entry
+
+      before_count = Claw::Tool.tool_classes.size
+      Kernel.load(entry.path)
+      new_classes = Claw::Tool.tool_classes[before_count..]
+
+      # Prefer the class whose tool_name matches
+      new_classes&.find { |c| c.tool_name == name } || new_classes&.first
+    end
+
+    private
+
+    # Extract tool_name and description from a .rb file using regex.
+    # Avoids require to keep startup fast.
+    def extract_metadata(path)
+      content = File.read(path, 4096) # Read only the first 4KB
+
+      name_match = content.match(/tool_name\s+["']([^"']+)["']/)
+      desc_match = content.match(/description\s+["']([^"']+)["']/)
+
+      return nil unless name_match
+
+      Entry.new(
+        name: name_match[1],
+        description: desc_match ? desc_match[1] : "",
+        path: path
+      )
+    end
+  end
+end

data/lib/claw/tool_registry.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Claw
+  # Manages the tool lifecycle: indexing, searching, loading, and tracking.
+  # Bridges project tools (Claw::Tool classes) with Mana's tool registration.
+  class ToolRegistry
+    attr_reader :index, :loaded_tools
+
+    def initialize(tools_dir: nil, hub: nil)
+      @tools_dir = tools_dir
+      @index = ToolIndex.new(tools_dir)
+      @hub = hub
+      @loaded_tools = {} # name → tool class
+    end
+
+    # Search local index (and optionally hub) for tools matching a keyword.
+    #
+    # @param keyword [String]
+    # @return [Array<Hash>] [{name:, description:, source:, loaded:}]
+    def search(keyword)
+      results = @index.search(keyword).map do |entry|
+        { name: entry.name, description: entry.description,
+          source: "project", loaded: @loaded_tools.key?(entry.name) }
+      end
+
+      # Query hub if configured and local results are sparse
+      if @hub && results.size < 3
+        hub_results = @hub.search(keyword) rescue []
+        hub_results.each do |hr|
+          next if results.any? { |r| r[:name] == hr[:name] }
+          results << hr.merge(source: "hub", loaded: false)
+        end
+      end
+
+      results
+    end
+
+    # Load a tool by name. Requires the file, registers with Mana.
+    #
+    # @param name [String]
+    # @return [String] success/error message
+    def load(name)
+      return "Tool '#{name}' is already loaded" if @loaded_tools.key?(name)
+
+      # Try local index first
+      klass = @index.load_tool(name)
+
+      # Try downloading from hub if not found locally
+      if klass.nil? && @hub
+        downloaded = download_from_hub(name)
+        klass = @index.load_tool(name) if downloaded
+      end
+
+      return "Tool '#{name}' not found" unless klass
+
+      register_with_mana(klass)
+      @loaded_tools[name] = klass
+      "Tool '#{name}' loaded successfully"
+    end
+
+    # Check if a tool is currently loaded.
+    def loaded?(name)
+      @loaded_tools.key?(name)
+    end
+
+    # Unload a tool (remove from Mana's registered tools).
+    def unload(name)
+      return "Tool '#{name}' is not loaded" unless @loaded_tools.key?(name)
+
+      # Remove from Mana's registrations
+      Mana.instance_variable_get(:@registered_tools)&.reject! { |t| t[:name] == name }
+      Mana.instance_variable_get(:@tool_handlers)&.delete(name)
+      @loaded_tools.delete(name)
+      "Tool '#{name}' unloaded"
+    end
+
+    # Download a tool from the hub into the local tools directory.
+    def download_from_hub(name)
+      return false unless @hub && @tools_dir
+
+      @hub.download(name, target_dir: @tools_dir)
+      @index.scan! # Refresh index
+      true
+    rescue => e
+      false
+    end
+
+    private
+
+    def register_with_mana(klass)
+      definition = klass.to_tool_definition
+      Mana.register_tool(definition) do |input|
+        kwargs = input.transform_keys(&:to_sym)
+        klass.new.call(**kwargs)
+      rescue => e
+        "error: #{e.class}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/claw/trace.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Claw
+  # Writes execution traces as Markdown files to .ruby-claw/traces/.
+  # Each task execution produces one trace file with timing, token usage,
+  # and tool call details per LLM iteration.
+  module Trace
+    TRACES_DIR = "traces"
+
+    class << self
+      # Write a trace file from engine trace_data.
+      #
+      # @param trace_data [Hash] from Mana::Engine#trace_data
+      # @param claw_dir [String] path to .ruby-claw/ directory
+      # @return [String] path to the written trace file
+      def write(trace_data, claw_dir)
+        dir = File.join(claw_dir, TRACES_DIR)
+        FileUtils.mkdir_p(dir)
+
+        ts = trace_data[:timestamp] || Time.now.iso8601
+        filename = ts.gsub(/[:\-]/, "").sub("T", "_").split("+").first + ".md"
+        path = File.join(dir, filename)
+
+        File.write(path, render(trace_data))
+        path
+      end
+
+      # Render trace_data as Markdown.
+      def render(data)
+        lines = []
+        prompt_summary = data[:prompt].to_s
+        prompt_summary = prompt_summary[0, 80] + "..." if prompt_summary.length > 80
+
+        lines << "# Task: #{prompt_summary}"
+        lines << ""
+        lines << "- Started: #{data[:timestamp]}"
+        lines << "- Model: #{data[:model]}"
+        lines << "- Steps: #{data[:steps].size}"
+
+        total_in = data[:steps].sum { |s| s.dig(:usage, :input_tokens) || 0 }
+        total_out = data[:steps].sum { |s| s.dig(:usage, :output_tokens) || 0 }
+        total_ms = data[:steps].sum { |s| s[:latency_ms] || 0 }
+
+        lines << "- Total tokens: #{total_in} in / #{total_out} out"
+        lines << "- Total latency: #{total_ms}ms"
+        lines << ""
+
+        data[:steps].each_with_index do |step, i|
+          lines << "## Step #{i + 1}"
+          lines << ""
+          lines << "- Latency: #{step[:latency_ms]}ms"
+          if step[:usage]
+            lines << "- Tokens: #{step[:usage][:input_tokens] || 0} in / #{step[:usage][:output_tokens] || 0} out"
+          end
+
+          if step[:tool_calls]&.any?
+            lines << ""
+            lines << "### Tool calls"
+            lines << ""
+            step[:tool_calls].each do |tc|
+              input_str = summarize_hash(tc[:input])
+              result_str = truncate(tc[:result].to_s, 100)
+              lines << "- **#{tc[:name]}**(#{input_str}) -> #{result_str}"
+            end
+          end
+          lines << ""
+        end
+
+        lines.join("\n")
+      end
+
+      private
+
+      def summarize_hash(hash)
+        return "" unless hash.is_a?(Hash)
+        hash.map { |k, v| "#{k}: #{truncate(v.inspect, 40)}" }.join(", ")
+      end
+
+      def truncate(str, max)
+        str.length > max ? "#{str[0, max]}..." : str
+      end
+    end
+  end
+end

data/lib/claw/tui/agent_executor.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Claw
+  module TUI
+    # Runs Mana::Engine#execute in a background thread, sending MVU messages
+    # back to the model via a callback. Manages runtime state transitions.
+    class AgentExecutor
+      def initialize(runtime)
+        @runtime = runtime
+        @mutex = Mutex.new
+        @running = false
+      end
+
+      # Is an LLM execution currently in progress?
+      def running? = @running
+
+      # Execute an LLM prompt in a background thread.
+      # Yields MVU message objects as events occur.
+      # Returns nil if already running.
+      #
+      # @param input [String] user prompt
+      # @param binding [Binding] caller's binding
+      # @return [Thread, nil] the execution thread, or nil if busy
+      def execute(input, binding, &on_event)
+        @mutex.synchronize do
+          return nil if @running
+          @running = true
+        end
+
+        @runtime&.transition!(:thinking)
+
+        # Capture thread-local state from main thread
+        parent_context = Thread.current[:mana_context]
+        parent_role = Thread.current[:claw_role]
+        parent_memory = Thread.current[:claw_memory]
+
+        Thread.new do
+          # Propagate thread-local state to agent thread
+          Thread.current[:mana_context] = parent_context
+          Thread.current[:claw_role] = parent_role
+          Thread.current[:claw_memory] = parent_memory
+
+          engine = Mana::Engine.new(binding)
+          step_num = 0
+
+          result = engine.execute(input) do |type, *args|
+            case type
+            when :text
+              on_event.call(AgentTextMsg.new(text: args[0]))
+
+            when :tool_start
+              step_num += 1
+              name, input_data = args
+              @runtime&.transition!(:executing_tool,
+                step: Runtime::Step.new(
+                  number: step_num,
+                  tool_name: name,
+                  target: input_data.is_a?(Hash) ? (input_data[:name] || input_data["name"] || name) : name
+                ))
+              on_event.call(ToolCallMsg.new(name: name, input: input_data))
+
+            when :tool_end
+              name, result_str = args
+              on_event.call(ToolResultMsg.new(name: name, result: result_str))
+              @runtime&.transition!(:thinking)
+            end
+          end
+
+          @runtime&.transition!(:idle)
+          on_event.call(ExecutionDoneMsg.new(result: result, trace: engine.trace_data))
+        rescue => e
+          @runtime&.transition!(:failed)
+          on_event.call(ExecutionErrorMsg.new(error: e))
+        ensure
+          @mutex.synchronize { @running = false }
+        end
+      end
+
+      # Execute a Ruby expression, returning the result or error.
+      #
+      # @param code [String] Ruby code to eval
+      # @param binding [Binding] caller's binding
+      # @return [Hash] { success: bool, result: Any, error: Exception? }
+      def eval_ruby(code, binding)
+        result = binding.eval(code)
+        { success: true, result: result }
+      rescue => e
+        { success: false, error: e }
+      end
+    end
+  end
+end