llm.rb 7.0.0 → 8.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c923952039095a2234eb1bd5c058a951b0d797d27577cdf7f679df59b49060b
-  data.tar.gz: 3667e0d79e44634f769dfced198dd07c1039f173cb43b72aab7d3204aa3638f8
+  metadata.gz: 4d726213f6b63342582738a133f7f82c1158934d6f25a48ae6b6c9e59a8f8262
+  data.tar.gz: 6288d177adc7a07a37368066329c882f746747d5bed9ffba7cb50d2bcbd1d98c
 SHA512:
-  metadata.gz: 655d450b2ffeb71ed9564b7c5c23a2a86e9e385de9dc1abdac18588e460cffdecd1b2da1d5ef9fc162dc3f3286b7d2c979baec3953cd1ddbdab74d1ef5b87112
-  data.tar.gz: a044fedb675c4d92eff55c210d588b68b80c7e3967188674c2de4d8f6bc69d76e8f15c18f49fb54e09a8c93dff89074304d231609337bfa3bc79c96e1f3f576b
+  metadata.gz: 4ae089f4117dc384000a70500c40ebadf48f42d1bd820d0840568b3b31b0197e51c65e9f60fe65d0e75c23aa4c7eac977be928a38969580174169bd0efe39912
+  data.tar.gz: 9653135f93b9b2b722102f055dc961346949368dab161a3cff64e99ddfc6781933a94b527151da9a24ff39451814f76c5409389f91c3692852eb17bd5d3d11f9

data/CHANGELOG.md

@@ -2,6 +2,105 @@
 
 ## 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`.
@@ -121,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`.
@@ -828,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-7.0.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,13 +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.
-  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.
+  `: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),
@@ -385,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.
@@ -865,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)
@@ -880,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

@@ -106,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
@@ -149,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
 
@@ -395,8 +398,10 @@ 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
 

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

data/lib/llm/function/array.rb

@@ -26,7 +26,8 @@ class LLM::Function
     #   Controls concurrency strategy:
     #   - `:thread`: Use threads
     #   - `:task`: Use async tasks (requires async gem)
-    #   - `:fiber`: Use raw fibers
+    #   - `:fiber`: Use scheduler-backed fibers (requires Fiber.scheduler)
+    #   - `:fork`: Use forked child processes
     #   - `:ractor`: Use Ruby ractors (class-based tools only; MCP tools are not supported)
     #
     # @return [LLM::Function::ThreadGroup, LLM::Function::TaskGroup, LLM::Function::FiberGroup, LLM::Function::Ractor::Group]
@@ -38,10 +39,12 @@ class LLM::Function
         ThreadGroup.new(map { |fn| fn.spawn(:thread) })
       when :fiber
         FiberGroup.new(map { |fn| fn.spawn(:fiber) })
+      when :fork
+        Fork::Group.new(map { |fn| fn.spawn(:fork) })
       when :ractor
         Ractor::Group.new(map { |fn| fn.spawn(:ractor) })
       else
-        raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :thread, :task, :fiber, or :ractor"
+        raise ArgumentError, "Unknown strategy: #{strategy.inspect}. Expected :thread, :task, :fiber, :fork, or :ractor"
       end
     end
 
@@ -53,7 +56,8 @@ class LLM::Function
     #   Controls concurrency strategy:
     #   - `:thread`: Use threads
     #   - `:task`: Use async tasks (requires async gem)
-    #   - `:fiber`: Use raw fibers
+    #   - `:fiber`: Use scheduler-backed fibers (requires Fiber.scheduler)
+    #   - `:fork`: Use forked child processes
     #   - `:ractor`: Use Ruby ractors (class-based tools only; MCP tools are not supported)
     #
     # @return [Array<LLM::Function::Return>]

data/lib/llm/function/fiber_group.rb

@@ -4,10 +4,10 @@ class LLM::Function
   ##
   # The {LLM::Function::FiberGroup} class wraps an array of
   # {Fiber} objects that are running {LLM::Function} calls
-  # concurrently using raw fibers.
+  # concurrently using scheduler-backed fibers.
   #
   # This class provides the same interface as {LLM::Function::ThreadGroup}
-  # but uses raw fibers for lightweight concurrency without the async gem.
+  # but uses scheduler-backed fibers for cooperative concurrency.
   #
   # @example
   #   llm = LLM.openai(key: ENV["KEY"])
@@ -90,10 +90,16 @@ class LLM::Function
     #   order as the original fibers.
     def wait
       @fibers.map do |fiber|
-        fiber.resume if fiber.alive?
+        fiber.alive? ? scheduler.run : nil
         fiber.value
       end
     end
     alias_method :value, :wait
+
+    private
+
+    def scheduler
+      Fiber.scheduler
+    end
   end
 end

data/lib/llm/function/fork/job.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+class LLM::Function
+  ##
+  # The {LLM::Function::Fork::Job} class represents a single fork-backed
+  # function call inside the child process.
+  #
+  # It is executed in the forked process and is responsible for running the
+  # resolved tool instance, handling control messages such as interrupts, and
+  # writing the final result back to the parent process.
+  class Fork::Job
+    ##
+    # @param [LLM::Function] function
+    # @param [LLM::Object] ch
+    # @return [LLM::Function::Fork::Job]
+    def initialize(function, ch)
+      @function = function
+      @ch = ch
+    end
+
+    ##
+    # @return [void]
+    def call
+      runner = @function.runner
+      controller = setup(runner)
+      @ch.result.write([:result, call!(runner)])
+    rescue => ex
+      @ch.result.write([:result, error(ex)])
+    ensure
+      controller&.kill
+      [@ch.control, @ch.result].each { _1.close unless _1.closed? }
+    end
+
+    private
+
+    def call!(runner)
+      kwargs = if Hash === @function.arguments
+        @function.arguments.transform_keys(&:to_sym)
+      else
+        @function.arguments
+      end
+      {id: @function.id, name: @function.name, value: runner.call(**kwargs)}
+    end
+
+    def error(ex)
+      {
+        id: @function.id,
+        name: @function.name,
+        value: {error: true, type: ex.class.name, message: ex.message}
+      }
+    end
+
+    def setup(runner)
+      ready = Queue.new
+      thread = Thread.new do
+        ready << true
+        kind = @ch.control.recv
+        next unless kind == :interrupt
+        hook = %i[on_cancel on_interrupt].find { runner.respond_to?(_1) }
+        runner.public_send(hook) if hook
+      rescue IOError, ArgumentError
+      end
+      ready.pop
+      thread
+    end
+  end
+end