smith-agents 0.4.2 → 0.4.3

data/lib/smith/workflow.rb

@@ -6,6 +6,11 @@ require "securerandom"
 require "set"
 require "time"
 
+require_relative "workflow/agent_result"
+require_relative "workflow/branch_env"
+require_relative "workflow/run_result"
+require_relative "workflow/usage_entry"
+
 module Smith
   class Workflow
     include DSL
@@ -21,113 +26,6 @@ module Smith
 
     DEFAULT_MAX_TRANSITIONS = 100
 
-    # `keyword_init: true` is mandatory: `build_run_result` constructs
-    # the result via keyword arguments. Plain Ruby Structs treat the
-    # kwargs hash as the first positional field, silently leaving the
-    # remaining fields nil — verified empirically. The `keyword_init`
-    # flag routes kwargs to the right fields. `usage_entries` is the
-    # 10th field, added in this slice for hadithi billing.
-    RunResult = Struct.new(:state, :output, :steps, :total_cost, :total_tokens, :context, :session_messages,
-                           :tool_results, :outcome, :usage_entries, keyword_init: true) do
-      def done?
-        state == :done
-      end
-
-      def failed?
-        state == :failed
-      end
-
-      def terminal_output
-        output
-      end
-
-      def outcome_kind
-        outcome&.dig(:kind)
-      end
-
-      def outcome_payload
-        outcome&.dig(:payload)
-      end
-
-      def last_error
-        steps.reverse.map { |step| step[:error] }.compact.first
-      end
-
-      def failed_transition
-        failure_detail&.fetch(:transition)
-      end
-
-      def failure_detail
-        failed_step = steps.reverse.find { |step| step[:error] }
-        return nil unless failed_step
-
-        {
-          transition: failed_step[:transition],
-          from: failed_step[:from],
-          to: failed_step[:to],
-          error: failed_step[:error]
-        }
-      end
-    end
-
-    # keyword_init: true so adding new fields in future schema versions
-    # remains backward-compatible: `from_response` and `from_h` can fill
-    # extra fields without breaking existing call sites that pass the
-    # historical positional args. Reading old persisted records into a
-    # newer Struct shape: from_h slices to current members (unknown keys
-    # silently dropped; missing keys default to nil).
-    AgentResult = Struct.new(
-      :content, :input_tokens, :output_tokens, :cost, :model_used,
-      keyword_init: true
-    ) do
-      def self.from_response(response, content, model_used: nil)
-        new(
-          content: content,
-          input_tokens: response.respond_to?(:input_tokens) ? response.input_tokens : nil,
-          output_tokens: response.respond_to?(:output_tokens) ? response.output_tokens : nil,
-          cost: nil,
-          model_used: model_used
-        )
-      end
-
-      def usage_known?
-        !input_tokens.nil? && !output_tokens.nil?
-      end
-    end
-
-    # One row per agent provider call. `usage_id` is a UUID generated
-    # at recording time and stable across persist/restore — hadithi
-    # uses it as the idempotency anchor on `usage_events.smith_usage_id`.
-    # Includes `to_h`/`from_h` for JSON serialization (plain Struct
-    # JSON-encodes to `"#<struct ...>"` — useless).
-    #
-    # keyword_init: true gives forward/backward compatibility:
-    # - Adding a new field: old persisted hashes restore cleanly (new
-    #   field defaults to nil).
-    # - Reading new persisted hashes with an older Smith version: from_h
-    #   slices to known members (unknown keys silently dropped).
-    UsageEntry = Struct.new(
-      :usage_id,
-      :agent_name,
-      :model,
-      :input_tokens,
-      :output_tokens,
-      :cost,
-      :attempt_kind,
-      :recorded_at,
-      keyword_init: true
-    ) do
-      def self.from_h(hash)
-        sym = hash.transform_keys(&:to_sym)
-        filtered = sym.slice(*members)
-        # Symbolize :agent_name and :attempt_kind for backward compat
-        # with callers that consume the field as Symbol.
-        filtered[:agent_name] = filtered[:agent_name].to_sym if filtered[:agent_name].is_a?(String)
-        filtered[:attempt_kind] = filtered[:attempt_kind].to_sym if filtered[:attempt_kind].is_a?(String)
-        new(**filtered)
-      end
-    end
-
     # Reconstruct Smith error classes from `@last_failed_step` snapshots.
     # Order matters: more-specific subclasses first, so a real DSF doesn't
     # get caught by the WorkflowError handler. Each lambda preserves the
@@ -167,24 +65,6 @@ module Smith
     RETRYABLE_BEARING_FAMILIES = %w[deterministic_step_failure tool_guardrail_failed].freeze
     private_constant :RETRYABLE_BEARING_FAMILIES
 
