ruby-mana 0.5.10 → 0.5.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dec47003f35644ccba81fd005d200be2046c9e32c8a939ce1b4e74d90defc9cc
-  data.tar.gz: 2f7986b4125ca844517002630195c16fedd0ea182a753ae3836d3cd951721d20
+  metadata.gz: 8d39f448801c8d3f8c7a9c14d30688bfc0469f6aac6d2d646faaadec7e3b93a6
+  data.tar.gz: '0278e9d363a63eb4f39c4b43149ac583f068c358bc09fc316ba64e5a376849f3'
 SHA512:
-  metadata.gz: caa5b68af0f5658f1cc5ff0c053b4b15cb44e88872d07102454171abd4b5d53eacfe39db1d5b8622e76f87a8f45e44944a5e0dfd44055975dfc2324d3af24560
-  data.tar.gz: 202a6b979ecd66f3c8dd4c949d299479ce73ff47e4a6cbc98d06651d103bc1fd5a791bdd0719be9abdfc1bf2aa745fdc5ba73a557119f9c1452d8b37689212ae
+  metadata.gz: 4940fea532999f3381a859cf970eaa4cd4075e8ed281bbb1a80d8b6ec4d91fa9a7c2990cb59e45b59ad6ee0e0ad0e7d72186e993b83035da857aab9c373fc12b
+  data.tar.gz: 84cd628d4af242be45ac7730d20e587e5dc69951e3598c0b66525c8b1e3ba2b0e4e3463b62533d58bff72361d0e2a492acd6743dce10ff9afc7c578b882b6e38

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.5.11] - 2026-03-27
+
+### Changed
+- Memory storage default path changed from `~/.mana/memory` to `{cwd}/.mana` (project-local)
+- Long-term memory injection uses keyword search when collection exceeds 20 memories
+
+### Added
+- Session persistence — short-term memory and summaries survive across restarts (`persist_session` config, default: true)
+- `Memory#save_session` / auto-load on init for session continuity
+- `Memory#search(query, top_k:)` — keyword-based fuzzy matching over long-term memories
+- `config.persist_session` (default: `true`) and `config.memory_top_k` (default: `10`) options
+- `MemoryStore#read_session` / `#write_session` abstract interface and `FileStore` implementation
+
 ## [0.5.10] - 2026-03-27
 
 ### Added

data/README.md

@@ -192,15 +192,15 @@ Each nested call gets its own conversation context. The outer LLM only sees the
 
 Mana has two types of memory:
 
-- **Short-term memory** — conversation history within the current process. Each `~"..."` call appends to it, so consecutive calls share context. Cleared when the process exits.
-- **Long-term memory** — persistent facts stored on disk (`~/.mana/`). Survives across script executions. The LLM can save facts via the `remember` tool.
+- **Short-term memory** — conversation history within the current process. Each `~"..."` call appends to it, so consecutive calls share context. Persisted to session files by default (survives restarts).
+- **Long-term memory** — persistent facts stored on disk (`.mana/` in your project directory). Survives across script executions. The LLM can save facts via the `remember` tool.
 
 ```ruby
 ~"translate <text1> to Japanese, store in <result1>"
 ~"translate <text2> to the same language, store in <result2>"   # remembers "Japanese"
 
 ~"remember that the user prefers concise output"
-# persists to ~/.mana/ — available in future script runs
+# persists to .mana/ — available in future script runs
 ```
 
 ```ruby
@@ -275,6 +275,8 @@ Mana.configure do |c|
   c.memory_keep_recent = 4        # keep last 4 rounds during compaction
   c.compact_model = nil           # nil = use main model for compaction
   c.memory_store = Mana::FileStore.new  # default file-based persistence
+  c.persist_session = true        # persist short-term memory across restarts
+  c.memory_top_k = 10             # max memories to inject when searching (> 20 memories)
 end
 ```
 

data/lib/mana/config.rb

@@ -9,13 +9,11 @@ module Mana
   #   base_url         - Custom API endpoint, falls back to ANTHROPIC_API_URL or OPENAI_API_URL
   #   backend          - :anthropic, :openai, or nil (auto-detect from model name)
   #   timeout          - HTTP timeout in seconds (default: 120)
