smith-agents 0.10.0 → 0.12.0

data/lib/smith/errors.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "diagnostic_text"
 require_relative "error"
 require_relative "persisted_failure_invalid"
 require_relative "pricing_configuration_error"
@@ -68,6 +69,21 @@ module Smith
   end
 
   class BudgetExceeded < Error; end
+
+  # A host's budget ledger (`budget_ledger`) refused a provider request's
+  # hold; nothing was sent. A BudgetExceeded, so it is not retried unless a
+  # step's `retry_on` names it (a durable retry waits for budget). One that
+  # paused a tool loop carries its `continuation` (Budget::Continuation),
+  # which the step's retry continues from.
+  class BudgetUnavailable < BudgetExceeded
+    attr_reader :continuation
+
+    def initialize(message = "the budget ledger refused the request", continuation: nil)
+      @continuation = continuation
+      super(message)
+    end
+  end
+
   class DeadlineExceeded < Error; end
   class MaxTransitionsExceeded < Error; end
   class GuardrailFailed < Error; end
@@ -88,6 +104,11 @@ module Smith
   class AgentError < Error; end
 
   class BlankAgentOutputError < AgentError
+    DETAIL_NAMES = %i[agent_name model_used].freeze
+    DETAIL_KEYS = DETAIL_NAMES.to_h { |name| [name.to_s.freeze, name] }.freeze
+    MAX_DETAIL_BYTES = 512
+    private_constant :DETAIL_NAMES, :DETAIL_KEYS, :MAX_DETAIL_BYTES
+
     attr_reader :agent_name, :model_used
 
     def initialize(agent_name:, model_used:)
@@ -101,17 +122,76 @@ module Smith
 
       super(detail)
     end
+
+    def details
+      {
+        agent_name: agent_name && DiagnosticText.capture(agent_name.to_s, max_bytes: MAX_DETAIL_BYTES),
+        model_used: model_used && DiagnosticText.capture(model_used.to_s, max_bytes: MAX_DETAIL_BYTES)
+      }.freeze
+    end
+
+    def self.from_details(details)
+      values = normalize_details(details)
+      new(agent_name: values.fetch(:agent_name)&.to_sym, model_used: values.fetch(:model_used))
+    end
+
+    def self.normalize_details(details)
+      raise ArgumentError, "blank agent output details must be a Hash" unless details.is_a?(Hash)
+
+      values = {}
+      Hash.instance_method(:each_pair).bind_call(details) do |key, value|
+        name = key.is_a?(Symbol) ? key : DETAIL_KEYS[key]
+        unless DETAIL_NAMES.include?(name)
+          raise ArgumentError, "blank agent output details contain an unknown attribute"
+        end
+        raise ArgumentError, "blank agent output details contain a duplicate attribute" if values.key?(name)
+
+        values[name] = bounded_detail(name, value)
+      end
+      raise ArgumentError, "blank agent output details are incomplete" unless values.length == DETAIL_NAMES.length
+
+      values
+    end
+
+    def self.bounded_detail(name, value)
+      return value if value.nil?
+
+      bounded = value.is_a?(String) && value.valid_encoding? && value.bytesize <= MAX_DETAIL_BYTES
+      raise ArgumentError, "blank agent output detail #{name} must be bounded text" unless bounded
+
+      value
+    end
+    private_class_method :normalize_details, :bounded_detail
   end
 
   class WorkflowError < Error; end
 
+  # A host's budget ledger (`budget_ledger`) could not be built or failed to
+  # answer `reserve!` (its service down, say); nothing was sent. Not a
+  # provider failure, so no fallback model is tried; not retried unless a
+  # step's `retry_on` names it.
+  class BudgetLedgerError < WorkflowError
+    def initialize(message = "the budget ledger failed") = super
+  end
+
   class DeterministicStepFailure < WorkflowError
-    attr_reader :retryable, :kind, :details
+    attr_reader :retryable, :kind, :details, :new_idempotency_key, :idempotency_scope
+
+    # `new_idempotency_key: true` declares that the failed attempt's own
+    # requests took no effect, so a retry of the step that raised it sends
+    # them under new keys; `idempotency_scope` is that step's position. The
+    # flag is not persisted with the failure record.
+    def initialize(message, retryable: nil, kind: nil, details: nil, new_idempotency_key: false, # rubocop:disable Metrics/ParameterLists
+                   idempotency_scope: nil)
+      unless [true, false, nil].include?(new_idempotency_key)
+        raise ArgumentError, "new_idempotency_key must be true or false"
+      end
 
