smith-agents 0.10.0 → 0.12.0

data/lib/smith/workflow/split_step_persistence/composite_branch_execution.rb

@@ -46,7 +46,10 @@ module Smith
             # (execution key from the restored persistence key, the split
             # step's transition, then the branch overlay downstream).
             # Restoration is owned by within_raw_step_context's snapshot.
-            install_step_attribution(@split_step_transition) if @split_step_transition
+            if @split_step_transition
+              install_step_attribution(@split_step_transition)
+              install_step_idempotency_scope(@split_step_transition)
+            end
             with_scoped_artifacts(&block)
           end
           [output, nil]

data/lib/smith/workflow/split_step_persistence/composite_preparation.rb

@@ -33,8 +33,10 @@ module Smith
 
         def prepare_composite_input(authorization, transition, specs)
           ThreadContextSnapshot.new.around do
+            # The step's position, as in-process guardrails run with it.
+            install_step_idempotency_scope(transition)
             run_composite_input_guardrails(authorization, transition, specs)
-            agent_messages = build_session&.prepare!
+            agent_messages = step_prepared_input(transition)
             Composite::Input.build(agent_messages:, session_messages: snapshot_session_messages)
           end
         end

data/lib/smith/workflow/split_step_persistence/dispatch_claim.rb

@@ -48,6 +48,7 @@ module Smith
         end
 
         def replace_exact_dispatch!(payload)