-  #   memory_pressure  - Token ratio (0-1) that triggers memory compaction (default: 0.7)
   class Config
     attr_accessor :model, :temperature, :api_key, :max_iterations, :base_url,
                   :backend, :verbose,
                   :namespace, :memory_store, :memory_path,
-                  :context_window, :memory_pressure, :memory_keep_recent,
-                  :compact_model, :on_compact
+                  :context_window
     attr_reader :timeout
 
     DEFAULT_ANTHROPIC_URL = "https://api.anthropic.com"
@@ -38,10 +36,6 @@ module Mana
       @memory_store = nil
       @memory_path = nil
       @context_window = 128_000
-      @memory_pressure = 0.7
-      @memory_keep_recent = 4
-      @compact_model = nil
-      @on_compact = nil
     end
 
     # Set timeout; must be a positive number

data/lib/mana/engine.rb

@@ -186,8 +186,6 @@ module Mana
       system_prompt = build_system_prompt(context)
 
       memory = @incognito ? nil : Memory.current
-      # Wait for any in-progress background compaction before reading messages
-      memory&.wait_for_compaction
 
       messages = memory ? memory.short_term : []
 
@@ -272,9 +270,6 @@ module Mana
         messages << { role: "assistant", content: [{ type: "text", text: "Done: #{done_result}" }] }
       end
 
-      # Schedule compaction if needed (runs in background, skip for nested)
-      memory&.schedule_compaction unless nested
-
       # Return written variables so Ruby 4.0+ users can capture them:
       #   result = ~"compute average and store in <result>"
       # Single write -> return the value directly; multiple -> return Hash.

data/lib/mana/knowledge.rb

@@ -136,8 +136,6 @@ module Mana
             Namespace is auto-detected from the git repo name, Gemfile directory, or cwd.
             Configurable via: Mana.configure { |c| c.memory_path = "/custom/path" }
             Or provide a custom MemoryStore subclass for Redis, DB, etc.
