ruby-mana 0.5.8 → 0.5.10

data/lib/mana/engine.rb

@@ -8,6 +8,10 @@ module Mana
   class Engine
     attr_reader :config, :binding
 
+    include Mana::BindingHelpers
+    include Mana::PromptBuilder
+    include Mana::ToolHandler
+
     TOOLS = [
       {
         name: "read_var",
@@ -20,7 +24,7 @@ module Mana
       },
       {
         name: "write_var",
-        description: "Write a value to a variable in the Ruby scope. Creates the variable if it doesn't exist.",
+        description: "Write a JSON-serializable value (string, number, boolean, array, hash, nil) to a variable. Cannot store lambdas, procs, or Ruby objects — use call_func with define_method for functions.",
         input_schema: {
           type: "object",
           properties: {
@@ -57,13 +61,14 @@ module Mana
       },
       {
         name: "call_func",
-        description: "Call a Ruby method/function available in the current scope. Use kwargs for keyword arguments.",
+        description: "Call a Ruby method/function. Use body to pass a block. To define new methods: call_func(name: 'define_method', args: ['method_name'], body: '|args| code').",
         input_schema: {
           type: "object",
           properties: {
             name: { type: "string", description: "Function/method name" },
             args: { type: "array", description: "Positional arguments", items: {} },
-            kwargs: { type: "object", description: "Keyword arguments (e.g. {sql: '...', limit: 10})" }
+            kwargs: { type: "object", description: "Keyword arguments (e.g. {sql: '...', limit: 10})" },
+            body: { type: "string", description: "Ruby code block body, passed as &block. Use |params| syntax. Example: '|x| x * 2'" }
           },
           required: ["name"]
         }
@@ -77,9 +82,43 @@ module Mana
             result: { description: "The answer or result to return. Always provide this." }
           }
         }
+      },
+      {
+        name: "error",
+        description: "Signal that the task cannot be completed. Call this when you encounter an unrecoverable problem. The message will be raised as an exception in the Ruby program.",
+        input_schema: {
+          type: "object",
+          properties: {
+            message: { type: "string", description: "Description of the error" }
+          },
+          required: ["message"]
+        }
+      },
+      {
+        name: "eval",
+        description: "Execute Ruby code directly in the caller's binding. Returns the result of the last expression. Use this for anything that's easier to express as Ruby code than as individual tool calls.",
+        input_schema: {
+          type: "object",
+          properties: {
+            code: { type: "string", description: "Ruby code to execute" }
+          },
+          required: ["code"]
+        }
+      },
+      {
+        name: "knowledge",
+        description: "Query the knowledge base. Covers ruby-mana internals, Ruby documentation (ri), and runtime introspection of classes/modules.",
+        input_schema: {
+          type: "object",
+          properties: {
+            topic: { type: "string", description: "Topic to look up. Examples: 'memory', 'tools', 'ruby', 'Array#map', 'Enumerable', 'Hash'" }
+          },
+          required: ["topic"]
+        }
       }
     ].freeze
 
+    # Separated from TOOLS because it's conditionally excluded in incognito mode
     REMEMBER_TOOL = {
       name: "remember",
       description: "Store a fact in long-term memory. This memory persists across script executions. Use when the user explicitly asks to remember something.",
@@ -90,6 +129,7 @@ module Mana
       }
     }.freeze
 
+
     class << self
       # Entry point for ~"..." prompts. Routes to mock handler or real LLM engine.
       def run(prompt, caller_binding)
@@ -101,12 +141,17 @@ module Mana
         new(caller_binding).execute(prompt)
       end
 
-      # Built-in tools + remember
+      # Built-in tools + remember (conditional)
       def all_tools
         tools = TOOLS.dup
         tools << REMEMBER_TOOL unless Memory.incognito?
         tools
       end
+
+      # Query the runtime knowledge base
+      def knowledge(topic)
+        Mana::Knowledge.query(topic)
+      end
     end
 
     # Capture the caller's binding, config, source path, and incognito state
@@ -117,8 +162,9 @@ module Mana
       @incognito = Memory.incognito?
     end
 
-    # Main execution loop: build context, call LLM, handle tool calls, iterate until done
-    def execute(prompt)
+    # Main execution loop: build context, call LLM, handle tool calls, iterate until done.
+    # Optional &on_text block receives streaming text deltas for real-time display.
+    def execute(prompt, &on_text)
       # Track nesting depth to isolate memory for nested ~"..." calls
       Thread.current[:mana_depth] ||= 0
       Thread.current[:mana_depth] += 1
