smith-agents 0.10.0 → 0.12.0

data/lib/smith/workflow/graph/transition_diagnostics.rb

@@ -4,6 +4,10 @@ module Smith
   class Workflow
     class Graph
       class TransitionDiagnostics
+        TARGET_ATTRIBUTES = %i[success_transition failure_transition timeout_transition].freeze
+        DECLARATION_CHECKS = [
+          BranchLimitDiagnostic, RetryPolicyDiagnostic, IsolatedInputDiagnostic, OutputKeyDiagnostic
+        ].freeze
         attr_reader :graph
 
         def initialize(graph)
@@ -13,13 +17,11 @@ module Smith
         def to_a
           graph.transitions.values.flat_map do |transition|
             [
-              transition_target_diagnostic(transition, :success_transition, transition.success_transition),
-              transition_target_diagnostic(transition, :failure_transition, transition.failure_transition),
+              *TARGET_ATTRIBUTES.map { transition_target_diagnostic(transition, _1, transition.public_send(_1)) },
               *router_target_diagnostics(transition),
               *deterministic_route_diagnostics(transition),
               *target_state_mismatch_diagnostics(transition),
-              branch_limit_diagnostic(transition),
-              RetryPolicyDiagnostic.new(transition:).call
+              *declaration_diagnostics(transition)
             ].compact
           end
         end
@@ -63,29 +65,14 @@ module Smith
             transition.failure_transition,
             expected_state: transition.from
           )
+          timeout = target_state_mismatch_diagnostic(transition, transition.timeout_transition,
+                                                     expected_state: transition.from)
 
-          [*success, failure].compact
+          [*success, failure, timeout].compact
         end
 
-        def branch_limit_diagnostic(transition)
-          branch_count = static_branch_count(transition)
-          limit = Smith.config.parallel_branch_limit
-          return unless branch_count && branch_count > limit
-
-          Diagnostic.new(
-            severity: :error,
-            code: :parallel_branch_limit_exceeded,
-            transition: transition.name,
-            message: "Transition #{ref(transition.name)} declares #{branch_count} parallel branches, " \
-                     "exceeding the configured limit #{limit}.",
-            suggestion: "Reduce the branch count or explicitly raise Smith.config.parallel_branch_limit."
-          )
-        end
-
-        def static_branch_count(transition)
-          return transition.fanout_config.fetch(:branches).length if transition.fanout?
-
-          transition.parallel_count if transition.parallel?
+        def declaration_diagnostics(transition)
+          DECLARATION_CHECKS.map { _1.new(transition:, workflow_class: graph.workflow_class).call }
         end
 
         def successful_target_names(transition)

data/lib/smith/workflow/graph/transition_snapshot.rb

@@ -29,14 +29,23 @@ module Smith
         option :parallel_count, default: proc {}
         option :success_transition, default: proc {}
         option :failure_transition, default: proc {}
+        option :timeout_transition, default: proc {}
         option :routes, default: proc {}
         option :fallback, default: proc {}
         option :deterministic_routes, default: proc {}
+        option :deterministic_fallthrough, default: proc {}
         option :fanout_branches, default: proc {}
         option :fanout, default: proc {}
         option :optimization, default: proc {}
         option :orchestration, default: proc {}
         option :retry_policy, default: proc {}
+        option :wait, default: proc {}
+        option :input, default: proc {}
+        option :output_to, default: proc {}
+        option :stream, default: proc {}
+        option :mode, default: proc {}
+        option :on_request_change, default: proc {}
+        option :children, default: proc {}
 
         def self.from_transition(transition, workflow_class: nil)
           new(**attributes_for(transition, workflow_class: workflow_class))
