smith-agents 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 986d706ecdf0a51035e20dde373106a6c6df18bc2150cae87e117993bd3fcd1e
-  data.tar.gz: e67ca0f8e6b4d6d35c5e1683876a9e191d0da92e29bee4c4379ca8b60b77c50e
+  metadata.gz: 450ce06c1d96f41a8b6ae6d0c0dd1b8dcc88b58d3da786d8536a26ecc8f111bb
+  data.tar.gz: 7b0696ff9aaccc3016ebef5223c4ded71aeeb883d1a1b70e6f2ab5959657e1da
 SHA512:
-  metadata.gz: fa10aed2a7fc3874e8629af28beb07c230d5632b5a653630e70374931c8067775b8f17bee8c70a5c7e96c723e70dbad10c693491c37f8f4bb4a3c7f29b5aed1e
-  data.tar.gz: 13560c156073e79e1950d46e460a7f8a1a964a3af6d9b63b68394a0835b6b117f1fb60636c8cecb62d4fb6380e9064a535607cd2e57155e92f64915d2ab76228
+  metadata.gz: da3c5cb55ef7efac304f223eb7ce468f058b4d85c9c4b60ea102f50882789d067eaf9c2a212871eb66a215f7f1cce2baa29de945dd3c0f2c0cc084d187fec1ae
+  data.tar.gz: 910ec83bc644cdbb5ad1a737ef1aa95af3d5ca784d952fea9179ae4b7e44d49a1edf7a7ae2b067c7a83a227bb623d3d6c798cc45a8d254501ff397f99e876b69

data/CHANGELOG.md

@@ -4,7 +4,53 @@ All notable changes to Smith are documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Smith is pre-1.0 and under active development; expect occasional contract tightening between minor versions until 1.0.
 
-## [Unreleased]
+## [0.7.0] - 2026-07-21
+
+### Added
+
+- Add an opaque host invocation context for tool adapters, propagated through
+  Smith parallel/fan-out branches and concurrent tools on individual chats
+  created by `Smith::Agent` without globally changing RubyLLM behavior. Durable
+  workers receive it only when the host installs a fresh process-local context.
+- Add opt-in strict tool-result capture with typed failure diagnostics and
+  persistence-safe reconstruction.
+
+### Changed
+
+- Bump `Smith::EXECUTION_SEMANTICS_VERSION` to `3` because composite branch
+  failure transport now preserves strict tool-capture uncertainty and its
+  typed tool metadata across persistence.
+- Support RubyLLM `>= 1.15, < 1.17`; Smith's per-chat concurrent tool context
+  integration is verified against those execution interfaces and fails closed
+  when the required chat hook is unavailable.
+
+### Fixed
+
+- Make agent tool-call allowance atomic across concurrent tool calls.
+- Install Smith's tool execution boundary on direct and persisted agent chat
+  entry points (`chat`, `create`, `create!`, and `find`) without modifying raw
+  RubyLLM chats globally, and capture invocation context independently for each
+  tool execution batch.
+- Give strict capture uncertainty precedence over sibling concurrent failures,
+  reject unusable collectors before host hooks or tool execution, and prevent
+  transition retries from replaying an uncertain tool outcome.
+- Preserve process-fatal failures across concurrent tool callbacks and root
+  workflow branches regardless of sibling completion order.
+- Reject malformed or future strict-capture diagnostics at persistence
+  boundaries, while preserving legacy non-capture composite error transport.
+- Preserve the existing per-concrete-class `capture_result` opt-in behavior and
+  the public `BranchEnv` member shape.
+
+## [0.6.1] - 2026-07-20
+
+### Fixed
+
+- Persist a composite transition's execution namespace with its prepared
+  split-step snapshot so prepared- and dispatch-state recovery reproduce the
+  exact same plan.
+- Pin composite namespace preparation to Smith-owned implementations so
+  subclass method collisions cannot bypass durable plan identity, and release
+  the preparation claim cleanly when namespace generation fails.
 
 ## [0.6.0] - 2026-07-20
 

data/docs/TOOLS_AND_GUARDRAILS.md

@@ -80,6 +80,67 @@ Captured tool results survive persistence — they are included in `to_state` an
 
 `tool_results` is designed for compact structured evidence (URLs, metadata, refs). Hosts should avoid storing large raw payloads there. If large tool outputs are needed, use artifacts and capture refs or metadata instead.
 
