phronomy 0.7.0 → 0.7.1

data/lib/phronomy/event_loop.rb

@@ -3,12 +3,37 @@
 module Phronomy
   # Singleton event loop that manages all FSMSession instances.
   #
-  # A single background thread reads from a global Thread::Queue and dispatches
-  # events to their target FSMSession. IO work (LLM calls, tool calls) runs in
-  # separate IO threads that post events back to the loop via EventLoop#post.
+  # A single background thread reads from a global {Phronomy::AsyncQueue} and
+  # dispatches events to their target FSMSession.  IO work (LLM calls, tool
+  # calls) must be dispatched via +Runtime.instance.spawn+ or
+  # +BlockingAdapterPool+, then post results back to the loop via
+  # {EventLoop#post}.
   #
   # Activated with: +Phronomy.configure { |c| c.event_loop = true }+
   #
+  # == Threading exception (see ADR-010 Rule 2)
+  #
+  # +EventLoop+ is a **deliberate exception** to Phronomy's cooperative-first
+  # concurrency model.  Its dispatch loop is an infinite +while @running+ loop
+  # that must never block the framework's own event processing.
+  # Running it on a shared scheduler task would consume the scheduler, preventing
+  # other tasks from running.  Therefore {#start} creates a dedicated
+  # {Runtime::ThreadScheduler} — this is correct and intentional per ADR-010.
+  # No other framework component should do the same; see the ADR-010 checklist.
+  #
+  # == Handler constraints
+  #
+  # Handlers dispatched by the EventLoop run **on the EventLoop thread**.
+  # They must not:
+  #
+  # * Perform blocking operations directly (database queries, LLM calls, HTTP
+  #   requests).  Schedule blocking work via +Runtime.instance.spawn+ or
+  #   +BlockingAdapterPool+, then post results back with {#post}.
+  # * Call +Workflow#invoke+ (or any synchronous +invoke+) from within a
+  #   handler.  That method would block waiting for the EventLoop to process
+  #   events, causing a deadlock.  Use the async pattern: post a follow-up
+  #   event instead.
+  #
   # == Fork safety
   #
   # +EventLoop.instance+ is lazily initialized. The background thread is not
@@ -20,14 +45,25 @@ module Phronomy
   # Do NOT call +Workflow#invoke+ (in EventLoop mode) from within a workflow
   # entry action. The entry action runs on the EventLoop thread; a nested
   # +invoke+ would block waiting for the same thread to process events →
-  # deadlock. Use the async IO pattern instead (spawn a Thread, post events
-  # back to the EventLoop).
+  # deadlock. Use the async pattern instead: schedule work via
+  # +Runtime.instance.spawn+ or +BlockingAdapterPool+, then post events back
+  # via +Phronomy::EventLoop.instance.post(...)+.
   class EventLoop
     # Returns the singleton instance, creating and starting it on first call.
     def self.instance
       @instance ||= new.tap(&:start)
     end
 
+    # Returns true when called from within the EventLoop dispatch task.
+    # Uses a task-local key set by the Runtime-spawned dispatch task so that
+    # the check works correctly for both thread-based and future fiber-based
+    # scheduler backends.
+    # @return [Boolean]
+    # @api private
+    def self.current?
+      Phronomy::Task.current&.name == "event-loop"
+    end
+
     # Stops and destroys the singleton. Primarily used in tests.
     # @api private
     def self.reset!
@@ -36,7 +72,7 @@ module Phronomy
     end
 
     def initialize
-      @queue = Thread::Queue.new  # global event queue (thread-safe; no Mutex needed)
+      @queue = Phronomy::AsyncQueue.new  # global event queue (thread-safe; no Mutex needed)
       @fsms = {}                  # { id => FSMSession }     — EventLoop thread only
       @waiting = {}               # { id => completion_queue } — EventLoop thread only
       # Mutex-backed FSM count for drain-mode shutdown.
@@ -45,6 +81,42 @@ module Phronomy
       @fsm_count = 0
       # Token cancelled when shutdown is requested; new child sessions receive it.
       @shutdown_token = Phronomy::CancellationToken.new
