phronomy 0.25.0 → 0.26.0

data/docs/migrations/durable-semantic-coordination-v2.md

@@ -42,7 +42,7 @@ results without hydration/callbacks. `Persistence#handoff_result(source_id)`
 follows the exact transfer chain without constructing a graph or Agent owners. `Orchestrator#resume(id)` continues existing
 static subagent coordination. There is no global generic class registry.
 
-Observer Task wait timeouts and shutdown do not request cancellation. Team's
+Observer TaskResult wait timeouts and shutdown do not request cancellation. Team's
 `cancel(run_id)` persists a run-scoped request before forwarding its live token;
 resume settles exact children or returns the existing rehydration error. Handoff's
 `cancel(execution_id)` follows only that turn. A cancellation token passed to

data/docs/persistence-backends.md

@@ -32,7 +32,7 @@ the following as part of this SPI:
 - EventLoop Agent execution-directory entries;
 - `AgentInvocation`;
 - `FSMSession`;
-- `Task` or callbacks;
+- `TaskResult` or callbacks;
 - EventLoop queue contents;
 - Runtime Workflow admission entries;
 - in-flight provider operations.

data/docs/runtime-and-concurrency.md

@@ -2,7 +2,7 @@
 
 Phronomy uses an **EventLoop / FSMSession first** architecture for framework
 lifecycle coordination. `FSMSession` represents explicit lifecycle state and
-events. `Phronomy::Task` is the common caller-facing completion handle, not an
+events. `Phronomy::TaskResult` is the common caller-facing completion handle, not an
 execution backend. Synchronous work that must stay off EventLoop is isolated in
 the bounded `OffloadPool`.
 
@@ -46,7 +46,7 @@ Runtime
 └─ EventLoop-driven timers
 
 EventLoop / FSMSession ─┐
-                       ├─> Task = completion handle
+                       ├─> TaskResult = completion handle
 OffloadPool ────────────┘
 ```
 
@@ -254,7 +254,7 @@ lifecycle. Logical halt/completion first enters a private
 `persisting_terminal` lifecycle condition; the FSMSession remains nonterminal
 while WorkflowRunner saves the terminal snapshot through OffloadPool. Only a
 known-successful save result returned to that same FSMSession permits
-`HALTED`/`COMPLETED`, admission release, and caller Task settlement.
+`HALTED`/`COMPLETED`, admission release, and caller TaskResult settlement.
 
 ```text
 RUNNING
@@ -282,10 +282,10 @@ remain durable conflict defense rather than distributed ownership.
 Phronomy exposes two execution modes for capabilities:
 
 - `:cooperative` — short EventLoop-safe work, or specialized asynchronous work
-  that starts another Phronomy lifecycle and returns a Task immediately;
+  that starts another Phronomy lifecycle and returns a TaskResult immediately;
 - `:offloaded` — synchronous work that must not run to completion on EventLoop.
 
-Both paths return `Phronomy::Task`. The execution mechanism differs; the
+Both paths return `Phronomy::TaskResult`. The execution mechanism differs; the
 completion abstraction does not.
 
 Phronomy does not classify application work into framework-level I/O/CPU/process
@@ -310,7 +310,7 @@ Correct shape:
 parent FSMSession
   → start child lifecycle
   → return immediately
-  → child Task settles
+  → child TaskResult settles
   → post parent EventLoop event
 ```
 
@@ -326,7 +326,7 @@ Agent preparation/commit and Workflow hydrate/save operations are submitted to
 
 A durable barrier may pause one logical lifecycle without blocking EventLoop.
 Persistence does not implement async repository variants and must not depend on
-EventLoop, FSMSession, Task settlement internals, or private OffloadPool operation
+EventLoop, FSMSession, TaskResult settlement internals, or private OffloadPool operation
 records.
 
 ## Sync versus async application APIs
@@ -336,7 +336,7 @@ records.
 | Top-level application code | `agent.invoke(...)` when blocking the caller is acceptable |
 | Top-level explicit async | `task = agent.invoke_async(...)`; optionally `task.wait_result` outside EventLoop |
 | Workflow entry/transition action | Start async work and continue through `Workflow#signal` |