-    def initialize(message, retryable: nil, kind: nil, details: nil)
       @retryable = retryable
       @kind = kind
       @details = details
+      @new_idempotency_key = new_idempotency_key == true
+      @idempotency_scope = idempotency_scope
       super(message)
     end
   end
@@ -127,6 +207,141 @@ module Smith
     end
   end
 
+  # An `await` step passed its deadline before `resume!` delivered its
+  # event, and the transition declares no `on_timeout` route. It takes the
+  # failure path (`on_failure`, or a raise) and is never retried.
+  class WaitTimedOut < WorkflowError
+    DETAIL_NAMES = %w[transition event deadline_at].freeze
+    private_constant :DETAIL_NAMES
+
+    attr_reader :transition, :event, :deadline_at
+
+    def initialize(transition:, event:, deadline_at:, message: nil)
+      @transition = DiagnosticText.capture(transition.to_s, max_bytes: 256)
+      @event = DiagnosticText.capture(event.to_s, max_bytes: 256)
+      @deadline_at = DiagnosticText.capture(deadline_at.to_s, max_bytes: 64)
+      super(message || "await #{@event} on transition #{@transition} passed its deadline #{@deadline_at}")
+    end
+
+    # Kept with the failure record, so a restored run's error is still a
+    # WaitTimedOut that names its wait.
+    def details = { transition:, event:, deadline_at: }.freeze
+
+    def self.from_details(details, message: nil)
+      raise ArgumentError, "wait timeout details must be a Hash" unless details.is_a?(Hash)
+
+      values = details.to_h { |key, value| [key.to_s, value] }
+      unless values.keys.sort == DETAIL_NAMES.sort && values.values.all?(String)
+        raise ArgumentError, "wait timeout details are invalid"
+      end
+
+      new(transition: values["transition"], event: values["event"], deadline_at: values["deadline_at"], message:)
+    end
+  end
+
+  # A `compute` or `run` step that declares `routes:` finished without
+  # calling `route_to`, declares no `on_success`, and did not opt into
+  # `fallthrough: true`. Without this error the run would silently take the
+  # first transition declared from the step's target state.
+  class UnroutedDeterministicStep < WorkflowError
+    attr_reader :transition, :routes
+
+    def initialize(transition:, routes:)
+      @transition = transition
+      @routes = routes
+      super(
+        "#{DiagnosticText.capture(transition.inspect, max_bytes: 256)} declares routes: " \
+        "#{DiagnosticText.capture(routes.inspect, max_bytes: 1024)} but did not call route_to; " \
+        "route to one of them, declare on_success, or opt into fallthrough: true"
+      )
+    end
+  end
+
+  # A deterministic step wrote a context key that the workflow's
+  # Smith::Context does not list in `persist :a, :b`. The write would be
+  # dropped at the next checkpoint, so it fails the step instead.
+  class UndeclaredContextKey < WorkflowError
+    attr_reader :key, :persisted_keys
+
+    def initialize(key:, persisted_keys:)
+      @key = key
+      @persisted_keys = persisted_keys
+      super(
+        "context key #{DiagnosticText.capture(key.inspect, max_bytes: 256)} is not a persisted context key " \
+        "(persist #{DiagnosticText.capture(persisted_keys.map(&:inspect).join(", "), max_bytes: 1024)}); " \
+        "declare it in the context's persist list, or use persist :auto"
+      )
+    end
+  end
+
+  # A step's content parts cannot be sent: a document or image is missing,
+  # unreadable, empty, not what its media type says, or past a bound, or no
+  # model in the chain takes it. Raised before the provider call, so it is
+  # never retried as a provider failure.
+  class ContentUnavailable < WorkflowError; end
+
+  # No artifact store is configured. Artifacts must outlive the process that
+  # stored them whenever a run waits, retries or resumes elsewhere, so Smith
+  # assumes none outside test_mode.
+  class ArtifactStoreMissing < WorkflowError
+    def initialize(message = "Smith.config.artifact_store is not configured; set it to :s3, :active_record or " \
+                             ":file (or a store) for runs that wait, retry or move between processes, or :memory " \
+                             "for a single process")
+      super
+    end
+  end
+
+  # A step streams to a sink Smith.config.stream_sinks does not name.
+  # Raised before the step's provider call.
+  class StreamSinkMissing < WorkflowError
+    def initialize(name)
+      super("Smith.config.stream_sinks has no sink #{name.inspect}; register the sink the step streams to")
+    end
+  end
+
+  # A step sends its request as a batch and Smith.config.batch_queue is not
+  # configured. Raised before anything is sent.
+  class BatchQueueMissing < WorkflowError
+    def initialize(message = "Smith.config.batch_queue is not configured; batch mode hands its requests to it")
+      super
+    end
+  end
+
+  # A batch step's call cannot go as a batch: its model's provider has no
+  # batch interface in Smith (Anthropic has), or its agent has tools (a batch
+  # request is one turn). Raised before anything is sent.
+  class BatchModeUnavailable < WorkflowError; end
+
+  # A batch result that did not answer: a server error (`errored`), a
+  # `canceled` or `expired` request, or none by the wait's deadline
+  # (`missing`). An AgentError, so `retry_on` sends it again.
+  class BatchResultFailed < AgentError
+    attr_reader :kind, :error_type
+
+    def initialize(kind:, error_type: nil)
+      @kind = kind.to_s.dup.freeze
+      @error_type = DiagnosticText.capture(error_type.to_s, max_bytes: 128) if error_type
+      super("batch result #{@kind}#{" (#{@error_type})" if @error_type}")
+    end
+  end
+
+  # A batch result answers a request other than the one its step renders
+  # now (a date in the prompt, data read afresh, a changed prompt), and the
+  # step declares `on_request_change: :fail`. An AgentError, so `retry_on`
+  # may send the request again (synchronously, if the mode callable says so
+  # at the next attempt); the result is charged all the same.
+  class BatchRequestChanged < AgentError
+    def initialize(message = "the step renders another request than its batch result answers") = super
+  end
+
+  # The provider refused a batch request as invalid; sending it again would
+  # be refused again.
+  class BatchRequestInvalid < WorkflowError
+    def initialize(message = "the provider refused the batch request as invalid")
+      super
+    end
+  end
+
   class SerializationError < Error; end
   class AgentRegistryError < Error; end
 
@@ -144,6 +359,42 @@ module Smith
     end
   end
 
+  # A workflow state past Smith.config.persistence_max_bytes. A stored
+  # run's step whose result would not fit fails with it before the result
+  # is kept (its usage recorded, `on_failure` taken; a response memo keeps
+  # what its calls got). Any other state past the bound is refused when it
+  # is stored, before anything is written, and the stored state stays as it
+  # was.
+  class PersistedStateTooLarge < WorkflowError
+    DETAIL_NAMES = %w[key bytes limit].freeze
+
+    attr_reader :key, :bytes, :limit
+
+    def initialize(key:, bytes:, limit:, message: nil)
+      @key = key
+      @bytes = bytes
+      @limit = limit
+      super(message || "the workflow state for #{key.inspect} is #{bytes} bytes, past persistence_max_bytes (#{limit})")
+    end
+
+    def details = { key:, bytes:, limit: }.freeze
+
+    def self.from_details(details, message: nil)
+      raise ArgumentError, "state size details must be a Hash" unless details.is_a?(Hash)
+
+      values = details.to_h { |name, value| [name.to_s, value] }
+      raise ArgumentError, "state size details are invalid" unless details?(values)
+
+      new(key: values["key"], bytes: values["bytes"], limit: values["limit"], message:)
+    end
+
+    def self.details?(values)
+      values.keys.sort == DETAIL_NAMES.sort && values["key"].is_a?(String) &&
+        values.values_at("bytes", "limit").all? { _1.is_a?(Integer) && _1.positive? }
+    end
+    private_class_method :details?
+  end
+
   # Raised when an adapter's optimistic-lock check detects a concurrent
   # write: another process modified the key between this process's
   # restore and persist. Hosts can rescue + restore + retry, or fail
@@ -185,15 +436,20 @@ module Smith
   # `idempotency_mode :strict`. Signals that a previous worker crashed
   # between `persist!` (before advance) and `persist!` (after advance);
   # the step's effects are unknown, so blindly re-running could
-  # double-execute non-idempotent agent calls or tools.
+  # double-execute non-idempotent agent calls or tools. `state` is the
+  # persisted state the interrupted step started from and `transition` the
+  # next transition the payload records; each is nil when unknown.
   class StepInProgressOnRestore < Error
-    attr_reader :workflow, :persistence_key
+    attr_reader :workflow, :persistence_key, :state, :transition
 
-    def initialize(workflow:, persistence_key:)
+    def initialize(workflow:, persistence_key:, state: nil, transition: nil)
       @workflow = workflow
       @persistence_key = persistence_key
+      @state = state.to_sym if state.is_a?(String) || state.is_a?(Symbol)
+      @transition = transition.to_sym if transition.is_a?(String) || transition.is_a?(Symbol)
       super(
-        "step in progress on restore for #{workflow} key=#{persistence_key.inspect}: " \
+        "step in progress on restore for #{workflow} key=#{persistence_key.inspect}" \
+        "#{" state=#{@state.inspect}" if @state}: " \
         "a previous worker crashed mid-step. Hosts using idempotency_mode :strict must " \
         "decide whether to clear the persisted state (idempotent re-run unsafe) or " \
         "switch to :lax (assume re-run is safe)."
@@ -201,6 +457,48 @@ module Smith
     end
   end
 
+  # Raised when a persisted payload's state is not one the restoring
+  # workflow class knows: neither declared with `state` nor named by any
+  # transition's `from:` or `to:`. Usually a deploy renamed or removed the
+  # state while a run was persisted. Restoring anyway would treat the
+  # unknown state as terminal and end the run silently. Hosts bridge a
+  # rename with `migrate_from`, or let the run finish on the workflow
+  # version that declared the state.
+  class UnknownStateOnRestore < Error
+    attr_reader :workflow, :persistence_key, :state
+
+    def initialize(workflow:, persistence_key:, state:)
+      @workflow = workflow
+      @persistence_key = persistence_key
+      @state = state
+      super(
+        "unknown state #{DiagnosticText.capture(state.inspect, max_bytes: 256)} restoring #{workflow} " \
+        "key=#{DiagnosticText.capture(persistence_key.inspect, max_bytes: 256)}: bump " \
+        "persistence_schema_version and declare `migrate_from` to map it, or finish the run on the " \
+        "workflow version that declared it."
+      )
+    end
+  end
+
+  # Raised when a persisted payload's pending transition is not declared by
+  # the restoring workflow class, for the same reasons as
+  # UnknownStateOnRestore.
+  class UnknownTransitionOnRestore < Error
+    attr_reader :workflow, :persistence_key, :transition
+
+    def initialize(workflow:, persistence_key:, transition:)
+      @workflow = workflow
+      @persistence_key = persistence_key
+      @transition = transition
+      super(
+        "unknown pending transition #{DiagnosticText.capture(transition.inspect, max_bytes: 256)} restoring " \
+        "#{workflow} key=#{DiagnosticText.capture(persistence_key.inspect, max_bytes: 256)}: bump " \
+        "persistence_schema_version and declare `migrate_from` to map it, or finish the run on the " \
+        "workflow version that declared it."
+      )
+    end
+  end
+
   # Raised when restoring a persisted payload whose schema_version does
   # not match the workflow's current persistence_schema_version AND no
   # migration block is registered to bridge the gap. Hosts fix this by

data/lib/smith/idempotency_key/canonical.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Smith
+  module IdempotencyKey
+    MAX_SCOPE_DEPTH = 32
+    MAX_SCOPE_NODES = 100_000
+
+    module Canonical
+      module_function
+
+      # The JSON form a scope is hashed in: Symbols become Strings, Hash
+      # entries are sorted by key, and a Float with a whole value becomes
+      # the Integer, so equal scopes give equal keys whatever their key order
+      # or numeric spelling (`12` and `12.0` from a model's JSON). Other
+      # finite Floats keep their shortest exact text. NaN, Infinity and
+      # other objects are refused, because they have no stable identity; so
+      # are scopes past MAX_SCOPE_DEPTH levels or MAX_SCOPE_NODES values,
+      # which bounds the work at O(MAX_SCOPE_NODES).
+      def value(input, budget = [MAX_SCOPE_NODES], depth = 0)
+        charge!(budget, depth)
+        case input
+        when nil, true, false, Integer then input
+        when Float then float_value(input)
+        when String, Symbol then string(input.to_s)
+        when Array then input.map { |item| value(item, budget, depth + 1) }
+        when Hash then hash_entries(input, budget, depth)
+        else
+          raise ArgumentError,
+                "idempotency key scope must be built from Strings, Symbols, numbers, booleans, nil, Arrays " \
+                "and Hashes, got #{DiagnosticText.error_class_name(input)}"
+        end
+      end
+
+      def charge!(budget, depth)
+        raise ArgumentError, "idempotency key scope is nested deeper than #{MAX_SCOPE_DEPTH} levels" if too_deep?(depth)
+        return unless (budget[0] -= 1).negative?
+
+        raise ArgumentError, "idempotency key scope has more than #{MAX_SCOPE_NODES} values"
+      end
+
+      def too_deep?(depth) = depth > MAX_SCOPE_DEPTH
+
+      def float_value(value)
+        raise ArgumentError, "idempotency key scope numbers must be finite" unless value.finite?
+
+        value == value.truncate ? value.to_i : value
+      end
+
+      def hash_entries(hash, budget, depth)
+        entries = hash.map { |key, item| [hash_key(key), value(item, budget, depth + 1)] }
+        keys = entries.map(&:first)
+        raise ArgumentError, "idempotency key scope has two keys with the same name" unless keys.uniq.size == keys.size
+
+        entries.sort_by(&:first).to_h
+      end
+
+      def hash_key(key)
+        return string(key.to_s) if key.is_a?(String) || key.is_a?(Symbol)
+
+        raise ArgumentError, "idempotency key scope Hash keys must be Strings or Symbols"
+      end
+
+      def string(string)
+        utf8 = string.encoding == Encoding::UTF_8 ? string : string.encode(Encoding::UTF_8)
+        return utf8 if utf8.valid_encoding?
+
+        raise EncodingError
+      rescue EncodingError
+        raise ArgumentError, "idempotency key scope Strings must be valid UTF-8 or convert to it"
+      end
+    end
+    private_constant :Canonical
+  end
+end

data/lib/smith/idempotency_key.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+require_relative "idempotency_key/canonical"
+
+module Smith
+  # Keys for requests a step sends outside the system, so that a replay of
+  # the step (a retry, or a restore after a crash) repeats each request
+  # under the key it used before and the receiver can drop the duplicate.
+  #
+  # A key is the SHA-256 of the run's execution namespace (a UUID assigned
+  # when the workflow is built and persisted with it), the step's position
+  # (step number and transition, then any nested workflow step, parallel or
+  # fan-out branch, optimizer round and role, or orchestrator round and
+  # task inside it) and a caller-chosen scope. It is the same on every
+  # attempt of the step, so a retry after a timeout cannot repeat a request
+  # that took effect, and after a restore. An attempt of a step that fails
+  # in a way showing its own requests took no effect can ask for new keys
+  # on the attempts after it (`fail!` with `new_idempotency_key: true`, or
+  # `retry_on ... new_idempotency_key_on:`), for receivers that store a
+  # failed reply under its key. A replay keeps its keys only when the run
+  # was persisted before the step began, as `advance_persisted!` and
+  # `run_persisted!` do. A persisted payload is a run's identity: runs
+  # built with `new` never share keys, but runs restored from copies of one
+  # payload do.
+  #
+  # Keys exist only while a step does its own work (its body, agents,
+  # tools and guardrails); event handlers and `on_step` callbacks get none.
+  # The position is thread-local state Smith carries into its own branch
+  # threads and concurrent tool calls; code in a Fiber or Thread the host
+  # creates has none, while `step.idempotency_key` works anywhere.
+  #
+  #   transition :notify, from: :reviewed, to: :notified do
+  #     compute { |step| Mailer.deliver(review, idempotency_key: step.idempotency_key) }
+  #   end
+  module IdempotencyKey
+    VERSION = "smith.idempotency.v1"
+
+    # Where execution is: the run's namespace and the path of positions
+    # inside it, deeply frozen. Internal: hosts reach keys through
+    # `current`, `step.idempotency_key` and `Tool#idempotency_key`.
+    Scope = Data.define(:run, :path) do
+      def within(*segment)
+        self.class.new(run:, path: [*path, IdempotencyKey.__send__(:own_segment, segment)].freeze)
+      end
+
+      def key(scope = nil)
+        Digest::SHA256.hexdigest(JSON.generate([VERSION, run, path, Canonical.value(scope)]))
+      end
+    end
+    private_constant :Scope
+
+    class << self
+      # The key for `scope` at the current position. Raises WorkflowError
+      # outside a running workflow step.
+      def current(scope = nil)
+        current_scope!.key(scope)
+      end
+
+      private
+
+      def root_scope(run) = Scope.new(run: run.dup.freeze, path: [].freeze)
+
+      def current_scope
+        Tool.__send__(:current_idempotency_scope)
+      end
+
+      def current_scope!
+        current_scope || raise(WorkflowError, "an idempotency key is only available inside a running workflow step")
+      end
+
+      # Narrows the current position for the block, when there is one.
+      def within(*segment, &)
+        outer = current_scope
+        return yield unless outer
+
+        swap(outer.within(*segment), &)
+      end
+
+      # Runs the block with no position, so code that is not a step's own
+      # work (event handlers, callbacks) cannot take a step's key.
+      def without(&) = swap(nil, &)
+
+      # Interrupts are deferred while the position is installed and
+      # restored, as for every other per-step thread value.
+      def swap(scope, &block)
+        raise ArgumentError, "block required" unless block
+
+        outer = current_scope
+        Thread.handle_interrupt(Object => :never) do
+          install(scope)
+          begin
+            Thread.handle_interrupt(Object => :immediate, &block)
+          ensure
+            install(outer)
+          end
+        end
+      end
+
+      def install(scope)
+        raise ArgumentError, "an idempotency position must be a Scope or nil" unless scope.nil? || scope.is_a?(Scope)
+
+        Tool.__send__(:current_idempotency_scope=, scope)
+      end
+
+      # A namespace for a payload written before namespaces were assigned at
+      # construction: derived from the payload's own durable facts, so every
+      # restore of it gets the same one, and shaped as the version 4 UUID
+      # `new` assigns.
+      def legacy_namespace(*facts)
+        hex = Digest::SHA256.hexdigest(JSON.generate([VERSION, "namespace", *facts.map(&:to_s)]))
+        variant = ((hex[16].to_i(16) & 0x3) | 0x8).to_s(16)
+        "#{hex[0, 8]}-#{hex[8, 4]}-4#{hex[13, 3]}-#{variant}#{hex[17, 3]}-#{hex[20, 12]}"
+      end
+
+      # A position segment: a label and Strings, Symbols or Integers, held
+      # as frozen copies so a caller cannot change a key after the fact.
+      def own_segment(segment)
+        segment.map do |part|
+          case part
+          when Integer then part
+          when Symbol then part.to_s.freeze
+          when String then Canonical.string(part).dup.freeze
+          else raise ArgumentError, "an idempotency position segment must be Strings, Symbols or Integers"
+          end
+        end.freeze
+      end
+
+      # Narrows the position to the `count`th copy of `value` seen under
+      # `label`, named by its content: a list a model regenerates on replay
+      # keeps each item's key whatever its order.
+      def within_content(label, value, copies, &)
+        digest = content_digest(value)
+        copies[digest] += 1
+        within(label, digest, copies[digest], &)
+      end
+
+      # A digest of a value's canonical form, for a position named by its
+      # content (an orchestrator task) rather than by its place in a list.
+      def content_digest(value) = Digest::SHA256.hexdigest(JSON.generate(Canonical.value(value)))
+    end
+  end
+end

data/lib/smith/launchers/inline.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Smith
+  module Launchers
+    # Runs each child to its end, one after another, in the parent's
+    # process, and returns their results, so the parent's step completes at
+    # once. Children run under the parent's deadline but with no tool
+    # evidence or attribution of the parent's. A child left waiting, or one
+    # that raised, is reported failed (with the error's class). For tests
+    # and scripts: a long map holds the parent's step for as long as it runs.
+    class Inline
+      def inline? = true
+
+      def launch(children:, parent_key:, await_token:) # rubocop:disable Lint/UnusedMethodArgument
+        deadline = Tool.current_deadline
+        children.map { |child| run_child(child, deadline) }
+      end
+
+      private
+
+      def run_child(child, deadline)
+        workflow = child.build
+        workflow.instance_variable_set(:@inherited_deadline, deadline) if deadline
+        run = apart { workflow.run! }
+        return failed(child, workflow.state, "waiting") if workflow.waiting?
+
+        ChildRun.result(ref: child.ref, run_result: run)
+      rescue StandardError => e
+        failed(child, nil, DiagnosticText.error_class_name(e))
+      end
+
+      def failed(child, state, error)
+        { ref: child.ref, status: "failed", state: state&.to_s, output: nil,
+          error: DiagnosticText.capture(error.to_s, max_bytes: 256) }
+      end
+
+      def apart(&)
+        tracker = Tool.current_tool_execution_tracker
+        Tool.current_tool_execution_tracker = nil
+        Attribution.carrying(nil, &)
+      ensure
+        Tool.current_tool_execution_tracker = tracker
+      end
+    end
+  end
+end