+      # Fairness metrics (EventLoop thread only, except where noted)
+      @lag_mutex = Mutex.new
+      @last_lag_ns = 0
+      @max_lag_ns = 0
+      @dispatch_count = 0
+      @total_lag_ns = 0
+    end
+
+    # Returns the most recently measured event-loop lag in seconds.
+    # Lag is the wall-clock time between {#post} and the moment the event
+    # is dequeued for dispatch.  Thread-safe.
+    # @return [Float]
+    # @api private
+    def last_lag_seconds
+      @lag_mutex.synchronize { @last_lag_ns } / 1_000_000_000.0
+    end
+
+    # Returns the maximum event-loop lag seen since the loop was started.
+    # Thread-safe.
+    # @return [Float]
+    # @api private
+    def max_lag_seconds
+      @lag_mutex.synchronize { @max_lag_ns } / 1_000_000_000.0
+    end
+
+    # Returns the mean event-loop lag across all dispatched events since the
+    # loop was started.  Returns 0.0 when no events have been dispatched.
+    # Thread-safe.
+    # @return [Float]
+    # @api private
+    def average_lag_seconds
+      @lag_mutex.synchronize do
+        return 0.0 if @dispatch_count.zero?
+
+        @total_lag_ns.to_f / @dispatch_count / 1_000_000_000.0
+      end
     end
 
     # Registers an FSMSession for execution and returns a completion queue.
@@ -58,21 +130,23 @@ module Phronomy
     # the popped value will be an Exception — callers are responsible for re-raising it.
     #
     # @param fsm_session [Phronomy::FSMSession]
-    # @return [Thread::Queue] resolves to final/halted context, or an Exception
+    # @return [Phronomy::AsyncQueue] resolves to final/halted context, or an Exception
     # @api private
     def register(fsm_session)
-      if Thread.current[:phronomy_event_loop_thread]
+      if Phronomy::EventLoop.current?
         raise Phronomy::Error,
           "Cannot call Workflow#invoke (EventLoop mode) from within an EventLoop " \
-          "entry action. Use the async IO pattern: spawn a Thread, post events " \
-          "back via Phronomy::EventLoop.instance.post(...) instead."
+          "entry action. Schedule work via Runtime.instance.spawn or " \
+          "BlockingAdapterPool, then post events back via " \
+          "Phronomy::EventLoop.instance.post(...) instead."
       end
 
-      completion_queue = Thread::Queue.new
+      completion_queue = Phronomy::AsyncQueue.new
       # Pass both session and completion_queue in the event payload so that the
       # EventLoop thread is the sole writer of @fsms and @waiting.
-      @queue.push(Event.new(type: :start, target_id: fsm_session.id,
-        payload: {session: fsm_session, completion: completion_queue}))
+      @queue.push([Event.new(type: :start, target_id: fsm_session.id,
+        payload: {session: fsm_session, completion: completion_queue}),
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)])
       completion_queue
     end
 
@@ -87,60 +161,77 @@ module Phronomy
     # @return [nil]
     # @api private
     def enqueue_child(agent_fsm)
-      @queue.push(Event.new(type: :start, target_id: agent_fsm.id,
-        payload: {session: agent_fsm, completion: nil}))
+      @queue.push([Event.new(type: :start, target_id: agent_fsm.id,
+        payload: {session: agent_fsm, completion: nil}),
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)])
       nil
     end
 
     # Posts an event to the loop. Safe to call from any thread (including IO threads).
+    # The current monotonic clock time is recorded so that the EventLoop can
+    # measure the dispatch lag when it dequeues the event.
     #
+    # @note **Handler constraint**: do not perform blocking operations or call
+    #   +Workflow#invoke+ directly from within the handler that processes a
+    #   posted event.  Handlers run on the EventLoop thread; blocking there
+    #   stalls all session processing.  For blocking work, post a new event
+    #   after the result is ready.
     # @param event [Phronomy::Event]
     # @api private
     def post(event)
-      @queue.push(event)
+      @queue.push([event, Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)])
     end
 