+Capture is best-effort by default for backward compatibility. Hosts that cannot
+complete a workflow checkpoint without captured evidence can opt into strict
+capture:
+
+```ruby
+class VerifiedSearch < Smith::Tool
+  capture_result(strict: true) do |kwargs, result|
+    { query: kwargs.fetch(:query), urls: extract_urls(result) }
+  end
+end
+```
+
+Strict capture raises `Smith::ToolCaptureFailed` when no workflow collector is
+active, the collector is not callable, the capture block fails or returns `nil`, or the collector rejects the
+entry by raising an exception. A collector return value of `nil` or `false` is
+accepted; delivery is rejected only when the collector raises. Best-effort
+capture logs and continues as before.
+
+Capture policy is declared per concrete tool class and is not inherited. This
+preserves the historical opt-in contract and prevents a subclass from beginning
+to capture or fail strictly without its own declaration.
+
+Strict capture validates that a collector exists before `perform`, but the
+capture block and collector run after `perform` returns. It is therefore
+post-result evidence, not a pre-effect transaction or durable operation receipt.
+`Smith::ToolCaptureFailed` is terminal: direct retry declarations are rejected,
+and broad explicit retry classes such as `StandardError` do not override that
+classification, because the external outcome may already have occurred. Hosts
+must give side-effecting tools their own idempotent operation receipt and
+reconciliation boundary before retrying them. Read-only tools can use strict
+capture to fail closed when their result cannot be checkpointed.
+
+### Host Invocation Context
+
+Hosts can expose one opaque, execution-scoped value to tool adapters without
+placing host identity or credentials in model arguments:
+
+```ruby
+Smith::Tool.with_invocation_context(execution_context) do
+  workflow.advance
+end
+
+Smith::Tool.current_invocation_context
+```
+
+Smith does not inspect, serialize, or persist this value. The scope restores the
+previous value even when execution raises, and the value propagates through
+Smith-managed same-agent and heterogeneous parallel branches, durable composite
+branch workers, and concurrent tool calls on chats returned by the Smith agent
+entry points `chat`, `create`, `create!`, and `find`. Invocation context is
+captured independently for each concurrent tool batch, so reusing a chat cannot
+retain a previous execution's scope. Smith scopes only those chat instances;
+requiring Smith does not alter raw RubyLLM chats. Arbitrary chats, threads, or
+fibers created by host code are outside this boundary and must install their own
+scope. Hosts remain responsible for using an immutable value and installing a
+fresh context after durable resume; context-dependent adapters must fail closed
+when no context is installed. Smith supports RubyLLM `>= 1.15, < 1.17` for this
+integration and fails closed if the required per-chat tool execution hook is
+unavailable. RubyLLM fiber concurrency still requires its optional `async`
+dependency; Smith does not make that scheduler a runtime dependency.
+
 You can still use RubyLLM agent tool wiring on your agents:
 
 ```ruby
@@ -137,4 +198,3 @@ class GuardedWorkflow < Smith::Workflow
   end
 end
 ```
-

data/lib/smith/agent.rb

@@ -2,6 +2,8 @@
 
 require "ruby_llm"
 
+require_relative "tool"
+
 module Smith
   class Agent < RubyLLM::Agent
     EXECUTION_IDENTITY_UNSET = Object.new.freeze
@@ -195,11 +197,23 @@ module Smith
         kwargs = inject_reserved_inputs(kwargs, profile)
         kwargs = nil_fill_declared_inputs(kwargs)
 
-        llm_chat = super
+        llm_chat = install_tool_execution_context(super)
         Smith::Models::Normalizer.apply!(llm_chat, profile: profile) if profile
         llm_chat
       end
 
+      def create(**kwargs)
+        install_tool_execution_context(super)
+      end
+
+      def create!(**kwargs)
+        install_tool_execution_context(super)
+      end
+
+      def find(id, **kwargs)
+        install_tool_execution_context(super)
+      end
+
       # Normalizes the |ctx| DSL across RubyLLM's block-form attribute setters.
       #
       # RubyLLM evaluates these blocks via `runtime.instance_exec(&block)`,
@@ -255,6 +269,14 @@ module Smith
 
       private
 
+      def install_tool_execution_context(chat_object)
+        return unless chat_object
+
+        llm_chat = chat_object.respond_to?(:to_llm) ? chat_object.to_llm : chat_object
+        Tool::ChatExecutionContext.install(llm_chat)
+        chat_object
+      end
+
       def resolve_profile(model_id)
         return nil unless model_id
         return nil unless defined?(Smith::Models)

data/lib/smith/tool/budget_enforcement.rb

@@ -10,23 +10,21 @@ module Smith
         ledger = self.class.current_ledger
         workflow_active = ledger&.limits&.key?(:tool_calls)
 
