ruby_llm-code_mode 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b92ccf0470dc8d3563eafa55662e7aa0db058095d8ac12a0d60a062547474f81
-  data.tar.gz: c2955740ee6b04b1a38279b25f63703194df752fa51f3d4f49166bab3f318ac3
+  metadata.gz: fb23ad192879e9ce6bcac0204c62c44ad068943dadd5e46a3a2e82bd177411c7
+  data.tar.gz: 39b52ca9cf5f733224a1a8a999ae50cbe091467819d86f63a7c38610be665233
 SHA512:
-  metadata.gz: 7fb1029e393ec6c0041d91d5a45fbef2acdc253fe28427986d0832a73eb33b43becfa42d97983212ac7a3312a771e9506765c271bd4bd2ebcf68968b7adf467e
-  data.tar.gz: 52e9aa1bf43f9dcedf0a6e50deb9578c86716bdd5ae353da6717a6553b7f5170f3773f5c40a4229779589be9686e0a3274788d3dc658cdb084fcc5ff862c206a
+  metadata.gz: 6e41645fd4404b2a70e3a3606ab6b1aba047e20e1e610278ddaac8ae85b8512d0c0af134a897fface831e7a1547b77610444bbb8dffb6a80b468bf4a79f09af2
+  data.tar.gz: 60adf578f5deafbd36822e14179e8bcd74856ba6d4b598910cc2be40520ef577f8fd534ffde0ecad2d5ab5c512ff2ac2b98ae60f8c66b0cc0dfa8253bde5b609

data/README.md

@@ -22,21 +22,41 @@ gem "ruby_llm-code_mode"
 
 ## Usage
 
-Define a tool class, declare the host folders the sandbox may see, and give it to
-your chat:
+Define a tool class, declare the host folders the sandbox may see, bind the
+host tools and MCP servers the code may call, and give it to your chat:
 
 ```ruby
 require "ruby_llm"
 require "ruby_llm/code_mode"
 
+# A host tool the sandboxed code can call with SB.call("notes", note: "...").
+class Notes < RubyLLM::Tool
+  description "Records a finding in the analysis log"
+
+  parameter :note, type: "string", description: "The finding to record"
+
+  def execute(note:)
+    # host-side write: log file, HTTP call, database query, ...
+    { recorded: note }
+  end
+end
+
+# An MCP server whose tools become callable from inside the sandbox too.
+docs = RubyLLM.mcp(url: "https://learn.microsoft.com/api/mcp")
+
 class Analytics < RubyLLM::CodeMode
   mount    source: "data/input", dest: "/data",      description: "CSV files with the raw data (read only)"
   mount_rw source: "workspace",  dest: "/workspace", description: "Write generated reports and artifacts here"
+
+  tools Notes                   # one, several (`tools A, B`) or arrays (`tools [A, B]`)
+  mcps   docs                   # one, several (`mcps A, B`) or arrays — classes work too
 end
 
 chat = RubyLLM.chat
 chat.with_tools(Analytics)
-chat.ask "Compute the total sales per month from the CSVs in /data and save the report to /workspace/report.md"
+chat.ask "Compute the total sales per month from the CSVs in /data, save the " \
+         "report to /workspace/report.md, record the biggest finding in the " \
+         "notes log and check the Azure docs for the storage API you used"
 ```
 
 ### What the model sees
@@ -50,7 +70,7 @@ a fixed description built from the declared mounts:
 - a **Read-only folders** section listing each `mount` as `` `/guest/path` — description``;
 - a **Read-write folders** section listing each `mount_rw`;
 - a **Host tools** section listing every bound `RubyLLM::Tool` with its
-  parameters, when any are bound with `tool` or `mcp`.
+  parameters, when any are bound with `tools` or `mcps`.
 
 The single parameter is `code` — a complete, self-contained Ruby script.
 