-          - Background compaction: when short-term memory exceeds the token pressure threshold
-            (currently #{Mana.config.memory_pressure}), old messages are summarized in a background thread.
           - Incognito mode: Mana.incognito { ~"..." } disables all memory.
           The LLM can store facts via the `remember` tool. These persist across script executions.
         TEXT
@@ -166,8 +164,6 @@ module Mana
           - timeout: #{c.timeout}s
           - max_iterations: #{c.max_iterations}
           - context_window: #{c.context_window}
-          - memory_pressure: #{c.memory_pressure}
-          - memory_keep_recent: #{c.memory_keep_recent}
           - verbose: #{c.verbose}
           All options can be set via Mana.configure { |c| ... } or environment variables
           (MANA_MODEL, MANA_BACKEND, MANA_TIMEOUT, MANA_VERBOSE, ANTHROPIC_API_KEY, OPENAI_API_KEY).

data/lib/mana/memory.rb

@@ -10,8 +10,6 @@ module Mana
       @long_term = []
       @summaries = []
       @next_id = 1
-      @compact_mutex = Mutex.new
-      @compact_thread = nil
       load_long_term
     end
 
@@ -48,7 +46,6 @@ module Mana
     # --- Token estimation ---
 
     # Estimate total token count across short-term messages, long-term facts, and summaries.
-    # Used to determine when memory compaction is needed.
     def token_count
       count = 0
       @short_term.each do |msg|
@@ -69,6 +66,13 @@ module Mana
       count
     end
 
+    # Rough token estimate: ~4 characters per token
+    def estimate_tokens(text)
+      return 0 unless text.is_a?(String)
+
+      (text.length / 4.0).ceil
+    end
+
     # --- Memory management ---
 
     # Clear both short-term and long-term memory
@@ -109,44 +113,6 @@ module Mana
       entry
     end
 
-    # --- Compaction ---
-
-    # Synchronous compaction: wait for any background run, then compact immediately
-    def compact!
-      wait_for_compaction
-      perform_compaction
-    end
-
-    # Check if token usage exceeds the configured memory pressure threshold
-    def needs_compaction?
-      cw = context_window
-      token_count > (cw * Mana.config.memory_pressure)
-    end
-
-    # Launch background compaction if token pressure exceeds the threshold.
-    # Only one compaction thread runs at a time (guarded by mutex).
-    def schedule_compaction
-      return unless needs_compaction?
-
-      @compact_mutex.synchronize do
-        # Skip if a compaction is already in progress
-        return if @compact_thread&.alive?
-
-        @compact_thread = Thread.new do
-          perform_compaction
-        rescue => e
-          # Silently handle compaction errors — don't crash the main thread
-          $stderr.puts "Mana compaction error: #{e.message}" if $DEBUG
-        end
-      end
-    end
-
-    # Block until the background compaction thread finishes (if running)
-    def wait_for_compaction
-      thread = @compact_mutex.synchronize { @compact_thread }
-      thread&.join
-    end
-
     # --- Display ---
 
     # Human-readable summary: counts and token usage
@@ -161,13 +127,6 @@ module Mana
       @short_term.count { |m| m[:role] == "user" && m[:content].is_a?(String) }
     end
 
-    # Rough token estimate: ~4 characters per token
-    def estimate_tokens(text)
-      return 0 unless text.is_a?(String)
-
-      (text.length / 4.0).ceil
-    end
-
     def context_window
       Mana.config.context_window
     end
@@ -209,121 +168,5 @@ module Mana
       # Set next ID to one past the highest existing ID
       @next_id = (@long_term.map { |m| m[:id] }.max || 0) + 1
     end
-
-    # Compact short-term memory: summarize old messages and keep only recent rounds.
-    # Merges existing summaries + old messages into a single new summary, so
-    # summaries don't accumulate unboundedly.
-    def perform_compaction
-      keep_recent = Mana.config.memory_keep_recent
-      # Find indices of user-prompt messages (each marks a conversation round)
-      user_indices = @short_term.each_with_index
-        .select { |msg, _| msg[:role] == "user" && msg[:content].is_a?(String) }
-        .map(&:last)
-
-      # Not enough rounds to compact — nothing to do
-      return if user_indices.size <= keep_recent
-
-      # Find the cutoff point: everything before the last N rounds gets summarized
-      # Clamp keep_recent to avoid negative index beyond array bounds
-      keep = [keep_recent, user_indices.size].min
-      cutoff_user_idx = user_indices[-keep]
-      old_messages = @short_term[0...cutoff_user_idx]
-      return if old_messages.empty?
-
-      # Build text from old messages for summarization
-      text_parts = old_messages.map do |msg|
-        content = msg[:content]
-        # Format each message as "role: content" for the summarizer
-        case content
-        when String then "#{msg[:role]}: #{content}"
-        # Array blocks: extract text parts and join
-        when Array
-          texts = content.map { |b| b[:text] || b[:content] }.compact
-          "#{msg[:role]}: #{texts.join(' ')}" unless texts.empty?
-        end
-      end.compact
-
-      return if text_parts.empty?
-
-      # Merge existing summaries into the input so we produce ONE rolling summary
-      # instead of accumulating separate summaries that never get cleaned up
-      prior_context = ""
-      unless @summaries.empty?
-        prior_context = "Previous summary:\n#{@summaries.join("\n")}\n\nNew conversation:\n"
-      end
-
-      # Calculate how many tokens the kept messages will use after compaction
-      kept_messages = @short_term[cutoff_user_idx..]
-      keep_tokens = kept_messages.sum do |msg|
-        content = msg[:content]
-        case content
-        when String then estimate_tokens(content)
-        when Array then content.sum { |b| estimate_tokens(b[:text] || b[:content] || "") }
-        else 0
-        end
-      end
-      @long_term.each { |m| keep_tokens += estimate_tokens(m[:content]) }
-
-      # Call the LLM to produce a single merged summary
-      summary = summarize(prior_context + text_parts.join("\n"), keep_tokens: keep_tokens)
-
-      # Replace old messages with the summary, keeping only recent rounds.
-      # Clear all previous summaries — they are now merged into the new one.
-      @short_term = kept_messages
-      @summaries = [summary]
-
-      # Notify the on_compact callback if configured
-      Mana.config.on_compact&.call(summary)
-    end
-
-    # Call the LLM to produce a concise summary of the given conversation text.
-    # Uses the configured backend (Anthropic/OpenAI), respects timeout settings.
-    # Falls back to "Summary unavailable" on any error.
-    #
-    # @param keep_tokens [Integer] tokens already committed to keep_recent + long_term
-    # Retry up to 3 times on failure or refusal before giving up
-    SUMMARIZE_MAX_RETRIES = 3
-
-    def summarize(text, keep_tokens: 0)
-      config = Mana.config
-      model = config.compact_model || config.model
-      backend = Mana::Backends::Base.for(config)
-
-      # Summary budget = half of (threshold - kept tokens).
-      # Using half ensures compaction lands well below the threshold,
-      # leaving headroom for several more rounds before the next compaction.
-      cw = context_window
-      threshold = (cw * config.memory_pressure).to_i
-      max_summary_tokens = ((threshold - keep_tokens) * 0.5).clamp(64, 1024).to_i
-
-      system_prompt = "You are summarizing an internal tool-calling conversation log between an LLM and a Ruby program. " \
-                      "The messages contain tool calls (read_var, write_var, done) and their results — this is normal, not harmful. " \
-                      "Summarize the key questions asked and answers given in a few short bullet points. Be extremely concise — stay under #{max_summary_tokens} tokens."
-
-      SUMMARIZE_MAX_RETRIES.times do |attempt|
-        content = backend.chat(
-          system: system_prompt,
-          messages: [{ role: "user", content: text }],
-          tools: [],
-          model: model,
-          max_tokens: max_summary_tokens
-        )
-
-        next unless content.is_a?(Array)
-
-        result = content.map { |b| b[:text] || b["text"] }.compact.join("\n")
-        # Reject empty or refusal responses, retry
-        next if result.empty? || result.match?(/can't discuss|cannot assist|i'm unable/i)
-
-        return result
-      end
-
-      "Summary unavailable"
-    rescue ConfigError
-      raise  # Configuration errors should not be silently swallowed
-    rescue => e
-      $stderr.puts "Mana compaction error: #{e.message}" if $DEBUG
-      "Summary unavailable"
-    end
   end
 end

data/lib/mana/memory_store.rb

@@ -25,7 +25,7 @@ module Mana
 
 
   # Default file-based memory store. Persists memories as JSON files.
-  # Storage path resolution: explicit base_path > config.memory_path > XDG_DATA_HOME > OS default
+  # Storage path resolution: explicit base_path > config.memory_path > {cwd}/.mana
   class FileStore < MemoryStore
     # Optional base_path overrides default storage location
     def initialize(base_path = nil)
@@ -65,15 +65,15 @@ module Mana
     end
 
     # Resolve the base directory for memory storage.
-    # Priority: explicit base_path > config.memory_path > ~/.mana/memory
+    # Priority: explicit base_path > config.memory_path > {cwd}/.mana
     def base_dir
       return File.join(@base_path, "memory") if @base_path
 
       custom_path = Mana.config.memory_path
       return File.join(custom_path, "memory") if custom_path
 
-      # Default fallback
-      File.join(Dir.home, ".mana", "memory")
+      # Default fallback — project-local .mana directory
+      File.join(Dir.pwd, ".mana")
     end
   end
 end

data/lib/mana/prompt_builder.rb

@@ -135,7 +135,7 @@ module Mana
 
       # User-defined classes/modules (skip Ruby internals)
       skip = [Object, Kernel, BasicObject, Module, Class, Mana, Mana::Engine,
-              Mana::Memory, Mana::Config, Mana::Chat]
+              Mana::Memory, Mana::Config]
       user_classes = ObjectSpace.each_object(Class)
         .reject { |c| c.name.nil? || c.name.start_with?("Mana::") || c.name.start_with?("#<") }
         .reject { |c| skip.include?(c) }