-        check_agent_tool_calls!(allowance)
-        commit_tool_call_charges!(ledger, allowance, workflow_active)
-      end
-
-      def check_agent_tool_calls!(allowance)
-        return unless allowance
+        if allowance.is_a?(CallAllowance)
+          return allowance.charge! { commit_workflow_tool_call!(ledger, workflow_active) }
+        end
+        if allowance.is_a?(Hash)
+          return CallAllowance.charge_legacy!(allowance) { commit_workflow_tool_call!(ledger, workflow_active) }
+        end
 
-        raise BudgetExceeded, "agent tool_calls budget exceeded" if allowance[:remaining] <= 0
+        commit_workflow_tool_call!(ledger, workflow_active)
       end
 
-      def commit_tool_call_charges!(ledger, allowance, workflow_active)
-        if workflow_active
-          reservation = ledger.reserve!(:tool_calls, 1)
-          ledger.reconcile!(reservation, 1)
-        end
+      def commit_workflow_tool_call!(ledger, workflow_active)
+        return unless workflow_active
 
-        allowance[:remaining] -= 1 if allowance
+        reservation = ledger.reserve!(:tool_calls, 1)
+        ledger.reconcile!(reservation, 1)
       end
     end
   end

data/lib/smith/tool/call_allowance.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool < RubyLLM::Tool
+    class CallAllowance
+      LEGACY_MUTEX = Mutex.new
+      LEGACY_ALLOWANCE_MUTEXES = ObjectSpace::WeakMap.new
+      private_constant :LEGACY_MUTEX
+      private_constant :LEGACY_ALLOWANCE_MUTEXES
+
+      def self.charge_legacy!(allowance)
+        legacy_allowance_mutex(allowance).synchronize do
+          Thread.handle_interrupt(Object => :never) do
+            remaining = allowance[:remaining]
+            unless remaining.is_a?(Integer) && remaining.positive?
+              raise BudgetExceeded, "agent tool_calls budget exceeded"
+            end
+
+            yield if block_given?
+            allowance[:remaining] = remaining - 1
+          end
+        end
+      end
+
+      def self.legacy_allowance_mutex(allowance)
+        LEGACY_MUTEX.synchronize do
+          LEGACY_ALLOWANCE_MUTEXES[allowance] ||= Mutex.new
+        end
+      end
+      private_class_method :legacy_allowance_mutex
+
+      def initialize(remaining)
+        unless remaining.is_a?(Integer) && remaining >= 0
+          raise ArgumentError, "tool call allowance must be a non-negative integer"
+        end
+
+        @remaining = remaining
+        @mutex = Mutex.new
+      end
+
+      def charge!
+        @mutex.synchronize do
+          Thread.handle_interrupt(Object => :never) do
+            raise BudgetExceeded, "agent tool_calls budget exceeded" unless @remaining.positive?
+
+            yield if block_given?
+            @remaining -= 1
+          end
+        end
+      end
+
+      def remaining
+        @mutex.synchronize { @remaining }
+      end
+
+      def [](key)
+        remaining if key == :remaining
+      end
+    end
+  end
+end

data/lib/smith/tool/capture.rb

@@ -3,19 +3,75 @@
 module Smith
   class Tool < RubyLLM::Tool
     module Capture
+      CAPTURE_FAILED = Object.new.freeze
+      private_constant :CAPTURE_FAILED
+
       private
 
+      def ensure_capture_ready!
+        return unless self.class.capture_result && self.class.capture_result_strict?
+
+        capture_collector(true)
+      end
+
       def capture_result_if_configured(kwargs, result)
         block = self.class.capture_result
         return unless block
 
-        collector = self.class.current_tool_result_collector
+        capture_with_policy(block, kwargs, result, self.class.capture_result_strict?)
+      end
+
+      def capture_with_policy(block, kwargs, result, strict)
+        collector = capture_collector(strict)
         return unless collector
 
-        captured = block.call(kwargs, result)
-        collector.call({ tool: name.to_s, captured: captured }) if captured
+        captured = captured_value(block, kwargs, result, strict)
+        return if captured.equal?(CAPTURE_FAILED)
+
+        append_capture(collector, captured, strict)
+      end
+
+      def capture_collector(strict)
+        collector = self.class.current_tool_result_collector
+        return collector unless strict
+        return collector if collector.respond_to?(:call)
+
+        reason = collector.nil? ? :collector_missing : :collector_invalid
+        raise tool_capture_failed(reason)
+      end
+
+      def captured_value(block, kwargs, result, strict)
+        captured = call_capture_block(block, kwargs, result, strict)
+        return captured if captured.equal?(CAPTURE_FAILED)
+        return captured unless captured.nil? && strict
+
+        raise tool_capture_failed(:capture_empty)
+      end
+
+      def call_capture_block(block, kwargs, result, strict)
+        block.call(kwargs, result)
       rescue StandardError => e
