phronomy 0.9.1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e84ccabf84c48e16cdb968c1f7b69f2348b24a70e477aa39bbbe1244d34edfc
-  data.tar.gz: f31dc2d1c4ed4bb7717e88278f1ced3debd0177f1f7a8042b170421a5d8e7493
+  metadata.gz: f8bcaf54fe256791053b04c22df3b58595d267b2c0ee16b67369fe2ecb36f19d
+  data.tar.gz: 9be01ec03a79ec5d557a3c51fc442992cd012a07e682a43cfa4c9e0358110fc8
 SHA512:
-  metadata.gz: 1c1ab4d05c27930b84abbad09f5c59027f9bfcddf9a89aa485608afdcd22ba50fcf971c2185a815206edfc37b29abb0fa99b7f80a8fa3f436c1d6a97b5ad38e4
-  data.tar.gz: 04016a561705ff24c4a6b9f8bb3d6918c303071f7bf97d94d70313b95f796ae561fee29fad9e7e620928655bf7e2007751cfa217bd973d83d2ad4d26d9754e3e
+  metadata.gz: 44de75b5cc59ddf380aeb0be3abcf2a2c566cb8a1db6c35540525b86c74e7e0c06e75a3581e30276a25eea7f5f0334226e05b54d7d9694ed8f2b881d04a54e60
+  data.tar.gz: 76821f0cad1a918b762bb1d5737f902cc67b726f8dafb0dcf646b5cfc8dd4173527733a8a04e92e71ebea9a152fdb6ebaea20d9ccde3037f32d7fc32f5b05497

data/CHANGELOG.md

@@ -11,10 +11,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-## [0.9.1] - 2026-06-06
+## [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
@@ -233,6 +271,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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

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 |
@@ -199,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

@@ -532,56 +532,6 @@ 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
-
-        parent_id = ctx.thread_id
-        thread_id = "#{parent_id}_agent_#{SecureRandom.uuid}"
-        Phronomy::Runtime.instance.spawn(name: "agent-child:#{thread_id}") do
-          result = _invoke_impl(input, messages: messages, thread_id: thread_id, config: config)
-          Phronomy::EventLoop.instance.post(
-            Phronomy::Event.new(type: :child_completed, target_id: parent_id, payload: result)
-          )
-        rescue => e
-          Phronomy::EventLoop.instance.post(
-            Phronomy::Event.new(type: :child_failed, target_id: parent_id, payload: e)
-          )
-        end
-        nil
-      end
-
       # Streaming version of #invoke. Yields {Phronomy::Agent::StreamEvent} objects
       # as they are produced by the underlying LLM.
       #

data/lib/phronomy/task/mapped_backend.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module Phronomy
+  class Task
+    # Backend for Tasks created by {Task#map}.
+    #
+    # A mapped task's lifecycle is driven entirely by the +on_complete+
+    # callback of its source task — it never spawns a thread of its own.
+    # +MappedBackend+ transitions the owning task to +:running+ immediately
+    # on initialization so that +FSMSession+ treats it as an in-progress
+    # async action.  Completion (or failure) is triggered externally via
+    # {Task#transition!} from the +on_complete+ callback registered by
+    # {Task#map}.
+    #
+    # +await+ and +join+ block until {#unblock} is called, which {Task#map}
+    # arranges by registering a second +on_complete+ callback on the *mapped*
+    # task itself after the transform callback has been registered.
+    #
+    # @api private
+    class MappedBackend < Backend
+      def initialize(task:, &)
+        super
+        @done_queue = Queue.new
+        task.transition!(:running)
+      end
+
+      # Unblocks +await+ / +join+.  Called by {Task#map} after the mapped task
+      # reaches a terminal state.
+      # @api private
+      def unblock(value, error)
+        @done_queue.push([value, error])
+      end
+
+      # Blocks until the mapped task reaches a terminal state.
+      # @return [Object] the mapped value
+      # @raise [Exception] if the source task or the map block raised an error
+      # @api private
+      def await
+        value, error = @done_queue.pop
+        raise error if error
+
+        value
+      end
+
+      # Returns +false+ — a mapped task has no independent thread to kill.
+      # @return [Boolean]
+      # @api private
+      def alive?
+        false
+      end
+
+      # No-op — mapped tasks carry no independent thread to cancel.
+      # @return [self]
+      # @api private
+      def cancel!
+        self
+      end
+
+      # Blocks until the mapped task completes, with an optional timeout.
+      # @param limit [Numeric, nil]
+      # @return [Object, nil] +nil+ on timeout
+      # @api private
+      def join(limit = nil)
+        if limit.nil?
+          await
+        else
+          begin
+            Timeout.timeout(limit) { await }
+          rescue Timeout::Error
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/task.rb