@@ -56,48 +65,56 @@ module Smith
           {
             success_transition: transition.success_transition,
             failure_transition: transition.failure_transition,
+            timeout_transition: transition.timeout_transition,
             routes: transition.router_config&.fetch(:routes, nil),
             fallback: transition.router_config&.fetch(:fallback, nil),
             deterministic_routes: transition.deterministic_routes,
+            deterministic_fallthrough: transition.deterministic_routes && transition.deterministic_fallthrough == true,
             fanout_branches: transition.fanout_config&.fetch(:branches, nil)
           }
         end
 
         def self.contract_attributes(transition, workflow_class:)
           {
-            fanout: fanout_for(transition, workflow_class: workflow_class),
-            optimization: optimization_for(transition, workflow_class: workflow_class),
-            orchestration: orchestration_for(transition, workflow_class: workflow_class),
-            retry_policy: retry_policy_for(transition)
+            fanout: FanoutContract.from_transition(transition, workflow_class:),
+            optimization: OptimizationContract.from_transition(transition, workflow_class:),
+            orchestration: OrchestrationContract.from_transition(transition, workflow_class:),
+            retry_policy: retry_policy_for(transition),
+            wait: transition.await_config,
+            input: (:callable if transition.step_input),
+            output_to: transition.output_to,
+            stream: transition.stream,
+            mode: transition.batch_mode,
+            on_request_change: transition.on_request_change,
+            children: children_for(transition)
           }
         end
 
-        def self.fanout_for(transition, workflow_class:)
-          FanoutContract.from_transition(transition, workflow_class: workflow_class)
-        end
-
-        def self.optimization_for(transition, workflow_class:)
-          OptimizationContract.from_transition(transition, workflow_class: workflow_class)
-        end
+        def self.retry_policy_for(transition)
+          config = transition.retry_config
+          return unless config
 
-        def self.orchestration_for(transition, workflow_class:)
-          OrchestrationContract.from_transition(transition, workflow_class: workflow_class)
+          new_key_classes = config.fetch(:new_idempotency_key_on, [])
+          { attempts: config.fetch(:attempts), error_classes: config.fetch(:error_classes).map(&:name),
+            backoff: config.fetch(:backoff), max_delay: config[:max_delay], jitter: config.fetch(:jitter),
+            new_idempotency_key_on: (new_key_classes.map(&:name) if new_key_classes.any?),
+            durable: (true if config[:durable]) }.compact
         end
 
-        def self.retry_policy_for(transition)
-          config = transition.retry_config
+        # A map, call or spawn: its child workflow (by name), bound, collect
+        # and failure modes, and its items (a context key, or :callable).
+        def self.children_for(transition)
+          config = transition.children_config
           return unless config
 
-          {
-            attempts: config.fetch(:attempts),
-            error_classes: config.fetch(:error_classes).map(&:name),
-            backoff: config.fetch(:backoff),
-            max_delay: config[:max_delay],
-            jitter: config.fetch(:jitter)
-          }.compact
+          workflow = config[:workflow]
+          config.merge(workflow: workflow.name || workflow.inspect)
         end
 
         def self.kind_for(transition)
+          return transition.children_config.fetch(:kind) if transition.child_runs?
+          return transition.await_config.fetch(:kind) if transition.awaits?
+
           kind = KINDS.find { |_name, predicate| transition.public_send(predicate) }
           return kind.first if kind
           return :agent if transition.agent_name
@@ -106,23 +123,7 @@ module Smith
         end
 
         def to_h
-          {
-            name: name,
-            from: from,
-            to: to,
-            kind: kind,
-            parallel_count: parallel_count,
-            success_transition: success_transition,
-            failure_transition: failure_transition,
-            routes: routes,
-            fallback: fallback,
-            deterministic_routes: deterministic_routes,
-            fanout_branches: fanout_branches,
-            fanout: fanout,
-            optimization: optimization,
-            orchestration: orchestration,
-            retry_policy: retry_policy
-          }.compact
+          self.class.dry_initializer.attributes(self).compact
         end
       end
     end