-        Smith.config.logger&.warn("[Smith] capture_result failed for #{name}: #{e.message}")
+        capture_failure(e, strict, reason: :capture_block_failed)
+      end
+
+      def append_capture(collector, captured, strict)
+        collector.call({ tool: name.to_s, captured: captured }) if strict || captured
+      rescue StandardError => e
+        capture_failure(e, strict, reason: :collector_failed)
+      end
+
+      def capture_failure(error, strict, reason:)
+        return CAPTURE_FAILED.tap { log_capture_failure(error) } unless strict
+
+        raise tool_capture_failed(reason), cause: error
+      end
+
+      def tool_capture_failed(reason)
+        ToolCaptureFailed.for_runtime(tool_name: name, reason:)
+      end
+
+      def log_capture_failure(error)
+        Smith.config.logger&.warn("[Smith] capture_result failed for #{name}: #{error.message}")
       end
     end
   end

data/lib/smith/tool/capture_configuration.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool < RubyLLM::Tool
+    module CaptureConfiguration
+      def capture_result(strict: false, &block)
+        return @capture_result unless block
+
+        raise ArgumentError, "capture_result strict must be true or false" unless [true, false].include?(strict)
+
+        @capture_result_strict = strict
+        @capture_result = block
+      end
+
+      def capture_result_strict?
+        @capture_result_strict == true
+      end
+    end
+  end
+end

data/lib/smith/tool/chat_execution_context.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool < RubyLLM::Tool
+    module ChatExecutionContext
+      def self.install(chat)
+        return chat unless chat.respond_to?(:tools) && chat.tools.respond_to?(:values)
+        unless chat.respond_to?(:execute_tool, true)
+          raise Error, "unsupported RubyLLM chat execution interface: missing #execute_tool"
+        end
+
+        chat.extend(self) unless chat.singleton_class < self
+        chat.__send__(:install_smith_tool_execution_context)
+        chat
+      end
+
+      private
+
+      def install_smith_tool_execution_context
+        return if defined?(@smith_tool_execution_batches_mutex)
+
+        @smith_tool_execution_batches = {}.compare_by_identity
+        @smith_tool_execution_batches_mutex = Mutex.new
+      end
+
+      def execute_tool(tool_call)
+        batch = execution_batch(tool_call)
+        return super unless batch
+
+        Tool::ScopedContext.around(batch.fetch(:context)) { super }
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        record_batch_failure(batch, e) if batch
+        raise
+      end
+
+      def execute_tools_concurrently(tool_calls, ...)
+        batch = execution_batch_context
+        register_execution_batch(tool_calls, batch)
+        super
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        raise e unless e.is_a?(StandardError)
+
+        fatal_failure = first_failure(batch&.fetch(:fatal_failures))
+        raise fatal_failure if fatal_failure
+
+        capture_failure = first_failure(batch&.fetch(:capture_failures))
+        raise capture_failure if capture_failure
+
+        raise
+      ensure
+        unregister_execution_batch(tool_calls, batch)
+      end
+
+      def execution_batch_context
+        {
+          context: Tool::ScopedContext.capture,
+          capture_failures: Queue.new,
+          fatal_failures: Queue.new
+        }.freeze
+      end
+
+      def register_execution_batch(tool_calls, batch)
+        @smith_tool_execution_batches_mutex.synchronize do
+          tool_calls.each_value do |tool_call|
+            raise Error, "tool call is already active on this chat" if @smith_tool_execution_batches.key?(tool_call)
+
+            @smith_tool_execution_batches[tool_call] = batch
+          end
+        end
+      end
+
+      def unregister_execution_batch(tool_calls, batch)
+        return unless tool_calls && batch
+
+        @smith_tool_execution_batches_mutex.synchronize do
+          tool_calls.each_value do |tool_call|
+            @smith_tool_execution_batches.delete(tool_call) if @smith_tool_execution_batches[tool_call].equal?(batch)
+          end
+        end
+      end
+
+      def execution_batch(tool_call)
+        @smith_tool_execution_batches_mutex.synchronize do
+          @smith_tool_execution_batches[tool_call]
+        end
+      end
+
+      def record_batch_failure(batch, error)
+        if error.is_a?(ToolCaptureFailed)
+          batch.fetch(:capture_failures).push(error)
+        elsif !error.is_a?(StandardError)
+          batch.fetch(:fatal_failures).push(error)
+        end
+      end
+
+      def first_failure(queue)
+        return unless queue
+
+        queue.pop(true)
+      rescue ThreadError
+        nil
+      end
+    end
+  end
+end