@@ -145,7 +191,9 @@ module Mana
 
       messages = memory ? memory.short_term : []
 
-      # Ensure messages don't end with an unpaired tool_use (causes API 400 error)
+      # Strip trailing unpaired tool_use messages from prior calls.
+      # Both Anthropic and OpenAI reject requests where the last assistant message
+      # has tool_use blocks without corresponding tool_result responses.
       while messages.last && messages.last[:role] == "assistant" &&
             messages.last[:content].is_a?(Array) &&
             messages.last[:content].any? { |b| (b[:type] || b["type"]) == "tool_use" }
@@ -170,19 +218,26 @@ module Mana
         @_iteration = iterations
         raise MaxIterationsError, "exceeded #{@config.max_iterations} iterations" if iterations > @config.max_iterations
 
-        response = llm_call(system_prompt, messages)
+        response = llm_call(system_prompt, messages, &on_text)
         tool_uses = extract_tool_uses(response)
 
         if tool_uses.empty?
-          # Model returned text without calling any tools.
-          # On the first iteration with no writes yet, nudge it to use tools.
+          # In streaming/chat mode, text-only responses are fine — just accept them
+          if on_text
+            messages << { role: "assistant", content: response }
+            text = response.is_a?(Array) ? response.filter_map { |b| b[:text] || b["text"] }.join("\n") : response.to_s
+            done_result = text unless text.empty?
+            break
+          end
+          # In script mode (~"..."), nudge the LLM to use tools
           if iterations == 1 && @written_vars.empty?
             messages << { role: "assistant", content: response }
-            messages << { role: "user", content: "You must use the provided tools (read_var, write_var, done) to complete this task. Do not just describe the answer in text." }
+            messages << { role: "user", content: "You must use the provided tools to complete this task. Do not just describe the answer in text." }
             next
           end
-          # Otherwise, accept the text-only response and exit the loop
-          break
+          # LLM refused to use tools after nudge — extract text and raise
+          text = response.is_a?(Array) ? response.filter_map { |b| b[:text] || b["text"] }.join("\n") : response.to_s
+          raise Mana::LLMError, "LLM did not use tools: #{text.slice(0, 200)}"
         end
 
         # Append assistant message with tool_use blocks
@@ -190,7 +245,18 @@ module Mana
 
         # Process each tool use and collect results
         tool_results = tool_uses.map do |tu|
+          if on_text
+            case tu[:name]
+            when "done", "error"
+              # handled separately
+            else
+              on_text.call(:tool_start, tu[:name], tu[:input])
+            end
+          end
           result = handle_effect(tu, memory)
+          if on_text && !%w[done error].include?(tu[:name])
+            on_text.call(:tool_end, tu[:name], result)
+          end
           done_result = (tu[:input][:result] || tu[:input]["result"]) if tu[:name] == "done"
           { type: "tool_result", tool_use_id: tu[:id], content: result.to_s }
         end
@@ -276,358 +342,35 @@ module Mana
 
     private
 
