llm.rb 16.0.0.pre.2 → 16.0.0.pre.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61578ce1082ecd25f86574ef19e1ffd4cc2b68c6689b705f0544f4aa3e391ede
-  data.tar.gz: 742b8d66f49113389c5ff08772e79498334eb6d5afe9821f05c2b8d1851cf4e8
+  metadata.gz: a8bd3b4f303036ba390981de3ec63ea0bb523cc653c4b77b221e4591e9b9a446
+  data.tar.gz: 3036ce3c4248e3ddad524657f31ea2c300f98282ad0aa68791848f56cd1b91f5
 SHA512:
-  metadata.gz: d0024edabc9ac7360a71a485362aed854644187c116777623b340e5fbd391ae257139aefe07ba29ce7fe9bf04573e66ff09c0f48024153833cbb28b385e13280
-  data.tar.gz: ec0b4f0b2ba6a66b38cd324c5c3ea6daccd4ff76cde43a1fa8c272c20da89bec735ff7b7bae3afb516d4b5a3131b4e383abe70f48365d6ba9c8a61028e233c48
+  metadata.gz: 604bafd36e8a55405e3fc487957ae97b9e4ffd67777711c071f7bfb9cfe005e0400294c089e72fbec3019538f4706c92cfe5bb15f3d0c2f994a324b9ba1a3322
+  data.tar.gz: d3bf4d7e1f9337cd7bdedb40ac4cfb4f95b6195e6df3360d428bfa6c220994edfaf8c5f053256e968c1feb9ae025b29854586dd9834dc84948729644f7a7b8ff

data/CHANGELOG.md

@@ -22,6 +22,7 @@
 | Old | New |
 |-----|-----|
 | Ruby 3.3 or later | Ruby 3.4 or later |
+| `record.messages` returns the messages the runtime holds | a `:jsonb` record returns a relation of `LLM::ActiveRecord::Message` rows |
 
 * **drop Ruby 3.3 support** <br>
   The gem now requires Ruby 3.4 or later: `required_ruby_version` is
@@ -30,6 +31,21 @@
   cancel that arrives before the tool starts is not delivered there, while
   Ruby 3.4 and 4.0 both deliver it.
 
