llm.rb 6.1.0 → 8.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57b39b3b4b79d1d9f8cfd10426ad233d698dd6e3ed84bfef887c8c63f543f40f
-  data.tar.gz: 443ed7e2a04259c69d41b1da7a42e7637efaa4ab1075548706ce349bced7ed51
+  metadata.gz: 4d726213f6b63342582738a133f7f82c1158934d6f25a48ae6b6c9e59a8f8262
+  data.tar.gz: 6288d177adc7a07a37368066329c882f746747d5bed9ffba7cb50d2bcbd1d98c
 SHA512:
-  metadata.gz: f8e53dc41eacf16cea35f64a6048aa77852fcf7a135676b2b9c02e37beff174b5a500948477c4f931ff0a71d20c4503ba3e9eef19358d3aaa204040e77fe14c5
-  data.tar.gz: 358ce7f33d2dca51365f6581867006970fd66079dcaa189268e2deff2f297c89b8332fd11b714bedfd89124413b7a9e12fc09d928c2c28f2e9cb2368f2bc3e24
+  metadata.gz: 4ae089f4117dc384000a70500c40ebadf48f42d1bd820d0840568b3b31b0197e51c65e9f60fe65d0e75c23aa4c7eac977be928a38969580174169bd0efe39912
+  data.tar.gz: 9653135f93b9b2b722102f055dc961346949368dab161a3cff64e99ddfc6781933a94b527151da9a24ff39451814f76c5409389f91c3692852eb17bd5d3d11f9

data/CHANGELOG.md

@@ -1,5 +1,135 @@
 # Changelog
 