+          check_state_size!(@split_step_persistence_key, payload)
           @split_step_adapter.replace_exact(
             @split_step_persistence_key,
             payload,

data/lib/smith/workflow/split_step_persistence/preparation.rb

@@ -70,10 +70,15 @@ module Smith
         end
 
         def prepare_claimed_persisted_step!(key, adapter)
+          raise WorkflowError, "split-step persistence cannot prepare a step while the run waits" if waiting?
+
           transition = pending_split_step_transition
           transition_name = @next_transition_name || transition&.name
           raise WorkflowError, "workflow has no pending transition" unless transition_name
 
+          refusal = "split-step persistence does not run steps that wait or launch runs"
+          raise WorkflowError, refusal if transition&.waits_or_launches?
+
           ensure_transition_budget!
           resolved_key = normalize_split_step_persistence_key(candidate_split_step_persistence_key(key))
           store = persistence_adapter!(adapter)

data/lib/smith/workflow/split_step_persistence/state_snapshot.rb

@@ -58,6 +58,7 @@ module Smith
 
         def detach_split_step_results!
           @last_output = snapshot_value(@last_output)
+          @last_transcript_output = snapshot_value(@last_transcript_output)
           @last_agent_execution = snapshot_value(@last_agent_execution)
           @last_failed_step = snapshot_value(@last_failed_step)
           @last_prepared_input = snapshot_value(@last_prepared_input)

data/lib/smith/workflow/step_completion.rb

@@ -3,26 +3,32 @@
 module Smith
   class Workflow
     module StepCompletion
+      # Room for what completing a step adds besides its output (its state,
+      # step count, last agent).
+      RESULT_MARGIN = 1024
+
       private
 
       def complete_step(transition, output)
+        StepCompletion.instance_method(:check_result_storable!).bind_call(self, output)
         step = { transition: transition.name, from: transition.from, to: transition.to, output: output }
         # Fold in the serial agent attribution captured for this step (if any),
         # then clear the transient carrier. record_step_snapshot reads these off
         # the returned step to update the durable @last_agent_execution.
-        if @pending_agent_execution
-          step[:model] = @pending_agent_execution[:model]
-          step[:provider] = @pending_agent_execution[:provider]
-        end
+        step.merge!(@pending_agent_execution.slice(:model, :provider)) if @pending_agent_execution
 
         @pending_agent_execution = nil
+        fold_pending_evaluations(step)
         result = SplitStepPersistence
                  .instance_method(:prepare_split_step_execution_result)
                  .bind_call(self, step)
-        StepCompletion.instance_method(:append_accepted_output).bind_call(self, output)
+        StepCompletion.instance_method(:keep_accepted_output).bind_call(self, transition, output)
         SplitStepPersistence
           .instance_method(:commit_split_step_execution_result!)
           .bind_call(self, result)
+        # Cleared only once the record is committed: a completion that fails
+        # before this folds the same verdicts into its failure record.
+        @pending_evaluations = nil
         @state = transition.to
         @next_transition_name = @router_next_transition || transition.success_transition
         @router_next_transition = nil
@@ -30,10 +36,37 @@ module Smith
         step
       end
 
-      def append_accepted_output(output)
-        return unless @session_messages && !output.nil?
+      # A stored run's step whose result would take its state past
+      # persistence_max_bytes fails with PersistedStateTooLarge before the
+      # result is kept, as with any error: its usage is recorded, its
+      # on_failure taken, and its run stays storable (strict mode
+      # included), where a refused store after the step would leave it
+      # unsaved. The estimate is the state's JSON and the output's, kept
+      # twice (in the context or transcript, and as the last output).
+      def check_result_storable!(output)
+        limit = Smith.config.persistence_max_bytes
+        return unless limit && @persistence_version.to_i.positive?
+
+        bytes = JSON.generate(to_state).bytesize + (JSON.generate(output).bytesize * 2) + RESULT_MARGIN
+        raise PersistedStateTooLarge.new(key: @persistence_key, bytes:, limit:) if bytes > limit
+      rescue JSON::GeneratorError, JSON::NestingError, Encoding::UndefinedConversionError
+        nil
+      end
+
+      # Once the result is captured, so a step whose result is refused leaves
+      # neither the context nor the transcript changed.
+      def keep_accepted_output(transition, output)
+        StepIO.instance_method(:deliver_output_to).bind_call(self, transition, output) if transition.output_to
+        StepCompletion.instance_method(:append_accepted_output).bind_call(self, transition, output)
+      end
+
+      # The transcript keeps an accepted output unless the step writes it to
+      # the context (`output_to:`) or the session is isolated.
+      def append_accepted_output(transition, output)
+        return unless @session_messages && !output.nil? && transcript_output?(transition)
 
         @session_messages << { role: :assistant, content: output }
+        @last_transcript_output = output
       end
     end
   end

data/lib/smith/workflow/step_context.rb

@@ -10,14 +10,17 @@ module Smith
 
       def with_step_context(transition, &block)
         ThreadContextSnapshot.new.around do
+          start_active_clock!
           setup_step_context
           install_step_attribution(transition)
+          install_step_idempotency_scope(transition)
           Thread.handle_interrupt(Object => :immediate, &block)
         rescue StandardError => e
           @outcome = nil
           GuardrailIntegration.instance_method(:handle_step_failure).bind_call(self, transition, e)
         ensure
           teardown_step_context
+          stop_active_clock!
         end
       ensure
         flush_step_failure_emission
@@ -47,12 +50,17 @@ module Smith
         end
       end
 
+      # A durable composite branch runs here, in its own restored instance:
+      # it starts from what is left of the run's wall_clock, and its running
+      # time is not added back to the run's active_seconds.
       def within_raw_step_context(&block)
         ThreadContextSnapshot.new.around do
+          start_active_clock!
           setup_step_context
           Thread.handle_interrupt(Object => :immediate, &block)
         ensure
           teardown_step_context
+          stop_active_clock!
         end
       end
 
@@ -80,6 +88,19 @@ module Smith
         )
       end
 
+      # The step's position for idempotency keys: its number and transition
+      # in this run's namespace. A nested workflow sharing the namespace (an
+      # in-process child) is placed under the parent's current position, so
+      # a child step never takes a key a parent step already used; any other
+      # workflow started inside a step is a run of its own. Restoration is
+      # owned by the surrounding ThreadContextSnapshot.
+      def install_step_idempotency_scope(transition)
+        namespace = ArtifactIntegration.instance_method(:execution_namespace).bind_call(self)
+        outer = IdempotencyKey.__send__(:current_scope)
+        base = outer && outer.run == namespace ? outer : IdempotencyKey.__send__(:root_scope, namespace)
+        IdempotencyKey.__send__(:install, base.within(:step, @step_count + 1, transition.name.to_s))
+      end
+
       def teardown_step_context
         Tool.current_guardrails = nil
         Tool.current_deadline = nil