@@ -4,6 +4,7 @@ require_relative "task/backend"
 require_relative "task/thread_backend"
 require_relative "task/immediate_backend"
 require_relative "task/fiber_backend"
+require_relative "task/mapped_backend"
 
 module Phronomy
   # A single unit of concurrent work.
@@ -195,6 +196,58 @@ module Phronomy
       self
     end
 
+    # Returns a new {Task} whose completed value is the result of applying
+    # +block+ to this task's completed value.
+    #
+    # If this task fails or is cancelled, the mapped task also fails/is
+    # cancelled with the same error.  The block is never called in error cases.
+    #
+    # The primary use-case is transforming an agent result into a
+    # {WorkflowContext} so that a Workflow entry action can return a Task
+    # whose value is picked up by {Workflow::FSMSession} via the existing
+    # +:action_completed+ path:
+    #
+    # @example Returning agent output into a Workflow state field
+    #   entry :translate, ->(ctx) {
+    #     TranslationAgent.new.invoke_async(ctx.query).map do |result|
+    #       ctx.merge(answer: result[:output])   # returns WorkflowContext
+    #     end
+    #   }
+    #
+    # @yield  [value] the completed value of this task
+    # @yieldreturn [Object] the value for the mapped task
+    # @return [Task] a new task that completes when this task does
+    # @api public
+    def map(&block)
+      # MappedBackend drives the task lifecycle entirely via on_complete;
+      # it never spawns a thread of its own.
+      mapped = self.class.spawn(
+        name: "#{@name}-mapped",
+        parent: @parent,
+        backend_class: MappedBackend
+      ) {}
+
+      on_complete do |value, error|
+        mapped_value = nil
+        mapped_error = error
+        unless error
+          begin
+            mapped_value = block.call(value)
+          rescue => e
+            mapped_error = e
+          end
+        end
+        if mapped_error
+          mapped.transition!(:failed, error: mapped_error)
+        else
+          mapped.transition!(:completed, value: mapped_value)
+        end
+        # Unblock mapped.await / mapped.join after the terminal transition.
+        mapped.backend.unblock(mapped_value, mapped_error)
+      end
+      mapped
+    end
+
     # Returns +true+ once the task has finished (success, error, or cancellation).
     # @return [Boolean]
     # @api private

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.9.1"
+  VERSION = "0.10.0"
 end

data/lib/phronomy.rb

@@ -123,7 +123,8 @@ module Phronomy
   # Raised when a {Phronomy::WorkflowContext} field is mutated from a thread
   # that does not own the context (i.e. not the EventLoop dispatch thread).
   # Only raised in EventLoop mode.  Use +context.merge(...)+ to produce a new
-  # context, or deliver updates as +:child_completed+ event payloads.
+  # context, or deliver updates as +:action_completed+ event payloads
+  # via {Agent::Base#invoke_async} + {Task#map}.
   class WorkflowContextOwnershipError < Error; end
 
   class << self

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.10.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-05 00:00:00.000000000 Z
+date: 2026-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -189,6 +189,7 @@ files:
 - lib/phronomy/task/backend.rb
 - lib/phronomy/task/fiber_backend.rb
 - lib/phronomy/task/immediate_backend.rb
+- lib/phronomy/task/mapped_backend.rb
 - lib/phronomy/task/thread_backend.rb
 - lib/phronomy/task_group.rb
 - lib/phronomy/testing.rb