-    # keyword_init: true for forward/backward compat (see UsageEntry).
-    BranchEnv = Struct.new(
-      :prepared_input, :guardrail_sources, :scoped_store, :branch_estimates, :deadline,
-      keyword_init: true
-    ) do
-      def setup_thread
-        Smith::Tool.current_guardrails = guardrail_sources
-        Smith::Tool.current_deadline = deadline
-        Smith.scoped_artifacts = scoped_store
-      end
-
-      def teardown_thread
-        Smith::Tool.current_guardrails = nil
-        Smith::Tool.current_deadline = nil
-        Smith.scoped_artifacts = nil
-      end
-    end
-
     attr_reader :state, :last_prepared_input, :session_messages, :ledger
 
     def initialize(context: {}, ledger: nil, created_at: nil)
@@ -239,12 +119,13 @@ module Smith
     end
 
     def advance!
-      max = self.class.max_transitions || DEFAULT_MAX_TRANSITIONS
-      raise MaxTransitionsExceeded if @step_count >= max
+      ensure_transition_budget!
+      @step_work_started = false
 
       transition = resolve_transition
       return if transition.nil?
 
+      @step_work_started = true
       step_result = execute_step(transition)
       @step_count += 1
       @updated_at = Time.now.utc.iso8601
@@ -274,11 +155,11 @@ module Smith
     end
 
     def done?
-      @state == :done
+      state_named?(:done)
     end
 
     def failed?
-      @state == :failed
+      state_named?(:failed)
     end
 
     def record_persisted_key!(key)
@@ -360,17 +241,40 @@ module Smith
       true
     end
 
+    def ensure_transition_budget!
+      max = self.class.max_transitions || DEFAULT_MAX_TRANSITIONS
+      raise MaxTransitionsExceeded if @step_count >= max
+    end
+
     def resolve_transition
       if @next_transition_name
         name = @next_transition_name
         @next_transition_name = nil
-        self.class.find_transition(name) ||
+        transition = self.class.find_transition(name) ||
           raise(UnresolvedTransitionError.new(name, self.class, @state))
+        validate_transition_origin!(transition)
+        transition
       else
         self.class.transitions_from(@state).first
       end
     end
 
+    def validate_transition_origin!(transition)
+      expected = transition.from
+      return if expected.nil? || expected == @state
+
+      raise WorkflowError,
+            "transition :#{transition.name} cannot run from state :#{@state}; expected :#{expected}"
+    end
+
+    def step_work_started?
+      @step_work_started == true
+    end
+
+    def state_named?(name)
+      @state == name || @state.to_s == name.to_s
+    end
+
     def build_run_result(steps)
       # `output` derivation matches existing semantics on fresh runs
       # (last non-nil step output via `compact.first`). Terminal-restore
@@ -416,8 +320,8 @@ module Smith
         # Skip const_get for retryable-bearing families. An unknown
         # subclass with a message-only constructor would const_get
         # successfully but discard the snapshot's `retryable`/`kind`/
-        # `details` (defaults to nil), and hadithi's `retryable?`
-        # check would misclassify a retryable failure as terminal.
+        # `details` (defaults to nil), and host retry classification
+        # could misclassify a retryable failure as terminal.
         # Family fallback rebuilds the parent class with kwargs intact.
         family_fallback(snap)
       else
@@ -436,9 +340,9 @@ module Smith
       # symbols; JSON round-trip stringifies them; coerce back to
       # match fresh-run shape exactly.
       {
-        transition: snap[:transition]&.to_sym,
-        from:       snap[:from]&.to_sym,
-        to:         snap[:to]&.to_sym,
+        transition: normalize_transition_name(snap[:transition]),
+        from:       normalize_state_name(snap[:from]),
+        to:         normalize_state_name(snap[:to]),
         error:      error
       }
     end
@@ -519,7 +423,7 @@ module Smith
     # `Struct#dup` is shallow — it shares mutable string fields between
     # the original and the duplicate. Smith's existing snapshot helpers
     # (`snapshot_context`, etc.) also use this round-trip pattern; the
-    # billing-facing RunResult must not alias mutable workflow state.
+    # usage-facing RunResult must not alias mutable workflow state.
     # Same rule applies to nested-workflow rollup (see
     # `nested_execution.rb`).
     def snapshot_usage_entries

data/lib/smith.rb

@@ -224,12 +224,20 @@ require_relative "smith/context/session"
 # Agent (depends on RubyLLM::Agent)
 require_relative "smith/agent"
 require_relative "smith/agent/lifecycle"