data/lib/smith/workflow/step_io.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative "execution_result_snapshot"
+require_relative "message_batch"
+require_relative "message_value_normalizer"
+
+module Smith
+  class Workflow
+    # Per-step input and output: a step's `input:` replaces the session
+    # transcript as its messages, `output_to:` writes its output to a context
+    # key instead of the transcript, and an isolated session keeps no
+    # transcript for agents at all. Also the run's untrusted keys: its own
+    # context's, and those of every workflow it is nested in.
+    module StepIO
+      INPUT_ROLES = %w[user assistant].freeze
+      INHERITED_UNTRUSTED_KEYS = :smith_inherited_untrusted_keys
+      private_constant :INPUT_ROLES, :INHERITED_UNTRUSTED_KEYS
+
+      # Builds a nested workflow with its parent's untrusted keys in force
+      # from construction, before its seed builder runs.
+      def self.with_inherited_untrusted_keys(keys)
+        outer = Thread.current[INHERITED_UNTRUSTED_KEYS]
+        Thread.current[INHERITED_UNTRUSTED_KEYS] = untrusted_key_names!(keys)
+        yield
+      ensure
+        Thread.current[INHERITED_UNTRUSTED_KEYS] = outer
+      end
+
+      # Context key names: at most 1,000, each a Symbol or String of 1 to 256
+      # characters, as Symbols.
+      def self.untrusted_key_names!(keys)
+        valid = keys.is_a?(Array) && keys.length <= 1_000 &&
+                keys.all? { (_1.is_a?(Symbol) || _1.is_a?(String)) && _1.length.between?(1, 256) }
+        raise WorkflowError, "untrusted keys must be up to 1,000 context key names" unless valid
+
+        keys.map(&:to_sym).uniq.freeze
+      end
+
+      # The keys handed to the workflow under construction; taken once, so a
+      # workflow its constructor builds does not inherit them too.
+      def self.take_inherited_untrusted_keys
+        keys = Thread.current[INHERITED_UNTRUSTED_KEYS]
+        Thread.current[INHERITED_UNTRUSTED_KEYS] = nil
+        keys || [].freeze
+      end
+
+      private
+
+      def isolated_session? = self.class.session == :isolated
+
+      def untrusted_context_keys
+        manager = self.class.context_manager
+        own = manager.respond_to?(:untrusted_keys) ? manager.untrusted_keys : []
+        own | (@inherited_untrusted_keys || [])
+      end
+
+      # The context without its untrusted keys, as `inject_state` formatters
+      # and the `seed_messages` builder read it.
+      def trusted_context_view
+        keys = untrusted_context_keys
+        keys.empty? || !@context.is_a?(Hash) ? @context : @context.except(*keys)
+      end
+
+      # The messages an agent step sees: its `input:`, or else the session
+      # transcript (with injected state). An isolated session has no
+      # transcript to give: an agent step there must declare `input:`, and
+      # any other step gets nothing, so state is never injected.
+      def step_prepared_input(transition)
+        return step_input_messages(transition) if transition.step_input
+        return build_session&.prepare! unless isolated_session?
+        return unless transition.agent_step?
+
+        raise WorkflowError, "transition #{DiagnosticText.capture(transition.name.to_s, max_bytes: 256)} runs an " \
+                             "agent in an isolated session and must declare input:"
+      end
+
+      # A non-empty Array of at most MessageBatch::MAX_MESSAGES user and
+      # assistant messages, bounded and JSON-shaped like session messages.
+      # The callable gets a copy of the context, so it cannot change the
+      # run's.
+      def step_input_messages(transition)
+        messages = transition.step_input.call(snapshot_value(@context))
+        unless messages.is_a?(Array) && !messages.empty? && messages.length <= MessageBatch::MAX_MESSAGES
+          raise WorkflowError, "input: must return a non-empty Array of at most #{MessageBatch::MAX_MESSAGES} messages"
+        end
+
+        MessageValueNormalizer.new(messages, label: "step input").call.map { |message| step_input_message(message) }
+      end
+
+      def step_input_message(message)
+        return step_input_parts_message(message) if Message.parts?(message)
+        unless message.is_a?(Hash) && message.keys.sort == %w[content role] && INPUT_ROLES.include?(message["role"]) &&
+               !message["content"].nil?
+          raise WorkflowError, "each input: message must be { role: :user or :assistant, content: } with content"
+        end
+
+        { role: message["role"].to_sym, content: message["content"] }
+      end
+
+      # A message with content parts (Smith::Message), user or assistant.
+      def step_input_parts_message(message)
+        checked = Message.check!(message)
+        raise WorkflowError, "an input: message with content parts must be a user or assistant message" unless
+          INPUT_ROLES.include?(checked["role"])
+
+        { role: checked["role"].to_sym, content: checked["content"], parts: true }
+      end
+
+      # Checked before the step runs, so a key the persist list refuses
+      # costs no agent call.
+      def writable_output_key!(transition)
+        key = transition.output_to
+        keys = declared_persist_keys
+        raise UndeclaredContextKey.new(key:, persisted_keys: keys) if keys && !keys.include?(key)
+
+        key
+      end
+
+      # The step's output, nil included, under `output_to:`: JSON-shaped and
+      # in the context's key shape, so it reads the same live and restored.
+      def deliver_output_to(transition, output)
+        key = writable_output_key!(transition)
+        value = MessageValueNormalizer.new(output, label: "output_to: value",
+                                                   max_bytes: ExecutionResultSnapshot::MAX_BYTES).call
+        @context[key] = ContextKeys.normalize(value)
+        record_persisted_key!(key)
+      end
+
+      def transcript_output?(transition) = transition.output_to.nil? && !isolated_session?
+    end
+  end
+end