-| EventLoop callback | Never block waiting for a Task that requires EventLoop progress |
+| EventLoop callback | Never block waiting for a TaskResult that requires EventLoop progress |
 | Top-level streaming | `agent.stream(...)` |
 | Non-blocking streaming | `agent.stream_async(...)` |
 | Approval from EventLoop callback | Resolve with `live_for_execution`, call `agent.approve_async(...)`, and return immediately |
@@ -345,37 +345,88 @@ Blocking synchronous APIs reject EventLoop re-entry with
 `Phronomy::EventLoopReentrancyError` when waiting would stall the same EventLoop
 needed for progress.
 
-## Task
+## TaskResult
 
-`Phronomy::Task` is thread-free. It represents one terminal result:
+`Phronomy::TaskResult` is thread-free. It represents one terminal result:
 
 - completed value;
 - failure;
 - cancellation.
 
-Task is the common completion abstraction for logical EventLoop/FSMSession
+TaskResult is the common completion abstraction for logical EventLoop/FSMSession
 lifecycles and OffloadPool-backed synchronous work.
 
-`Task#wait_result(timeout:)` is a bridge for external synchronous callers. Its
-timeout is waiter-local: it does not settle/cancel the Task or alter OffloadPool
+`TaskResult#wait_result(timeout:)` is a bridge for external synchronous callers. Its
+timeout is waiter-local: it does not settle/cancel the TaskResult or alter OffloadPool
 abandonment state.
 
-`Task#on_complete` registers an independent notification callback. Callback
+`TaskResult#on_complete` registers an independent notification callback. Callback
 execution thread is not guaranteed. A callback may be delivered by an OffloadPool
 worker, a timer/cancellation caller, an EventLoop-related control path, or the
 thread that registers after settlement. Callbacks must therefore be thread-safe
 and should complete quickly. Framework lifecycle code normally converts worker
 completion into an explicit EventLoop event before applying live state.
 
-`Task#map` is application-level composition. A transformation exception settles
-the mapped Task as failed.
+`TaskResult#map` is application-level composition. A transformation exception settles
+the mapped TaskResult as failed.
 
-Framework components own Task settlement. Application code should not use
-`Task#complete`, `Task#fail`, or `Task#cancel!` as operation-control APIs. Request
+`flat_map` connects a returned TaskResult's completion, while `all_settled`
+observes an input-order list of results. `Execution.run_async` starts and joins
+JOBs under whole-execution controls. See [Result composition and Execution](async-composition.md)
+for the complete contracts, ownership boundaries and development-release migration.
+
+Framework components own TaskResult settlement. Application code should not use
+`TaskResult#complete`, `TaskResult#fail`, or `TaskResult#cancel!` as operation-control APIs. Request
 operation-wide cancellation through the `CancellationToken` accepted by the API
-that created the Task. Task settlement never propagates backwards to cancel a
+that created the TaskResult. TaskResult settlement never propagates backwards to cancel a
 shared CancellationToken.
 
+### Settled TaskResult factories
+
+`TaskResult.completed(value)` and `TaskResult.failed(error)` create results that are already
+settled. They are useful when application code has a result or an error in hand
+and needs to present it through the same `TaskResult` contract as a lifecycle-backed
+completion:
+
+```ruby
+# Already-computed value — no execution started.
+task = Phronomy::TaskResult.completed("cached result")
+
+# Known failure — no execution started.
+task = Phronomy::TaskResult.failed(StandardError.new("precondition not met"))
+```
+
+Settled results satisfy `TaskResult#wait_result`, `TaskResult#on_complete`, and `TaskResult#map` with
+the same contract as a normally-completed TaskResult.
+
+## Blocking
+
+`Phronomy::Blocking.call_async(&block)` submits a synchronous block to the
+existing default Runtime OffloadPool and returns a `TaskResult`. It is the public
+application entry point for one-off synchronous work that should not block the
+caller:
+
+```ruby
+task = Phronomy::Blocking.call_async { expensive_io_call }
+result = task.wait_result
+```
+
+The optional `invocation_context:` connects this operation to an Execution
+scope or an existing invocation context. Context controls and the optional
+individual `cancellation_token:` both apply, without reverse cancellation of
+shared controls. The application chooses when synchronous work needs OffloadPool.
+
+The method uses the existing bounded OffloadPool. It does not create a new thread
+or scheduler. Capacity and backpressure semantics are inherited from the pool
+configuration (`offload_pool_size` / `offload_queue_size`).
+
+`Blocking.call_async` always uses non-waiting admission (`on_full: :raise`) and can
+be called from within the EventLoop thread. Admission `StandardError` failures (for
+example `BackpressureError` when the queue is full) are caught and returned as a
+failed `TaskResult`. Accepted work retains the pool's original `TaskResult` unchanged. Do not
+call `TaskResult#wait_result` on the returned `TaskResult` from within the EventLoop — waiting
+for a `TaskResult` that requires EventLoop progress will deadlock.
+
 ## OffloadPool
 
 `OffloadPool` is a bounded worker pool for synchronous work that must not execute