+require_relative "smith/agent/registry_binding"
 require_relative "smith/agent/registry"
 
 # Workflow (Transition, DSL, Persistence, and Execution must load before Workflow)
 require_relative "smith/workflow/transition"
 require_relative "smith/workflow/graph"
 require_relative "smith/workflow/graph_dsl"
+require_relative "smith/workflow/run_result"
+require_relative "smith/workflow/agent_result"
+require_relative "smith/workflow/usage_entry"
+require_relative "smith/workflow/branch_env"
+require_relative "smith/workflow/optimization_state"
+require_relative "smith/workflow/orchestration_state"
+require_relative "smith/workflow/worker_execution"
 require_relative "smith/workflow/dsl"
 require_relative "smith/workflow/persistence"
 require_relative "smith/workflow/durability"
@@ -254,6 +262,7 @@ require_relative "smith/workflow/execution_frame"
 require_relative "smith/workflow/pipeline"
 require_relative "smith/workflow/router"
 require_relative "smith/workflow/parallel"
+require_relative "smith/workflow/parallel/cancellation_signal"
 require_relative "smith/workflow/parallel/cancellation"
 
 # Conditional Rails integration

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: smith-agents
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.4.3
 platform: ruby
 authors:
 - Samuel Ralak
@@ -135,6 +135,8 @@ files:
 - lib/smith/agent.rb
 - lib/smith/agent/lifecycle.rb
 - lib/smith/agent/registry.rb
+- lib/smith/agent/registry/introspection.rb
+- lib/smith/agent/registry_binding.rb
 - lib/smith/artifacts.rb
 - lib/smith/artifacts/file.rb
 - lib/smith/artifacts/memory.rb
@@ -206,7 +208,9 @@ files:
 - lib/smith/types.rb
 - lib/smith/version.rb
 - lib/smith/workflow.rb
+- lib/smith/workflow/agent_result.rb
 - lib/smith/workflow/artifact_integration.rb
+- lib/smith/workflow/branch_env.rb
 - lib/smith/workflow/budget_integration.rb
 - lib/smith/workflow/claim.rb
 - lib/smith/workflow/data_volume_policy.rb
@@ -221,12 +225,22 @@ files:
 - lib/smith/workflow/execution_frame.rb
 - lib/smith/workflow/fanout_execution.rb
 - lib/smith/workflow/graph.rb
+- lib/smith/workflow/graph/contract_helpers.rb
 - lib/smith/workflow/graph/diagnostic.rb
+- lib/smith/workflow/graph/fanout_contract.rb
 - lib/smith/workflow/graph/metrics.rb
+- lib/smith/workflow/graph/nested_readiness_diagnostics.rb
+- lib/smith/workflow/graph/optimization_contract.rb
+- lib/smith/workflow/graph/orchestration_contract.rb
 - lib/smith/workflow/graph/reachability.rb
 - lib/smith/workflow/graph/reachability_diagnostics.rb
 - lib/smith/workflow/graph/reference.rb
 - lib/smith/workflow/graph/report.rb
+- lib/smith/workflow/graph/runtime_binding_diagnostic_builder.rb
+- lib/smith/workflow/graph/runtime_binding_diagnostics.rb
+- lib/smith/workflow/graph/runtime_readiness.rb
+- lib/smith/workflow/graph/runtime_readiness_metrics.rb
+- lib/smith/workflow/graph/runtime_readiness_report.rb
 - lib/smith/workflow/graph/state_diagnostics.rb
 - lib/smith/workflow/graph/targets.rb
 - lib/smith/workflow/graph/transition_diagnostics.rb
@@ -235,15 +249,21 @@ files:
 - lib/smith/workflow/graph_dsl.rb
 - lib/smith/workflow/guardrail_integration.rb
 - lib/smith/workflow/nested_execution.rb
+- lib/smith/workflow/optimization_state.rb
+- lib/smith/workflow/orchestration_state.rb
 - lib/smith/workflow/orchestrator_worker.rb
 - lib/smith/workflow/parallel.rb
 - lib/smith/workflow/parallel/cancellation.rb
+- lib/smith/workflow/parallel/cancellation_signal.rb
 - lib/smith/workflow/parallel_execution.rb
 - lib/smith/workflow/persistence.rb
 - lib/smith/workflow/pipeline.rb
 - lib/smith/workflow/retry_execution.rb
 - lib/smith/workflow/router.rb
+- lib/smith/workflow/run_result.rb
 - lib/smith/workflow/transition.rb
+- lib/smith/workflow/usage_entry.rb
+- lib/smith/workflow/worker_execution.rb
 - script/profile_tool_results.rb
 - sig/smith.rbs
 homepage: https://github.com/samuelralak/smith