+## Unreleased
+
+## v8.0.0
+
+Changes since `v7.0.0`.
+
+This release adds Unix-fork concurrency for process-isolated tool
+execution, extends `LLM::Object` with `#merge` and `#delete`, and drops
+Ruby 3.2 support due to segfaults observed with the `:fork` path. It
+promotes `LLM::Pipe` to the top-level namespace and adds
+`persistent: true` on `LLM::MCP.http` for direct persistent transport
+configuration. `LLM::Function#runner` is exposed as public API, agent
+tracer overrides are supported, fiber execution now uses `Fiber.schedule`,
+missing optional dependencies raise clearer `LLM::LoadError` guidance,
+and ActiveRecord wrapper plumbing is deduplicated between `acts_as_llm`
+and `acts_as_agent`.
+
+### Breaking
+
+* **Drop Ruby 3.2 support** <br>
+  Stop supporting Ruby 3.2 due to a segfault observed with the `:fork`
+  tool concurrency strategy.
+
+### Add
+
+* **Add `LLM::Object#merge`** <br>
+  Let `LLM::Object` return a new wrapped object when merging hash-like
+  data through `#merge`.
+
+* **Add `LLM::Object#delete`** <br>
+  Let `LLM::Object` delete keys directly through `#delete`.
+
+### Change
+
+* **Add fork-based tool concurrency** <br>
+  Add `:fork` as a new concurrency strategy for `LLM::Function#spawn`,
+  `LLM::Function::Array#wait`, and `LLM::Agent.concurrency` that runs
+  class-based tools in isolated child processes. Fork-backed tools support
+  tracer callbacks, `on_interrupt`/`on_cancel` hooks, and `alive?` checks.
+  Requires the `xchan` gem for inter-process communication with `:fork`.
+  This is especially useful for tools that need process isolation, such as
+  running shell commands or handling unsafe data.
+
+* **Promote `LLM::Pipe` from MCP namespace to top-level** <br>
+  Move `LLM::MCP::Pipe` to `LLM::Pipe` so the pipe abstraction is available
+  outside MCP internals. The new class adds a `binmode:` option for binary
+  pipes. `LLM::MCP::Command` and related MCP transport code have been updated
+  to use `LLM::Pipe`.
+
+* **Allow `persistent: true` on `LLM::MCP.http`** <br>
+  Let `LLM::MCP.http(...)` enable persistent HTTP transport directly
+  through `persistent: true`, instead of requiring a separate
+  `.persistent` call after construction.
+
+* **Expose `LLM::Function#runner` as public API** <br>
+  Promote the internal runner instantiation to a public `runner` method on
+  `LLM::Function`, so callers can inspect or reuse the resolved tool instance
+  that a function wraps.
+
+* **Allow agent instance tracer overrides** <br>
+  Let `LLM::Agent.new(..., tracer: ...)` override the class-level tracer
+  for that agent instance.
+
+* **Make `:fiber` use scheduler-backed fibers** <br>
+  Change `:fiber` tool execution to use `Fiber.schedule` and require
+  `Fiber.scheduler`, instead of wrapping direct calls in raw fibers. This
+  gives `:fiber` a real cooperative concurrency model instead of acting as
+  a thin wrapper around sequential execution.
+
+* **Read stored values from zero-argument `LLM::Object` method calls** <br>
+  Let calls like `obj.delete`, `obj.fetch`, `obj.merge`, `obj.key?`,
+  `obj.dig`, `obj.slice`, or `obj.keys` return a stored value when that
+  method name exists as a key and no arguments are given.
+
+* **Harden `LLM::Object` against arbitrary key names** <br>
+  Move internal lookup logic off `LLM::Object` instances and onto the
+  singleton class instead, making stored keys like `method_missing`
+  more resilient while preserving normal dynamic field access.
+
+* **Deduplicate ActiveRecord wrapper plumbing** <br>
+  Move shared ActiveRecord wrapper defaults and utility methods into
+  `LLM::ActiveRecord`, reducing duplication between `acts_as_llm` and
+  `acts_as_agent`.
+
+* **Raise clearer errors for missing optional runtime dependencies** <br>
+  Route optional `async`, `xchan`, and `net/http/persistent` loads
+  through `LLM.require` so missing runtime gems raise `LLM::LoadError`
+  with installation guidance instead of leaking raw `LoadError`
+  exceptions.
+
+### Fix
+
+* **Avoid `RuntimeError` from `Async::Task.current` lookups** <br>
+  Check `Async::Task.current?` before reading the current Async task so
+  provider transports fall back to `Fiber.current` without raising when
+  no Async task is active.
+
+* **Serialize `LLM::Object` values correctly through `LLM.json`** <br>
+  Make `LLM::Object#to_json` call `LLM.json.dump(to_h, ...)` so
+  `LLM::Object` values serialize through the llm.rb JSON adapter.
+
+## v7.0.0
+
+Changes since `v6.1.0`.
+
+This release turns agent tool-loop limit errors into in-band advisory
+returns so the LLM can react to rate limits and continue the loop. It
+adds `tool_attempts: nil` as a way to opt out of advisory tool-limit
+returns entirely, and fixes the default provider HTTP path to keep
+`net-http-persistent` optional when not explicitly enabled.
+
+### Breaking
+
+* **Return in-band tool-loop limit errors from agents** <br>
+  Stop raising `LLM::ToolLoopError` when an agent exhausts its tool loop
+  attempt budget, and instead send advisory `LLM::Function::Return`
+  errors back through the model so the LLM can react to the rate limit
+  in-band and continue the loop.
+
+* **Allow `tool_attempts: nil` to disable advisory tool-limit returns** <br>
+  Keep the default `tool_attempts` budget at `25`, but treat an explicit
+  `tool_attempts: nil` as an opt-out that disables advisory tool-limit
+  returns entirely.
+
+### Fix
+
+* **Keep `net-http-persistent` optional on normal HTTP requests** <br>
+  Stop the default provider HTTP path from loading `net/http/persistent`
+  unless persistent transport support is explicitly enabled.
+
 ## v6.1.0
 
 Changes since `v6.0.0`.
@@ -90,6 +220,12 @@ and `LLM::RactorError` is raised for unsupported ractor tool work.
   for unsupported tool types such as skill-backed tools, instead of letting
   deeper Ruby isolation errors leak out later in execution.
 