-    # Starts the background event loop thread.
+    # Starts the EventLoop dispatch task under {Runtime} ownership.
+    #
+    # The dispatch loop runs as a {Phronomy::Task} so that {Runtime#shutdown}
+    # can drain it together with all other in-flight tasks.  The task is named
+    # +"event-loop"+ so that {.current?} can identify it via
+    # +Task.current&.name+.
     # @return [self]
     # @api private
     def start
-      return self if @thread&.alive?
+      return self if @task&.alive?
 
       # Reset shutdown state so the loop can be restarted after a stop.
       @shutdown_token = Phronomy::CancellationToken.new
       @fsm_count_mutex.synchronize { @fsm_count = 0 }
       @running = true
-      @thread = Thread.new do
-        Thread.current[:phronomy_event_loop_thread] = true
+      # The dispatch loop must always run in a real background thread.
+      # A cooperative scheduler (FakeScheduler/ImmediateBackend) executes tasks
+      # synchronously on the caller's thread, which would block forever inside
+      # the run_loop infinite loop.  Create a dedicated Runtime with
+      # ThreadScheduler to guarantee async execution regardless of the global
+      # runtime_backend setting.
+      thread_runtime = Phronomy::Runtime.new(scheduler: Phronomy::Runtime::ThreadScheduler.new)
+      @task = thread_runtime.spawn(name: "event-loop") do
         run_loop
       end
-      @thread.abort_on_exception = false
       self
     end
 
-    # Stops the background thread. Used in tests only.
+    # Stops the EventLoop dispatch task.
     #
     # Sends a cooperative shutdown sentinel to the event queue so that the
-    # worker thread can finish any in-flight handler before exiting.  Waits up
-    # to +timeout+ seconds for a clean shutdown; if the thread is still alive
-    # afterwards it is force-killed as a last resort.
+    # dispatch task can finish any in-flight handler before exiting.  Waits up
+    # to +timeout+ seconds for a clean shutdown; if the task is still alive
+    # afterwards it is cancelled (cooperative cancellation via {Task#cancel!}).
     #
     # @param timeout [Numeric] seconds to wait for cooperative shutdown. Defaults
     #   to +Phronomy.configuration.event_loop_stop_grace_seconds+ (5 s).
     # @param drain [Boolean] when +true+, wait for all active FSMSessions to
     #   complete before signalling the loop to stop.  Bounded by +timeout+.
     #   Defaults to +false+.
-    # @param force_kill [Boolean] when +true+, the worker thread is killed with
-    #   +Thread#kill+ if it does not stop within +timeout+. When +false+
-    #   (default), the thread is never killed; the method returns +:timeout+
-    #   instead. +false+ is safer for production because +Thread#kill+ can
-    #   interrupt +ensure+ blocks.
+    # @param force_kill [Boolean] deprecated — retained for backward compatibility.
+    #   When +true+, the dispatch task is cancelled via {Task#cancel!} if it does
+    #   not stop within +timeout+.  +Thread#kill+ is no longer used; cooperative
+    #   cancellation (raising {CancellationError}) replaces it.
     # @return [Symbol] shutdown status:
     #   - +:clean+ — loop exited cooperatively with no active sessions discarded
     #   - +:drained_with_discards+ — drain mode requested but sessions remained;
     #     they were discarded and the loop was stopped
-    #   - +:timeout+ — the worker thread did not stop in time and +force_kill:+ is +false+
-    #   - +:force_killed+ — the worker thread did not stop in time and was killed
+    #   - +:timeout+ — the task did not stop in time and +force_kill:+ is +false+
+    #   - +:force_killed+ — the task was cancelled because it did not stop in time
     # @api private
     def stop(timeout: Phronomy.configuration.event_loop_stop_grace_seconds, drain: false, force_kill: false)
       @shutdown_token.cancel!
@@ -160,31 +251,31 @@ module Phronomy
       end
 
       @running = false
-      @queue.push(:__stop__)   # unblock queue.pop so the worker can see @running = false
+      @queue.push(:__stop__)   # unblock queue.pop so the task can see @running = false
       begin
-        @thread&.join(timeout)
+        @task&.join(timeout)
       rescue