data/lib/smith/workflow/graph/untrusted_input_diagnostic.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "dry-initializer"
+
+module Smith
+  class Workflow
+    class Graph
+      # An agent that names a context key the workflow's context marks
+      # untrusted among its `inputs` is refused at invocation.
+      class UntrustedInputDiagnostic
+        extend Dry::Initializer
+
+        param :graph
+        option :binding
+
+        # The context keys an agent reads as inputs: its declared `inputs`,
+        # without the reserved names Smith never reads from the context.
+        def self.context_inputs(agent_name)
+          agent_class = Agent::Registry.binding_for(agent_name)&.fetch(:agent_class)
+          inputs = agent_class.respond_to?(:inputs) ? Array(agent_class.inputs) : []
+          inputs - Agent::RESERVED_INPUT_NAMES
+        end
+
+        # The untrusted context keys a workflow class declares.
+        def self.declared_keys(workflow_class)
+          manager = workflow_class.context_manager if workflow_class.respond_to?(:context_manager)
+          manager.respond_to?(:untrusted_keys) ? manager.untrusted_keys : []
+        end
+
+        def self.suggestion(key)
+          "Pass #{Reference.format(key)} through the step's input:, wrapped with Smith::Untrusted.wrap."
+        end
+
+        def call
+          key = untrusted_input
+          return unless key
+
+          Diagnostic.new(
+            severity: :error, code: :untrusted_agent_input, transition: binding.fetch(:transition).name,
+            target: binding.fetch(:agent), message: message(key), suggestion: self.class.suggestion(key)
+          )
+        end
+
+        def untrusted_input
+          (self.class.context_inputs(binding.fetch(:agent)) & self.class.declared_keys(graph.workflow_class)).first
+        end
+
+        def message(key)
+          role = binding.fetch(:role)
+          "#{role[0].upcase}#{role[1..]} #{Reference.format(binding.fetch(:agent))} on transition " \
+            "#{Reference.format(binding.fetch(:transition).name)} declares untrusted context key " \
+            "#{Reference.format(key)} as an input."
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/graph/waiting_child_diagnostic.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    class Graph
+      # An in-process child (a nested workflow, or a child run the launcher
+      # runs in process) that reaches a step that waits, or a nested
+      # workflow that launches runs of its own.
+      module WaitingChildDiagnostic
+        def self.build(transition, label)
+          runs = transition.child_runs?
+          verb = runs ? "starts in-process runs of" : "nests"
+          Diagnostic.new(
+            severity: :error, code: :nested_workflow_waits, transition: transition.name, target: label,
+            message: "Transition #{Reference.format(transition.name)} #{verb} #{label}, " \
+                     "which reaches a step that waits#{" or launches runs of its own" unless runs}.",
+            suggestion: "An in-process child cannot wait#{" or launch" unless runs}; move the step into the parent " \
+                        "workflow#{", or use a launcher that queues children" if runs}."
+          )
+        end
+      end
+    end
+  end
+end

data/lib/smith/workflow/graph.rb

@@ -93,6 +93,7 @@ require_relative "graph/execution_successors"
 require_relative "graph/reachability"
 require_relative "graph/reachability_diagnostics"
 require_relative "graph/metrics"
+require_relative "graph/inherited_untrusted_diagnostics"
 require_relative "graph/nested_readiness_diagnostics"
 require_relative "graph/report"
 require_relative "graph/runtime_binding_diagnostic_builder"
@@ -104,6 +105,17 @@ require_relative "graph/optimization_contract"
 require_relative "graph/orchestration_contract"
 require_relative "graph/transition_snapshot"
 require_relative "graph/retry_policy_diagnostic"
+require_relative "graph/branch_limit_diagnostic"
+require_relative "graph/isolated_input_diagnostic"
+require_relative "graph/output_key_diagnostic"
+require_relative "graph/stream_diagnostic"
+require_relative "graph/batch_diagnostic"
+require_relative "graph/budget_ledger_diagnostic"
+require_relative "graph/untrusted_input_diagnostic"
+require_relative "graph/output_schema_diagnostic"
+require_relative "graph/run_launcher_diagnostic"
+require_relative "graph/waiting_child_diagnostic"
+require_relative "graph/durable_retry_diagnostic"
 require_relative "graph/transition_diagnostics"
 require_relative "graph/validator"
 require_relative "graph/runtime_readiness"

data/lib/smith/workflow/guarded_step_execution.rb

@@ -14,26 +14,71 @@ module Smith
           begin
             Thread.handle_interrupt(Object => :immediate) { run_tracked_guarded_step(transition) }
           rescue StandardError => e