+* **Delegate interrupt to concurrent task implementations** <br>
+  Make `LLM::Function::Task#interrupt!` delegate to the underlying fork or
+  ractor task when it supports interruption, so `ctx.interrupt!` and
+  `task.interrupt!` work correctly for fork- and ractor-backed tool
+  execution.
+
 ## v5.4.0
 
 Changes since `v5.3.0`.
@@ -797,7 +933,7 @@ Changes since `v4.9.0`.
 
 - Add HTTP transport for MCP with `LLM::MCP::Transport::HTTP` for remote servers
 - Add JSON Schema union types (`any_of`, `all_of`, `one_of`) with parser integration
-- Add JSON Schema type array union support (e.g., `"type": ["object", "null"]`)
+- Add JSON Schema type array union support (e.g., `"type\": [\"object\", \"null\"]`)
 - Add JSON Schema type inference from `const`, `enum`, or `default` fields
 
 ### Change

data/README.md

@@ -4,7 +4,7 @@
 <p align="center">
   <a href="https://0x1eef.github.io/x/llm.rb?rebuild=1"><img src="https://img.shields.io/badge/docs-0x1eef.github.io-blue.svg" alt="RubyDoc"></a>
   <a href="https://opensource.org/license/0bsd"><img src="https://img.shields.io/badge/License-0BSD-orange.svg?" alt="License"></a>
-  <a href="https://github.com/llmrb/llm.rb/tags"><img src="https://img.shields.io/badge/version-6.1.0-green.svg?" alt="Version"></a>
+  <a href="https://github.com/llmrb/llm.rb/tags"><img src="https://img.shields.io/badge/version-8.0.0-green.svg?" alt="Version"></a>
 </p>
 
 ## About
@@ -24,6 +24,11 @@ It provides one runtime for providers, agents, tools, skills, MCP servers, strea
 schemas, files, and persisted state, so real systems can be built out of one coherent
 execution model instead of a pile of adapters.
 