-        # Thread may have terminated with an exception (e.g. simulated crash in
-        # tests). Suppress the re-raise so the cleanup below always runs.
+        # Task may have terminated with an error (e.g. simulated crash in tests).
+        # Suppress the re-raise so the cleanup below always runs.
         nil
       end
-      if @thread&.alive?
+      if @task&.alive?
         if force_kill
           Phronomy.configuration.logger&.warn(
-            "[Phronomy] EventLoop thread did not stop within #{timeout}s; force-killing. " \
+            "[Phronomy] EventLoop task did not stop within #{timeout}s; cancelling. " \
             "This is a last resort — check for blocking operations in event handlers."
           )
-          @thread.kill
+          @task.cancel!
           status = :force_killed
         else
           Phronomy.configuration.logger&.warn(
-            "[Phronomy] EventLoop thread did not stop within #{timeout}s; abandoning " \
+            "[Phronomy] EventLoop task did not stop within #{timeout}s; abandoning " \
             "(force_kill: false). Check for blocking operations in event handlers."
           )
           status = :timeout
         end
       end
-      @thread = nil
+      @task = nil
       status
     end
 
@@ -192,14 +283,22 @@ module Phronomy
 
     def run_loop
       while @running
-        event = @queue.pop
+        item = @queue.pop
         # :__stop__ is used purely as an unblock signal for @queue.pop; the
         # actual stop condition is @running == false (set before the push).
         # Treating it as `next` instead of `break` prevents a stale sentinel
         # (left by a previous stop call that raced with thread start) from
         # immediately terminating a freshly restarted EventLoop.
-        next if event == :__stop__
+        next if item == :__stop__
 
+        # item is [event, posted_at_ns] — unwrap and measure lag
+        event, posted_at_ns = item
+        dequeued_at_ns = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+        lag_ns = dequeued_at_ns - posted_at_ns
+        update_lag_metrics(lag_ns)
+        check_starvation_lag(lag_ns, event)
+
+        dispatch_start_ns = dequeued_at_ns
         case event.type
         when :finished, :halted, :error
           # All three terminal events share the same cleanup path.
@@ -244,11 +343,50 @@ module Phronomy
                  "no handler for target_id #{event.target_id.inspect}"
           end
         end
+
+        # Check how long this dispatch took; warn if it exceeds the threshold.
+        check_dispatch_time(dispatch_start_ns, event)
       end
     rescue => e
       # Unblock all waiting callers if the loop dies unexpectedly.
       @waiting.values.each { |cq| cq.push(e) }
       raise
     end
+
+    def update_lag_metrics(lag_ns)
+      @lag_mutex.synchronize do
+        @last_lag_ns = lag_ns
+        @max_lag_ns = lag_ns if lag_ns > @max_lag_ns
+        @total_lag_ns += lag_ns
+        @dispatch_count += 1
+      end
+    end
+
+    def check_starvation_lag(lag_ns, event)
+      threshold = Phronomy.configuration.event_loop_starvation_threshold_seconds
+      return unless threshold && lag_ns > (threshold * 1_000_000_000)
+
+      Phronomy.configuration.logger&.warn do
+        "[Phronomy::EventLoop] Starvation detected: event #{event.type.inspect} " \
+        "for target #{event.target_id.inspect} waited " \
+        "#{format("%.3f", lag_ns / 1_000_000_000.0)}s in queue " \
+        "(threshold: #{threshold}s)"
+      end
+    end
+
+    def check_dispatch_time(dispatch_start_ns, event)
+      threshold = Phronomy.configuration.event_loop_dispatch_threshold_seconds
+      return unless threshold
+
+      elapsed_ns = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) - dispatch_start_ns
+      return unless elapsed_ns > (threshold * 1_000_000_000)
+
+      Phronomy.configuration.logger&.warn do
+        "[Phronomy::EventLoop] Long dispatch: event #{event.type.inspect} " \
+        "for target #{event.target_id.inspect} took " \
+        "#{format("%.3f", elapsed_ns / 1_000_000_000.0)}s on the EventLoop thread " \
+        "(threshold: #{threshold}s). Consider moving blocking work to BlockingAdapterPool."
+      end
+    end
   end
 end