data/lib/smith/tool/scoped_context.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Smith
+  class Tool < RubyLLM::Tool
+    module ScopedContext
+      CONTEXT_KEYS = {
+        current_guardrails: :smith_tool_guardrails,
+        current_deadline: :smith_tool_deadline,
+        current_ledger: :smith_tool_ledger,
+        current_tool_call_allowance: :smith_tool_call_allowance,
+        current_tool_result_collector: :smith_tool_result_collector,
+        current_invocation_context: :smith_tool_invocation_context
+      }.freeze
+
+      CONTEXT_KEYS.each do |reader, key|
+        define_method(reader) { Thread.current[key] }
+        define_method("#{reader}=") { |value| Thread.current[key] = value }
+      end
+
+      def self.capture
+        CONTEXT_KEYS.to_h { |reader, key| [reader, Thread.current[key]] }.freeze
+      end
+
+      def self.around(values, &block)
+        raise ArgumentError, "block required" unless block
+
+        validate!(values)
+        previous = capture
+        Thread.handle_interrupt(Object => :never) do
+          install(values)
+          begin
+            Thread.handle_interrupt(Object => :immediate, &block)
+          ensure
+            install(previous)
+          end
+        end
+      end
+
+      def with_invocation_context(value, &block)
+        raise ArgumentError, "block required" unless block
+
+        previous = current_invocation_context
+        Thread.handle_interrupt(Object => :never) do
+          self.current_invocation_context = value
+          begin
+            Thread.handle_interrupt(Object => :immediate, &block)
+          ensure
+            self.current_invocation_context = previous
+          end
+        end
+      end
+
+      def self.install(values)
+        CONTEXT_KEYS.each do |reader, key|
+          Thread.current[key] = values.fetch(reader)
+        end
+      end
+      private_class_method :install
+
+      def self.validate!(values)
+        complete = values.is_a?(Hash) && values.length == CONTEXT_KEYS.length && CONTEXT_KEYS.each_key.all? do |key|
+          values.key?(key)
+        end
+        return if complete
+
+        raise ArgumentError, "tool context must contain the complete scoped context"
+      end
+      private_class_method :validate!
+    end
+  end
+end

data/lib/smith/tool.rb

@@ -4,15 +4,22 @@ require "ruby_llm"
 
 require_relative "tool/capability_builder"
 require_relative "tool/policy"
+require_relative "tool/call_allowance"
 require_relative "tool/budget_enforcement"
+require_relative "tool_capture_failed"
 require_relative "tool/capture"
+require_relative "tool/capture_configuration"
 require_relative "tool/compatibility"
+require_relative "tool/scoped_context"
+require_relative "tool/chat_execution_context"
 
 module Smith
   class Tool < RubyLLM::Tool
     include Policy
     include BudgetEnforcement
     include Capture
+    extend CaptureConfiguration
+    extend ScopedContext
 
     class << self
       # Tool subclasses inherit the parent's compatible_with spec by
@@ -40,46 +47,6 @@ module Smith
 
       attr_reader :compatible_with_spec
 
-      def current_guardrails
-        Thread.current[:smith_tool_guardrails]
-      end
-
-      def current_guardrails=(value)
-        Thread.current[:smith_tool_guardrails] = value
-      end
-
-      def current_deadline
-        Thread.current[:smith_tool_deadline]
-      end
-
-      def current_deadline=(value)
-        Thread.current[:smith_tool_deadline] = value
-      end
-
-      def current_ledger
-        Thread.current[:smith_tool_ledger]
-      end
-
-      def current_ledger=(value)
-        Thread.current[:smith_tool_ledger] = value
-      end
-
-      def current_tool_call_allowance
-        Thread.current[:smith_tool_call_allowance]
-      end
-
-      def current_tool_call_allowance=(value)
-        Thread.current[:smith_tool_call_allowance] = value
-      end
-
-      def current_tool_result_collector
-        Thread.current[:smith_tool_result_collector]
-      end
-
-      def current_tool_result_collector=(value)
-        Thread.current[:smith_tool_result_collector] = value
-      end
-
       def category(value = nil)
         return @category if value.nil?
 
@@ -105,15 +72,10 @@ module Smith
 
         @before_execute = block
       end
-
-      def capture_result(&block)
-        return @capture_result unless block_given?
-
-        @capture_result = block
-      end
     end
 
     def execute(**kwargs)
+      ensure_capture_ready!
       run_before_execute_hook!(kwargs)
       check_tool_deadline!
       check_privilege!(kwargs)