+It provides concurrent tool execution with multiple strategies exposed through a single
+runtime: async-task, threads, fibers, ractors and processes (fork). The first three are
+good for IO-bound work and the last two are good for CPU-bound work. Ractor support is
+experimental and comes with limitations.
+
 Want to see some code? Jump to [the examples](#examples) section. <br>
 Want to see a self-hosted LLM environment built on llm.rb? Check out [Relay](https://github.com/llmrb/relay).
 
@@ -287,8 +292,13 @@ end
 #### Concurrency
 
 Tool execution can run sequentially with `:call` or concurrently through
-`:thread`, `:task`, `:fiber`, and experimental `:ractor`, without rewriting
-your tool layer.
+`:thread`, `:task`, `:fiber`, `:fork`, and experimental `:ractor`, without
+rewriting your tool layer. Async tasks, threads, and fibers are the
+I/O-bound options. Fork and ractor are the CPU-bound options. `:fork`
+requires [`xchan.rb`](https://github.com/0x1eef/xchan.rb#readme) support,
+and `:ractor` is still experimental.
+
+`:fiber` uses `Fiber.schedule`, so it requires `Fiber.scheduler`.
 
 ```ruby
 class Agent < LLM::Agent
@@ -311,8 +321,9 @@ finer sequential control across several steps before shutting the client down.
 ```ruby
 mcp = LLM::MCP.http(
   url: "https://api.githubcopilot.com/mcp/",
-  headers: {"Authorization" => "Bearer #{ENV["GITHUB_PAT"]}"}
-).persistent
+  headers: {"Authorization" => "Bearer #{ENV["GITHUB_PAT"]}"},
+  persistent: true
+)
 mcp.run do
   ctx = LLM::Context.new(llm, tools: mcp.tools)
 end
@@ -367,9 +378,13 @@ worker.join
   Use `LLM::Agent` when you want the same stateful runtime surface as
   `LLM::Context`, but with tool loops executed automatically according to a
   configured concurrency mode such as `:call`, `:thread`, `:task`, `:fiber`,
-  or experimental `:ractor` support for class-based tools. MCP tools are not
-  supported by the current `:ractor` mode, but mixed tool sets can still
-  route MCP tools and local tools through different strategies at runtime.
+  `:fork`, or experimental `:ractor` support for class-based tools. MCP tools
+  are not supported by the current `:ractor` mode, but mixed tool sets can
+  still route MCP tools and local tools through different strategies at
+  runtime. By default, the tool attempt budget is `25`. When an agent
+  exhausts that budget, it sends advisory tool errors back through the model
+  instead of raising out of the runtime. Set `tool_attempts: nil` to disable
+  that advisory behavior.
 - **Tool calls have an explicit lifecycle** <br>
   A tool call can be executed, cancelled through
   [`LLM::Function#cancel`](https://0x1eef.github.io/x/llm.rb/LLM/Function.html#cancel-instance_method),
@@ -381,13 +396,15 @@ worker.join
   [`LLM::Context#cancel!`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html#cancel-21-instance_method)
   is inspired by Go's context cancellation model.
 - **Concurrency is a first-class feature** <br>
-  Use threads, fibers, async tasks, or experimental ractors without
-  rewriting your tool layer. The current `:ractor` mode is for class-based
-  tools and does not support MCP tools, but mixed workloads can branch on
-  `tool.mcp?` and choose a supported strategy per tool. Class-based
-  `:ractor` tools still emit normal tool tracer callbacks. `:ractor` is
-  especially useful for CPU-bound tools, while `:task`, `:fiber`, or
-  `:thread` may be a better fit for I/O-bound work.
+  Use async tasks, threads, fibers, forks, or experimental ractors without
+  rewriting your tool layer. Async tasks, threads, and fibers are the
+  I/O-bound options. Fork and ractor are the CPU-bound options. `:fork`
+  requires [`xchan.rb`](https://github.com/0x1eef/xchan.rb#readme) support.
+  The current `:ractor` mode is for class-based tools, and MCP tools are
+  not supported by ractor, but mixed workloads can branch on `tool.mcp?`
+  and choose a supported strategy per tool. Class-based `:ractor` tools
+  still emit normal tool tracer callbacks. `:fiber` uses `Fiber.schedule`,
+  so it requires `Fiber.scheduler`.
 - **Advanced workloads are built in, not bolted on** <br>
   Streaming, concurrent tool execution, persistence, tracing, and MCP support
   all fit the same runtime model.
@@ -625,7 +642,7 @@ This example uses [`LLM::Context`](https://0x1eef.github.io/x/llm.rb/LLM/Context
 [`LLM::Stream`](https://0x1eef.github.io/x/llm.rb/LLM/Stream.html) together so
 long-lived contexts can summarize older history and expose the lifecycle
 through stream hooks. This approach is inspired by General Intelligence
-Systems' [Brute](https://github.com/general-intelligence-systems/brute). The
+Systems. The
 compactor can also use its own `model:` if you want summarization to run on a
 different model from the main context. `token_threshold:` accepts either a
 fixed token count or a percentage string like `"90%"`, which resolves
@@ -861,8 +878,9 @@ require "net/http/persistent"
 llm = LLM.openai(key: ENV["KEY"])
 mcp = LLM::MCP.http(
   url: "https://api.githubcopilot.com/mcp/",
-  headers: {"Authorization" => "Bearer #{ENV["GITHUB_PAT"]}"}
-).persistent
+  headers: {"Authorization" => "Bearer #{ENV["GITHUB_PAT"]}"},
+  persistent: true
+)
 
 mcp.start
 ctx = LLM::Context.new(llm, stream: $stdout, tools: mcp.tools)
@@ -876,8 +894,9 @@ For scoped work, `mcp.run do ... end` is shorter and handles cleanup for you:
 ```ruby
 mcp = LLM::MCP.http(
   url: "https://api.githubcopilot.com/mcp/",
-  headers: {"Authorization" => "Bearer #{ENV["GITHUB_PAT"]}"}
-).persistent
+  headers: {"Authorization" => "Bearer #{ENV["GITHUB_PAT"]}"},
+  persistent: true
+)
 mcp.run do
   ctx = LLM::Context.new(llm, stream: $stdout, tools: mcp.tools)
   ctx.talk("Pull information about my GitHub account.")

data/lib/llm/active_record/acts_as_agent.rb

@@ -10,10 +10,6 @@ module LLM::ActiveRecord
   # tools, schema, instructions, and concurrency are configured on the model
   # class and forwarded to an internal agent subclass.
   module ActsAsAgent
-    EMPTY_HASH = LLM::ActiveRecord::ActsAsLLM::EMPTY_HASH
-    DEFAULTS = LLM::ActiveRecord::ActsAsLLM::DEFAULTS
-    Utils = LLM::ActiveRecord::ActsAsLLM::Utils
-
     module ClassMethods
       def model(model = nil)
         return agent.model if model.nil?
@@ -96,7 +92,7 @@ module LLM::ActiveRecord
       def llm
         options = self.class.llm_plugin_options
         return @llm if @llm
-        @llm = Utils.resolve_provider(self, options, ActsAsAgent::EMPTY_HASH)
+        @llm = Utils.resolve_provider(self, options, EMPTY_HASH)
         @llm.tracer = Utils.resolve_option(self, options[:tracer]) if options[:tracer]
         @llm
       end
@@ -108,7 +104,7 @@ module LLM::ActiveRecord
       def ctx
         @ctx ||= begin
           options = self.class.llm_plugin_options
-          params = Utils.resolve_options(self, options[:context], ActsAsAgent::EMPTY_HASH).dup
+          params = Utils.resolve_options(self, options[:context], EMPTY_HASH).dup
           ctx = self.class.agent.new(llm, params.compact)
           columns = Utils.columns(options)
           data = self[columns[:data_column]]

data/lib/llm/active_record/acts_as_llm.rb

@@ -16,84 +16,6 @@ module LLM::ActiveRecord
   # handling JSON typecasting for the model. `provider:`, `context:`, and
   # `tracer:` can also be configured as symbols that are called on the model.
   module ActsAsLLM
-    EMPTY_HASH = {}.freeze
-    DEFAULTS = {
-      data_column: :data,
-      format: :string,
-      tracer: nil,
-      provider: nil,
-      context: EMPTY_HASH
-    }.freeze
-
-    ##
-    # Shared helper methods for the ORM wrapper.
-    #
-    # These utilities keep persistence plumbing out of the wrapped model's
-    # method namespace so the injected surface stays focused on the runtime
-    # API itself.
-    # @api private
-    module Utils
-      ##
-      # Resolves a single configured option against a model instance.
-      # @return [Object]
-      def self.resolve_option(obj, option)
-        case option
-        when Proc then obj.instance_exec(&option)
-        when Symbol then obj.send(option)
-        when Hash then option.dup
-        else option
-        end
-      end
-
-      ##
-      # Resolves hash-like wrapper options against a model instance.
-      # @return [Hash]
-      def self.resolve_options(obj, option, empty_hash)
-        case option
-        when Proc, Symbol, Hash then resolve_option(obj, option)
-        else empty_hash.dup
-        end
-      end
-
-      ##
-      # Serializes the runtime into the configured storage format.
-      # @return [String, Hash]
-      def self.serialize_context(ctx, format)
-        case format
-        when :string then ctx.to_json
-        when :json, :jsonb then ctx.to_h
-        else raise ArgumentError, "Unknown format: #{format.inspect}"
-        end
-      end
-
-      ##
-      # Maps wrapper options onto the record's storage columns.
-      # @return [Hash]
-      def self.columns(options)
-        {
-          data_column: options[:data_column]
-        }.freeze
-      end
-
-      ##
-      # Resolves the provider runtime for a record.
-      # @return [LLM::Provider]
-      def self.resolve_provider(obj, options, empty_hash)
-        provider = resolve_option(obj, options[:provider])
-        return provider if LLM::Provider === provider
-        raise ArgumentError, "provider: must resolve to an LLM::Provider instance"
-      end
-
-      ##
-      # Persists the runtime state and usage columns back onto the record.
-      # @return [void]
-      def self.save(obj, ctx, options)
-        columns = self.columns(options)
-        obj.assign_attributes(columns[:data_column] => serialize_context(ctx, options[:format]))
-        obj.save!
-      end
-    end
-
     module Hooks
       ##
       # Called when hooks are extended onto an ActiveRecord model.
@@ -133,7 +55,7 @@ module LLM::ActiveRecord
       # @return [LLM::Response]
       def talk(...)
         options = self.class.llm_plugin_options
-        ctx.talk(...).tap { Utils.save(self, ctx, options) }
+        ctx.talk(...).tap { Utils.save!(self, ctx, options) }
       end
 
       ##
@@ -142,7 +64,7 @@ module LLM::ActiveRecord
       # @return [LLM::Response]
       def respond(...)
         options = self.class.llm_plugin_options
-        ctx.respond(...).tap { Utils.save(self, ctx, options) }
+        ctx.respond(...).tap { Utils.save!(self, ctx, options) }
       end
 
       ##
@@ -270,7 +192,7 @@ module LLM::ActiveRecord
       def llm
         options = self.class.llm_plugin_options
         return @llm if @llm
-        @llm = Utils.resolve_provider(self, options, ActsAsLLM::EMPTY_HASH)
+        @llm = Utils.resolve_provider(self, options, EMPTY_HASH)
         @llm.tracer = Utils.resolve_option(self, options[:tracer]) if options[:tracer]
         @llm
       end
@@ -283,7 +205,7 @@ module LLM::ActiveRecord
         @ctx ||= begin
           options = self.class.llm_plugin_options
           columns = Utils.columns(options)
-          params = Utils.resolve_options(self, options[:context], ActsAsLLM::EMPTY_HASH).dup
+          params = Utils.resolve_options(self, options[:context], EMPTY_HASH).dup
           ctx = LLM::Context.new(llm, params.compact)
           data = self[columns[:data_column]]
           if data.nil? || data == ""

data/lib/llm/active_record.rb

@@ -1,4 +1,82 @@
 # frozen_string_literal: true
 
-require "llm/active_record/acts_as_llm"
-require "llm/active_record/acts_as_agent"
+module LLM::ActiveRecord
+  EMPTY_HASH = {}.freeze
+  DEFAULTS = {
+    data_column: :data,
+    format: :string,
+    tracer: nil,
+    provider: nil,
+    context: EMPTY_HASH
+  }.freeze
+
+  ##
+  # These utilities keep persistence plumbing out of the wrapped model's
+  # method namespace so the injected surface stays focused on the runtime
+  # API itself.
+  # @api private
+  module Utils
+    ##
+    # Resolves a single configured option against a model instance.
+    # @return [Object]
+    def self.resolve_option(obj, option)
+      case option
+      when Proc then obj.instance_exec(&option)
+      when Symbol then obj.send(option)
+      when Hash then option.dup
+      else option
+      end
+    end
+
+    ##
+    # Resolves hash-like wrapper options against a model instance.
+    # @return [Hash]
+    def self.resolve_options(obj, option, empty_hash)
+      case option
+      when Proc, Symbol, Hash then resolve_option(obj, option)
+      else empty_hash.dup
+      end
+    end
+
+    ##
+    # Serializes the runtime into the configured storage format.
+    # @return [String, Hash]
+    def self.serialize_context(ctx, format)
+      case format
+      when :string then ctx.to_json
+      when :json, :jsonb then ctx.to_h
+      else raise ArgumentError, "Unknown format: #{format.inspect}"
+      end
+    end
+
+    ##
+    # Maps wrapper options onto the record's storage columns.
+    # @return [Hash]
+    def self.columns(options)
+      {
+        data_column: options[:data_column]
+      }.freeze
+    end
+
+    ##
+    # Resolves the provider runtime for a record.
+    # @return [LLM::Provider]
+    def self.resolve_provider(obj, options, empty_hash)
+      provider = resolve_option(obj, options[:provider])
+      return provider if LLM::Provider === provider
+      raise ArgumentError, "provider: must resolve to an LLM::Provider instance"
+    end
+
+    ##
+    # Persists the runtime state and usage columns back onto the record.
+    # @return [void]
+    def self.save!(obj, ctx, options)
+      columns = self.columns(options)
+      obj.assign_attributes(columns[:data_column] => serialize_context(ctx, options[:format]))
+      obj.save!
+    end
+  end
+
+  require "llm/active_record/acts_as_llm"
+  require "llm/active_record/acts_as_agent"
+end

data/lib/llm/agent.rb

@@ -19,6 +19,9 @@ module LLM
   # * The automatic tool loop enables the wrapped context's `guard` by default.
   #   The built-in {LLM::LoopGuard LLM::LoopGuard} detects repeated tool-call
   #   patterns and blocks stuck execution before more tool work is queued.
+  # * The default tool attempt budget is `25`. After that, the agent sends
+  #   advisory tool errors back through the model and keeps the loop in-band.
+  #   Set `tool_attempts: nil` to disable that advisory behavior.
   # * Tool loop execution can be configured with `concurrency :call`,
   #   `:thread`, `:task`, `:fiber`, `:ractor`, or a list of queued task
   #   types such as `[:thread, :ractor]`.
@@ -103,7 +106,8 @@ module LLM
     #  - `:call`: sequential calls
     #  - `:thread`: concurrent threads
     #  - `:task`: concurrent async tasks
-    #  - `:fiber`: concurrent raw fibers
+    #  - `:fiber`: concurrent scheduler-backed fibers
+    #  - `:fork`: forked child processes
     #  - `:ractor`: concurrent Ruby ractors for class-based tools; MCP tools are not supported,
     #    and this mode is especially useful for CPU-bound tool work
     #  - `[:thread, :ractor]`: the possible concurrency strategies to wait on, in the
@@ -146,12 +150,14 @@ module LLM
     # @option params [Array<LLM::Function>, nil] :tools Defaults to nil
     # @option params [Array<String>, nil] :skills Defaults to nil
     # @option params [#to_json, nil] :schema Defaults to nil
+    # @option params [LLM::Tracer, Proc, nil] :tracer Optional tracer override for this agent instance
     # @option params [Symbol, Array<Symbol>, nil] :concurrency Defaults to the agent class concurrency
     def initialize(llm, params = {})
       defaults = {model: self.class.model, tools: self.class.tools, skills: self.class.skills, schema: self.class.schema}.compact
       @concurrency = params.delete(:concurrency) || self.class.concurrency
       @llm = llm
-      @tracer = resolve_option(self.class.tracer) unless self.class.tracer.nil?
+      tracer = params.key?(:tracer) ? params.delete(:tracer) : self.class.tracer
+      @tracer = resolve_option(tracer) unless tracer.nil?
       @ctx = LLM::Context.new(llm, defaults.merge({guard: true}).merge(params))
     end
 
@@ -161,7 +167,10 @@ module LLM
     #
     # @param prompt (see LLM::Provider#complete)
     # @param [Hash] params The params passed to the provider, including optional :stream, :tools, :schema etc.
-    # @option params [Integer] :tool_attempts The maxinum number of tool call iterations (default 25)
+    # @option params [Integer] :tool_attempts
+    #  The maxinum number of tool call iterations before the agent sends
+    #  in-band advisory tool errors back through the model (default 25).
+    #  Set to `nil` to disable advisory tool-limit returns.
     # @return [LLM::Response] Returns the LLM's response for this turn.
     # @example
     #   llm = LLM.openai(key: ENV["KEY"])
@@ -180,7 +189,10 @@ module LLM
     # @note Not all LLM providers support this API
     # @param prompt (see LLM::Provider#complete)
     # @param [Hash] params The params passed to the provider, including optional :stream, :tools, :schema etc.
-    # @option params [Integer] :tool_attempts The maxinum number of tool call iterations (default 25)
+    # @option params [Integer] :tool_attempts
+    #  The maxinum number of tool call iterations before the agent sends
+    #  in-band advisory tool errors back through the model (default 25).
+    #  Set to `nil` to disable advisory tool-limit returns.
     # @return [LLM::Response] Returns the LLM's response for this turn.
     # @example
     #   llm = LLM.openai(key: ENV["KEY"])
@@ -386,27 +398,46 @@ module LLM
     def call_functions
       case concurrency || :call
       when :call then call(:functions)
-      when :thread, :task, :fiber, :ractor, Array then wait(concurrency)
-      else raise ArgumentError, "Unknown concurrency: #{concurrency.inspect}. Expected :call, :thread, :task, :fiber, :ractor, or an array of queued task types"
+      when :thread, :task, :fiber, :fork, :ractor, Array then wait(concurrency)
+      else raise ArgumentError, "Unknown concurrency: #{concurrency.inspect}. " \
+                                "Expected :call, :thread, :task, :fiber, :fork, :ractor, " \
+                                "or an array of the mentioned options"
       end
     end
 
     def run_loop(method, prompt, params)
       loop = proc do
-        max = Integer(params.delete(:tool_attempts) || 25)
+        max = params.key?(:tool_attempts) ? params.delete(:tool_attempts) : 25
+        max = Integer(max) if max
         stream = params[:stream] || @ctx.params[:stream]
         stream.extra[:concurrency] = concurrency if LLM::Stream === stream
         res = @ctx.public_send(method, apply_instructions(prompt), params)
-        max.times do
+        loop do
           break if @ctx.functions.empty?
-          res = @ctx.public_send(method, call_functions, params)
+          if max
+            max.times do
+              break if @ctx.functions.empty?
+              res = @ctx.public_send(method, call_functions, params)
+            end
+            break if @ctx.functions.empty?
+            res = @ctx.public_send(method, @ctx.functions.map { rate_limit(_1) }, params)
+          else
+            res = @ctx.public_send(method, call_functions, params)
+          end
         end
-        raise LLM::ToolLoopError, "pending tool calls remain" unless @ctx.functions.empty?
         res
       end
       @tracer ? @llm.with_tracer(@tracer, &loop) : loop.call
     end
 
+    def rate_limit(function)
+      LLM::Function::Return.new(function.id, function.name, {
+        error: true,
+        type: LLM::ToolLoopError.name,
+        message: "tool loop rate limit reached"
+      })
+    end
+
     def resolve_option(option)
       Proc === option ? instance_exec(&option) : option
     end

data/lib/llm/compactor.rb

@@ -5,8 +5,7 @@
 # smaller replacement message when a context grows too large.
 #
 # This work is directly inspired by the compaction approach developed by
-# General Intelligence Systems in
-# [Brute](https://github.com/general-intelligence-systems/brute).
+# General Intelligence Systems.
 #
 # The compactor can also use a different model from the main context by
 # setting `model:` in the compactor config. Compaction thresholds are opt-in:

data/lib/llm/context.rb

@@ -96,8 +96,7 @@ module LLM
     ##
     # Returns a context compactor
     # This feature is inspired by the compaction approach developed by
-    # General Intelligence Systems in
-    # [Brute](https://github.com/general-intelligence-systems/brute).
+    # General Intelligence Systems.
     # @return [LLM::Compactor]
     def compactor
       @compactor = LLM::Compactor.new(self, @compactor || {}) unless LLM::Compactor === @compactor

data/lib/llm/error.rb

@@ -78,4 +78,8 @@ module LLM
   ##
   # When {LLM::Registry} can't map a registry
   NoSuchRegistryError = Class.new(Error)
+
+  ##
+  # When an optional runtime dependency cannot be required
+  LoadError = Class.new(Error)
 end