data/lib/mana/tool_handler.rb

@@ -85,11 +85,9 @@ module Mana
     rescue LLMError
       # LLMError must propagate to the caller (e.g. from the error tool)
       raise
-    rescue SyntaxError => e
-      # Catch syntax errors from body eval so the LLM can retry with corrected code
-      "error: #{e.class}: #{e.message}"
-    rescue => e
-      # Return errors as strings so the LLM can see and react to them
+    rescue ScriptError, StandardError => e
+      # ScriptError covers SyntaxError, LoadError, NotImplementedError
+      # StandardError covers everything else (NameError, TypeError, etc.)
       "error: #{e.class}: #{e.message}"
     end
 

data/lib/mana/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mana
-  VERSION = "0.5.10"
+  VERSION = "0.5.11"
 end

data/lib/mana.rb

@@ -17,7 +17,6 @@ require_relative "mana/introspect"
 require_relative "mana/compiler"
 require_relative "mana/string_ext"
 require_relative "mana/mixin"
-require_relative "mana/chat"
 
 module Mana
   class Error < StandardError; end
@@ -70,10 +69,6 @@ module Mana
       Compiler.cache_dir = dir
     end
 
-    # Enter interactive chat mode. Mana will have access to the caller's binding.
-    def chat
-      Chat.start(binding.of_caller(1))
-    end
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-mana
 version: !ruby/object:Gem::Version
