phronomy 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d91e0fb85732153a69d268b41bdfe865791dd8f007e8bed983269284478af002
-  data.tar.gz: c334678280139ac7934b6804b06e282051218472985c022823d26913a3f64905
+  metadata.gz: f8bcaf54fe256791053b04c22df3b58595d267b2c0ee16b67369fe2ecb36f19d
+  data.tar.gz: 9be01ec03a79ec5d557a3c51fc442992cd012a07e682a43cfa4c9e0358110fc8
 SHA512:
-  metadata.gz: 393567f7c01633ea20160101705b0fde21ddd009a4950f1cb44a106285500b90a3bec88d4c9681cebb7656d0529c09c9e7c52da42e3e12f103231423921b43aa
-  data.tar.gz: 03f5d2e764df9d3becb782ecdec0bf42f03b0f3fc7414efaad2334fe1d047443ef3180e1993244cad92c305607113d0afe2915caa6ff53d14c05c779a61f6b4b
+  metadata.gz: 44de75b5cc59ddf380aeb0be3abcf2a2c566cb8a1db6c35540525b86c74e7e0c06e75a3581e30276a25eea7f5f0334226e05b54d7d9694ed8f2b881d04a54e60
+  data.tar.gz: 76821f0cad1a918b762bb1d5737f902cc67b726f8dafb0dcf646b5cfc8dd4173527733a8a04e92e71ebea9a152fdb6ebaea20d9ccde3037f32d7fc32f5b05497

data/CHANGELOG.md