+* **activerecord: read a `:jsonb` record's messages from the column** <br>
+  [`LLM::ActiveRecord`](https://r.uby.dev/api-docs/llm.rb/LLM/ActiveRecord.html)
+  now answers `#messages` for a record whose `format` is `:jsonb` with an
+  [`ActiveRecord::Relation`](https://api.rubyonrails.org/classes/ActiveRecord/Relation.html)
+  over the column, through
+  [`LLM::ActiveRecord::Message`](https://r.uby.dev/api-docs/llm.rb/LLM/ActiveRecord/Message.html),
+  so a conversation can be filtered, counted, and ordered in SQL, and reading it
+  needs no provider and no credentials. Before this, every record loaded the
+  runtime and returned the messages it held, whatever the format. The relation
+  is not a drop-in replacement for that buffer: it reads what is persisted
+  rather than what a runtime holds in memory, it is unordered, so order by
+  `position`, and its rows answer `unwrap!` rather than being
+  [`LLM::Message`](https://r.uby.dev/api-docs/llm.rb/LLM/Message.html) objects.
+  Every other format, and Sequel, still loads the runtime.
+
 ### Console
 
 * **console: erase with the backspace key on OpenBSD** <br>
@@ -39,6 +55,13 @@
   terminal's terminfo describes the key. All three erase. Before this only 127
   did, so the backspace key did nothing on the OpenBSD console.
 
+### Fix
+
+* **fork: require xchan.rb `~> 0.24`** <br>
+  The `:fork` concurrency strategy now requires the `xchan.rb` gem at `~> 0.24`
+  instead of `~> 0.23`, and the gemspec's development dependency follows. An
+  application that uses `:fork` needs `xchan.rb` 0.24 or later.
+
 ### Function
 
 * **function: deliver an interrupt to the tool, not to whatever is running** <br>
@@ -77,6 +100,21 @@
   side effects happening and its result written to a queue nobody read, and the
   reactor thread stayed alive until a group's `wait` stopped it.
 
+* **function: run the interrupt hook on every strategy** <br>
+  A tool that implements
+  [`LLM::Tool#on_interrupt`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#on_interrupt-instance_method)
+  or
+  [`LLM::Tool#on_cancel`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html#on_cancel-instance_method)
+  is now told on every concurrency strategy. `:thread`, `:fiber`, and `:async`
+  run the hook on the thread or fiber that ran the call, `:fork` and `:ractor`
+  run it inside the child or the ractor before the interrupt is delivered, and
+  a sequential group's cancel tells every task it holds. Before this, `:async`,
+  `:fork`, and `:ractor` never ran the hook, the others ran it on the thread
+  that cancelled, and a class-backed tool ran it on no strategy at all, because
+  `interrupt!` read the hook off the tool's definition and a class answers
+  `respond_to?` with false for an instance method. A hook that raises becomes
+  what the caller sees in place of the call's result.
+
 ### Provider
 
 * **deepseek: support image attachments in chat completions** <br>
@@ -97,13 +135,26 @@
   `qwen3.5-flash`, `qwen3.7-flash`, and `qwen3.8-omni-flash`, and gives
   `qwen3.7-plus` attachments, structured output, and a lower price; OpenAI adds
   `gpt-daybreak-blue-latest` and `gpt-daybreak-red-latest`; Bedrock adds
-  `openai.gpt-6-sol` and `openai.gpt-6-luna`; and DeepInfra adds
-  `tencent/Hy4-preview` and the Xiaomi MiMo V2.6 Pro and V2.6 Flash models.
+  `openai.gpt-6-sol`, `openai.gpt-6-luna`, and
+  `global.anthropic.claude-sonnet-5-5`; and DeepInfra adds `tencent/Hy4-preview`
+  and the Xiaomi MiMo V2.6 Pro and V2.6 Flash models.
   Bedrock also corrects the context and output limits of fifteen models, Google
   lowers the limits of `gemini-2.5-computer-use-preview-10-2025` and
-  `gemini-3-pro-image`, and OpenRouter adds four models, drops six, and reprices
+  `gemini-3-pro-image`, and OpenRouter adds five models, drops six, and reprices
   many of the DeepSeek, Z.ai, and Qwen entries.
 
+### Schema
+
+* **schema: apply every `parameter` option to the leaf** <br>
+  [`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html) now applies each
+  option given to `parameter` to the leaf its type resolves to, so settings such
+  as `min:`, `max:`, `multiple_of:`, and `const:` reach the schema instead of
+  being dropped. Before this only `required`, `default`, and `enum` were read, so
+  `parameter :age, Integer, "Age", min: 1, max: 9` sent a plain integer and lost
+  the range. A `default:` of `false` survives now as well, where the old code
+  discarded a false default, and `required: false` marks the parameter optional
+  rather than being ignored.
+
 ## v15.5.0
 
 Changes since `v15.4.1`.

data/docs/deepdive/features/database.md

@@ -407,6 +407,25 @@ you write across every agent is not covered by default; index the state
 column for those, for example with a GIN index on
 `data jsonb_path_ops`.
 
+A record whose `format` is `:jsonb` also returns this view from
+`#messages`, so a conversation can be read without building a runtime:
+no provider, and no credentials. What it returns differs from the
+runtime's own `#messages` in three ways. It reads what is persisted
+rather than the state a context holds in memory and has not saved. It
+is unordered, and conversation order is `position` rather than `id`, so
+order it explicitly. And its rows are
+[`LLM::ActiveRecord::Message`](https://r.uby.dev/api-docs/llm.rb/LLM/ActiveRecord/Message.html)
+records rather than
+[`LLM::Message`](https://r.uby.dev/api-docs/llm.rb/LLM/Message.html)
+objects, until
+[`#unwrap!`](https://r.uby.dev/api-docs/llm.rb/LLM/ActiveRecord/Message.html#unwrap!-instance_method)
+turns them back.
+
+Every other format loads the runtime and returns the messages it
+holds, as it always did, and that is the default. Sequel has no
+equivalent: its plugin persists the same state, and there is no view to
+read it back in the database.
+
 ### Sequel
 
 #### Overview

data/lib/llm/active_record/acts_as_llm.rb

@@ -89,10 +89,28 @@ module LLM::ActiveRecord
       end
 
       ##
+      # Returns the messages this record holds.
+      #
+      # A record that stores its state as jsonb reads them from the column,
+      # as a relation: the conversation can be filtered, counted and ordered
+      # in the database, and nothing here needs a provider to be built. Every
+      # other format loads the runtime and hands back the messages it holds.
+      #
+      # The two do not agree about what is visible. The relation reads what is
+      # persisted rather than what the runtime holds in memory, it is
+      # unordered - conversation order is `position`, not `id` - and its rows
+      # are {LLM::ActiveRecord::Message} records until
+      # {LLM::ActiveRecord::Message#unwrap!} turns them back into
+      # {LLM::Message} objects.
       # @see LLM::Context#messages
-      # @return [Array<LLM::Message>]
+      # @return [ActiveRecord::Relation, LLM::Buffer]
       def messages
-        ctx.messages
+        options = self.class.llm_plugin_options
+        if options[:format] == :jsonb
+          LLM::ActiveRecord::Message.for(agent: self)
+        else
+          ctx.messages
+        end
       end
 
       ##

data/lib/llm/function/async/task.rb

@@ -43,6 +43,19 @@ module LLM::Function::Async
     # which one that saves its work does, is torn down with `Cancel`, which
     # nothing here catches and nothing pushes, leaving a caller blocked on a
     # queue that will never fill.
+    #
+    # The tool's hook runs from inside that block, so it runs on the
+    # reactor's thread, and the result is held in a local until it has: a
+    # hook that runs after the queue was pushed is a hook the caller can
+    # race past.
+    #
+    # The rescue below is the other half of that promise, and it is written
+    # to catch everything rather than an interrupt. A hook that raises from
+    # the block's `ensure` unwinds past the push, so the queue would be left
+    # empty and `#wait` would wait on it forever - the outcome this comment
+    # already names. Whatever comes out of the block is pushed, and `#wait`
+    # hands anything that is an exception to the caller the way `Thread#value`
+    # and `Fiber#value` do for the other in-process strategies.
     # @return [nil]
     def spawn
       return if @guarded
@@ -53,8 +66,27 @@ module LLM::Function::Async
         @task = task
         @scheduler = Fiber.scheduler
         raise LLM::Interrupt if @cancelled
-        task.defer_cancel { @queue << function.call }
-      rescue LLM::Interrupt => e
+        task.defer_cancel do
+          result = begin
+            function.call
+          ensure
+            ##
+            # The hook runs on the reactor's thread rather than on the one
+            # that cancelled. See the note on
+            # `LLM::Function::Thread::Task#spawn` for why it cannot run
+            # before the call's frame has ended, and what `@delivered`
+            # means.
+            function.interrupt! if @delivered
+          end
+          @queue << result
+        end
+      rescue => e
+        ##
+        # This runs after the `defer_cancel` block's `ensure`, so the tool is
+        # told first and the caller second. It answers an interrupt, a
+        # cancel that arrived before `spawn` - the block raises before it
+        # reaches a tool, and there is no result to push - and a hook whose
+        # own error unwound past the push.
         @queue << e
         raise
       end
@@ -74,6 +106,12 @@ module LLM::Function::Async
     # it lets it raise, and either way the block above is what the caller
     # hears from - its value, or the exception it forwards.
     #
+    # The tool is told from inside the reactor, not here, so that a tool
+    # whose state belongs to the reactor's thread sees that thread.
+    # `@delivered` is set where the raise is issued into a live fiber: a
+    # cancel that arrives before the task starts, or after it has finished,
+    # interrupted nothing and tells nobody.
+    #
     # Nothing is done to the reactor here. Where it is stopped is `#wait`'s
     # own `ensure`, the only point at which it is known to be idle, and the
     # point a group's `wait` already stops it from: a task cannot tell
@@ -89,6 +127,7 @@ module LLM::Function::Async
       @alive = false
       @cancelled = true
       if @task&.fiber&.alive?
+        @delivered = true
         @scheduler.fiber_interrupt(@task.fiber, LLM::Interrupt.new)
       elsif @task.nil? && @queue
         ##
@@ -110,6 +149,10 @@ module LLM::Function::Async
     # strategy's, and a tool that will not stop meets the join and the kill
     # here rather than in the caller's cancel.
     #
+    # Anything that is an exception is raised rather than returned, which is
+    # what `Thread#value` and `Fiber#value` do. An interrupt is the usual
+    # one, and a hook that raised from the block's `ensure` is the other.
+    #
     # The guarded path returns before any of that, so a task whose guard
     # blocked it does not stop a reactor it never used - which matters in a
     # group, where the reactor is not its own.
@@ -120,7 +163,7 @@ module LLM::Function::Async
         spawn unless @queue
         result = @queue.pop
         @alive = false
-        raise result if LLM::Interrupt === result
+        raise result if Exception === result
         result
       ensure
         @reactor&.stop

data/lib/llm/function/fiber/task.rb

@@ -11,6 +11,9 @@ module LLM::Function::Fiber
   # {#wait}. Interrupting a running task raises
   # {LLM::Interrupt} on the fiber, which stops it at the next
   # yield point.
+  #
+  # A tool that implements `on_interrupt` is told on that fiber, once the
+  # call has ended, rather than on the thread that cancelled it.
   class Task < LLM::Function::Task
     ##
     # @param [LLM::Function] fn
@@ -26,7 +29,16 @@ module LLM::Function::Fiber
       if Fiber.scheduler.nil?
         raise ArgumentError, "Fiber concurrency requires Fiber.scheduler"
       else
-        @fiber = Fiber.schedule { function.call }
+        @fiber = Fiber.schedule do
+          function.call
+        ensure
+          ##
+          # The hook runs on the fiber the call runs on, once the call has
+          # ended, rather than on the thread that cancelled. See the note on
+          # `LLM::Function::Thread::Task#spawn` for why it cannot run before
+          # the call's frame has ended, and what `@delivered` means.
+          function.interrupt! if @delivered
+        end
         nil
       end
     end
@@ -40,8 +52,10 @@ module LLM::Function::Fiber
     ##
     # @return [nil]
     def interrupt!
-      @fiber&.raise(LLM::Interrupt) if @fiber&.alive?
-      function.interrupt!
+      if @fiber&.alive?
+        @delivered = true
+        @fiber.raise(LLM::Interrupt)
+      end
       nil
     end
     alias_method :cancel!, :interrupt!

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

@@ -72,17 +72,43 @@ class LLM::Function
       }
     end
 
+    ##
+    # Starts the watcher that turns a control message into an interrupt.
+    #
+    # The watcher is the only thread in the child that has the tool in hand,
+    # which is why the runner is passed to it rather than resolved again: a
+    # fork copies it, and the copy the parent holds is not the object that
+    # runs here.
+    # @param [Object] runner
+    # @return [Thread]
     def setup(runner)
       ready = Queue.new
       thread = ::Thread.new do
         ready << true
-        kind = @ch.control.recv
-        next unless kind == :interrupt
         ##
-        # The window decides whether this is the tool's to handle, or
-        # whether the tool has already been and gone.
-        @window.interrupt!
-      rescue IOError, ArgumentError
+        # Only the receive is guarded: it raises when the parent has gone,
+        # and nothing else in this block should be answerable to that
+        # rescue. A hook that raises must not be swallowed by it, and must
+        # not take the raise with it either - hence the `ensure` below,
+        # which delivers whatever the hook does.
+        kind = begin
+          @ch.control.recv
+        rescue IOError, ArgumentError
+          next
+        end
+        next unless kind == :interrupt
+        begin
+          ##
+          # The tool is told first, so a tool that releases a resource has
+          # done so by the time the raise lands on it, and so that a tool
+          # which rescues `LLM::Interrupt` reads what its hook wrote.
+          LLM::Function.interrupt(runner)
+        ensure
+          ##
+          # The window decides whether the raise is the tool's to handle,
+          # or whether the tool has already been and gone.
+          @window.interrupt!
+        end
       end
       ready.pop
       thread

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

@@ -79,22 +79,46 @@ class LLM::Function
         # a caller: it is `Thread.current`, the ractor's own main
         # thread, and the thread the tool runs on.
         window = LLM::Function::Window.new(thread: ::Thread.current)
+        ##
+        # The tool is built outside the window, so a raise from
+        # `initialize` is not answered as an interrupt, and before the
+        # watcher, so that the watcher has something to tell: a ractor
+        # cannot be handed the function, and the instance the parent
+        # holds is not this one.
+        runner = runner_class.new
         ::Thread.new do
-          ::Ractor.receive == :interrupt or next
           ##
-          # The window decides whether this is the tool's to handle, or
-          # whether the tool has already been and gone.
-          window.interrupt!
-        rescue ::Ractor::Error
+          # Only the receive is guarded: it raises when the ractor this
+          # one talks to has gone, and nothing else here should be
+          # answerable to that rescue. A hook that raises must not be
+          # swallowed by it, and must not take the raise with it either -
+          # hence the `ensure` below, which delivers whatever the hook
+          # does.
+          kind = begin
+            ::Ractor.receive
+          rescue ::Ractor::Error
+            next
+          end
+          next unless kind == :interrupt
+          begin
+            ##
+            # The tool is told first, so a tool that releases a resource
+            # has done so by the time the raise lands on it, and so that
+            # a tool which rescues `LLM::Interrupt` reads what its hook
+            # wrote.
+            LLM::Function.interrupt(runner)
+          ensure
+            ##
+            # The window decides whether the raise is the tool's to
+            # handle, or whether the tool has already been and gone.
+            window.interrupt!
+          end
         end
         ##
         # Everything the call needs is prepared outside the window, so
         # the distance from `running!` to the tool's first instruction is
-        # the method dispatch and nothing else. The tool is built outside
-        # it too: a raise from `initialize` is not an interrupt to
-        # answer, and inside the window it would be answered as one.
+        # the method dispatch and nothing else.
         kwargs = Hash === arguments ? arguments.transform_keys(&:to_sym) : arguments
-        runner = runner_class.new
         window.running!
         result = runner.call(**kwargs)
         ##

data/lib/llm/function/sequential/group.rb

@@ -34,13 +34,18 @@ module LLM::Function::Sequential
     end
 
     ##
-    # Interrupts the thread blocked in {#wait}.
-    # Sequential functions run on the caller's thread,
-    # and this methods raises {LLM::Interrupt} on that
-    # thread.
+    # Interrupts the thread blocked in {#wait}, and tells the tasks.
+    #
+    # Sequential functions run on the caller's thread, so the raise is what
+    # interrupts the call and it has to land there. It is issued first, and
+    # the tasks are told second: the delivery is this group's whole
+    # interrupt, and a hook that raises must not be able to take it with it
+    # or to leave the remaining tasks untold. That is also the order the
+    # in-process strategies use, where the hook runs after the raise.
     # @return [nil]
     def interrupt!
       @owner&.raise(LLM::Interrupt)
+      @tasks.each(&:interrupt!)
       nil
     end
     alias_method :cancel!, :interrupt!

data/lib/llm/function/task.rb

@@ -17,8 +17,9 @@ class LLM::Function
     #  An optional set of options that are specific
     #  to a given concurrency strategy.
     # @option options [LLM::Function::Return, nil] :guarded
-    #  A blocked return produced by the function's guard. When set, the
-    #  task yields it without running the tool.
+    #  A blocked return produced by the function's guard, or the in-band
+    #  error for a tool that cannot be built. When set, the task yields it
+    #  without running the tool.
     def initialize(fn, options = {})
       @function = fn
       @guarded = options[:guarded]

data/lib/llm/function/thread/task.rb

@@ -12,6 +12,9 @@ module LLM::Function::Thread
   # the thread, which stops the tool call mid-flight. The thread
   # is created with `report_on_exception` disabled so unhandled
   # exceptions propagate through {#wait} instead of to stderr.
+  #
+  # A tool that implements `on_interrupt` is told on that thread, once
+  # the call has ended, rather than on the thread that cancelled it.
   class Task < LLM::Function::Task
     ##
     # @param [LLM::Function] fn
@@ -24,7 +27,29 @@ module LLM::Function::Thread
     # @return [nil]
     def spawn
       return if @guarded
-      @thread = ::Thread.new { function.call }
+      @thread = ::Thread.new do
+        function.call
+      ensure
+        ##
+        # The hook runs on this thread rather than on the one that
+        # cancelled, because a tool's state belongs to the thread its call
+        # runs on, and the caller's thread is not that thread.
+        #
+        # On the job's own thread the hook can only run after the call's
+        # frame has ended - you cannot run code on a thread blocked inside
+        # a method it owns except by raising into it - and `@delivered` is
+        # written before the raise and read after it, so the flag says what
+        # it means. It is set only where the raise was issued into a live
+        # thread: a cancel that arrives before the call starts, or after it
+        # has finished, interrupted nothing and tells nobody.
+        #
+        # The hook runs before this thread ends, so it has run before
+        # `#wait` can return - which is the other half of telling the tool
+        # before the caller. A hook that raises becomes what this thread
+        # returns instead, so the error reaches the caller in place of the
+        # call's result.
+        function.interrupt! if @delivered
+      end
       @thread.report_on_exception = false
       nil
     end
@@ -38,8 +63,10 @@ module LLM::Function::Thread
     ##
     # @return [nil]
     def interrupt!
-      @thread&.raise(LLM::Interrupt) if @thread&.alive?
-      function.interrupt!
+      if @thread&.alive?
+        @delivered = true
+        @thread.raise(LLM::Interrupt)
+      end
       nil
     end
     alias_method :cancel!, :interrupt!

data/lib/llm/function.rb

@@ -53,6 +53,32 @@ class LLM::Function
   extend LLM::Function::Registry
   prepend LLM::Function::Tracing
 
+  ##
+  # Returns strategies that execute in an isolated environment.
+  # @return [Array<Symbol>]
+  def self.isolated
+    %i[fork ractor]
+  end
+
+  ##
+  # Tells a runner that its call was interrupted, if it wants telling.
+  #
+  # Internal to the strategies that run the hook from their own side, where
+  # the runner is a local rather than something {#interrupt!} can resolve:
+  # the child's copy in `:fork` is not the parent's, and a ractor cannot be
+  # handed the function at all. The argument is the runner and not the
+  # function, which is what separates this from {#interrupt!}, and one lookup
+  # means `on_cancel` keeps its precedence over `on_interrupt` everywhere.
+  # @param [Object, nil] runner
+  # @return [nil]
+  # @api private
+  def self.interrupt(runner)
+    return nil unless runner
+    hook = %i[on_cancel on_interrupt].find { runner.respond_to?(_1) }
+    runner.public_send(hook) if hook
+    nil
+  end
+
   ##
   # {LLM::Function::Return LLM::Function::Return} represents the result of a
   # tool call.
@@ -252,6 +278,13 @@ class LLM::Function
   #   task = tool.task(:thread)
   #   result = task.value
   #
+  # @note
+  #   An in-process strategy resolves the tool here, so a task that has
+  #   not been spawned already holds a live instance, and
+  #   {LLM::Function::Array#task} builds one for every pending function at
+  #   once. A tool that cannot be built carries the same in-band error the
+  #   guard produces rather than raising, so a constructor's failure
+  #   answers the model on every strategy.
   # @param [Symbol] strategy
   #   Controls concurrency strategy:
   #   - `:sequential`: Call the function sequentially
@@ -269,6 +302,25 @@ class LLM::Function
     # the tool to the strategy. The task carries the blocked result and
     # returns it without running if the guard intervenes.
     options = options.merge(guarded: @guard&.call(function: self))
+    ##
+    # Resolve the runner here, on the calling thread, before the task
+    # returned below exists for another thread to interrupt.
+    #
+    # `#interrupt!` resolves the same instance, and `@_runner ||=` is a
+    # check-then-create: reached from two threads at once it builds two,
+    # runs the call on one and tells the hook on the other.
+    #
+    # `:async` is in the list because its reactor runs on a background
+    # thread, which is the exposure `:thread` has. The cost is that the
+    # tool is built on the calling thread rather than inside the reactor,
+    # so a tool whose `initialize` wants a current `Async::Task` or a
+    # scheduler-installed fiber does not get one.
+    #
+    # A guarded task runs nothing, so it resolves nothing. A strategy in
+    # {LLM::Function.isolated} stays lazy on purpose, because there the
+    # tool is built in the child process or the ractor and this instance
+    # is not the one that runs.
+    options = options.merge(guarded: options[:guarded] || resolve(strategy))
     case strategy
     when :sequential
       Sequential::Task.new(self, options)
@@ -310,12 +362,39 @@ class LLM::Function
   ##
   # Notifies the function runner that the call was interrupted.
   # This is cooperative and only applies to runners that implement
-  # `on_interrupt`.
+  # `on_cancel` or `on_interrupt`.
+  #
+  # Resolved through {#runner} rather than read off `@runner`, so that a
+  # class-backed tool is told on the object the call will run on. Read off
+  # the definition instead, a class answers `respond_to?` with false for
+  # both hooks, and a tool that implements one is never told.
+  #
+  # An in-process strategy has already resolved the runner in {#task}, on
+  # the thread that built the task, so this reads a memo rather than
+  # creating one. Where there is no tool to tell - one that cannot be
+  # built, or a function whose task was never made - this is a no-op
+  # rather than a raise, because the call path is where a constructor's
+  # failure belongs.
+  #
+  # Six routes reach the hook, and they differ in where it runs and in
+  # whether an interrupt has to have been delivered first:
+  #
+  # - `:thread`, `:fiber` and `:async` run it on the thread or fiber that ran
+  #   the call, once the call has ended, and only where the raise was issued
+  #   into a live job.
+  # - `:fork` and `:ractor` run it inside the child or the ractor, before the
+  #   interrupt is delivered, and only for a message that arrived.
+  # - `:sequential` is the exception, and this method is how it is reached:
+  #   nothing is raised into a sequential tool, so the hook is its only
+  #   notification and it runs on the thread that cancelled, through
+  #   {Sequential::Task#interrupt!}.
+  #
+  # A caller that reaches this directly - `LLM::Context#interrupt!` over
+  # pending functions, say - takes the last route, with no delivery to speak
+  # of and nothing running.
   # @return [nil]
   def interrupt!
-    hook = %i[on_cancel on_interrupt].find { @runner.respond_to?(_1) }
-    @runner.public_send(hook) if hook
-    nil
+    LLM::Function.interrupt(runner_or_nil)
   end
   alias_method :cancel!, :interrupt!
 
@@ -393,15 +472,85 @@ class LLM::Function
 
   ##
   # Returns the bound function runner instance.
+  #
+  # Resolved once and kept, so that the object an interrupt has to reach is
+  # the object that runs the call. A class-backed tool would otherwise build
+  # an instance here and discard it, leaving {#interrupt!} with a class to
+  # send the hook to.
+  #
+  # An in-process strategy resolves it in {#task}, on the calling thread,
+  # before the task exists for another thread to interrupt. Every other
+  # path resolves it at the first call.
+  #
+  # The tracer is assigned when the instance is resolved, so a tracer set
+  # after that does not reach it.
+  #
+  # The instance belongs to this function object rather than to a call. The
+  # per-call copy is the one {LLM::Message#functions} makes, and that is
+  # what keeps the usual path to one call per instance; a second {#task} on
+  # one function, or a retry, reuses the instance and whatever its ivars
+  # hold.
   # @return [Object]
   def runner
-    runner = Class === @runner ? @runner.new : @runner
-    runner.tracer = @tracer if runner.respond_to?(:tracer=)
-    runner
+    @_runner ||= begin
+      _runner = Class === @runner ? @runner.new : @runner
+      _runner.tracer = @tracer if _runner.respond_to?(:tracer=)
+      _runner
+    end
   end
 
   private
 
+  ##
+  # Resolves the runner for a strategy that runs in this process, and
+  # answers with an in-band error when the tool cannot be built.
+  #
+  # {#call_function} resolves inside its own rescue, and that rescue is what
+  # answers the model with an error rather than raising into the turn.
+  # Resolving earlier keeps that promise by producing the return the guard
+  # would have produced.
+  #
+  # An interrupt is re-raised rather than answered, which is what
+  # {#call_function} does for the same reason: an interrupt is not a tool's
+  # failure, and the runner is the thing it is aimed at.
+  # @param [Symbol] strategy
+  # @return [LLM::Function::Return, nil]
+  def resolve(strategy)
+    return nil if LLM::Function.isolated.include?(strategy)
+    runner
+    nil
+  rescue LLM::Interrupt
+    raise
+  rescue => ex
+    Return.new(id, name, {error: true, type: ex.class.name, message: ex.message})
+  end
+
+  ##
+  # The runner, or nil when it cannot be built.
+  #
+  # An interrupt has nothing to tell if there is no tool to tell, and a
+  # cancel is the wrong place to raise a constructor's failure, which the
+  # call path answers in-band.
+  # @return [Object, nil]
+  def runner_or_nil
+    runner
+  rescue StandardError
+    nil
+  end
+
+  ##
+  # A duplicate resolves its own runner.
+  #
+  # The copy a task runs belongs to one call, and the instance that call
+  # resolves belongs to that copy - never to the definition it was
+  # duplicated from, which is shared and globally registered.
+  # @param [LLM::Function] other
+  # @return [void]
+  def initialize_copy(other)
+    super
+    @_runner = nil
+  end
+
   ##
   # Internal method that calls the function and returns a Return object.
   # Handles both class-based and proc-based runners, and rescues exceptions.

data/lib/llm/schema/leaf.rb

@@ -96,9 +96,11 @@ class LLM::Schema
 
     ##
     # Mark a leaf as required
+    # @param [Boolean] value
+    #  When false, marks the leaf as optional
     # @return [LLM::Schema::Leaf]
-    def required
-      tap { @required = true }
+    def required(value = true)
+      tap { @required = value }
     end
 
     ##

data/lib/llm/sequel/plugin.rb

@@ -188,8 +188,13 @@ module LLM::Sequel
     end
 
     ##
+    # @note There is no view over the jsonb column on this side, so a record
+    #   always loads the runtime to answer this - unlike
+    #   {LLM::ActiveRecord}, where a jsonb record reads the column directly.
+    #   The two wrappers are written to mirror each other, and this is the
+    #   one place they do not.
     # @see LLM::Context#messages
-    # @return [Array<LLM::Message>]
+    # @return [LLM::Buffer]
     def messages
       ctx.messages
     end

data/lib/llm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LLM
-  VERSION = "16.0.0.pre.2"
+  VERSION = "16.0.0.pre.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm.rb
 version: !ruby/object:Gem::Version
-  version: 16.0.0.pre.2
+  version: 16.0.0.pre.3
 platform: ruby
 authors:
 - Robert Gleeson