-    # --- Context Building ---
-
-    # Extract <var> references from the prompt and read their current values.
-    # Variables that don't exist yet are silently skipped (LLM will create them).
-    def build_context(prompt)
-      var_names = prompt.scan(/<(\w+)>/).flatten.uniq
-      ctx = {}
-      var_names.each do |name|
-        val = resolve(name)
-        ctx[name] = serialize_value(val)
-      rescue NameError
-        # Variable doesn't exist yet — will be created by LLM
-      end
-      ctx
-    end
-
-    # Assemble the system prompt with rules, memory, variables, available functions, and custom effects
-    def build_system_prompt(context)
-      parts = [
-        "You are embedded inside a Ruby program. You interact with the program's live state using the provided tools.",
-        "",
-        "Rules:",
-        "- Use read_var / read_attr to inspect variables and objects.",
-        "- Use write_var to create or update variables in the Ruby scope.",
-        "- Use write_attr to set attributes on Ruby objects.",
-        "- Use call_func to call Ruby methods listed below. Only call functions that are explicitly listed — do NOT guess or try to discover functions by calling methods like `methods`, `local_variables`, etc.",
-        "- Call done(result: ...) when the task is complete. ALWAYS put the answer in the result field — it is the return value of ~\"...\". If no <var> is referenced, the done result is the only way to return a value.",
-        "- When the user references <var>, that's a variable in scope.",
-        "- If a referenced variable doesn't exist yet, the user expects you to create it with write_var.",
-        "- Be precise with types: use numbers for numeric values, arrays for lists, strings for text.",
-        "- Respond in the same language as the user's prompt unless explicitly told otherwise.",
-        "- PRIORITY: The user's current prompt ALWAYS overrides any prior context, conversation history, or long-term memories. Treat it like Ruby's inner scope shadowing outer scope."
-      ]
-
-      if @incognito
-        parts << ""
-        parts << "You are in incognito mode. The remember tool is disabled. No memories will be loaded or saved."
-      else
-        memory = Memory.current
-        # Inject memory context when available
-        if memory
-          # Add compaction summaries from prior conversations
-          unless memory.summaries.empty?
-            parts << ""
-            parts << "Previous conversation summary:"
-            memory.summaries.each { |s| parts << "  #{s}" }
-          end
-
-          # Add persistent long-term facts
-          unless memory.long_term.empty?
-            parts << ""
-            parts << "Long-term memories (persistent background context):"
-            memory.long_term.each { |m| parts << "- #{m[:content]}" }
-            parts << "NOTE: Long-term memories are background defaults. The user's current prompt ALWAYS takes priority. If the prompt conflicts with a memory (e.g. memory says Japanese but prompt says Chinese), follow the prompt."
-          end
-
-          unless memory.long_term.empty?
-            parts << ""
-            parts << "You have a `remember` tool to store new facts in long-term memory when the user asks."
-          end
-        end
-      end
-
-      # Inject current variable values referenced in the prompt
-      unless context.empty?
-        parts << ""
-        parts << "Current variable values:"
-        context.each { |k, v| parts << "  #{k} = #{v}" }
-      end
-
-      # Discover available functions from two sources:
-      # 1. AST scan of the caller's source file (gets parameter signatures)
-      # 2. Receiver's methods minus Ruby builtins (catches require'd functions)
-      file_methods = begin
-        Mana::Introspect.methods_from_file(@caller_path)
-      rescue => _e
-        []
-      end
-      file_method_names = file_methods.map { |m| m[:name] }
-
-      # Methods on the receiver not from Object/Kernel (user-defined or require'd)
-      receiver = @binding.receiver
-      receiver_methods = (receiver.methods - Object.methods - Kernel.methods - [:~@, :mana])
-        .select { |m| receiver.method(m).owner != Object && receiver.method(m).owner != Kernel }
-        .reject { |m| file_method_names.include?(m.to_s) }  # avoid duplicates with AST scan
-        .map { |m|
-          meth = receiver.method(m)
-          params = meth.parameters.map { |(type, name)|
-            case type
-            when :req then name.to_s
-            when :opt then "#{name}=..."
-            when :rest then "*#{name}"
-            when :keyreq then "#{name}:"
-            when :key then "#{name}: ..."
-            when :keyrest then "**#{name}"
-            when :block then "&#{name}"
-            else name.to_s
-            end
-          }
-          { name: m.to_s, params: params }
-        }
-
-      all_methods = file_methods + receiver_methods
-      # Append available function signatures so the LLM knows what it can call
-      unless all_methods.empty?
-        parts << ""
-        parts << Mana::Introspect.format_for_prompt(all_methods)
-      end
-
-      parts.join("\n")
-    end
-
-    # --- Effect Handling ---
-
-    # Dispatch a single tool call from the LLM.
-    # Handle built-in tool calls from the LLM.
-    def handle_effect(tool_use, memory = nil)
-      name = tool_use[:name]
-      input = tool_use[:input] || {}
-      # Normalize keys to strings for consistent access
-      input = input.transform_keys(&:to_s) if input.is_a?(Hash)
-
-      case name
-      when "read_var"
-        # Read a variable from the caller's binding and return its serialized value
-        val = serialize_value(resolve(input["name"]))
-        vlog_value("   ↩ #{input['name']} =", val)
-        val
-
-      when "write_var"
-        # Write a value to the caller's binding and track it for the return value
-        var_name = input["name"]
-        value = input["value"]
-        write_local(var_name, value)
-        @written_vars[var_name] = value
-        vlog_value("   ✅ #{var_name} =", value)
-        "ok: #{var_name} = #{value.inspect}"
-
-      when "read_attr"
-        # Read an attribute (public method) from a Ruby object in scope
-        obj = resolve(input["obj"])
-        validate_name!(input["attr"])
-        serialize_value(obj.public_send(input["attr"]))
-
-      when "write_attr"
-        # Set an attribute (public setter) on a Ruby object in scope
-        obj = resolve(input["obj"])
-        validate_name!(input["attr"])
-        obj.public_send("#{input['attr']}=", input["value"])
-        "ok: #{input['obj']}.#{input['attr']} = #{input['value'].inspect}"
-
-      when "call_func"
-        func = input["name"]
-        args = input["args"] || []
-        kwargs = (input["kwargs"] || {}).transform_keys(&:to_sym)
-        policy = @config.security
-
-        # Handle chained calls (e.g. Time.now, Time.now.to_s, File.read)
-        if func.include?(".")
-          # Split into receiver constant and method chain for security check
-          first_dot = func.index(".")
-          receiver_name = func[0...first_dot]
-          rest = func[(first_dot + 1)..]
-          methods_chain = rest.split(".")
-          first_method = methods_chain.first
-
-          # Enforce security policy on the receiver+method pair
-          if policy.receiver_call_blocked?(receiver_name, first_method)
-            raise NameError, "'#{receiver_name}.#{first_method}' is blocked by security policy (level #{policy.level}: #{policy.preset})"
-          end
-          if policy.method_blocked?(first_method)
-            raise NameError, "'#{first_method}' is blocked by security policy"
-          end
-
-          # Validate receiver is a simple constant name (e.g. "Time", "File", "Math")
-          # NOT an expression like "ENV['HOME']" which could bypass security policy
-          unless receiver_name.match?(/\A[A-Z][A-Za-z0-9_]*(::[A-Z][A-Za-z0-9_]*)*\z/)
-            raise NameError, "'#{receiver_name}' is not a valid constant name"
-          end
-
-          begin
-            receiver = @binding.eval(receiver_name)
-          rescue => e
-            raise NameError, "cannot resolve '#{receiver_name}': #{e.message}"
-          end
-          result = receiver.public_send(first_method.to_sym, *args)
-
-          # Chain remaining methods without args (e.g. .to_s, .strftime)
-          methods_chain[1..].each do |m|
-            result = result.public_send(m.to_sym)
-          end
-
-          vlog_value("   ↩ #{func}(#{args.map(&:inspect).join(', ')}) →", result)
-          return serialize_value(result)
-        end
-
-        # Simple (non-chained) function call
-        validate_name!(func)
-        if policy.method_blocked?(func)
-          raise NameError, "'#{func}' is blocked by security policy (level #{policy.level}: #{policy.preset})"
-        end
-
-        # Try local variable (lambdas/procs) first, then receiver methods
-        callable = if @binding.local_variables.include?(func.to_sym)
-                     # Local lambda/proc takes priority
-                     @binding.local_variable_get(func.to_sym)
-                   elsif @binding.receiver.respond_to?(func.to_sym, true)
-                     # Fall back to method defined on the receiver (self)
-                     @binding.receiver.method(func.to_sym)
-                   else
-                     raise NameError, "undefined function '#{func}'"
-                   end
-        result = kwargs.empty? ? callable.call(*args) : callable.call(*args, **kwargs)
-        call_desc = args.map(&:inspect).concat(kwargs.map { |k, v| "#{k}: #{v.inspect}" }).join(", ")
-        vlog_value("   ↩ #{func}(#{call_desc}) →", result)
-        serialize_value(result)
-
-      when "remember"
-        # Store a fact in long-term memory (persistent across executions)
-        if @incognito
-          "Memory not saved (incognito mode)"
-        elsif memory
-          entry = memory.remember(input["content"])
-          "Remembered (id=#{entry[:id]}): #{input['content']}"
-        else
-          "Memory not available"
-        end
-
-      when "done"
-        # Signal task completion; the result becomes the return value
-        done_val = input["result"]
-        vlog_value("🏁 Done:", done_val)
-        vlog("═" * 60)
-        input["result"].to_s
-
-      else
-        "error: unknown tool #{name}"
-      end
-    rescue => e
-      # Return errors as strings so the LLM can see and react to them
-      "error: #{e.class}: #{e.message}"
-    end
-
-    # --- Binding Helpers ---
-
-    VALID_IDENTIFIER = /\A[A-Za-z_][A-Za-z0-9_]*\z/
-
-    # Ensure a name is a valid Ruby identifier (prevents injection)
-    def validate_name!(name)
-      raise Mana::Error, "invalid identifier: #{name.inspect}" unless name.match?(VALID_IDENTIFIER)
-    end
+    # --- LLM Client ---
 