data/lib/phronomy/fsm_session.rb

@@ -49,12 +49,13 @@ module Phronomy
     # @param external_events     [Hash]          { event_name => [{from:, to:, guard:}] }
     # @param phase_machine_class [Class]         state_machines-backed phase tracker class
     # @param recursion_limit     [Integer]
+    # @param action_timeouts     [Hash]          { state_name => seconds }
     # @param resume_event        [Symbol, nil]   external event to fire when resuming
     # @param resume_phase        [Symbol, nil]   wait state name to resume from
     # @api private
     def initialize(id:, context:, entry_point:, entry_actions:, auto_state_set:,
       declared_states:, wait_state_names:, external_events:, phase_machine_class:,
-      recursion_limit:, resume_event: nil, resume_phase: nil)
+      recursion_limit:, action_timeouts: {}, resume_event: nil, resume_phase: nil)
       @id = id
       @ctx = context
       @entry_point = entry_point
@@ -65,6 +66,7 @@ module Phronomy
       @external_events = external_events
       @phase_machine_class = phase_machine_class
       @recursion_limit = recursion_limit
+      @action_timeouts = action_timeouts
       @resume_event = resume_event
       @resume_phase = resume_phase
       @step = 0
@@ -91,23 +93,58 @@ module Phronomy
         @tracker.context = @ctx
         (@entry_actions[@current_state] || []).each do |c|
           result = c.call(@ctx)
-          @ctx = result if result.is_a?(Phronomy::WorkflowContext)
+          if result.is_a?(Phronomy::Task)
+            # Awaitable action: spawn a task to await without blocking EventLoop.
+            @tracker.async_pending = true
+            session_id = @id
+            current_state_name = @current_state
+            timeout_secs = @action_timeouts[current_state_name]
+            Phronomy::Runtime.instance.spawn(name: "fsm-await-#{session_id}") do
+              if timeout_secs
+                if result.join(timeout_secs).nil?
+                  result.cancel!
+                  raise Phronomy::ActionTimeoutError,
+                    "Action in state #{current_state_name.inspect} timed out after #{timeout_secs}s"
+                end
+              end
+              task_result = result.await
+              if task_result.is_a?(Phronomy::WorkflowContext)
+                event_loop.post(Event.new(type: :action_completed, target_id: session_id, payload: task_result))
+              else
+                event_loop.post(Event.new(type: :state_completed, target_id: session_id, payload: nil))
+              end
+            rescue => e
+              event_loop.post(Event.new(type: :error, target_id: session_id, payload: e))
+            end
+            break # Only one async action at a time per state
+          elsif result.is_a?(Phronomy::WorkflowContext)
+            @ctx = result
+          end
         end
         @tracker.context = @ctx
-        advance_or_halt
+        advance_or_halt unless @tracker.async_pending
       end
     rescue => e
       finish_with_error(e)
     end
 
     # Processes an event dispatched from EventLoop.
-    # Called for :state_completed and all user-defined external events.
+    # Called for :state_completed, :action_completed, and all user-defined external events.
     #
     # @param event [Phronomy::Event]
     # @api private
     def handle(event)
       return if @done
 
+      if event.type == :action_completed
+        # An awaitable entry action completed: update context and advance.
+        @ctx = event.payload if event.payload.is_a?(Phronomy::WorkflowContext)
+        @tracker.context = @ctx
+        @tracker.async_pending = false  # Reset flag set by start or fire_and_advance!
+        advance_or_halt
+        return
+      end
+
       fire_and_advance!(event.type)
     rescue => e
       finish_with_error(e)
@@ -129,6 +166,15 @@ module Phronomy
       # When next_phase == @current_state, no transition matched → treat as terminal.
       @current_state = (next_phase == @current_state) ? FINISH : next_phase
       @step += 1
+
+      # If an entry action returned a Task, the after_transition callback set
+      # async_pending = true and spawned a thread. Skip advance_or_halt — the
+      # background thread will post :action_completed or :state_completed.
+      if @tracker.async_pending
+        @tracker.async_pending = false
+        return
+      end
+
       advance_or_halt
     end
 