@@ -9,8 +9,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+---
+
+## [0.10.0] - 2026-06-08
+
+### Added
+
+- **`Task#map` — transform a Task's completed value** (#384):
+  `task.map { |result| ctx.merge(answer: result[:output]) }` returns a new `Task`
+  whose completed value is the block's return value. Primary use-case: wire
+  `Agent::Base#invoke_async` into a Workflow entry action so the agent result
+  reaches `WorkflowContext` through the standard `:action_completed` path without
+  requiring any changes to `FSMSession`. If the source task fails or is cancelled,
+  the mapped task propagates the error without calling the block.
+
+### Removed
+
+- **`Agent::Base#run_as_child` removed** (#384):
+  Introduced when agents had their own FSM (`Agent::FSM`). After `Agent::FSM` was
+  removed in v0.9.0, the `:child_completed` event payload was silently discarded by
+  `FSMSession`, so `ctx.answer` was never populated. Migrate to
+  `invoke_async + Task#map`:
+
+  ```ruby
+  # Before (removed)
+  entry :translate, ->(ctx) { TranslationAgent.new.run_as_child(ctx.query, ctx: ctx) }
+  transition from: :translate, on: :child_completed, to: :done
+
+  # After (recommended)
+  entry :translate, ->(ctx) {
+    TranslationAgent.new.invoke_async(ctx.query).map { |r| ctx.merge(answer: r[:output]) }
+  }
+  transition from: :translate, to: :done
+  ```
+
 ### Added
 
+- **`Task#map` — transform a Task's completed value** (post-v0.9.0):
+  `task.map { |result| ctx.merge(answer: result[:output]) }` returns a new `Task`
+  whose completed value is the block's return value.  The primary use-case is
+  connecting `Agent::Base#invoke_async` to a Workflow entry action so the agent
+  result populates the `WorkflowContext` through the standard `:action_completed`
+  path.  If the source task fails or is cancelled, the mapped task propagates the
+  error without calling the block.
+
 - **`Phronomy::Diagnostics` and `SchedulerReentrancyError`** (#278, #279):
   `Phronomy::Diagnostics` exposes a snapshot of current scheduler state
   (`pending_count`, `active_tasks`, `pool_utilization`, etc.) for debugging and
@@ -174,10 +216,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   tasks are treated the same as errors and follow the existing `on_error:` policy (`:raise`
   or `:skip`).
 
-- **MCP `HttpTransport` custom authentication headers** (#144): `McpTool.from_server` now
-  accepts `headers: {}`, forwarded all the way to `HttpTransport#initialize`. Arbitrary
-  headers (e.g. `Authorization: Bearer …`) are injected into every JSON-RPC request,
-  enabling use of MCP servers that require bearer tokens or API keys.
+- **MCP `HttpTransport` custom authentication headers** (#144): `Phronomy::Tools::Mcp::HttpTransport#initialize`
+  now accepts `headers: {}`. Arbitrary headers (e.g. `Authorization: Bearer …`) are injected
+  into every JSON-RPC request, enabling use of MCP servers that require bearer tokens or
+  API keys. Threading `headers:` through `Mcp.from_server` is tracked in issue #144 and
+  pending in PR #151.
 
 - **`StdioTransport` — `env:`, `cwd:`, and `startup_timeout:` options** (#145):
   Three new keyword arguments are now accepted when constructing a `StdioTransport` (and
@@ -226,8 +269,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `dispatch_parallel` and `fan_out` accept `cancellation_token:` and automatically
   inject it into every worker task's config unless the task already supplies its own.
 
+### Added (post-v0.9.0)
+
+- **`Agent::Base#run_as_child` removed** (post-v0.9.0):
+  `run_as_child` was introduced when agents had their own FSM.  After `Agent::FSM`
+  was removed, the `:child_completed` event payload was silently discarded by
+  `FSMSession`, meaning `ctx.answer` was never populated.  The method has been
+  removed.  Use `invoke_async + Task#map` instead:
+
+  ```ruby
+  # Before (deprecated)
+  entry :translate, ->(ctx) { TranslationAgent.new.run_as_child(ctx.query, ctx: ctx) }
+  transition from: :translate, on: :child_completed, to: :done
+
+  # After (recommended)
+  entry :translate, ->(ctx) {
+    TranslationAgent.new.invoke_async(ctx.query).map { |r| ctx.merge(answer: r[:output]) }
+  }
+  transition from: :translate, to: :done
+  ```
+
+- **`Phronomy::Agent::CheckpointStore` — idempotency store for HITL resume** (post-v0.9.0):
+  New in-memory store tracks consumed checkpoint IDs. Calling `Agent::Base#resume` twice
+  with the same checkpoint raises `Phronomy::CheckpointAlreadyResumedError` instead of
+  silently re-executing the approved tool. Custom stores can be injected via
+  `agent.checkpoint_store = MyRedis::CheckpointStore.new`. Duck-type contract:
+  `consumed?(id)`, `consume!(id)`, and optionally `cleanup!(id)` / `clear!`.
+
+- **`checkpoint_id`, `agent_class`, `requested_at` on `Checkpoint`; `Agent::Base.resume` class method** (post-v0.9.0):
+  `Checkpoint` now carries a UUID `checkpoint_id` (idempotency key), `agent_class`
+  (fully-qualified class name), and `requested_at` (UTC timestamp). The new class-level
+  `Agent::Base.resume(checkpoint, approved:)` method instantiates the correct agent class
+  automatically and delegates to `#resume`, simplifying job-queue resume flows.
+
+- **`CheckpointStore#cleanup!` and `#clear!`** (post-v0.9.0):
+  Optional methods on the `CheckpointStore` duck-type contract. `cleanup!(checkpoint_id)`
+  removes a single checkpoint entry; `clear!` wipes all tracking state.
+
 ### Removed
 
+- **`Phronomy::ReactAgent` class removed** (post-v0.9.0):
+  Use `Phronomy::Agent::Base` directly. `ReactAgent` had no distinct public API beyond
+  `Agent::Base` and was not listed in the stability table.
+
+- **`Phronomy::Agent::FSM` class removed** (post-v0.9.0, internal):
+  The agent invocation path is now unified through `Agent::Base#invoke` with inline logic.
+  No public API impact.
+
+- **`Phronomy::Agent::Lifecycle::FSMSession` and `::PhaseMachineBuilder` moved to `Workflow` namespace** (post-v0.9.0, internal):
+  These internal classes now live at `Phronomy::Workflow::FSMSession` and
+  `Phronomy::Workflow::PhaseMachineBuilder`. No public API impact.
+
 - **BREAKING: `Agent::Base#run_as_child` drops `&result_writer` block parameter** (#265):
   The optional block form `run_as_child(input, ctx: ctx) { |r| ctx.answer = r[:output] }`
   is no longer supported. The result is now delivered **exclusively** as the

data/README.md

@@ -54,8 +54,9 @@ It provides composable building blocks — Workflows, Agents, Tools, Guardrails,
 | Feature | Stability |
 |---|---|
 | **Workflow EventLoop Mode** — Opt-in event-driven execution: `Phronomy.configure { \|c\| c.event_loop = true }` | Experimental |
-| **Agent EventLoop Mode** — `Agent#invoke` (non-blocking via EventLoop), `Agent#run_as_child` (child-FSM pattern for Workflow integration), parallel tool dispatch via `ParallelToolChat` | Experimental |
+| **Agent EventLoop Mode** — `Agent#invoke` (non-blocking via EventLoop), `Agent#invoke_async` + `Task#map` (child-agent pattern for Workflow integration), parallel tool dispatch via `ParallelToolChat` | Experimental |
 | **`invoke_async` / `call_async`** — `Agent::Base#invoke_async` and `Workflow#invoke_async` return a `Task`; `Agent::Context::Capability::Base#call_async` similarly; compatible with EventLoop and standalone contexts | Experimental |
+| **`Task#map`** — transforms a `Task`'s completed value via a block; returns a new `Task` whose value is the block's return value; if the source task fails or is cancelled the mapped task propagates the error without calling the block; primary use-case: `invoke_async.map { \|r\| ctx.merge(answer: r[:output]) }` to wire agent results into a `WorkflowContext` | Experimental |
 | **CancellationToken** — Cooperative cancellation via `cancel!`/`cancelled?`/`raise_if_cancelled!`; `timeout_after(seconds)` for monotonic-clock deadlines; optional `deadline:` (wall-clock) for backward compatibility; passed as `config: { cancellation_token: token }` to agents and `dispatch_parallel`; injected into `tool.execute` when the method declares a `cancellation_token:` keyword | Experimental |
 | **`dispatch_parallel` / `fan_out` `force_kill:` option** — `force_kill: false` (default) leaves timed-out workers running and raises `TimeoutError` immediately; `force_kill: true` restores the old `Thread#kill` behaviour with a `logger.warn` | Beta |
 | **`execution_mode` DSL on `Agent::Context::Capability::Base`** — Declares how a tool's `execute` should be dispatched: `:cooperative` (same scheduler thread), `:blocking_io` (default; offloaded to `BlockingAdapterPool`), `:cpu_bound`, `:external_process` | Experimental |
@@ -76,6 +77,7 @@ It provides composable building blocks — Workflows, Agents, Tools, Guardrails,
 | **Agent::TeamCoordinator** — Agent teams pattern: LLM coordinator + stateful workers with sequential task assignment (worker-local message history persisted across tasks) | Beta |
 | **Agent::SharedState** — Shared state pattern: peer agents collaborate via a shared KnowledgeStore; `member` DSL with per-agent instructions and `coordination` team protocol | Experimental |
 | **`ScopePolicy`** — Configurable policy callable that maps (tool, scope, agent) to `:allow`/`:approve`/`:reject`; default policy auto-routes high-risk scopes through the approval gate | Experimental |
+| **HITL Checkpoint/Resume** — `Agent::Base#invoke` returns `{ suspended: true, checkpoint: Checkpoint }` when an approval-required tool is encountered without a synchronous handler; `Agent::Base#resume(checkpoint, approved:)` resumes execution; `Agent::Base.resume(checkpoint, approved:)` (class-level) resolves the agent class automatically; `Checkpoint#to_h` / `Checkpoint.from_h` for serialization; `Agent::Base#checkpoint_store=` for custom idempotency backends; `CheckpointAlreadyResumedError` raised on duplicate resume | Experimental |
 
 > **Public API boundary**: The tables above are the complete list of classes, modules, and features
 > intended for gem consumers. Every entry has an associated stability label.
@@ -198,20 +200,18 @@ final = app.send_event(state: state, event: :approve)
 puts "Approved: #{final.approved}"  # => true
 ```
 
-In EventLoop mode (`c.event_loop = true`), `Agent#run_as_child` spawns a child agent
-asynchronously. When the child succeeds, `:child_completed` is dispatched with the result
-`{ output:, messages:, usage: }` as its payload; when it fails, `:child_failed` is
-dispatched. Always declare both transitions to avoid a stuck workflow:
+In EventLoop mode (`c.event_loop = true`), use `invoke_async + Task#map` to run an agent
+asynchronously inside a Workflow entry action.  The mapped Task returns a `WorkflowContext`,
+which `FSMSession` picks up via the standard `:action_completed` path:
 
 ```ruby
-# EventLoop mode: workflow that runs an agent as a child FSM.
-# The result { output:, messages:, usage: } arrives as the :child_completed event
-# payload — write it back to the context in the target state's entry action.
-entry :run_agent, ->(ctx) {
-  MyAgent.new.run_as_child(ctx.query, ctx: ctx)
+# EventLoop mode: workflow that runs an agent and captures the result.
+entry :translate, ->(ctx) {
+  TranslationAgent.new.invoke_async(ctx.query).map do |result|
+    ctx.merge(answer: result[:output])   # returns WorkflowContext
+  end
 }
-transition from: :run_agent, on: :child_completed, to: :done
-transition from: :run_agent, on: :child_failed,    to: :handle_error
+transition from: :translate, to: :done   # no on: needed
 ```
 
 ### Multi-Agent — Agent-as-Tool pattern

data/lib/phronomy/agent/base.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "securerandom"
+require_relative "checkpoint_store"
 require_relative "concerns/retryable"
 require_relative "concerns/guardrailable"
 require_relative "concerns/before_completion"
@@ -374,6 +375,27 @@ module Phronomy
             @context_overhead = val.to_i
           end
         end
+
+        # Resumes a suspended invocation identified by +checkpoint+ without
+        # requiring the original agent instance to be kept in memory.
+        #
+        # Validates that the checkpoint was created by this agent class, then
+        # instantiates a fresh agent and delegates to {Suspendable#resume}.
+        #
+        # @param checkpoint [Phronomy::Agent::Checkpoint]
+        # @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
+        # @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)
+        end
       end
 
       # Registers an anonymous handoff tool class on this agent instance.
@@ -442,12 +464,35 @@ module Phronomy
         if invocation_context
           thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
         end
-        if Phronomy.configuration.event_loop
-          _invoke_via_event_loop(input, messages: messages, thread_id: thread_id, config: config)
-        else
-          _check_scheduler_reentrancy
-          invoke_async(input, messages: messages, thread_id: thread_id, config: config).await
+        _check_scheduler_reentrancy
+
+        timeout_sec = self.class.invoke_timeout
+        unless timeout_sec
+          return invoke_async(input, messages: messages, thread_id: thread_id, config: config).await
+        end
+
+        # invoke_timeout: create a CancellationScope with deadline, pass its token
+        # to the async invocation, and use scope.pop_queue so the calling thread
+        # unblocks as soon as either the result arrives or the deadline fires.
+        scope = Phronomy::Concurrency::CancellationScope.new(parent_token: config[:cancellation_token])
+        scope.deadline_in(timeout_sec)
+        effective_config = config.merge(cancellation_token: scope.token)
+        task = invoke_async(input, messages: messages, thread_id: thread_id, config: effective_config)
+
+        # 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)
+        rescue => e
+          completion_queue.push(e)
         end
+
+        result = scope.pop_queue(completion_queue) do
+          raise Phronomy::TimeoutError,
+            "Agent #{self.class.name} invoke timed out after #{timeout_sec}s"
+        end
+        raise result if result.is_a?(Exception)
+        result
       end
 
       # Invokes this agent asynchronously and returns a {Phronomy::Task}.
@@ -487,60 +532,13 @@ module Phronomy
         end
       end
 
-      # Registers this agent as a child {AgentFSM} inside the given Workflow context.
-      #
-      # Use this method from a Workflow entry action (running on the EventLoop thread)
-      # instead of {#invoke}, which would raise a deadlock error because +invoke+ blocks
-      # on a +Thread::Queue+ when EventLoop mode is active.
-      #
-      # The agent runs asynchronously in a background IO thread.  When it finishes, the
-      # parent {FSMSession} receives a +:child_completed+ event whose payload is the
-      # result hash +{ output:, messages:, usage: }+.  Declare an +on: :child_completed+
-      # transition in your Workflow to advance to the next state.
-      #
-      # The result is delivered exclusively as the +:child_completed+ event payload.
-      # The parent Workflow task is the sole owner of the parent +WorkflowContext+ and
-      # applies the result after receiving the event — no background thread writes to
-      # the parent context directly.
-      #
-      # @example
-      #   entry :run_agent, ->(ctx) { MyAgent.new.run_as_child(ctx.query, ctx: ctx) }
-      #   transition from: :run_agent, on: :child_completed, to: :process_result
-      #
-      # @param input     [String, Hash]  user input passed to the agent
-      # @param ctx       [Object]        a WorkflowContext that responds to +#thread_id+
-      # @param messages  [Array]         prior conversation history
-      # @param config    [Hash]          invocation config (forwarded to +_invoke_impl+)
-      # @return [nil]  the caller must not wait on any return value;
-      #                the result arrives as a +:child_completed+ event
-      # @raise [Phronomy::Error] when EventLoop mode is not enabled
-      # @api public
-      def run_as_child(input, ctx:, messages: [], config: {})
-        unless Phronomy.configuration.event_loop
-          raise Phronomy::Error,
-            "run_as_child requires EventLoop mode. " \
-            "Enable with: Phronomy.configure { |c| c.event_loop = true }"
-        end
-
-        fsm = Agent::FSM.new(
-          agent: self,
-          input: input,
-          messages: messages,
-          thread_id: "#{ctx.thread_id}_agent_#{SecureRandom.uuid}",
-          config: config,
-          parent_id: ctx.thread_id
-        )
-        Phronomy::EventLoop.instance.enqueue_child(fsm)
-        nil
-      end
-
       # Streaming version of #invoke. Yields {Phronomy::Agent::StreamEvent} objects
       # as they are produced by the underlying LLM.
       #
       # Events emitted (in order):
       #   :token       — each content delta from the LLM
-      #   :tool_call   — when the LLM requests a tool (ReactAgent subclasses only)
-      #   :tool_result — after a tool completes (ReactAgent subclasses only)
+      #   :tool_call   — when the LLM requests a tool
+      #   :tool_result — after a tool completes
       #   :done        — final event carrying output, messages, and usage
       #   :error       — if an unrecoverable error occurs
       #
@@ -587,42 +585,6 @@ module Phronomy
         [effective_thread_id, effective_config]
       end
 
-      def _invoke_via_event_loop(input, messages:, thread_id:, config:)
-        if Phronomy::EventLoop.current?
-          raise Phronomy::Error,
-            "Cannot call Agent#invoke (EventLoop mode) from within an EventLoop " \
-            "entry action. Use agent.run_as_child(input, ctx: ctx) instead."
-        end
-
-        timeout_sec = self.class.invoke_timeout
-        effective_config, scope = if timeout_sec
-          s = Phronomy::Concurrency::CancellationScope.new(parent_token: config[:cancellation_token])
-          s.deadline_in(timeout_sec)
-          [config.merge(cancellation_token: s.token), s]
-        else
-          [config, nil]
-        end
-
-        fsm = Agent::FSM.new(
-          agent: self,
-          input: input,
-          messages: messages,
-          thread_id: thread_id || SecureRandom.uuid,
-          config: effective_config
-        )
-        completion_queue = Phronomy::EventLoop.instance.register(fsm)
-        result = if scope
-          scope.pop_queue(completion_queue) do
-            raise Phronomy::TimeoutError,
-              "Agent #{self.class.name} invoke timed out after #{timeout_sec}s"
-          end
-        else
-          completion_queue.pop
-        end
-        raise result if result.is_a?(Exception)
-        result
-      end
-
       def _check_scheduler_reentrancy
         return unless Phronomy::Task.current
 
@@ -851,12 +813,30 @@ module Phronomy
       # 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|
-          Agent::InvocationPipeline.new(self).run(
+          run_input_guardrails!(input)
+
+          user_message = extract_message(input)
+          chat = build_chat
+          context = build_context(
             input,
-            messages: messages,
-            thread_id: thread_id,
-            config: config
+            messages: messages, thread_id: thread_id, config: config,
+            budget: build_token_budget, instruction: build_instructions(input),
+            tools: self.class.tools + _handoff_tools
+          )
+          _apply_context_to_chat(chat, context)
+
+          run_before_completion_hooks!(chat, config)
+          _register_suspension_hook!(chat)
+          check_cancellation!(config, "invocation cancelled before LLM call")
+
+          result, usage = _complete_with_suspension_guard(
+            chat, user_message, config,
+            thread_id: thread_id, original_input: input
           )
+          next [result, usage] if result[:suspended]
+
+          run_output_guardrails!(result[:output])
+          [result, usage]
         end
       end
 
@@ -877,6 +857,36 @@ 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)
@@ -920,12 +930,12 @@ module Phronomy
       end
 
       # Returns the chat class to instantiate for this invocation.
-      # When EventLoop mode is enabled ({Phronomy.configuration.event_loop}),
+      # When {Phronomy.configuration.parallel_tool_execution} is true,
       # returns {ParallelToolChat} so that concurrent tool dispatch is enabled.
       # Falls back to +nil+ otherwise, signalling {#build_chat} to use the
       # standard +RubyLLM.chat+ factory.
       def build_chat_class
-        Phronomy.configuration.event_loop ? Phronomy::MultiAgent::ParallelToolChat : nil
+        Phronomy.configuration.parallel_tool_execution ? Phronomy::MultiAgent::ParallelToolChat : nil
       end
 
       def build_chat

data/lib/phronomy/agent/checkpoint.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module Phronomy
   module Agent
     # Encapsulates the suspended state of an agent invocation.
@@ -19,6 +21,18 @@ module Phronomy
     #   end
     #   puts result[:output]
     class Checkpoint
+      # @return [String] a globally unique identifier for this checkpoint;
+      #   used as an idempotency key when guarding against duplicate resumes
+      attr_reader :checkpoint_id
+
+      # @return [String, nil] the fully-qualified name of the agent class that
+      #   created this checkpoint (e.g. +"MyApp::ReviewAgent"+); used by the
+      #   class-level +resume+ method to validate the correct agent is used
+      attr_reader :agent_class
+
+      # @return [Time] the UTC timestamp when this checkpoint was created
+      attr_reader :requested_at
+
       # @return [String, nil] the thread_id from the invocation config
       attr_reader :thread_id
 
@@ -41,6 +55,9 @@ module Phronomy
       #   inject the tool result message on resume)
       attr_reader :pending_tool_call_id
 
+      # @param checkpoint_id        [String] unique identifier; defaults to a new UUID
+      # @param agent_class           [String, nil] fully-qualified agent class name
+      # @param requested_at          [Time] when the checkpoint was created; defaults to +Time.now.utc+
       # @param thread_id            [String, nil]
       # @param original_input       [String, Hash] the input passed to the original #invoke call
       # @param messages             [Array<RubyLLM::Message>]
@@ -48,7 +65,11 @@ module Phronomy
       # @param pending_tool_args    [Hash]
       # @param pending_tool_call_id [String]
       # @api public
-      def initialize(thread_id:, original_input:, messages:, pending_tool_name:, pending_tool_args:, pending_tool_call_id:)
+      def initialize(thread_id:, original_input:, messages:, pending_tool_name:, pending_tool_args:, pending_tool_call_id:,
+        checkpoint_id: SecureRandom.uuid, agent_class: nil, requested_at: Time.now.utc)
+        @checkpoint_id = checkpoint_id
+        @agent_class = agent_class
+        @requested_at = requested_at
         @thread_id = thread_id
         @original_input = original_input
         @messages = messages.dup.freeze
@@ -71,6 +92,9 @@ module Phronomy
       # @api public
       def to_h
         {
+          checkpoint_id: @checkpoint_id,
+          agent_class: @agent_class,
+          requested_at: @requested_at&.iso8601,
           thread_id: @thread_id,
           original_input: @original_input,
           messages: @messages.map { |m| serialize_message(m) },
@@ -99,7 +123,12 @@ module Phronomy
           end
         }
         messages = Array(h[:messages]).map { |m| deserialize_message(m) }
+        requested_at_raw = h[:requested_at]
+        requested_at = requested_at_raw ? Time.parse(requested_at_raw.to_s).utc : nil
         new(
+          checkpoint_id: h[:checkpoint_id]&.to_s || SecureRandom.uuid,
+          agent_class: h[:agent_class]&.to_s,
+          requested_at: requested_at || Time.now.utc,
           thread_id: h[:thread_id],
           original_input: h[:original_input],
           messages: messages,

data/lib/phronomy/agent/checkpoint_store.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Default in-memory idempotency store for {Checkpoint} resume operations.
+    #
+    # Tracks consumed checkpoint IDs so that calling {Agent::Base#resume} twice
+    # with the same checkpoint raises {Phronomy::CheckpointAlreadyResumedError}
+    # instead of silently executing the approved tool a second time.
+    #
+    # This implementation is *not thread-safe*. It assumes a single agent instance
+    # is accessed from only one thread at a time, which is the expected usage pattern.
+    # Agent instances themselves are not thread-safe (state like +@messages+, +@config+
+    # is not protected), so concurrent calls to the same agent instance are unsupported.
+    #
+    # Each agent instance gets its own store by default, so no sharing occurs unless
+    # the caller explicitly assigns the same store object to multiple agents.
+    #
+    # For distributed environments (multiple processes or background jobs), swap this
+    # for a custom implementation backed by Redis, ActiveRecord, or another shared store.
+    # *Your custom store implementation is responsible for ensuring thread-safety* if
+    # your application shares the same store instance across multiple threads.
+    #
+    # @example Plugging in a custom store
+    #   agent = MyAgent.new
+    #   agent.checkpoint_store = MyRedis::CheckpointStore.new
+    #
+    # @example Duck-type contract required by any replacement
+    #   # consumed?(checkpoint_id) => Boolean
+    #   # consume!(checkpoint_id)  => void; raises CheckpointAlreadyResumedError if duplicate
+    #   # cleanup!(checkpoint_id)  => void (optional); removes tracking for the checkpoint
+    #   # clear!                   => void (optional); removes all tracked checkpoints
+    #
+    # @api public
+    class CheckpointStore
+      def initialize
+        @consumed = Set.new
+      end
+
+      # Returns +true+ if the given checkpoint ID has already been consumed.
+      #
+      # @param checkpoint_id [String]
+      # @return [Boolean]
+      # @api public
+      def consumed?(checkpoint_id)
+        @consumed.include?(checkpoint_id)
+      end
+
+      # Marks +checkpoint_id+ as consumed, or raises if it was already consumed.
+      #
+      # @param checkpoint_id [String]
+      # @raise [Phronomy::CheckpointAlreadyResumedError]
+      # @return [void]
+      # @api public
+      def consume!(checkpoint_id)
+        if @consumed.include?(checkpoint_id)
+          raise Phronomy::CheckpointAlreadyResumedError,
+            "checkpoint #{checkpoint_id} has already been resumed"
+        end
+        @consumed.add(checkpoint_id)
+        nil
+      end
+
+      # Removes tracking for a specific checkpoint ID.
+      #
+      # Use this to explicitly discard a checkpoint when the application
+      # determines it is no longer needed (e.g., user abandons an approval
+      # workflow).
+      #
+      # This method is optional in the duck-type contract. Custom store
+      # implementations may choose not to implement it.
+      #
+      # @param checkpoint_id [String]
+      # @return [void]
+      # @api public
+      def cleanup!(checkpoint_id)
+        @consumed.delete(checkpoint_id)
+        nil
+      end
+
+      # Removes all tracked checkpoint IDs.
+      #
+      # Use this for test cleanup, periodic maintenance, or application
+      # shutdown.
+      #
+      # This method is optional in the duck-type contract. Custom store
+      # implementations may choose not to implement it.
+      #
+      # @return [void]
+      # @api public
+      def clear!
+        @consumed.clear
+        nil
+      end
+    end
+  end
+end

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

@@ -49,7 +49,7 @@ module Phronomy
 
         private
 
-        # Retry loop for #invoke. Separated so that ReactAgent can override #invoke_once.
+        # Retry loop for #invoke.
         def _invoke_impl(input, messages: [], thread_id: nil, config: {})
           # Fail fast when the token is already cancelled before any LLM call.
           if (token = config[:cancellation_token]) && token.cancelled?