@@ -70,9 +90,10 @@ A JSON object sent back to the model:
 ```ruby
 mount    source: host_path, dest: guest_path, description: "..."  # read-only
 mount_rw source: host_path, dest: guest_path, description: "..." # read-write
-tool     SomeRubyLLMTool                                          # host tool
-tool     "name" => SomeRubyLLMTool                                # explicit name
-mcp      SomeMcpServer                                            # MCP server (instance or class)
+tools    SomeRubyLLMTool                                          # host tool
+tools    SomeTool, OtherTool                                      # several (or arrays)
+tools    "name" => SomeRubyLLMTool                                # explicit name(s)
+mcps     SomeMcpServer                                            # MCP server(s) (instance or class)
 ```
 
 - `source:` — folder on the host machine, relative to the process working
@@ -80,12 +101,15 @@ mcp      SomeMcpServer                                            # MCP server (
 - `dest:` — absolute, normalized path inside the sandbox (may not overlap
   the reserved `/work`, `/usr` or `/src` trees, and must be unique).
 - `description:` — shown to the model in the tool description.
-- `tool` — a `RubyLLM::Tool` class or instance; the name inside the sandbox
-  is derived from the class-name leaf (`MyApp::Tools::Weather` → `weather`),
-  or the explicit one from the one-pair form.
-- `mcp` — a `RubyLLM::MCP` instance or class (auto-instantiated, with the
-  server's declared inputs as keywords); all of the server's tools are bound
-  under their own names.
+- `tools` — one or more `RubyLLM::Tool` classes/instances (or arrays of
+  them); the name inside the sandbox is derived from the class-name leaf
+  (`MyApp::Tools::Weather` → `weather`), or the explicit one from the
+  `"name" => tool` pairs. Called without arguments, it returns the bound
+  tools.
+- `mcps` — one or more `RubyLLM::MCP` instances or classes
+  (auto-instantiated, with the server's declared inputs as keywords); all of
+  each server's tools are bound under their own names. Called without
+  arguments, it returns the connected servers.
 
 Invalid declarations raise at class-definition time, so a misconfigured tool
 never reaches a live chat. Subclasses inherit their parent's mounts and tools.
@@ -107,8 +131,8 @@ end
 
 class Assistant < RubyLLM::CodeMode
   mount source: "data", dest: "/data", description: "Project data"
-  tool  Weather                 # binds as `weather`
-  tool  "forecast" => Weather   # or bind it under an explicit name
+  tools Weather                    # binds as `weather`
+  tools "forecast" => Weather      # or bind it under an explicit name
 end
 ```
 
@@ -136,7 +160,7 @@ report = SB.call("weather", city: "Porto Alegre")
 
 ### MCP servers
 
-The `mcp` DSL connects [RubyLLM::MCP](https://rubyllm.com/next/mcp/) servers
+The `mcps` DSL connects [RubyLLM::MCP](https://rubyllm.com/next/mcp/) servers
 and binds all their tools in one call, letting the sandboxed code reach the
 server through the host RPC channel:
 
@@ -144,9 +168,9 @@ server through the host RPC channel:
 docs = RubyLLM.mcp(url: "https://learn.microsoft.com/api/mcp")
 
 class DocsResearch < RubyLLM::CodeMode
-  mcp docs                       # instance
-  # mcp MicrosoftDocs            # or the class (instantiated with .new)
-  # mcp Linear, user: current_user  # class + the server's declared inputs
+  mcps docs                       # instance
+  # mcps MicrosoftDocs            # or the class (instantiated with .new)
+  # mcps Linear, user: current_user  # class + the server's declared inputs
 end
 ```
 
@@ -170,11 +194,41 @@ result[:error]      # => true when the tool reported a failure
   and raise at definition time.
 - The class form binds the tools of one instance built at definition time —
   for servers that act per-user, pass a ready instance instead
-  (`mcp Linear.new(user: current_user)`) where the user is available.
+  (`mcps Linear.new(user: current_user)`) where the user is available.
 
 The sandbox itself never sees the network — every `SB.call` performs the MCP
 request on the host. A runnable example lives in `sample/ruby_llm_mcp/`.
 
+### Per-instance tools and servers
+
+Class-level `tools`/`mcps` bind once for every instance of the class. When the
+same tool class needs a different toolset per chat — per-user credentials, a
+server list composed at runtime — bind additions on the instance instead:
+
+```ruby
+tool = Analytics.new
+tool.add_tools(UserSearch.new(user: current_user))   # ready instance (classes work too)
+tool.add_mcps(user_linear)                           # server instance, class or array
+
+chat = RubyLLM.chat
+chat.with_tools(tool)   # the description already includes the additions
+chat.ask "Search the docs and log the findings"
+tool.execute(code: 'SB.call("user_search", q: "...")')
+```
+
+- `add_tools` accepts the same forms as `tools`: classes, ready instances,
+  several at once, arrays and `"name" => tool` pairs. Names may not collide
+  with the class-level bindings or each other, and the 64-tool limit counts
+  both levels together.
+- `add_mcps` accepts the same forms as `mcps`; the servers' tools bind into
+  this instance only — other instances and the class itself are unaffected.
+- Both are all-or-nothing: on any failure nothing is bound.
+- The instance description includes the additions, so register the tool with
+  the chat after calling them.
+- The sandbox is configured on the first execution: after that,
+  `add_tools`/`add_mcps` raise — create a new instance instead. Instances
+  without additions share the class configuration.
+
 ### Sandbox limits
 
 Defaults: `timeout_ms: 30_000` (wall clock), `fuel_ms: 10_000` (CPU budget).

data/lib/ruby_llm/code_mode.rb

@@ -5,14 +5,14 @@ require "security_box"
 
 module RubyLLM
   class CodeMode < Tool
-    VERSION = "0.2.0"
+    VERSION = "0.4.0"
 
     DEFAULT_TIMEOUT_MS = 30_000
     DEFAULT_FUEL_MS = 10_000
     MAX_TOOLS = SecurityBox::Rpcs::MAX_RPCS
 
-    TOOL_USAGE = "tool expects a RubyLLM::Tool class or instance, " \
-                 'or exactly one "name" => tool pair'
+    TOOL_USAGE = "tools expects RubyLLM::Tool classes or instances, " \
+                 'or "name" => tool pairs'
 
     FIXED_DESCRIPTION = <<~DESC.freeze
       Executes Ruby code inside a secure sandbox and returns what it produced.
@@ -53,6 +53,221 @@ module RubyLLM
 
     McpEntry = Struct.new(:name, :mcp, :instructions, keyword_init: true)
 
+    # Shared registration and rendering core, parameterized by the target
+    # collections: the class-level DSL (tools/mcps) and the instance-level API
+    # (add_tools/add_mcps) run the exact same validation and rollback logic,
+    # only over different hashes/arrays.
+    module Registry
+      EMPTY = {}.freeze
+
+      class << self
+        # Binds tools into `target` (a name => ToolEntry hash). Accepts tool
+        # classes/instances, arrays of them, and "name" => tool pairs (hash
+        # arguments or kwargs). All-or-nothing: on any failure `target` is
+        # restored and the error re-raised. `reserved` lists names already
+        # taken elsewhere (e.g. the class-level bindings for instance
+        # additions); duplicates against it raise.
+        def register_tools(target, args, kwargs, reserved: EMPTY)
+          snapshot = target.dup
+          begin
+            args.flatten(1).each do |item|
+              if item.is_a?(Hash)
+                item.each { |name, bound| add_tool(target, bound, name.to_s, reserved) }
+              else
+                add_tool(target, item, nil, reserved)
+              end
+            end
+            kwargs.each { |name, bound| add_tool(target, bound, name.to_s, reserved) }
+          rescue StandardError
+            target.replace(snapshot)
+            raise
+          end
+          target
+        end
+
+        # Connects MCP server(s) and binds all their tools into
+        # `target_tools`/`target_mcps`. All-or-nothing across both
+        # collections.
+        def register_mcps(target_tools, target_mcps, servers, inputs, reserved: EMPTY)
+          snapshot_tools = target_tools.dup
+          snapshot_mcps = target_mcps.dup
+          flat = servers.flatten(1)
+          raise ArgumentError, "expected at least one RubyLLM::MCP server" if flat.empty?
+          unless inputs.empty? || flat.all?(Class)
+            raise ArgumentError, "inputs only apply when passing RubyLLM::MCP classes"
+          end
+
+          normalize_mcp_servers(flat, inputs).each do |server|
+            bind_mcp_server(target_tools, target_mcps, server, reserved)
+          end
+          target_mcps
+        rescue StandardError
+          target_tools.replace(snapshot_tools)
+          target_mcps.replace(snapshot_mcps)
+          raise
+        end
+
+        def rpc_handlers(tools)
+          tools.transform_values { |entry| ->(args) { call_bound_tool(entry, args) } }
+        end
+
+        def tools_section(tools)
+          return nil if tools.empty?
+
+          [
+            "## Host tools (call with SB.call)",
+            HOST_TOOLS_INTRO.rstrip,
+            *tools.values.flat_map { |entry| tool_lines(entry) }
+          ].join("\n")
+        end
+
+        def server_notes_section(mcps)
+          notes = mcps.filter_map do |entry|
+            instructions = entry.instructions.to_s
+            next if instructions.empty?
+
+            "- **#{entry.name}** — #{instructions}"
+          end
+          return nil if notes.empty?
+
+          ["## Server notes", *notes].join("\n")
+        end
+
+        private
+
+        def add_tool(target, bound, name, reserved)
+          instance = normalize_bound_tool(bound)
+          if instance.is_a?(RubyLLM::CodeMode)
+            raise ArgumentError, "cannot bind a RubyLLM::CodeMode inside another CodeMode"
+          end
+
+          name = (name || tool_binding_name(instance)).to_s
+          raise ArgumentError, "tool name must be a non-empty String" if name.empty?
+          if target.key?(name) || reserved.key?(name)
+            raise ArgumentError, "tool name #{name.inspect} is already bound"
+          end
+          total = target.size + reserved.size
+          if total >= MAX_TOOLS
+            raise ArgumentError, "too many tools (#{total + 1}); the limit is #{MAX_TOOLS}"
+          end
+
+          target[name] = ToolEntry.new(name: name, tool: instance)
+        end
+
+        def normalize_bound_tool(bound)
+          if bound.is_a?(Class)
+            unless bound <= RubyLLM::Tool
+              raise ArgumentError, "expected a RubyLLM::Tool (class or instance), got #{bound.inspect}"
+            end
+
+            bound.new
+          elsif bound.is_a?(RubyLLM::Tool)
+            bound
+          else
+            raise ArgumentError, "expected a RubyLLM::Tool (class or instance), got #{bound.inspect}"
+          end
+        end
+
+        # Leaf-only name derivation, like .tool_name — the guest has no use
+        # for the RubyLLM namespace ("MyApp::Tools::Search" binds as "search").
+        def leaf_tool_name(klass)
+          leaf = klass.name.to_s.split('::').last
+          return "" unless leaf
+
+          RubyLLM::Support::Utils.underscore(leaf).delete_suffix('_tool')
+        end
+
+        # Regular tools keep the leaf-only derivation; MCP tools carry their
+        # own (server) name, which is what they bind under inside the sandbox.
+        def tool_binding_name(instance)
+          return instance.name.to_s if instance.respond_to?(:server_name)
+
+          leaf_tool_name(instance.class)
+        end
+
+        def call_bound_tool(entry, args)
+          unless args.is_a?(Hash)
+            raise ArgumentError,
+                  "tool #{entry.name.inspect} expects a hash of arguments, got #{args.class}"
+          end
+
+          normalize_result(entry.tool.call(**args))
+        end
+
+        # MCP tools return RubyLLM::MCP::Result objects; SecurityBox JSON
+        # round-trips handler returns, so give the guest plain data instead
+        # of an inspect string.
+        def normalize_result(value)
+          return value unless defined?(RubyLLM::MCP::Result) && value.is_a?(RubyLLM::MCP::Result)
+
+          { text: value.text, structured: value.structured, error: value.error? }
+        end
+
+        def normalize_mcp_servers(servers, inputs)
+          unless defined?(RubyLLM::MCP)
+            raise ArgumentError,
+                  "RubyLLM::MCP is not available; mcps needs a ruby_llm version with MCP support"
+          end
+
+          servers.map do |server|
+            case server
+            when Class
+              unless server <= RubyLLM::MCP
+                raise ArgumentError, "expected a RubyLLM::MCP (class or instance), got #{server.inspect}"
+              end
+
+              server.new(**inputs)
+            when RubyLLM::MCP
+              server
+            else
+              raise ArgumentError, "expected a RubyLLM::MCP (class or instance), got #{server.inspect}"
+            end
+          end
+        end
+
+        def bind_mcp_server(target_tools, target_mcps, server, reserved)
+          # Fetching .tools connects to the server; snapshot the instructions
+          # right after, so description builds never touch the network.
+          tools_list = server.tools
+          target_mcps << McpEntry.new(
+            name: server.name.to_s, mcp: server, instructions: server.instructions.to_s
+          )
+          tools_list.each { |tool| bind_mcp_tool(target_tools, server, tool, reserved) }
+        end
+
+        def bind_mcp_tool(target_tools, server, tool, reserved)
+          name = tool_binding_name(tool)
+          if (target_tools.key?(name) || reserved.key?(name)) && !server.name.to_s.empty?
+            name = "#{server.name}_#{name}"
+          end
+          add_tool(target_tools, tool, name, reserved)
+        end
+
+        def tool_lines(entry)
+          line = "- `#{entry.name}`"
+          description = entry.tool.description.to_s
+          line += " — #{description}" unless description.empty?
+
+          [line, *param_lines(entry.tool).map { |param| "  #{param}" }]
+        end
+
+        def param_lines(tool)
+          schema = tool.parameters_schema || {}
+          properties = schema["properties"] || {}
+          required = schema["required"] || []
+
+          properties.filter_map do |param, spec|
+            spec ||= {}
+            status = required.include?(param) ? "required" : "optional"
+            line = "- `#{param}` (#{spec["type"] || "string"}, #{status})"
+            description = spec["description"].to_s
+            line += " — #{description}" unless description.empty?
+            line
+          end
+        end
+      end
+    end
+
     class << self
       def tool_name
         leaf = name.to_s.split('::').last
@@ -69,22 +284,24 @@ module RubyLLM
         add_mount(source, dest, :read_write, description)
       end
 
-      def tool(mapping = nil, **kwargs)
-        if !kwargs.empty?
-          raise ArgumentError, TOOL_USAGE unless kwargs.size == 1 && mapping.nil?
-
-          name, bound = kwargs.first
-          mapping = { name.to_s => bound }
-        end
-
-        if mapping.is_a?(Hash)
-          raise ArgumentError, TOOL_USAGE unless mapping.size == 1
-
-          name, bound = mapping.first
-          add_tool(bound, name.to_s)
-        else
-          add_tool(mapping, nil)
-        end
+      # Binds RubyLLM::Tool classes/instances as host tools callable from
+      # inside the sandbox via SB.call:
+      #
+      #   tools Weather                     # class (instantiated with .new)
+      #   tools Weather, Echo               # several at once
+      #   tools [Weather, Echo]             # or arrays
+      #   tools "forecast" => Weather       # explicit sandbox name
+      #   tools forecast: Weather           # same, as kwargs
+      #
+      # Without arguments it returns the hash of bound tools. The name is
+      # derived from the class-name leaf (`MyApp::Tools::Weather` binds as
+      # `weather`). Fails fast: every item must be a RubyLLM::Tool (class or
+      # instance), names must be unique and non-empty, and if anything goes
+      # wrong nothing is bound.
+      def tools(*args, **kwargs)
+        return @tools ||= {} if args.empty? && kwargs.empty?
+
+        Registry.register_tools(tools, args, kwargs)
       end
 
       # Connects MCP server(s) and binds all their tools into the sandbox:
@@ -92,66 +309,51 @@ module RubyLLM
       #   docs = RubyLLM.mcp(url: "https://learn.microsoft.com/api/mcp")
       #
       #   class DocsResearch < RubyLLM::CodeMode
-      #     mcp docs                    # instance
-      #     mcp MicrosoftDocs           # or the class (instantiated with .new)
-      #     mcp Linear, user: current_user  # class + declared inputs
-      #     mcp Docs, Github            # several servers / arrays at once
+      #     mcps docs                    # instance
+      #     mcps MicrosoftDocs           # or the class (instantiated with .new)
+      #     mcps Linear, user: current_user  # class + declared inputs
+      #     mcps Docs, Github            # several servers / arrays at once
       #   end
       #
-      # Server tools keep their names (`microsoft_docs_search`, ...); a tool
-      # whose name is already bound is re-bound as "<server>_tool". The
-      # servers' instructions (when the server sends them) are snapshotted
-      # at definition and listed in the description under "## Server notes".
+      # Without arguments it returns the array of connected servers. Server
+      # tools keep their names (`microsoft_docs_search`, ...); a tool whose
+      # name is already bound is re-bound as "<server>_tool". The servers'
+      # instructions (when the server sends them) are snapshotted at
+      # definition and listed in the description under "## Server notes".
       # Fails fast: every argument must be a RubyLLM::MCP (class or
       # instance), and if anything goes wrong — a server that cannot be
       # reached, a name that stays colliding after prefixing — nothing is
       # bound.
-      def mcp(*servers, **inputs)
-        flat = servers.flatten(1)
-        raise ArgumentError, "expected at least one RubyLLM::MCP server" if flat.empty?
-        unless inputs.empty? || flat.all?(Class)
-          raise ArgumentError, "inputs only apply when passing RubyLLM::MCP classes"
-        end
+      def mcps(*servers, **inputs)
+        return @mcps ||= [] if servers.empty? && inputs.empty?
 
-        snapshot_tools = tools.dup
-        snapshot_mcps = mcps.dup
-        normalize_mcp_servers(flat, inputs).each { |server| bind_mcp_server(server) }
-        mcps
-      rescue StandardError
-        instance_variable_set(:@tools, snapshot_tools)
-        instance_variable_set(:@mcps, snapshot_mcps)
-        raise
+        Registry.register_mcps(tools, mcps, servers, inputs)
       end
 
       def mounts
         @mounts ||= []
       end
 
-      def tools
-        @tools ||= {}
-      end
-
-      def mcps
-        @mcps ||= []
-      end
-
       def configuration
         @configuration ||= SecurityBox::Configuration.build(
           timeout_ms: DEFAULT_TIMEOUT_MS,
           fuel_ms: DEFAULT_FUEL_MS,
           mounts: mounts.map(&:payload),
-          rpcs: build_rpcs
+          rpcs: Registry.rpc_handlers(tools)
         )
       end
 
-      def build_description
+      # Builds the description the model sees. `extra_tools`/`extra_mcps`
+      # carry the per-instance additions (see #add_tools/#add_mcps); with no
+      # extras the output is identical to the class-level description.
+      def build_description(extra_tools: {}, extra_mcps: [])
         read_only, read_write = mounts.partition { |m| m.mode == :read_only }
         [
           FIXED_DESCRIPTION.rstrip,
           folder_section("## Read-only folders (readable, never writable)", read_only),
           folder_section("## Read-write folders (readable and writable)", read_write),
-          tools_section,
-          server_notes_section
+          Registry.tools_section(tools.merge(extra_tools)),
+          Registry.server_notes_section(mcps + extra_mcps)
         ].compact.join("\n\n")
       end
 
@@ -191,113 +393,6 @@ module RubyLLM
               "Invalid mount #{source.inspect} => #{dest.inspect}: #{e.message}"
       end
 
-      def add_tool(bound, name)
-        instance = normalize_bound_tool(bound)
-        if instance.is_a?(RubyLLM::CodeMode)
-          raise ArgumentError, "cannot bind a RubyLLM::CodeMode inside another CodeMode"
-        end
-
-        name = (name || tool_binding_name(instance)).to_s
-        raise ArgumentError, "tool name must be a non-empty String" if name.empty?
-        raise ArgumentError, "tool name #{name.inspect} is already bound" if tools.key?(name)
-        if tools.size >= MAX_TOOLS
-          raise ArgumentError, "too many tools (#{tools.size + 1}); the limit is #{MAX_TOOLS}"
-        end
-
-        tools[name] = ToolEntry.new(name: name, tool: instance)
-      end
-
-      def normalize_bound_tool(bound)
-        if bound.is_a?(Class)
-          unless bound <= RubyLLM::Tool
-            raise ArgumentError, "expected a RubyLLM::Tool (class or instance), got #{bound.inspect}"
-          end
-
-          bound.new
-        elsif bound.is_a?(RubyLLM::Tool)
-          bound
-        else
-          raise ArgumentError, "expected a RubyLLM::Tool (class or instance), got #{bound.inspect}"
-        end
-      end
-
-      # Leaf-only name derivation, like .tool_name — the guest has no use
-      # for the RubyLLM namespace ("MyApp::Tools::Search" binds as "search").
-      def leaf_tool_name(klass)
-        leaf = klass.name.to_s.split('::').last
-        return "" unless leaf
-
-        RubyLLM::Support::Utils.underscore(leaf).delete_suffix('_tool')
-      end
-
-      # Regular tools keep the leaf-only derivation; MCP tools carry their
-      # own (server) name, which is what they bind under inside the sandbox.
-      def tool_binding_name(instance)
-        return instance.name.to_s if instance.respond_to?(:server_name)
-
-        leaf_tool_name(instance.class)
-      end
-
-      def build_rpcs
-        tools.transform_values { |entry| ->(args) { call_bound_tool(entry, args) } }
-      end
-
-      def call_bound_tool(entry, args)
-        unless args.is_a?(Hash)
-          raise ArgumentError,
-                "tool #{entry.name.inspect} expects a hash of arguments, got #{args.class}"
-        end
-
-        normalize_result(entry.tool.call(**args))
-      end
-
-      # MCP tools return RubyLLM::MCP::Result objects; SecurityBox JSON
-      # round-trips handler returns, so give the guest plain data instead
-      # of an inspect string.
-      def normalize_result(value)
-        return value unless defined?(RubyLLM::MCP::Result) && value.is_a?(RubyLLM::MCP::Result)
-
-        { text: value.text, structured: value.structured, error: value.error? }
-      end
-
-      def normalize_mcp_servers(servers, inputs)
-        unless defined?(RubyLLM::MCP)
-          raise ArgumentError,
-                "RubyLLM::MCP is not available; mcp needs a ruby_llm version with MCP support"
-        end
-
-        servers.map do |server|
-          case server
-          when Class
-            unless server <= RubyLLM::MCP
-              raise ArgumentError, "expected a RubyLLM::MCP (class or instance), got #{server.inspect}"
-            end
-
-            server.new(**inputs)
-          when RubyLLM::MCP
-            server
-          else
-            raise ArgumentError, "expected a RubyLLM::MCP (class or instance), got #{server.inspect}"
-          end
-        end
-      end
-
-      def bind_mcp_server(server)
-        # Fetching .tools connects to the server; snapshot the instructions
-        # right after, so description builds never touch the network.
-        tools_list = server.tools
-        mcps << McpEntry.new(
-          name: server.name.to_s, mcp: server, instructions: server.instructions.to_s
-        )
-        tools_list.each { |tool| bind_mcp_tool(server, tool) }
-      end
-
-      def bind_mcp_tool(server, tool)
-        name = tool_binding_name(tool)
-        name = "#{server.name}_#{name}" if tools.key?(name) && !server.name.to_s.empty?
-        add_tool(tool, name)
-      end
-
       def folder_section(header, entries)
         return nil if entries.empty?
 
@@ -308,54 +403,37 @@ module RubyLLM
         end
         [header, *lines].join("\n")
       end
+    end
 
-      def tools_section
-        return nil if tools.empty?
-
-        [
-          "## Host tools (call with SB.call)",
-          HOST_TOOLS_INTRO.rstrip,
-          *tools.values.flat_map { |entry| tool_lines(entry) }
-        ].join("\n")
-      end
-
-      def server_notes_section
-        notes = mcps.filter_map do |entry|
-          instructions = entry.instructions.to_s
-          next if instructions.empty?
-
-          "- **#{entry.name}** — #{instructions}"
-        end
-        return nil if notes.empty?
-
-        ["## Server notes", *notes].join("\n")
-      end
-
-      def tool_lines(entry)
-        line = "- `#{entry.name}`"
-        description = entry.tool.description.to_s
-        line += " — #{description}" unless description.empty?
+    parameter :code, description: "Complete Ruby script to execute in the sandbox"
 
-        [line, *param_lines(entry.tool).map { |param| "  #{param}" }]
-      end
+    # Binds more host tools onto this specific instance, on top of the
+    # class-level ones. Accepts the same forms as the class-level .tools:
+    # classes, ready instances, several at once, arrays, and
+    # "name" => tool pairs (hash or kwargs). Instances of the same class are
+    # unaffected, and the additions show up in this instance's description,
+    # so chats built after the call expose them to the model. Fails fast and
+    # rolls everything back; once the first execution happened the sandbox is
+    # already built and further additions raise.
+    def add_tools(*args, **kwargs)
+      ensure_extendable!
+
+      Registry.register_tools(instance_tools, args, kwargs, reserved: self.class.tools)
+    end
 
-      def param_lines(tool)
-        schema = tool.parameters_schema || {}
-        properties = schema["properties"] || {}
-        required = schema["required"] || []
+    # Connects MCP server(s) onto this specific instance, on top of the
+    # class-level ones. Same forms and fail-fast semantics as .mcps
+    # (instances, classes with their declared inputs, arrays); the servers'
+    # tools bind into this instance only. Raises after the first execution.
+    def add_mcps(*servers, **inputs)
+      ensure_extendable!
 
-        properties.filter_map do |param, spec|
-          spec ||= {}
-          status = required.include?(param) ? "required" : "optional"
-          line = "- `#{param}` (#{spec["type"] || "string"}, #{status})"
-          description = spec["description"].to_s
-          line += " — #{description}" unless description.empty?
-          line
-        end
-      end
+      Registry.register_mcps(instance_tools, instance_mcps, servers, inputs, reserved: self.class.tools)
     end
 
-    parameter :code, description: "Complete Ruby script to execute in the sandbox"
+    def description
+      self.class.build_description(extra_tools: instance_tools, extra_mcps: instance_mcps)
+    end
 
     def execute(code:)
       format_result(sandbox.eval(code))
@@ -365,8 +443,38 @@ module RubyLLM
 
     private
 
+    def ensure_extendable!
+      return unless instance_variable_defined?(:@sandbox)
+
+      raise ArgumentError,
+            "cannot add tools or MCP servers after the first execution; " \
+            "create a new #{self.class.name} instance instead"
+    end
+
+    def instance_tools
+      @instance_tools ||= {}
+    end
+
+    def instance_mcps
+      @instance_mcps ||= []
+    end
+
+    # Instances without additions share the class configuration; instances
+    # with additions build their own, merging the class rpcs with the
+    # instance ones (names cannot collide — the registrations validate that).
+    def configuration
+      return self.class.configuration if instance_tools.empty? && instance_mcps.empty?
+
+      @configuration ||= SecurityBox::Configuration.build(
+        timeout_ms: DEFAULT_TIMEOUT_MS,
+        fuel_ms: DEFAULT_FUEL_MS,
+        mounts: self.class.mounts.map(&:payload),
+        rpcs: self.class.configuration.rpcs.merge(Registry.rpc_handlers(instance_tools))
+      )
+    end
+
     def sandbox
-      @sandbox ||= SecurityBox::Sandbox.new(self.class.configuration)
+      @sandbox ||= SecurityBox::Sandbox.new(configuration)
     end
 
     def format_result(result)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-code_mode
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Juneira