-            raise unless tracker.started?
-            raise if terminal_retry_error?(e)
+            raise unless uncertain_after_tools?(tracker, e)
 
             raise ToolOutcomeUncertain.new(
               "transition failed after tool execution began; retry could replay an uncertain outcome"
             ), cause: e
           ensure
+            # Tool evidence travels up: a step running inside another step
+            # (a nested workflow's step) marks the enclosing step too, so the
+            # enclosing step is never retried over tools that already ran.
+            previous_tracker&.mark_started! if tracker.started?
             Tool.current_tool_execution_tracker = previous_tracker
           end
         end
       end
 
+      # A failure after a tool ran leaves its outcome uncertain, unless its
+      # retry could not run the tool again: a terminal failure, or a tool
+      # loop paused for budget, whose retry continues from its tools'
+      # results.
+      def uncertain_after_tools?(tracker, error)
+        tracker.started? && !terminal_retry_error?(error) &&
+          !(error.is_a?(BudgetUnavailable) && error.continuation)
+      end
+
       def run_tracked_guarded_step(transition)
         return apply_composite_reduction!(transition) if @composite_reduction
 
         @resolved_parallel_branch_count = preflight_branch_count(transition)
-        run_standard_guarded_step(transition)
+        context_before = @context.dup
+        output = run_standard_guarded_step(transition)
+        enforce_context_shape!(context_before)
+        output
       ensure
         @resolved_parallel_branch_count = nil
       end
+
+      # Hooks that receive the live context (`before_eval`,
+      # `after_completion`, guardrails) can write to it directly. At the end
+      # of the step every new top-level key must be a Symbol that an explicit
+      # `persist` list allows, and every new or replaced value takes the
+      # context's key shape. On a violation the context goes back to its
+      # top-level values from the start of the step, as a failed
+      # deterministic step keeps none of its writes. A value changed in place
+      # is not seen until the next restore normalizes it. `O(K)` plus the size
+      # of changed values.
+      def enforce_context_shape!(before)
+        allowed = declared_persist_keys
+        normalized = @context.each_with_object({}) do |(key, value), changed|
+          next if before.key?(key) && before[key].equal?(value)
+
+          admit_context_key!(key, new_key: !before.key?(key), allowed:)
+          changed[key] = ContextKeys.normalize(value)
+        end
+        @context.merge!(normalized)
+      rescue WorkflowError
+        @context.replace(before)
+        raise
+      end
+
+      def admit_context_key!(key, new_key:, allowed:)
+        ContextKeys.validate_top_level_key!(key)
+        return unless new_key && allowed && !allowed.include?(key)
+
+        raise UndeclaredContextKey.new(key:, persisted_keys: allowed)
+      end
     end
   end
 end

data/lib/smith/workflow/guardrail_integration.rb

@@ -24,6 +24,8 @@ module Smith
 
       def handle_step_failure(transition, error)
         step = { transition: transition.name, from: transition.from, to: transition.to, error: error }
+        fold_pending_evaluations(step)
+        @pending_evaluations = nil
         # Staged, not emitted: this rescue runs under the step snapshot's
         # interrupt mask, and host StepFailed handlers must not execute
         # unkillable. with_step_context flushes after the mask closes.

data/lib/smith/workflow/message_batch.rb

@@ -4,6 +4,7 @@ require "dry-initializer"
 
 require_relative "../errors"
 require_relative "message_admission"
+require_relative "message_roles"
 
 module Smith
   class Workflow
@@ -50,6 +51,11 @@ module Smith
         role = message["role"]
         reject!("each session message requires a non-empty role") unless
           role.is_a?(String) && !role.strip.empty?
+        reject!("session messages admitted by the host cannot have the system role") if role.strip.casecmp?("system")
+        reject!("session messages admitted by the host cannot carry content parts") if Message.parts?(message)
+        return if MessageRoles.role(message, MessageRoles::ADMITTED)
+
+        reject!("session messages admitted by the host must have the role user, assistant or tool")
       end
 
       def reject!(message)