-    # Resolve a name to a value: try local variable first, then receiver method
-    def resolve(name)
-      validate_name!(name)
-      if @binding.local_variable_defined?(name.to_sym)
-        # Found as a local variable in the caller's binding
-        @binding.local_variable_get(name.to_sym)
-      elsif @binding.receiver.respond_to?(name.to_sym)
-        # Found as a public method on the caller's self
-        @binding.receiver.public_send(name.to_sym)
-      else
-        raise NameError, "undefined variable or method '#{name}'"
-      end
-    end
+    # Send a request to the LLM backend and log the response.
+    # When &on_text is provided and the backend supports streaming, streams text deltas.
+    def llm_call(system, messages, &on_text)
+      vlog("\n#{"─" * 60}")
+      vlog("🔄 LLM call ##{@_iteration} → #{@config.model}")
+      backend = Backends::Base.for(@config)
 
-    # Write a value into the caller's binding, with Ruby 4.0+ singleton method fallback.
-    # Only defines a singleton method when the variable doesn't already exist as a local
-    # AND the receiver doesn't already have a real method with that name.
-    def write_local(name, value)
-      validate_name!(name)
-      sym = name.to_sym
-
-      # Check if the variable already exists before setting
-      existed = @binding.local_variable_defined?(sym)
-      @binding.local_variable_set(sym, value)
-
-      # Ruby 4.0+: local_variable_set can no longer create new locals visible
-      # in the caller's scope. Define a singleton method ONLY for new variables
-      # that don't conflict with existing methods on the receiver.
-      unless existed
-        receiver = @binding.eval("self")
-        # Don't overwrite real instance methods — only add if no method exists
-        unless receiver.class.method_defined?(sym) || receiver.class.private_method_defined?(sym)
-          old_verbose, $VERBOSE = $VERBOSE, nil
-          receiver.define_singleton_method(sym) { value }
-          $VERBOSE = old_verbose
+      result = if on_text && backend.respond_to?(:chat_stream)
+        backend.chat_stream(
+          system: system,
+          messages: messages,
+          tools: self.class.all_tools,
+          model: @config.model,
+          max_tokens: 4096
+        ) do |event|
+          on_text.call(:text, event[:text]) if event[:type] == :text_delta
         end