@@ -391,7 +442,7 @@ Its guarantees include:
 - runtime metrics;
 - shutdown/drain behavior.
 
-`OffloadPool#submit` returns a `Phronomy::Task`. OffloadPool does not expose its
+`OffloadPool#submit` returns a `Phronomy::TaskResult`. OffloadPool does not expose its
 execution record as a caller-facing future/promise. Its private `Operation` owns:
 
 - the submitted block;
@@ -403,27 +454,36 @@ execution record as a caller-facing future/promise. Its private `Operation` owns
 - metrics state needed by the pool.
 
 This separation keeps execution details private while allowing every asynchronous
-Phronomy API to expose the same Task completion contract.
+Phronomy API to expose the same TaskResult completion contract.
 
 ### EventLoop queue admission
 
 Framework-owned EventLoop-origin submissions must not wait for a free worker
 queue slot. They use non-blocking admission (`on_full: :raise`) and route
-`BackpressureError` through the ordinary FSM/Task completion path.
+`BackpressureError` through the ordinary FSM/TaskResult completion path.
+
+Any internal `OffloadPool#submit` call that requests waiting admission
+(`on_full: :wait` or `:timeout`) is **rejected before the Operation is created**
+when the caller is on the EventLoop thread. The rejection raises
+`Phronomy::EventLoopReentrancyError` directly; it does not create an Operation,
+timer, cancellation subscription, or TaskResult. The public `Phronomy::Blocking.call_async`
+always uses `on_full: :raise` and therefore does not trigger this guard; it converts
+admission `StandardError` (such as `BackpressureError`) into a failed `TaskResult` at the
+public-API layer.
 
 External management threads may choose a blocking admission policy when blocking
 the caller is acceptable.
 
 ## Submit timeout and cancellation
 
-Submit-time timeout and submit cancellation settle the caller-facing Task. They
+Submit-time timeout and submit cancellation settle the caller-facing TaskResult. They
 do **not** asynchronously interrupt an already-running synchronous worker.
 
 ### Before worker start
 
 If timeout/cancellation wins before execution starts:
 
-- the Task settles (`TimeoutError` failure or cancellation);
+- the TaskResult settles (`TimeoutError` failure or cancellation);
 - the submitted block does not run;
 - the private Operation is not counted as abandoned.
 
@@ -431,7 +491,7 @@ If timeout/cancellation wins before execution starts:
 
 If timeout/cancellation wins after execution starts:
 
-- the Task settles immediately;
+- the TaskResult settles immediately;
 - the private Operation is marked abandoned;
 - the worker continues until its synchronous call returns;
 - the eventual worker result is discarded.
@@ -447,7 +507,7 @@ requiring callback delivery promote the deadline to explicit `cancel!` through
 the Runtime timer queue. OffloadPool does this for its submit cancellation token.
 
 A CancellationToken may be shared by multiple operations. For that reason,
-settling or cancelling one Task does not cancel the token in the reverse
+settling or cancelling one TaskResult does not cancel the token in the reverse
 direction.
 
 ## Native async boundary
@@ -455,7 +515,7 @@ direction.
 A genuine native-async driver that does not create a Phronomy-owned OS Thread and
 does not block EventLoop need not consume an OffloadPool worker. If Phronomy
 formally exposes such an extension point, it must adapt completion to