data/lib/smith/workflow/message_roles.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # The roles a session message may carry, matched exactly. A host admits
+    # user, assistant and tool messages; system messages come only from
+    # Smith (injected state) and the host's `seed_messages` builder.
+    module MessageRoles
+      ALL = %w[system user assistant tool].freeze
+      ADMITTED = %w[user assistant tool].freeze
+
+      module_function
+
+      # The role of a message Hash with String or Symbol keys, when it is
+      # one of `allowed`; nil otherwise.
+      def role(message, allowed = ALL)
+        return unless message.is_a?(Hash)
+
+        value = message.key?(:role) ? message[:role] : message["role"]
+        value = value.to_s if value.is_a?(Symbol)
+        value if value.is_a?(String) && allowed.include?(value)
+      end
+    end
+  end
+end

data/lib/smith/workflow/message_value_normalizer.rb

@@ -20,6 +20,7 @@ module Smith
 
       param :value
       option :label, default: proc { "session message" }
+      option :max_bytes, default: proc { MAX_BYTES }
 
       def call
         @active = {}.compare_by_identity
@@ -100,7 +101,7 @@ module Smith
 
       def copy_string(string)
         @bytes += StringSnapshot.bytesize(string)
-        reject!("#{label} exceeds maximum bytes #{MAX_BYTES}") if @bytes > MAX_BYTES
+        reject!("#{label} exceeds maximum bytes #{max_bytes}") if @bytes > max_bytes
 
         StringSnapshot.copy(string, freeze: true)
       end

data/lib/smith/workflow/nested_execution.rb

@@ -11,18 +11,55 @@ module Smith
         check_deadline!
         child = build_child_workflow(transition.workflow_class)
         child_result = run_child_workflow(child)
+        reject_waiting_child!(child, child_result)
         handle_child_result(child_result)
       end
 
+      # A child that raises passes its error to the parent unchanged, after
+      # its billable usage is rolled up. If a tool ran in the child, the
+      # parent's step already carries that evidence and turns the failure
+      # into ToolOutcomeUncertain (GuardedStepExecution).
       def run_child_workflow(child)
         child.run!
-      rescue Smith::Error => e
-        raise WorkflowError, "nested workflow failed: #{e.message}"
+      rescue StandardError
+        roll_up_child_totals(raised_child_usage(child))
+        raise
+      end
+
+      # An in-process child cannot be left waiting inside its parent's step:
+      # its usage is kept, and the parent's step fails.
+      def reject_waiting_child!(child, child_result)
+        return unless child.waiting?
+
+        roll_up_child_totals(child_result)
+        cause = RetryWait.instance_method(:retry_wait_error).bind_call(child)
+        raise WorkflowError, "a nested workflow reached a step that waits (an await, delay or durable retry); " \
+                             "an in-process child cannot wait", cause:
+      end
+
+      RaisedChildUsage = Struct.new(:usage_entries, :total_cost, :total_tokens)
+      private_constant :RaisedChildUsage
+
+      def raised_child_usage(child)
+        RaisedChildUsage.new(child.usage_entries, child.instance_variable_get(:@total_cost),
+                             child.instance_variable_get(:@total_tokens))
+      end
+
+      # A nested workflow inherits the run's untrusted keys, and charges the
+      # run's budget ledger unless it names its own.
+      def new_nested_workflow(child_class)
+        StepIO.with_inherited_untrusted_keys(untrusted_context_keys) do
+          Budget::HostLedger.inheriting(method(:run_budget_ledger)) do
+            ResponseMemo.inheriting([*@memo_attempts, @step_attempt.to_i]) do
+              child_class.new(context: @context.dup, ledger: @ledger, created_at: @created_at)
+            end
+          end
+        end
       end
 
       def build_child_workflow(child_class)
         @split_step_active_execution_authorization&.verify_workflow!(child_class)
-        child = child_class.new(context: @context.dup, ledger: @ledger, created_at: @created_at)
+        child = new_nested_workflow(child_class)
         unless child.instance_of?(child_class)
           raise WorkflowError, "nested workflow constructor returned #{child.class} instead of #{child_class}"
         end
@@ -49,8 +86,14 @@ module Smith
       def handle_child_result(child_result)
         roll_up_child_totals(child_result)
 