-      end
-    end
-
-    # Find the user's source file by walking up the call stack.
-    # Used for introspecting available methods in the caller's code.
-    def caller_source_path
-      # Try binding's source_location first (most direct)
-      loc = @binding.source_location
-      return loc[0] if loc.is_a?(Array)
-
-      # Fallback: scan caller_locations, skip frames inside the mana gem itself
-      caller_locations(4, 20)&.each do |frame|
-        path = frame.absolute_path || frame.path
-        next if path.nil? || path.include?("mana/")
-        return path
-      end
-      nil
-    end
-
-    # Serialize a Ruby value to a string representation the LLM can understand.
-    # Handles primitives, collections, and arbitrary objects (via ivar inspection).
-    def serialize_value(val)
-      case val
-      when Time
-        # Format Time as a human-readable timestamp string
-        val.strftime("%Y-%m-%d %H:%M:%S %z").inspect
-      when String, Integer, Float, TrueClass, FalseClass, NilClass
-        # Primitives: use Ruby's built-in inspect
-        val.inspect
-      when Symbol
-        # Convert symbol to string for LLM readability
-        val.to_s.inspect
-      when Array
-        # Recursively serialize each element
-        "[#{val.map { |v| serialize_value(v) }.join(', ')}]"
-      when Hash
-        # Recursively serialize key-value pairs
-        pairs = val.map { |k, v| "#{serialize_value(k)} => #{serialize_value(v)}" }
-        "{#{pairs.join(', ')}}"
       else
-        # Arbitrary object: show class name and instance variables
-        ivars = val.instance_variables
-        obj_repr = ivars.map do |ivar|
-          attr_name = ivar.to_s.delete_prefix("@")
-          "#{attr_name}: #{val.instance_variable_get(ivar).inspect}" rescue nil
-        end.compact.join(", ")
-        "#<#{val.class} #{obj_repr}>"
+        backend.chat(
+          system: system,
+          messages: messages,
+          tools: self.class.all_tools,
+          model: @config.model,
+          max_tokens: 4096
+        )
       end
-    end
-
-    # --- LLM Client ---
 
-    # Send a request to the LLM backend and log the response
-    def llm_call(system, messages)
-      vlog("\n#{"─" * 60}")
-      vlog("🔄 LLM call ##{@_iteration} → #{@config.model}")
-      backend = Backends::Base.for(@config)
-      result = backend.chat(
-        system: system,
-        messages: messages,
-        tools: self.class.all_tools,
-        model: @config.model,
-        max_tokens: 4096
-      )
       result.each do |block|
         type = block[:type] || block["type"]
         case type