-`Phronomy::Task` rather than exposing a provider-specific future or a private
+`Phronomy::TaskResult` rather than exposing a provider-specific future or a private
 Runtime type.
 
 The current Persistence, VectorStore, Embeddings, and LLM call-extension
@@ -473,8 +533,8 @@ Two metrics answer different operational questions:
 - `offload_pool_abandoned_active` — current number of abandoned operations whose
   synchronous workers still occupy pool capacity.
 
-The abandonment state belongs to the private OffloadPool Operation, not to Task.
-Task reports only caller-facing settlement.
+The abandonment state belongs to the private OffloadPool Operation, not to TaskResult.
+TaskResult reports only caller-facing settlement.
 
 ## EventLoop metrics
 

data/lib/phronomy/agent/agent_invocation_session_builder.rb

@@ -542,7 +542,7 @@ module Phronomy
       end
 
       def self.register_child_session(runtime, child, session, parent_event_sink)
-        completion = Phronomy::Task.deferred(name: "tool-session:#{child.id}")
+        completion = Phronomy::TaskResult.deferred(name: "tool-session:#{child.id}")
         completion.on_complete do |_result, error|
           next unless error
 

data/lib/phronomy/agent/base.rb

@@ -799,18 +799,12 @@ module Phronomy
       def _prepare_invocation_config(config, invocation_context)
         __assert_live_agent!
         _reject_removed_generic_identity_keys!(config)
-        effective_config = invocation_context ?
+        invocation_context ?
           config.merge(invocation_context: invocation_context) : config
 
-        if invocation_context && effective_config[:cancellation_token].nil?
-          if (tok = invocation_context.effective_timeout_token)
-            effective_config = effective_config.merge(
-              cancellation_token: tok,
-              phronomy_timeout_deadline: invocation_context.deadline
-            )
-          end
-        end
-        effective_config
+        # ExecutionCoordinator connects context and individual controls together
+        # at admission, before returning the result. Do not arm a second timer
+        # here or replace one cancellation source with another.
       end
 
       def _reject_removed_generic_identity_keys!(config)

data/lib/phronomy/agent/exact_execution.rb

@@ -4,7 +4,7 @@ module Phronomy
   module Agent
     # Observes a reserved execution using ordinary Agent admission and Recovery.
     # Durable reads/materialization run off EventLoop. Workers never wait for a
-    # child lifecycle: the existing EventLoop completion waiter settles Task.
+    # child lifecycle: the existing EventLoop completion waiter settles TaskResult.
     # @api private
     class ExactExecution
       Wait = Data.define(:coordinator, :agent, :execution_id)
@@ -17,7 +17,7 @@ module Phronomy
       def initialize(agent, execution_id, input, config)
         @agent, @id, @input, @config = agent, execution_id.to_s.freeze, input, config.freeze
         @runtime = Phronomy::Runtime.instance
-        @completion = Phronomy::Task.deferred(name: "exact-execution:#{@id}")
+        @completion = Phronomy::TaskResult.deferred(name: "exact-execution:#{@id}")
       end
 
       def start
@@ -92,7 +92,7 @@ module Phronomy
         end
         observers = Array(state.invocation.config[:phronomy_exact_observers])
         state.invocation.merge_config!(phronomy_exact_observers: (observers + [@completion]).uniq.freeze)
-        waiter = Phronomy::Task.deferred(name: "exact-wait:#{@id}")
+        waiter = Phronomy::TaskResult.deferred(name: "exact-wait:#{@id}")
         waiter.on_complete { |_result, failure| reconcile(failure) }
         @runtime.event_loop.register_agent_completion_waiter(@id, waiter)
       rescue => failure

data/lib/phronomy/agent/execution_coordinator.rb

@@ -135,7 +135,15 @@ module Phronomy
       )
         @agent.send(:__assert_live_agent!)
         @agent.send(:_reject_removed_generic_identity_keys!, config)