-  version: 0.5.10
+  version: 0.5.11
 platform: ruby
 authors:
 - Carl Li
 autorequire:
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2026-03-27 00:00:00.000000000 Z
+date: 2026-03-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: binding_of_caller
@@ -24,20 +24,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.0'
-- !ruby/object:Gem::Dependency
-  name: reline
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.5'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: dotenv
   requirement: !ruby/object:Gem::Requirement
@@ -57,21 +43,18 @@ description: |
   with full access to your program's live state. Read/write variables, call
   functions, manipulate objects — all from a simple ~"..." syntax.
 email:
-executables:
-- mana
+executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE
 - README.md
-- exe/mana
 - lib/mana.rb
 - lib/mana/backends/anthropic.rb
 - lib/mana/backends/base.rb
 - lib/mana/backends/openai.rb
 - lib/mana/binding_helpers.rb
-- lib/mana/chat.rb
 - lib/mana/compiler.rb
 - lib/mana/config.rb
 - lib/mana/engine.rb

data/exe/mana

@@ -1,12 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-begin
-  require "dotenv/load"
-rescue LoadError
-  # dotenv not installed — skip
-end
-
-require "mana"
-
-Mana::Chat.start(TOPLEVEL_BINDING)

data/lib/mana/chat.rb

@@ -1,301 +0,0 @@
-# frozen_string_literal: true
-
-module Mana
-  # Interactive chat mode — enter with Mana.chat to talk to Mana in your Ruby runtime.
-  # Supports streaming output, colored prompts, and full access to the caller's binding.
-  # Auto-detects Ruby code vs natural language. Use '!' prefix to force Ruby execution.
-  module Chat
-    USER_PROMPT  = "\e[36mmana>\e[0m "    # cyan
-    MANA_PREFIX  = "\e[33mmana>\e[0m "   # yellow
-    RUBY_PREFIX  = "\e[35m=>\e[0m "      # magenta
-    THINK_COLOR  = "\e[3;36m"            # italic cyan
-    TOOL_COLOR   = "\e[2;33m"            # dim yellow
-    RESULT_COLOR = "\e[2;32m"            # dim green
-    CODE_COLOR   = "\e[36m"              # cyan for code
-    BOLD         = "\e[1m"               # bold
-    ERROR_COLOR  = "\e[31m"              # red
-    DIM          = "\e[2m"               # dim
-    RESET        = "\e[0m"
-
-    CONT_PROMPT  = "\e[2m  \e[0m"
-    EXIT_COMMANDS = /\A(exit|quit|bye|q)\z/i
-
-    # Entry point — starts the REPL loop with Reline for readline support.
-    # Reline is required lazily so chat mode doesn't penalize non-interactive usage.
-    HISTORY_FILE = File.join(Dir.home, ".mana_history")
-    HISTORY_MAX  = 1000
-
-    def self.start(caller_binding)
-      require "reline"
-      load_history
-      puts "#{DIM}Mana chat · type 'exit' to quit#{RESET}"
-      puts
-
-      loop do
-        input = read_input
-        break if input.nil?
-        next if input.strip.empty?
-        break if input.strip.match?(EXIT_COMMANDS)
-
-        # Three-tier dispatch:
-        # "!" prefix — force Ruby eval (bypass ambiguity detection)
-        # Valid Ruby syntax — try Ruby first, fall back to LLM if NameError
-        # Everything else — send directly to the LLM
-        if input.start_with?("!")
-          eval_ruby(caller_binding, input[1..].strip)
-        elsif ruby_syntax?(input)
-          eval_ruby(caller_binding, input) { run_mana(caller_binding, input) }
-        else
-          run_mana(caller_binding, input)
-        end
-        puts
-      end
-
-      save_history
-      puts "#{DIM}bye!#{RESET}"
-    end
-
-    def self.load_history
-      return unless File.exist?(HISTORY_FILE)
-
-      File.readlines(HISTORY_FILE, chomp: true).last(HISTORY_MAX).each do |line|
-        Reline::HISTORY << line
-      end
-    rescue StandardError
-      # ignore corrupt history
-    end
-    private_class_method :load_history
-
-    def self.save_history
-      lines = Reline::HISTORY.to_a.last(HISTORY_MAX)
-      File.write(HISTORY_FILE, lines.join("\n") + "\n")
-    rescue StandardError
-      # ignore write failures
-    end
-    private_class_method :save_history
-
-    # Reads input with multi-line support — keeps prompting with continuation
-    # markers while the buffer contains incomplete Ruby (unclosed blocks, strings, etc.)
-    def self.read_input
-      # Second arg to readline: true = add to history, false = don't
-      buffer = Reline.readline(USER_PROMPT, true)
-      return nil if buffer.nil?
-
-      while incomplete_ruby?(buffer)
-        line = Reline.readline(CONT_PROMPT, false)
-        break if line.nil?
-        buffer += "\n" + line
-      end
-      buffer
-    end
-    private_class_method :read_input
-
-    # Heuristic: if RubyVM can compile it, treat as Ruby code.
-    # This lets users type `x = 1 + 2` without needing the "!" prefix.
-    def self.ruby_syntax?(input)
-      RubyVM::InstructionSequence.compile(input)
-      true
-    rescue SyntaxError
-      false
-    end
-    private_class_method :ruby_syntax?
-
-    # Distinguishes incomplete code (needs more input) from invalid code (syntax error).
-    # Only "unexpected end-of-input" and "unterminated" indicate the user is still typing;
-    # other SyntaxErrors mean the code is complete but malformed.
-    def self.incomplete_ruby?(code)
-      RubyVM::InstructionSequence.compile(code)
-      false
-    rescue SyntaxError => e
-      e.message.include?("unexpected end-of-input") ||
-        e.message.include?("unterminated")
-    end
-    private_class_method :incomplete_ruby?
-
-    # Eval Ruby in the caller's binding. On NameError/NoMethodError, yields to the
-    # fallback block (which sends to the LLM) — this is how ambiguous input like
-    # "sort this list" gets routed: Ruby rejects it, then the LLM handles it.
-    def self.eval_ruby(caller_binding, code)
-      result = caller_binding.eval(code)
-      puts "#{RUBY_PREFIX}#{result.inspect}"
-    rescue NameError, NoMethodError => e
-      block_given? ? yield : puts("#{ERROR_COLOR}#{e.class}: #{e.message}#{RESET}")
-    rescue => e
-      puts "#{ERROR_COLOR}#{e.class}: #{e.message}#{RESET}"
-    end
-    private_class_method :eval_ruby
-
-    # --- Mana LLM execution with streaming + markdown rendering ---
-
-    # Executes a prompt via the LLM engine with streaming output.
-    # Uses a line buffer to render complete lines with markdown formatting
-    # while the LLM streams tokens incrementally.
-    def self.run_mana(caller_binding, input)
-      streaming_text = false
-      in_code_block = false
-      line_buffer = +""       # mutable string — accumulates partial lines until \n
-      engine = Engine.new(caller_binding)
-
-      begin
-        result = engine.execute(input) do |type, *args|
-          case type
-          when :text
-            unless streaming_text
-              print MANA_PREFIX
-              streaming_text = true
-            end
-
-            # Buffer text and flush complete lines with markdown rendering
-            line_buffer << args[0].to_s
-            while (idx = line_buffer.index("\n"))
-              line = line_buffer.slice!(0, idx + 1)
-              in_code_block = render_line(line.chomp, in_code_block)
-              puts
-            end
-
-          when :tool_start
-            flush_line_buffer(line_buffer, in_code_block) if streaming_text
-            streaming_text = false
-            in_code_block = false
-            line_buffer.clear
-            name, input_data = args
-            detail = format_tool_call(name, input_data)
-            puts "#{TOOL_COLOR}  ⚡ #{detail}#{RESET}"
-
-          when :tool_end
-            name, result_str = args
-            summary = truncate(result_str.to_s, 120)
-            puts "#{RESULT_COLOR}  ↩ #{summary}#{RESET}" unless summary.start_with?("ok:")
-          end
-        end
-
-        # Flush any remaining buffered text
-        flush_line_buffer(line_buffer, in_code_block) if streaming_text
-
-        # Non-streaming fallback: if no text was streamed (e.g. tool-only response),
-        # render the final result as a single block
-        unless streaming_text
-          display = case result
-                    when Hash then result.inspect
-                    when nil then nil
-                    when String then render_markdown(result)
-                    else result.inspect
-                    end
-          puts "#{MANA_PREFIX}#{display}" if display
-        end
-      rescue LLMError, MaxIterationsError => e
-        flush_line_buffer(line_buffer, in_code_block) if streaming_text
-        puts "#{ERROR_COLOR}error: #{e.message}#{RESET}"
-      end
-    end
-    private_class_method :run_mana
-
-    # --- Markdown → ANSI rendering ---
-
-    # Render a single line, handling code block state.
-    # Returns the new in_code_block state.
-    def self.render_line(line, in_code_block)
-      if line.strip.start_with?("```")
-        if in_code_block
-          # End of code block — don't print the closing ```
-          return false
-        else
-          # Start of code block — don't print the opening ```
-          return true
-        end
-      end
-
-      if in_code_block
-        print "  #{CODE_COLOR}#{line}#{RESET}"
-      else
-        print render_markdown_inline(line)
-      end
-      in_code_block
-    end
-    private_class_method :render_line
-
-    # Flush remaining text in the line buffer
-    def self.flush_line_buffer(buffer, in_code_block)
-      return if buffer.empty?
-      text = buffer.dup
-      buffer.clear
-      if in_code_block
-        print "  #{CODE_COLOR}#{text}#{RESET}"
-      else
-        print render_markdown_inline(text)
-      end
-      puts
-    end
-    private_class_method :flush_line_buffer
-
-    # Convert inline markdown to ANSI codes.
-    # Handles **bold**, `inline code` (with negative lookbehind to skip ```),
-    # and # headings. Intentionally minimal — just enough for readable terminal output.
-    def self.render_markdown_inline(text)
-      text
-        .gsub(/\*\*(.+?)\*\*/, "#{BOLD}\\1#{RESET}")
-        .gsub(/(?<!`)`([^`]+)`(?!`)/, "#{CODE_COLOR}\\1#{RESET}")
-        .gsub(/^\#{1,3}\s+(.+)/) { BOLD + $1 + RESET }
-    end
-    private_class_method :render_markdown_inline
-
-    # Render a complete block of markdown text (for non-streaming results)
-    def self.render_markdown(text)
-      lines = text.lines
-      result = +""
-      in_code = false
-      lines.each do |line|
-        stripped = line.strip
-        if stripped.start_with?("```")
-          in_code = !in_code
-          next
-        end
-        if in_code
-          result << "  #{CODE_COLOR}#{line.rstrip}#{RESET}\n"
-        else
-          result << render_markdown_inline(line.rstrip) << "\n"
-        end
-      end
-      result.chomp
-    end
-    private_class_method :render_markdown
-
-    # --- Tool formatting helpers ---
-
-    def self.format_tool_call(name, input)
-      case name
-      when "call_func"
-        func = input[:name] || input["name"]
-        args = input[:args] || input["args"] || []
-        body = input[:body] || input["body"]
-        desc = func.to_s
-        desc += "(#{args.map(&:inspect).join(', ')})" if args.any?
-        desc += " { #{truncate(body, 40)} }" if body
-        desc
-      # Display read_var as just the name, write_var as an assignment
-      when "read_var", "write_var"
-        var = input[:name] || input["name"]
-        val = input[:value] || input["value"]
-        val ? "#{var} = #{truncate(val.inspect, 60)}" : var.to_s
-      when "read_attr", "write_attr"
-        obj = input[:obj] || input["obj"]
-        attr = input[:attr] || input["attr"]
-        "#{obj}.#{attr}"
-      when "remember"
-        content = input[:content] || input["content"]
-        "remember: #{truncate(content.to_s, 60)}"
-      when "knowledge"
-        topic = input[:topic] || input["topic"]
-        "knowledge(#{topic})"
-      else
-        name.to_s
-      end
-    end
-    private_class_method :format_tool_call
-
-    def self.truncate(str, max)
-      str.length > max ? "#{str[0, max]}..." : str
-    end
-    private_class_method :truncate
-  end
-end