data/lib/smith/workflow/step_stream.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Smith
+  class Workflow
+    # A step declared with `stream:` streams through its sink
+    # (Smith::Streaming), which hears the step's outcome: its accepted
+    # output, a durable retry's wait, or its failure. Every other step clears
+    # the stream, so none of its calls reach another step's sink; a nested
+    # workflow is a run of its own, with its own steps.
+    #
+    # The accepted output reaches the sink once the step is stored: at once
+    # for a run that is not stored (no persistence key), else when `persist!`
+    # stores it, or when the run moves on without storing it. A store that
+    # fails tells the sink the step failed, with the store's error.
+    module StepStream
+      private
+
+      def with_step_stream(transition)
+        @step_stream = transition.stream &&
+                       Streaming.open(transition.stream, execution_key: @persistence_key, transition: transition.name)
+        step = yield
+        if wait_pending?(step) then @step_stream&.suspend
+        elsif @step_stream then accept_streamed(@step_stream, step[:output])
+        end
+        step
+      rescue Exception => e # rubocop:disable Lint/RescueException -- the sink hears of every failure, then it goes on
+        @step_stream&.fail(e.class)
+        raise
+      ensure
+        @step_stream = nil
+      end
+
+      def accept_streamed(session, output)
+        return session.finish(output) unless @persistence_key
+
+        @streamed_output = [session, output]
+      end
+
+      def deliver_streamed_output
+        session, output = @streamed_output
+        @streamed_output = nil
+        session&.finish(output)
+      end
+
+      def discard_streamed_output(error_class)
+        session, = @streamed_output
+        @streamed_output = nil
+        session&.fail(error_class)
+      end
+    end
+  end
+end

data/lib/smith/workflow/thread_context_snapshot.rb

@@ -20,6 +20,7 @@ module Smith
         current_invocation_context
         current_invocation_sequence
         current_invocation
+        current_idempotency_scope
       ].freeze
       THREAD_KEYS = %i[
         smith_attribution
@@ -28,6 +29,7 @@ module Smith
         smith_failed_agent_results
         smith_last_agent_result
         smith_parallel_agent_binding
+        smith_step_depth
       ].freeze
 
       option :tool_attributes, default: proc { TOOL_ATTRIBUTES }