-        result_task = Phronomy::Task.deferred(name: "agent-#{@agent.agent_id}-#{mode}")
+        result_task = Phronomy::TaskResult.deferred(name: "agent-#{@agent.agent_id}-#{mode}")
+        if config[:invocation_context]
+          binding = Phronomy::Execution.__operation_binding(
+            invocation_context: config[:invocation_context],
+            cancellation_token: config[:cancellation_token]
+          )
+          binding.bind(result_task)
+          config = config.merge(cancellation_token: binding.token)
+        end
         command = StartCommand.new(
           coordinator: self,
           input: input,
@@ -164,7 +172,7 @@ module Phronomy
       )
         @agent.send(:__assert_live_agent!)
         @agent.send(:_reject_removed_generic_identity_keys!, config)
-        result_task = Phronomy::Task.deferred(
+        result_task = Phronomy::TaskResult.deferred(
           name: "agent-approval-resume:#{execution_id}"
         )
         command = ResumeCommand.new(
@@ -397,6 +405,11 @@ module Phronomy
       def begin_start_on_event_loop(request)
         runtime = Phronomy::Runtime.instance
         event_loop = runtime.event_loop
+        scope = request.config[:invocation_context]&.__execution_scope
+        if scope && (!scope.__open? || request.config[:cancellation_token]&.cancelled?)
+          deliver_start_failure_on_event_loop(request, scope.__cancellation_error)
+          return
+        end
         root = @agent.agent_root
         if root.lifecycle_status == :closed
           deliver_start_failure_on_event_loop(
@@ -966,7 +979,7 @@ module Phronomy
           prepared.execution.execution_id,
           request.result_task
         )
-        source_task = Phronomy::Task.deferred(name: "#{request.result_task.name}-source")
+        source_task = Phronomy::TaskResult.deferred(name: "#{request.result_task.name}-source")
         source_task.on_complete do |invocation, error|
           finish_on_event_loop(
             prepared.execution.execution_id,
@@ -1927,7 +1940,7 @@ module Phronomy
           invocation: invocation,
           fsm_session_id: parent_session.id
         )
-        source_task = Phronomy::Task.deferred(name: "#{result_task.name}-source")
+        source_task = Phronomy::TaskResult.deferred(name: "#{result_task.name}-source")
         source_task.on_complete do |completed, error|
           finish_on_event_loop(
             execution_id,
@@ -1969,7 +1982,7 @@ module Phronomy
           resume_event: :resume, resume_phase: :suspended, runtime: runtime)
         event_loop.replace_agent_execution(execution_id, invocation: invocation, fsm_session_id: session.id)
         event_loop.mark_agent_execution_admission(@agent.agent_id, execution_id: execution_id, state: :executing)
-        source = Phronomy::Task.deferred(name: "framework-tool-recovery-source")
+        source = Phronomy::TaskResult.deferred(name: "framework-tool-recovery-source")
         source.on_complete do |result, error|
           finish_on_event_loop(execution_id, result_task, result || session.context, error, fsm_session_id: session.id)
         end
@@ -1982,7 +1995,7 @@ module Phronomy
       end
 
       def register_child(event_loop, child, session, parent_event_sink)
-        completion = Phronomy::Task.deferred(name: "tool-session:#{child.id}")
+        completion = Phronomy::TaskResult.deferred(name: "tool-session:#{child.id}")
         completion.on_complete do |_result, error|
           next unless error
 
@@ -2170,7 +2183,7 @@ module Phronomy
         )
         task = runtime.offload.submit(on_full: :raise) do
           # Only the operation-specific immutable durable snapshot crosses the
-          # worker boundary. Task/listener delivery state stays outside it.
+          # worker boundary. TaskResult/listener delivery state stays outside it.
           compute_terminal(operation)
         end
         task.on_complete do |outcome, error|

data/lib/phronomy/agent/phase_machine_builder.rb

@@ -140,9 +140,9 @@ module Phronomy
       def build_entry_callback(callable, state_name)
         ->(machine) {
           result = callable.call(machine.context)
-          if result.is_a?(Phronomy::Task)
+          if result.is_a?(Phronomy::TaskResult)
             raise Phronomy::InvalidAsyncEntryActionError,
-              "Agent entry action for #{state_name.inspect} returned Phronomy::Task"
+              "Agent entry action for #{state_name.inspect} returned Phronomy::TaskResult"
           end
           machine.context = result if result.respond_to?(:set_graph_metadata)
         }

data/lib/phronomy/agent/recovery_coordinator/continuation.rb

@@ -128,7 +128,7 @@ module Phronomy
             resume_event: resume_event, resume_phase: resume_phase, runtime: @runtime)
           event_loop.replace_agent_execution(execution.execution_id, invocation: invocation, fsm_session_id: session.id)
           event_loop.register_agent_completion_waiter(execution.execution_id, completion)