+        # A child that handled its failure through its own `on_failure` route
+        # has already applied its failure policy, so the parent sees a
+        # non-retryable WorkflowError, as before.
         failed_step = child_result.steps.find { |s| s.key?(:error) }
-        raise WorkflowError, "nested workflow failed: #{failed_step[:error]&.message}" if failed_step
+        if failed_step
+          raise WorkflowError,
+                "nested workflow failed: #{DiagnosticText.capture(failed_step[:error]&.message.to_s, max_bytes: 1024)}"
+        end
 
         child_result.output
       end

data/lib/smith/workflow/optimization_state.rb

@@ -3,10 +3,10 @@
 module Smith
   class Workflow
     OptimizationState = Struct.new(
-      :config, :prepared_input, :candidate, :feedback, :last_score, :generator_class, :evaluator_class
+      :config, :prepared_input, :candidate, :feedback, :last_score, :generator_class, :evaluator_class, :evaluations
     ) do
       def initialize(config, prepared_input)
-        super(config, prepared_input, nil, nil, nil, nil, nil)
+        super(config, prepared_input, nil, nil, nil, nil, nil, [].freeze)
       end
     end
   end

data/lib/smith/workflow/orchestrator_worker.rb

@@ -40,7 +40,7 @@ module Smith
 
       def run_orchestration_loop(state)
         state.config[:max_delegation_rounds].times do |round|
-          result = run_orchestration_round(state, round)
+          result = IdempotencyKey.__send__(:within, :round, round) { run_orchestration_round(state, round) }
           return result if result
         end
 
@@ -65,12 +65,18 @@ module Smith
         invoke_agent_with_budget(state.orchestrator_class, input)
       end
 
+      # A task's position is its content, not its place in the list: a
+      # replayed orchestrator may list the same tasks in another order.
       def execute_workers(state, tasks)
         runner = method(:run_worker_with_schema)
+        output_schema = state.config[:worker_output_schema]
+        copies = Hash.new(0)
         tasks.map do |task|
           validate_task!(task, state.config[:task_schema])
-          execution = WorkerExecution.run(state.worker_class, task, state.config[:worker_output_schema], runner)
-          validate_worker_output!(execution.output, state.config[:worker_output_schema])
+          execution = IdempotencyKey.__send__(:within_content, :task, task, copies) do
+            WorkerExecution.run(state.worker_class, task, output_schema, runner)
+          end
+          validate_worker_output!(execution.output, output_schema)
           { execution_id: execution.execution_id, task: execution.task, output: execution.output }
         end
       end

data/lib/smith/workflow/parallel_execution.rb

@@ -36,6 +36,7 @@ module Smith
       def run_branch(transition, index, env, ledger, signal)
         binding = ParallelAgentBinding.new(self, transition, env.agent_class)
         with_branch_context(env, ledger, parallel_agent_binding: binding) do
+          narrow_idempotency_scope(:branch, index)
           with_agent_context(env.agent_class) do
             branch_ledger = effective_call_ledger
             reserved = reserve_branch_call(branch_ledger, env, ledger)
@@ -74,6 +75,7 @@ module Smith
           # Restoration is owned by the snapshot above, which tracks the
           # attribution thread key.
           Attribution.install(Attribution.ambient.merge(**attribution_overlay)) if attribution_overlay
+          narrow_idempotency_scope(:branch, attribution_overlay[:branch_key]) if attribution_overlay&.key?(:branch_key)
 
           unless parallel_agent_binding.equal?(NO_PARALLEL_BINDING)
             Thread.current[:smith_parallel_agent_binding] = parallel_agent_binding
@@ -84,6 +86,14 @@ module Smith
         end
       end
 
+      # Each branch of a step is a position of its own, so the same request
+      # from two branches gets two keys. Restoration is owned by the
+      # branch's ThreadContextSnapshot.
+      def narrow_idempotency_scope(*segment)
+        scope = IdempotencyKey.__send__(:current_scope)
+        IdempotencyKey.__send__(:install, scope.within(*segment)) if scope
+      end
+
       def setup_branch_context(env, ledger)
         env.setup_thread
         Tool.current_ledger = ledger