data/lib/phronomy/guardrail/prompt_injection_guardrail.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Guardrail
+    # Detects potential prompt injection attempts in the agent input.
+    #
+    # Prompt injection is an attack where an adversary embeds LLM instructions
+    # inside data sources (e.g. RAG chunks, tool results, user input) to override
+    # the agent's intended behaviour.
+    #
+    # This guardrail scans the input string for common injection patterns and
+    # calls {#fail!} when a match is found.  It is intended to be registered as
+    # an input guardrail on agents that consume untrusted external content.
+    #
+    # @example
+    #   class MyAgent < Phronomy::Agent::Base
+    #     model "gpt-4o"
+    #     input_guardrails Phronomy::Guardrail::PromptInjectionGuardrail.new
+    #   end
+    #
+    # @example Custom patterns
+    #   guard = Phronomy::Guardrail::PromptInjectionGuardrail.new(
+    #     extra_patterns: [/exfiltrate/i]
+    #   )
+    class PromptInjectionGuardrail < InputGuardrail
+      # Common prompt injection / jailbreak patterns.
+      DEFAULT_PATTERNS = [
+        /ignore\s+(previous|prior|all)\s+instructions?/i,
+        /disregard\s+(previous|prior|all)\s+instructions?/i,
+        /forget\s+(previous|prior|all)\s+instructions?/i,
+        /override\s+(previous|prior|all)\s+instructions?/i,
+        /new\s+instructions?:\s/i,
+        /\byour\s+new\s+(role|instructions?|task)\b/i,
+        /you\s+are\s+now\s+(a|an)\b/i,
+        /\bact\s+as\s+(a|an)\b/i,
+        /\bpretend\s+(you\s+are|to\s+be)\b/i,
+        /\bdo\s+not\s+follow\s+(your|the)\s+instructions?\b/i
+      ].freeze
+
+      # @param extra_patterns [Array<Regexp>] additional patterns to scan for
+      # @api private
+      def initialize(extra_patterns: [])
+        super()
+        @patterns = DEFAULT_PATTERNS + extra_patterns
+      end
+
+      # Scans the input string for injection patterns.
+      # @param input [String, Hash]
+      # @api private
+      def check(input)
+        text = input.is_a?(Hash) ? input.values.join(" ") : input.to_s
+        @patterns.each do |pattern|
+          fail!("Potential prompt injection detected") if text.match?(pattern)
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/invocation_context.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Carries all per-invocation context values through the call stack.
+  #
+  # +InvocationContext+ is a plain value object (struct-like, frozen on
+  # creation) that replaces ad-hoc +Thread.current[...]+ propagation.
+  # Pass it explicitly wherever context needs to cross a method boundary
+  # or be handed to a child {Task} / {TaskGroup}.
+  #
+  # @example Build a context for a new agent invocation
+  #   ctx = Phronomy::InvocationContext.new(
+  #     thread_id:         "conv-123",
+  #     cancellation_token: Phronomy::CancellationToken.timeout_after(30),
+  #     max_parallel_tools: 5
+  #   )
+  #   agent.invoke("Hello", invocation_context: ctx)
+  class InvocationContext
+    # @return [String, nil] conversation / workflow thread identifier
+    attr_reader :thread_id
+
+    # @return [String, nil] session identifier (e.g. Rails session id)
+    attr_reader :session_id
+
+    # @return [String, nil] end-user identifier for tracing / audit
+    attr_reader :user_id
+
+    # @return [CancellationToken, nil]
+    attr_reader :cancellation_token
+
+    # @return [Deadline, nil]
+    attr_reader :deadline
+
+    # @return [Object, nil] OpenTelemetry / tracing span
+    attr_reader :tracer_span
+
+    # @return [Integer, nil] max tokens the agent may consume this invocation
+    attr_reader :token_budget
+
+    # @return [Integer] maximum simultaneous tool calls (default: 10)
+    attr_reader :max_parallel_tools
+
+    # @return [Object, nil] approval policy applied before write-scope tools
+    attr_reader :approval_policy
+
+    # @return [Object, nil] redaction policy applied to tool args / results
+    attr_reader :redaction_policy
+
+    # @return [Hash, nil] per-provider concurrency / rate-limit overrides
+    attr_reader :provider_limits
+
+    # @return [String, nil] unique identifier for this task in the trace tree
+    attr_reader :task_id
+
+    # @return [String, nil] task_id of the parent span / task
+    attr_reader :parent_task_id
+
+    # @param thread_id [String, nil]
+    # @param session_id [String, nil]
+    # @param user_id [String, nil]
+    # @param cancellation_token [CancellationToken, nil]
+    # @param deadline [Deadline, nil]
+    # @param tracer_span [Object, nil]
+    # @param token_budget [Integer, nil]
+    # @param max_parallel_tools [Integer]
+    # @param approval_policy [Object, nil]
+    # @param redaction_policy [Object, nil]
+    # @param provider_limits [Hash, nil]
+    # @param task_id [String, nil]
+    # @param parent_task_id [String, nil]
+    # @api private
+    def initialize(
+      thread_id: nil,
+      session_id: nil,
+      user_id: nil,
+      cancellation_token: nil,
+      deadline: nil,
+      tracer_span: nil,
+      token_budget: nil,
+      max_parallel_tools: 10,
+      approval_policy: nil,
+      redaction_policy: nil,
+      provider_limits: nil,
+      task_id: nil,
+      parent_task_id: nil
+    )
+      @thread_id = thread_id
+      @session_id = session_id
+      @user_id = user_id
+      @cancellation_token = cancellation_token
+      @deadline = deadline
+      @tracer_span = tracer_span
+      @token_budget = token_budget
+      @max_parallel_tools = max_parallel_tools
+      @approval_policy = approval_policy
+      @redaction_policy = redaction_policy
+      @provider_limits = provider_limits
+      @task_id = task_id
+      @parent_task_id = parent_task_id
+    end
+
+    # Returns a new +InvocationContext+ with the given attributes merged in.
+    # All other attributes are carried over unchanged.
+    #
+    # @param overrides [Hash] keyword arguments to override
+    # @return [InvocationContext]
+    # @api private
+    def merge(**overrides)
+      InvocationContext.new(
+        thread_id: overrides.fetch(:thread_id, @thread_id),
+        session_id: overrides.fetch(:session_id, @session_id),
+        user_id: overrides.fetch(:user_id, @user_id),
+        cancellation_token: overrides.fetch(:cancellation_token, @cancellation_token),
+        deadline: overrides.fetch(:deadline, @deadline),
+        tracer_span: overrides.fetch(:tracer_span, @tracer_span),
+        token_budget: overrides.fetch(:token_budget, @token_budget),
+        max_parallel_tools: overrides.fetch(:max_parallel_tools, @max_parallel_tools),
+        approval_policy: overrides.fetch(:approval_policy, @approval_policy),
+        redaction_policy: overrides.fetch(:redaction_policy, @redaction_policy),
+        provider_limits: overrides.fetch(:provider_limits, @provider_limits),
+        task_id: overrides.fetch(:task_id, @task_id),
+        parent_task_id: overrides.fetch(:parent_task_id, @parent_task_id)
+      )
+    end
+
+    # Convenience: returns the cancellation token or a new never-cancelled token.
+    # @return [CancellationToken]
+    # @api private
+    def effective_cancellation_token
+      @cancellation_token || CancellationToken.new
+    end
+
+    # Returns the cancellation token to use for an invocation, taking both the
+    # explicit +cancellation_token+ and the +deadline+ into account.
+    #
+    # - When +cancellation_token+ is set, it is returned unchanged.
+    # - When only +deadline+ is set, a new {CancellationToken} is created and
+    #   the deadline is attached to it via {Deadline#attach_to}.
+    # - When neither is set, returns +nil+.
+    #
+    # @return [CancellationToken, nil]
+    # @api private
+    def effective_timeout_token
+      return @cancellation_token if @cancellation_token
+      return nil if @deadline.nil?
+
+      token = CancellationToken.new
+      @deadline.attach_to(token)
+      token
+    end
+  end
+end