-          source = Phronomy::Task.deferred(name: "#{completion.name}-source")
+          source = Phronomy::TaskResult.deferred(name: "#{completion.name}-source")
           source.on_complete do |completed, error|
             main.send(:finish_on_event_loop, execution.execution_id, completion,
               completed || session.context, error, fsm_session_id: session.id)

data/lib/phronomy/agent/recovery_coordinator/installation.rb

@@ -315,7 +315,7 @@ module Phronomy
           main = agent.send(:execution_coordinator_for, agent.__coordination_config)
 
           if framework_batch?(execution)
-            internal = Phronomy::Task.deferred(name: "framework-tool-recovery:#{execution.execution_id}")
+            internal = Phronomy::TaskResult.deferred(name: "framework-tool-recovery:#{execution.execution_id}")
             continue_recovery_on_event_loop(execution, internal, material: material)
             completion.complete(agent)
             return
@@ -323,7 +323,7 @@ module Phronomy
 
           case execution.phase.to_sym
           when :preparing
-            internal_task = Phronomy::Task.deferred(
+            internal_task = Phronomy::TaskResult.deferred(
               name: "agent-recovery-auto:#{execution.execution_id}"
             )
             observe_recovery_execution(internal_task, execution)
@@ -348,7 +348,7 @@ module Phronomy
               raise Phronomy::ExecutionRehydrationRequiredError,
                 "approved resuming execution requires Tool outcome resolution"
             end
-            internal_task = Phronomy::Task.deferred(
+            internal_task = Phronomy::TaskResult.deferred(
               name: "agent-recovery-auto:#{execution.execution_id}"
             )
             observe_recovery_execution(internal_task, execution)
@@ -366,7 +366,7 @@ module Phronomy
             )
             completion.complete(agent)
           when :recovery_tools_completed, :recovery_provider_completed, :recovery_resolved_failed
-            internal_task = Phronomy::Task.deferred(name: "agent-recovery-auto:#{execution.execution_id}")
+            internal_task = Phronomy::TaskResult.deferred(name: "agent-recovery-auto:#{execution.execution_id}")
             continue_recovery_on_event_loop(execution, internal_task, material: material)
             completion.complete(agent)
           else

data/lib/phronomy/agent/recovery_coordinator.rb

@@ -89,7 +89,7 @@ module Phronomy
             "load must register on_event"
         end
 
-        completion = Phronomy::Task.deferred(
+        completion = Phronomy::TaskResult.deferred(
           name: "agent-recovery-load:#{execution.execution_id}"
         )
         command = InstallCommand.new(
@@ -140,7 +140,7 @@ module Phronomy
         failure = error_present ?
           RecoverySupport.resolution_failure(error) : nil
 
-        completion = Phronomy::Task.deferred(
+        completion = Phronomy::TaskResult.deferred(
           name: "agent-recovery-resolve:#{execution_id}"
         )
         command = ResolveCommand.new(
@@ -163,7 +163,7 @@ module Phronomy
         end
         completion
       rescue => caught
-        completion ||= Phronomy::Task.deferred(
+        completion ||= Phronomy::TaskResult.deferred(
           name: "agent-recovery-resolve:#{execution_id}"
         )
         completion.fail(caught)

data/lib/phronomy/agent/tool_executor.rb

@@ -4,15 +4,15 @@ module Phronomy
   module Agent
     # Routes Tool work according to the Tool execution contract.
     #
-    # Both execution modes return {Phronomy::Task}; only the execution mechanism
+    # Both execution modes return {Phronomy::TaskResult}; only the execution mechanism
     # differs.
     #
     # :cooperative Tool calls execute inline and must return quickly. call_async
-    # wraps their result in an already-settled Task and never consumes an
+    # wraps their result in an already-settled TaskResult and never consumes an
     # OffloadPool worker.
     #
     # :offloaded Tool calls route synchronous work through OffloadPool, whose
-    # caller-facing completion handle is also a Task. Phronomy does not distinguish
+    # caller-facing completion handle is also a TaskResult. Phronomy does not distinguish
     # whether the reason is blocking I/O, CPU-bound work, or another long
     # synchronous operation.
     module ToolExecutor
@@ -28,7 +28,7 @@ module Phronomy
 
         case mode
         when :cooperative
-          task = Phronomy::Task.deferred(name: "tool-#{tool.name}")
+          task = Phronomy::TaskResult.deferred(name: "tool-#{tool.name}")
           begin
             task.complete(
               tool.call(args, cancellation_token: cancellation_token)

data/lib/phronomy/agent/tool_invocation.rb

@@ -502,7 +502,7 @@ module Phronomy
           value.is_a?(Phronomy::WorkflowRunner) ||
           value.is_a?(Phronomy::WorkflowContext) ||
           value.is_a?(Phronomy::Runtime) ||
-          value.is_a?(Phronomy::Task) ||
+          value.is_a?(Phronomy::TaskResult) ||
           value.is_a?(Phronomy::EventLoop) ||
           value.is_a?(Phronomy::FSMSession) ||
           value.is_a?(Phronomy::FSMSession::EventSink) ||

data/lib/phronomy/agent/tool_invocation_session_builder.rb

@@ -181,9 +181,9 @@ module Phronomy
       def self.build_entry_callback(callable, state_name)
         ->(machine) {
           result = callable.call(machine.context)
-          if result.is_a?(Phronomy::Task)
+          if result.is_a?(Phronomy::TaskResult)
             raise Phronomy::InvalidAsyncEntryActionError,
-              "Tool entry action for #{state_name.inspect} returned Phronomy::Task"
+              "Tool entry action for #{state_name.inspect} returned Phronomy::TaskResult"
           end
           machine.context = result if result.respond_to?(:set_graph_metadata)
         }

data/lib/phronomy/blocking.rb

@@ -7,27 +7,34 @@ module Phronomy
   module Blocking
     # Submits synchronous application work to the default Runtime OffloadPool.
     # Admission never waits for queue space. Admission StandardError failures
-    # become failed Tasks; accepted work retains the pool's Task unchanged.
-    # A timeout/cancellation can settle that Task before a running worker exits.
-    # The block must not wait for another Agent, Workflow, or Task.
+    # become failed results; accepted work retains the pool's TaskResult unchanged.
+    # A timeout/cancellation can settle that TaskResult before a running worker exits.
+    # The block must not wait for another Agent, Workflow, or TaskResult.
     # @param timeout [Numeric, nil] operation deadline, including queue time
     # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
+    # @param invocation_context [Phronomy::InvocationContext, nil] explicit context/scope
     # @yield synchronous application work
-    # @return [Phronomy::Task] original accepted Task or failed admission Task
+    # @return [Phronomy::TaskResult] original accepted TaskResult or failed admission TaskResult
     # @raise [ArgumentError] if no block is supplied
     # @api public
-    def self.call_async(timeout: nil, cancellation_token: nil, &block)
+    def self.call_async(timeout: nil, cancellation_token: nil, invocation_context: nil, &block)
       raise ArgumentError, "Blocking.call_async requires a block" unless block
 
       begin
-        Phronomy::Runtime.instance.offload.submit(
+        unless invocation_context.nil?
+          binding = Execution.__operation_binding(invocation_context: invocation_context,
+            cancellation_token: cancellation_token)
+        end
+        result = Phronomy::Runtime.instance.offload.submit(
           on_full: :raise,
           timeout: timeout,
-          cancellation_token: cancellation_token,
+          cancellation_token: binding ? binding.token : cancellation_token,
           &block
         )
+        binding ? binding.bind(result) : result
       rescue => error
-        Phronomy::Task.failed(error, name: "blocking-admission-failed")
+        result = Phronomy::TaskResult.failed(error, name: "blocking-admission-failed")
+        binding ? binding.bind(result) : result
       end
     end
   end