phronomy 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e73d1b49c4638232021afad5cc807466c4bb7b2cfcfe60446930288e868a3db9
-  data.tar.gz: 624e783c532fc2ea009db99a7bda4a1308f06019bc0e776a78d206b70031b352
+  metadata.gz: 9b5c5fc2f42107629541d051e1330e90e48298ccf19192440e7be77a30b6ca68
+  data.tar.gz: 78e4440ec72afb39b7021810c8cdfc8de44f94f15d97442f91000eff50aa967c
 SHA512:
-  metadata.gz: 0ce003a8f0b0c85cd29a744b86ee89ad7414c511ea46c1ad446227824100174b6bfae76de8a4caa32428a50f77606af8006c17ae307eb514692a92829331570c
-  data.tar.gz: 10a3e965b58c730d5ba21eefc3c7151725a26e6accc24dbde04dd91546aa6c65bea801faae0fe5ef1908995a78c259159712c0f8dffe3f19938fa64b14988c16
+  metadata.gz: 79c98ed427ae1c55d245f871ba9248279199496b27535dfaca2b94d89998bfa95583c8b87a7c192f00f5143c755f6234a4f513ec37c86172ea2c286579e9b72a
+  data.tar.gz: 30d8c27a6a0a0d003da85438ee903fc73af648079c83ab42618ce53d98570b9cfaa39144a71c49e8cce77d94b0f679bb82b87b484e06e654eb8298379e8dc093

data/README.md

@@ -603,14 +603,16 @@ Understanding when to use each prevents scheduler stalls and hidden deadlocks.
 | Context | Recommended API |
 |---------|----------------|
 | Top-level application code, Rails controller, background job | `agent.invoke(input)` — blocks the calling thread until done |
-| Inside a `Runtime#spawn` block, `TaskGroup`, Workflow action, Tool `execute` | `agent.invoke_async(input).await` — non-blocking within the scheduler |
+| Workflow action / EventLoop callback | `agent.invoke_async(input).map { |r| ctx.merge(output: r[:output]) }` — returns a Task and resumes by state transition |
+| Top-level code that wants explicit async | `agent.invoke_async(input).wait_result` — blocks the calling thread until the Task completes |
 
 ### Why this matters
 
 `invoke` is a synchronous wrapper that calls `invoke_async` and then _blocks_ the calling
-thread until the task completes. When called from **inside** an active scheduler task, the
-calling task blocks the scheduler thread, preventing other tasks from making progress — a
-hidden deadlock when all scheduler threads are occupied.
+thread until the task completes.  It is intended for top-level application threads such as
+Rails controller actions, CLI scripts, or background jobs.  Inside EventLoop-driven
+workflow actions, return a Task and let `Task#map` / `Task#on_complete` drive the next
+state transition instead of waiting inside the EventLoop thread.
 
 ### Runtime guard
 
@@ -630,14 +632,21 @@ You can also query the current context directly:
 Phronomy::Runtime.in_scheduler_context?  # => true if called from inside a task
 ```
 
-### Migration: invoke → invoke_async
+### Migration: blocking wait → Task mapping
 
 ```ruby
-# Before (blocks scheduler if called from inside a task)
+# Top-level synchronous use
 result = my_agent.invoke("Hello")
 
-# After (safe inside tasks and TaskGroups)
-result = my_agent.invoke_async("Hello").await
+# Explicit async from top-level code
+result = my_agent.invoke_async("Hello").wait_result
+
+# Workflow action / EventLoop-safe use
+NODE = ->(ctx) {
+  my_agent.invoke_async("Hello").map { |result|
+    ctx.merge(answer: result[:output])
+  }
+}
 ```
 
 ### :immediate backend (synchronous / test mode)

data/benchmark/bench_agent_invoke.rb

@@ -39,6 +39,7 @@ class BenchStubChat
   def with_temperature(_) = self
   def with_cache_instructions(_) = self
   def with_output_schema(_) = self
+  def on_tool_call(&) = self
   def last_message = @response
 
   def ask(_)

data/lib/phronomy/agent/base.rb

@@ -1,11 +1,9 @@
 # frozen_string_literal: true
 
 require "securerandom"
-require_relative "checkpoint_store"
 require_relative "concerns/retryable"
 require_relative "concerns/filterable"
 require_relative "concerns/before_completion"
-require_relative "concerns/suspendable"
 require_relative "concerns/error_translation"
 
 module Phronomy
@@ -36,7 +34,6 @@ module Phronomy
       include Concerns::Retryable
       include Concerns::Filterable
       include Concerns::BeforeCompletion
-      include Concerns::Suspendable
       include Concerns::ErrorTranslation
 
       class << self
@@ -376,25 +373,21 @@ module Phronomy
           end
         end
 
-        # Resumes a suspended invocation identified by +checkpoint+ without
-        # requiring the original agent instance to be kept in memory.
+        # Continues a suspended invocation identified by +session_id+.
         #
-        # Validates that the checkpoint was created by this agent class, then
-        # instantiates a fresh agent and delegates to {Suspendable#resume}.
+        # Instantiates a fresh agent and delegates to the instance-level #approve.
+        # When +approved: false+, the agent rejects the pending tool call and ends
+        # the invocation.
         #
-        # @param checkpoint [Phronomy::Agent::Checkpoint]
+        # @param session_id [String] the session_id from the suspended result hash
         # @param approved   [Boolean] +true+ to execute the pending tool; +false+ to deny
         # @param config     [Hash] same runtime options as {#invoke}
         # @return [Hash] same shape as {#invoke} — may contain +suspended: true+ if
         #   another approval-required tool is encountered during continuation
-        # @raise [ArgumentError] when +checkpoint.agent_class+ does not match this class
+        # @raise [ArgumentError] when no suspended session matches +session_id+
         # @api public
-        def resume(checkpoint, approved:, config: {})
-          if checkpoint.agent_class && checkpoint.agent_class != name
-            raise ArgumentError,
-              "checkpoint belongs to #{checkpoint.agent_class}, cannot resume with #{name}"
-          end
-          new.resume(checkpoint, approved: approved, config: config)
+        def approve(session_id, approved: true, config: {})
+          new.approve(session_id, approved: approved, config: config)
         end
       end
 
@@ -416,6 +409,35 @@ module Phronomy
         @_handoff_tools || []
       end
 
+      # Registers a synchronous approval callback that is invoked before
+      # executing any tool that has +requires_approval true+ set.
+      # The block receives the tool name (String) and the arguments Hash, and
+      # must return a truthy value to allow execution.
+      # Returning a falsy value causes the tool to return a denial message.
+      #
+      # When no handler is registered and a tool with +requires_approval+ is
+      # called, #invoke returns a suspended result hash containing a
+      # +session_id+. Call #approve to continue execution.
+      #
+      # @example
+      #   agent.on_approval_required { |tool_name, args| prompt_user(tool_name, args) }
+      # @return [self]
+      # @api public
+      def on_approval_required(&block)
+        @approval_handler = block
+        self
+      end
+
+      # Registers a scope policy callable for this agent instance.
+      #
+      # The callable receives +(tool_class, scope, agent)+ and must return
+      # +:allow+, +:reject+, or +:approve+.
+      #
+      # @param policy [#call]
+      # @return [void]
+      # @api public
+      attr_writer :scope_policy
+
       # Invokes the agent with the given input and returns a result Hash.
       # Applies the retry policy configured via {.retry_policy} when transient
       # errors occur. {Phronomy::FilterBlockError} is never retried.
@@ -468,7 +490,10 @@ module Phronomy
 
         timeout_sec = self.class.invoke_timeout
         unless timeout_sec
-          return invoke_async(input, messages: messages, thread_id: thread_id, config: config).await
+          return trace("agent.invoke", input: input, **_build_caller_meta(config)) do |_span|
+            result = invoke_async(input, messages: messages, thread_id: thread_id, config: config).wait_result
+            [result, result[:usage]]
+          end
         end
 
         # invoke_timeout: create a CancellationScope with deadline, pass its token
@@ -482,7 +507,7 @@ module Phronomy
         # Bridge the task result to an AsyncQueue so scope.pop_queue can observe the deadline.
         completion_queue = Phronomy::Concurrency::AsyncQueue.new
         Phronomy::Runtime.instance.spawn(name: "invoke-timeout-bridge:#{(self.class.name || "agent").downcase}") do
-          completion_queue.push(task.await)
+          completion_queue.push(task.wait_result)
         rescue => e
           completion_queue.push(e)
         end
@@ -508,7 +533,7 @@ module Phronomy
       #
       # @example
       #   task = agent.invoke_async("Hello!")
-      #   result = task.await   # => { output: "...", messages: [...], usage: ... }
+      #   result = task.wait_result   # => { output: "...", messages: [...], usage: ... }
       #
       # @param input    [String, Hash]
       # @param messages [Array]
@@ -524,11 +549,11 @@ module Phronomy
         bp = Phronomy.configuration.backpressure
         on_full = (bp == :raise) ? :reject : (bp || :wait)
         bp_timeout = Phronomy.configuration.backpressure_timeout
+        result_task = Phronomy::Task.deferred(name: "agent-#{(self.class.name || "anonymous").downcase}-async")
         gate = Phronomy::Runtime.instance.gate(:agent)
-        Phronomy::Runtime.instance.spawn(name: "agent-#{(self.class.name || "anonymous").downcase}-async") do
-          gate.acquire(on_full: on_full, timeout: bp_timeout) do
-            _invoke_impl(input, messages: messages, thread_id: thread_id, config: config)
-          end
+        gate.acquire(on_full: on_full, timeout: bp_timeout) do
+          _start_invoke_attempt(result_task, input, messages: messages, thread_id: thread_id, config: config, attempt: 0)
+          return result_task
         end
       end
 
@@ -809,35 +834,154 @@ module Phronomy
       end
       protected :instance_knowledge_chunks
 
-      # Performs a single (non-retried) invocation. Extracted so that #invoke can
-      # wrap it in a retry loop without duplicating the LLM interaction logic.
-      def invoke_once(input, messages: [], thread_id: nil, config: {})
-        trace("agent.invoke", input: input, **_build_caller_meta(config)) do |_span|
-          input = run_input_filters!(input)
-
-          user_message = extract_message(input)
-          chat = build_chat
-          context = build_context(
-            input,
-            messages: messages, thread_id: thread_id, config: config,
-            budget: build_token_budget, instruction: build_instructions(input),
-            tools: self.class.tools + _handoff_tools
+      # Runs the agent invocation through the FSM-based execution engine.
+      # Called by Retryable#_invoke_impl (which wraps it in a retry loop).
+      # Returns the result hash: { output:, messages:, usage: } on success,
+      # or { suspended: true, session_id:, messages: } when awaiting approval.
+      # @api private
+      def _invoke_via_fsm(input, messages: [], thread_id: nil, config: {})
+        effective_config = thread_id ? config.merge(thread_id: thread_id) : config
+        # Fail fast when the token is already cancelled before any LLM call.
+        check_cancellation!(effective_config, "invocation cancelled")
+        # Ensure EventLoop is running. start is idempotent when already alive.
+        Phronomy::EventLoop.instance.start
+        trace("agent.invoke", input: input, **_build_caller_meta(effective_config)) do |_span|
+          session = Agent::InvocationSession.build(
+            agent: self,
+            input: input,
+            messages: messages,
+            config: effective_config
           )
-          _apply_context_to_chat(chat, context)
+          completion_queue = Phronomy::EventLoop.instance.register(session)
+          ctx = completion_queue.pop
+          raise ctx if ctx.is_a?(Exception)
+          result = _extract_invoke_result(ctx, session.id)
+          [result, result[:usage]]
+        end
+      end
 
-          run_before_completion_hooks!(chat, config)
-          _register_suspension_hook!(chat)
-          check_cancellation!(config, "invocation cancelled before LLM call")
+      # Starts a single invocation attempt and wires retry/translation onto result_task.
+      # Non-blocking: registers with EventLoop and returns immediately.
+      # On error, retries via timer_queue when policy allows; otherwise translates
+      # and resolves result_task as failed.
+      # @api private
+      def _start_invoke_attempt(result_task, input, messages:, thread_id:, config:, attempt:)
+        effective_config = thread_id ? config.merge(thread_id: thread_id) : config
+        check_cancellation!(effective_config, "invocation cancelled")
+        Phronomy::EventLoop.instance.start
+        session = Agent::InvocationSession.build(
+          agent: self,
+          input: input,
+          messages: messages,
+          config: effective_config
+        )
+        source_task = Phronomy::Task.deferred(name: "#{result_task.name}-attempt-#{attempt}")
+        Phronomy::EventLoop.instance.register(session, completion: source_task)
+        session_id = session.id
+        policy = self.class._retry_policy
+
+        source_task.on_complete do |ctx, error|
+          retriable = error &&
+            !error.is_a?(Phronomy::FilterBlockError) &&
+            !error.is_a?(Phronomy::CancellationError) &&
+            policy && attempt < policy[:times]
+
+          if retriable
+            wait = compute_agent_retry_wait(policy[:wait], policy[:base], attempt)
+            # Call _sleep_proc for instrumentation (test spy records the duration;
+            # in production this is a no-op since timer_queue handles the actual delay).
+            self.class._sleep_proc.call(wait) if wait > 0
+            do_retry = -> {
+              _start_invoke_attempt(
+                result_task, input,
+                messages: messages, thread_id: thread_id, config: config,
+                attempt: attempt + 1
+              )
+            }
+            if wait > 0
+              Phronomy::Runtime.instance.timer_queue.schedule(seconds: wait, &do_retry)
+            else
+              do_retry.call
+            end
+          elsif error
+            begin
+              translate_and_reraise!(error)
+            rescue => translated
+              result_task.backend.unblock(nil, translated)
+              result_task.transition!(:failed, error: translated)
+            end
+          else
+            begin
+              result = _extract_invoke_result(ctx, session_id)
+              result_task.backend.unblock(result, nil)
+              result_task.transition!(:completed, value: result)
+            rescue => e
+              result_task.backend.unblock(nil, e)
+              result_task.transition!(:failed, error: e)
+            end
+          end
+        end
+      rescue => e
+        result_task.backend.unblock(nil, e)
+        result_task.transition!(:failed, error: e)
+      end
 
-          result, usage = _complete_with_suspension_guard(
-            chat, user_message, config,
-            thread_id: thread_id, original_input: input
-          )
-          next [result, usage] if result[:suspended]
+      # Continues a suspended invocation identified by +session_id+.
+      # When +approved: true+, executes the pending tool and continues.
+      # When +approved: false+, rejects the tool call and ends the invocation.
+      #
+      # @param session_id [String]
+      # @param approved   [Boolean]
+      # @param config     [Hash]
+      # @return [Hash]
+      # @api public
+      def approve(session_id, approved: true, config: {})
+        ctx = Agent::SuspendedSessionRegistry.fetch(session_id)
+        raise ArgumentError, "No suspended session found: #{session_id}" unless ctx
+
+        # Reset approval_required so executing_tool_action proceeds instead of
+        # re-suspending when called after the :approve FSM transition.
+        ctx.approval_required = false
+        ctx.approved = true if approved  # signals executing_tool to run the tool
+        ctx.rejected = !approved  # signals _extract_invoke_result for rejection
+
+        if approved
+          _resume_fsm(ctx, :approve)
+        else
+          _resume_fsm(ctx, :reject)
+        end
+      end
+      public :approve
 
-          filtered_output = run_output_filters!(result[:output])
-          result = result.merge(output: filtered_output) unless filtered_output.equal?(result[:output])
-          [result, usage]
+      # Builds and runs a resume FSMSession for the given context and event.
+      # @api private
+      def _resume_fsm(ctx, event)
+        session = Agent::InvocationSession.build_for_resume(
+          agent: self,
+          context: ctx,
+          resume_event: event,
+          resume_phase: :awaiting_approval
+        )
+        completion_queue = Phronomy::EventLoop.instance.register(session)
+        resumed_ctx = completion_queue.pop
+        raise resumed_ctx if resumed_ctx.is_a?(Exception)
+        _extract_invoke_result(resumed_ctx, session.id)
+      end
+
+      # Interprets the InvocationContext after FSM completion/halt and returns
+      # the appropriate result hash or raises the block error.
+      # @api private
+      def _extract_invoke_result(ctx, session_id)
+        if ctx.phase == :awaiting_approval
+          Agent::SuspendedSessionRegistry.store(session_id, ctx)
+          {suspended: true, session_id: session_id, messages: ctx.messages}
+        elsif ctx.input_blocked? || ctx.output_blocked?
+          raise ctx.block_error
+        elsif ctx.rejected
+          # Rejected path: :reject event → :blocked terminal
+          {rejected: true, messages: ctx.messages}
+        else
+          {output: ctx.output, messages: ctx.messages, usage: ctx.usage}
         end
       end
 
@@ -858,36 +1002,6 @@ module Phronomy
         context[:messages].each { |msg| chat.messages << msg }
       end
 
-      # Submits the LLM call via LLMAdapter and handles SuspendSignal.
-      # Sets/clears the chat cancellation token around the call so that
-      # ParallelToolChat can observe cancellation without Thread.current.
-      # Returns [result_hash, usage_or_nil].
-      def _complete_with_suspension_guard(chat, user_message, config, thread_id:, original_input:)
-        chat.cancellation_token = config[:cancellation_token] if chat.respond_to?(:cancellation_token=)
-        begin
-          adapter = Phronomy.configuration.llm_adapter
-          response = adapter.complete_async(chat, user_message, config: config).await
-        rescue SuspendSignal => signal
-          checkpoint = Checkpoint.new(
-            checkpoint_id: SecureRandom.uuid,
-            agent_class: self.class.name,
-            requested_at: Time.now.utc,
-            thread_id: thread_id,
-            original_input: original_input,
-            messages: chat.messages.dup,
-            pending_tool_name: signal.tool_name,
-            pending_tool_args: signal.args,
-            pending_tool_call_id: signal.tool_call_id
-          )
-          return [{output: nil, suspended: true, checkpoint: checkpoint, messages: chat.messages}, nil]
-        ensure
-          chat.cancellation_token = nil if chat.respond_to?(:cancellation_token=)
-        end
-        output = response.content
-        usage = Phronomy::TokenUsage.from_tokens(response.tokens)
-        [{output: output, messages: chat.messages, usage: usage}, usage]
-      end
-
       def _drain_stream(chat, user_message, config, &block)
         adapter = Phronomy.configuration.llm_adapter
         chunk_queue = Phronomy::Concurrency::AsyncQueue.new(max_size: Phronomy.configuration.stream_queue_max_size)
@@ -900,7 +1014,7 @@ module Phronomy
           check_cancellation!(config, "invocation cancelled during streaming")
         end
 
-        response = pending.await
+        response = pending.blocking_wait
         [response.content, Phronomy::TokenUsage.from_tokens(response.tokens)]
       end
 
@@ -1059,7 +1173,7 @@ module Phronomy
             effective_name = resolved.new.name
             rejected_class = Class.new(resolved) do
               tool_name effective_name
-              define_method(:call) do |_args|
+              define_method(:call) do |_args, **_kwargs|
                 "Tool execution denied: scope :#{scope} is not permitted."
               end
             end
@@ -1085,9 +1199,9 @@ module Phronomy
           effective_name = resolved.new.name
           resolved = Class.new(resolved) do
             tool_name effective_name
-            define_method(:call) do |args|
+            define_method(:call) do |args, **kwargs|
               if handler.call(name, args)
-                super(args)
+                super(args, **kwargs)
               else
                 "Tool execution denied."
               end
@@ -1102,8 +1216,8 @@ module Phronomy
         effective_name4 = resolved.new.name
         Class.new(resolved) do
           tool_name effective_name4
-          define_method(:call) do |args|
-            result = super(args)
+          define_method(:call) do |args, **kwargs|
+            result = super(args, **kwargs)
             result_filters.inject(result) { |val, f| f.call(val, tool_name: name, args: args) }
           end
         end

data/lib/phronomy/agent/concerns/error_translation.rb

@@ -36,7 +36,7 @@ module Phronomy
           when RubyLLM::Error
             raise Phronomy::TransportError, error.message
           else
-            raise # bare re-raise preserves $! and its backtrace unchanged
+            raise error # preserve original class, message, and backtrace
           end
         end
       end

data/lib/phronomy/agent/concerns/retryable.rb

@@ -35,7 +35,11 @@ module Phronomy
           # @return [Hash, nil]
           attr_reader :_retry_policy
 
-          # Injectable sleep callable for testing (shared with Tool::Base pattern).
+          # Injectable sleep callable for testing.
+          # In the EventLoop-driven invoke path, actual delay is handled by
+          # timer_queue (non-blocking); _sleep_proc is called only as an
+          # instrumentation hook.  The default is a no-op; tests override it
+          # with a spy lambda to record sleep durations.
           # @return [#call]
           # @api private
           def _sleep_proc
@@ -59,7 +63,7 @@ module Phronomy
           policy = self.class._retry_policy
           attempt = 0
           begin
-            invoke_once(input, messages: messages, thread_id: thread_id, config: config)
+            _invoke_via_fsm(input, messages: messages, thread_id: thread_id, config: config)
           rescue Phronomy::FilterBlockError
             raise
           rescue Phronomy::CancellationError

data/lib/phronomy/agent/invocation_context.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Holds the mutable state for a single Agent#invoke execution.
+    #
+    # An InvocationContext is created at the start of each invoke call and
+    # passed through every FSM state as the context object. It plays the same
+    # role as WorkflowContext does for Workflow executions.
+    #
+    # Fields:
+    #   input                  — the (possibly filter-transformed) user input
+    #   messages               — conversation history (Array of RubyLLM::Message)
+    #   chat                   — the RubyLLM::Chat object built during :building_context
+    #   output                 — the final LLM text response
+    #   usage                  — Phronomy::TokenUsage after completion
+    #   tool_call_pending      — whether the last LLM response contained a tool call
+    #   approval_required      — whether the pending tool requires human approval
+    #   input_blocked          — whether an input filter called block!
+    #   output_blocked         — whether an output filter called block!
+    #   block_error            — the FilterBlockError raised (for :blocked terminal)
+    #   pending_tool_call      — the intercepted tool_call object (name/arguments/id)
+    #   user_message_sent      — true after the first LLM call (continuation uses nil msg)
+    #   sync_approval_handler  — true when agent has an on_approval_required block
+    #   session_id             — FSM session id (set by set_graph_metadata)
+    #   phase                  — terminal FSM phase (set by set_graph_metadata)
+    #
+    # @api private
+    class InvocationContext
+      # @return [String, Hash] user input (may be transformed by input filters)
+      attr_accessor :input
+
+      # @return [Array] conversation history
+      attr_accessor :messages
+
+      # @return [Object, nil] RubyLLM::Chat instance
+      attr_accessor :chat
+
+      # @return [String, nil] final LLM output text
+      attr_accessor :output
+
+      # @return [Phronomy::TokenUsage, nil]
+      attr_accessor :usage
+
+      # @return [Boolean] true when calling_llm returned a tool call
+      attr_accessor :tool_call_pending
+
+      # @return [Boolean] true when the pending tool requires human approval
+      attr_accessor :approval_required
+
+      # @return [Boolean] true when an input filter called block!
+      attr_accessor :input_blocked
+
+      # @return [Boolean] true when an output filter called block!
+      attr_accessor :output_blocked
+
+      # @return [Phronomy::FilterBlockError, nil]
+      attr_accessor :block_error
+
+      # @return [Object, nil] intercepted RubyLLM tool_call (name/arguments/id)
+      attr_accessor :pending_tool_call
+
+      # @return [Boolean] true after the first LLM call (continuation passes nil msg)
+      attr_accessor :user_message_sent
+
+      # @return [Boolean] true when Agent.approve was called (signals executing_tool
+      #   to execute the pending tool rather than re-suspending)
+      attr_accessor :approved
+
+      # @return [Boolean] true when the pending tool call was rejected via
+      #   Agent.approve(session_id, approved: false)
+      attr_accessor :rejected
+
+      # @return [String, nil] FSM session id (set by set_graph_metadata)
+      attr_reader :session_id
+
+      # @return [Symbol, nil] terminal FSM phase (set by set_graph_metadata)
+      attr_reader :phase
+
+      # @return [Boolean] true when agent has a synchronous on_approval_required handler
+      attr_reader :sync_approval_handler
+
+      # @return [Phronomy::Agent::Base] the agent instance driving this invocation
+      attr_reader :agent
+
+      # @return [Hash] the config hash passed to invoke
+      attr_reader :config
+
+      # @return [String, nil] thread_id from config
+      attr_reader :thread_id
+
+      # @param agent    [Phronomy::Agent::Base]
+      # @param input    [String, Hash]
+      # @param messages [Array]
+      # @param config   [Hash]
+      # @api private
+      def initialize(agent:, input:, messages:, config:)
+        @agent = agent
+        @input = input
+        @messages = Array(messages)
+        @config = config
+        @thread_id = config[:thread_id]
+        @chat = nil
+        @output = nil
+        @usage = nil
+        @tool_call_pending = false
+        @approval_required = false
+        @input_blocked = false
+        @output_blocked = false
+        @block_error = nil
+        @pending_tool_call = nil
+        @user_message_sent = false
+        @approved = false
+        @rejected = false
+        @sync_approval_handler = !agent.instance_variable_get(:@approval_handler).nil?
+        @session_id = nil
+        @phase = nil
+      end
+
+      # Called by FSMSession#finish! and FSMSession#halt! to record the
+      # terminal/halted phase and the session id.
+      # Mirrors the WorkflowContext interface so FSMSession works with both.
+      # @param thread_id [String, nil]
+      # @param phase     [Symbol, nil]
+      # @return [void]
+      # @api private
+      def set_graph_metadata(thread_id: nil, phase: nil)
+        @session_id = thread_id if thread_id
+        @phase = phase
+      end
+
+      # Guard helpers used by PhaseMachineBuilder transitions.
+
+      # @return [Boolean]
+      # @api private
+      def input_passed?
+        !@input_blocked
+      end
+
+      # @return [Boolean]
+      # @api private
+      def input_blocked?
+        @input_blocked
+      end
+
+      # @return [Boolean]
+      # @api private
+      def output_passed?
+        !@output_blocked
+      end
+
+      # @return [Boolean]
+      # @api private
+      def output_blocked?
+        @output_blocked
+      end
+
+      # @return [Boolean]
+      # @api private
+      def tool_call_pending?
+        @tool_call_pending
+      end
+
+      # @return [Boolean]
+      # @api private
+      def approval_required?
+        @approval_required
+      end
+    end
+  end
+end