phronomy 0.26.0 → 0.28.0

data/docs/runtime-and-concurrency.md

@@ -23,37 +23,38 @@ are defined by
 
 ## Runtime model
 
-```text
-Runtime
-├─ Agent ownership registry
-│  └─ agent_id -> one mutable live Agent instance
-├─ EventLoop (one control-plane operating-system Thread)
-│  ├─ FSMSession
-│  │  ├─ Agent
-│  │  ├─ Workflow
-│  │  ├─ ToolInvocation
-│  │  └─ MultiAgent fan-out
-│  ├─ Agent top-level admission
-│  │  └─ agent_id -> one nonterminal logical Execution admission
-│  └─ Agent execution directory
-│     └─ execution_id -> immutable live-state record
-├─ OffloadPool (bounded operating-system Threads)
-│  ├─ private Operation records
-│  ├─ blocking input/output (I/O)
-│  ├─ central-processing-unit (CPU)-bound synchronous work
-│  └─ operation-specific durable Agent/Workflow work
-├─ named OffloadPools
-└─ EventLoop-driven timers
-
-EventLoop / FSMSession ─┐
-                       ├─> TaskResult = completion handle
-OffloadPool ────────────┘
-```
+| Runtime-retained component | Implementation owner and responsibility |
+|---|---|
+| Shutdown participants | Feature-owned registries: Agent identity, Team identity, and MultiAgent synchronous-call admission |
+| EventLoop | Engine dispatcher thread, FSMSessions and registered feature receivers |
+| Execution receivers | Agent/Workflow own execution admission, state and idle policies; mutations run on EventLoop |
+| OffloadPool and named pools | Engine bounded workers and private physical-operation records |
+| Timers | Engine EventLoop-driven scheduling |
+
+Runtime retains participants through a generic lifecycle protocol; it does not
+construct Agent or Team identity registries. Each feature registers its own
+instance. See [ADR-041](decisions/041-feature-owned-identity-registries.md).
 
 The framework does not allocate one operating-system Thread per logical
 Agent/Workflow/Tool lifecycle. Logical waits remain explicit states plus later
 EventLoop events.
 
+## Feature execution receivers
+
+[ADR-042](decisions/042-feature-owned-execution-state.md) separates implementation
+ownership from the single-writer execution context. Agent and Workflow create
+`Agent::ExecutionRegistry` and `WorkflowExecutionRegistry` respectively; Engine
+retains registered receivers without selecting concrete feature types.
+
+Receiver registration and new request admission close before idle checks.
+Already queued requests, pending durable operations and supervised physical
+work are counted until their feature continuation settles. Worker callbacks
+only enqueue results. Workflow instance routing and generic FSM enqueue share
+one lock. After a clean join, receiver cleanup invalidates retained state;
+a failing receiver makes Runtime cleanup incomplete. Dispatcher failure instead
+notifies receivers on the failing loop thread with the original error.
+
+
 ## Live state and durable state
 
 A live Agent or Workflow owns its current logical state. `Persistence` is the
@@ -61,7 +62,7 @@ last committed durable representation and recovery source; it is not reloaded at
 every semantic boundary.
 
 For active Agents, **EventLoop is the single writer of Phronomy-managed live
-execution state**. EventLoop owns a process-local execution directory keyed by
+execution state**. `Agent::ExecutionRegistry` owns the process-local directory keyed by
 canonical `execution_id`. Each directory value is immutable and is replaced on
 EventLoop when the current AgentExecution, RuntimeProjection, AgentInvocation, or
 owning FSMSession changes. The former mutex-protected
@@ -75,7 +76,7 @@ handling; workers do not receive AgentInvocation as a mutable state authority.
 Mutable Agent/Execution/Journal state is not automatically reloaded before every
 LLM or Tool step. Durable writes use optimistic revision/position guardrails; an
 external writer that advances the durable base causes
-`Persistence::ConflictError` rather than automatic reload or merge.
+`Storage::ConflictError` rather than automatic reload or merge.
 
 For Workflows, the current `WorkflowContext` and FSMSession own the active
 logical state. A durable Workflow hydrates once at invocation/resume and saves at
@@ -88,8 +89,9 @@ content reference is value materialization rather than mutable state refresh.
 
 `agent_id` identifies one logical Agent, not a reusable lookup key for independent
 mutable objects. One Runtime therefore publishes at most one mutable live Agent
-instance for a given `agent_id`. The Runtime-owned registry is an authority, not a
-cache, and reserves the identity before create/load materialization.
+instance for a given `agent_id`. The Agent-owned registry, strongly retained by
+Runtime, is an authority, not a cache, and reserves the identity before
+create/load materialization.
 
 The application-facing identity operations are distinct:
 
@@ -100,7 +102,7 @@ new / create
 load(agent_id, persistence:)
   live -> exact same Ruby object, with no Persistence reload
   durable-only -> hydrate and publish once
-  missing -> Persistence::NotFoundError
+  missing -> Storage::NotFoundError
 
 get(agent_id)
   live Runtime lookup only; missing -> nil
@@ -114,7 +116,8 @@ invalidates the old object, deletes durable state, releases the process-local
 identity, and allows a later new Agent to reuse the textual ID.
 
 Live Agent ownership and top-level Execution admission are separate lifetimes.
-For one live Agent, EventLoop admits at most one nonterminal top-level Execution.
+For one live Agent, `Agent::ExecutionRegistry` admits at most one nonterminal
+top-level Execution on EventLoop.
 Admission is acquired **before** the initial Offload/Persistence operation:
 
 ```text
@@ -195,6 +198,15 @@ Phronomy-managed live domain objects are rejected from that value data. A comple
 value-type/serialization contract for arbitrary Application-owned opaque objects is
 deferred; such objects remain Application-owned and must be worker-safe.
 
+The existing restricted types declare the internal methodless
+`Concurrency::WorkerInputRestricted` marker at their own definitions.
+ToolInvocation checks that execution-boundary contract instead of enumerating
+Agent/Workflow/Runtime classes. Frozen marked values and subclasses remain
+restricted; Hash keys and values, nested Arrays and behavior handles are all
+checked. The marker does not inspect opaque application fields or closure
+captures and is not a general restriction on every OffloadPool command.
+See [ADR-045](decisions/045-worker-input-restriction-ownership.md).
+
 Worker authorization/execution outcomes return as values carrying
 `tool_invocation_id`; the Tool FSMSession consumes a mismatched semantic result
 without advancing its current state.
@@ -279,6 +291,32 @@ remain durable conflict defense rather than distributed ownership.
 
 ## Tool execution modes
 
+The default dispatch helper is the private
+`Phronomy::Tool::ToolExecutor`, colocated with Capability
+Base. Agent ToolInvocation supplies Runtime and admission policy for the
+standard path, and owns authorization and logical result handling. Custom
+`call_async` implementations keep the public Tool protocol. This ownership is
+defined by [ADR-035](decisions/035-tool-executor-capability-ownership.md); the
+public `Phronomy::Tool::Base` facade and its Class identity remain unchanged.
+
+Agent uses ordinary `RubyLLM::Chat` for both complete and streaming Provider
+calls. The `before_tool_call` callback takes the complete assistant Tool-call
+batch before RubyLLM executes the first Tool body. `AgentInvocation` then owns
+authorization, dispatch, approval suspension and result collection. Offloaded
+Tools can overlap within Runtime capacity; short cooperative Tools run according
+to their existing execution contract.
+
+On successful batch completion, Agent records one Tool result per call ID in
+request order and includes the whole exchange in the next Provider request.
+Worker completion order does not split the conversation or trigger a partial
+Provider continuation. Failure, cancellation and approval keep their existing
+Agent lifecycle semantics.
+
+There is no separate Chat execution path or `parallel_tool_execution` switch.
+The removed internal `MultiAgent::ParallelToolChat` class is not replaced by an
+alias. See the [Chat migration guide](migrations/parallel-tool-chat-removal.md)
+for application configuration and existing stored model-config records.
+
 Phronomy exposes two execution modes for capabilities:
 
 - `:cooperative` — short EventLoop-safe work, or specialized asynchronous work
@@ -539,14 +577,86 @@ TaskResult reports only caller-facing settlement.
 ## EventLoop metrics
 
 `Phronomy::Metrics.snapshot` also reports EventLoop queue depth and lag values.
+
+Metrics and Diagnostics only observe resources already owned by the default
+Runtime. Calling `Metrics.snapshot`, `Diagnostics.snapshot` or `Diagnostics.dump`
+does not initialize a Runtime, pool, EventLoop or timer. Missing resources report
+zero values, including `offload_pool_size: 0` when no default pool exists. Once a
+pool exists, this field remains its configured capacity, not a live-worker count.
+Named pools are not aggregated into the default-pool metrics.
+
+Retained resources remain observable during and after shutdown, including
+incomplete cleanup. Observation does not reopen admission or change a shutdown
+result. After the default Runtime is reset, missing resources again report zero;
+the next snapshot uses any newly initialized default Runtime. Counters are sampled
+independently and do not constitute an atomic cross-resource snapshot.
 Use these to distinguish worker saturation from EventLoop backlog/latency.
 
 ## Shutdown
 
+Pool creation and registration close atomically before the shutdown resource set
+is captured. Accepted continuations can still acquire resources during Runtime's
+draining phase. Once resource shutdown begins, all pools close admission before
+any pool waits for its workers.
+
+The stop-phase monotonic deadline is shared by EventLoop and every pool join.
+A join timeout does not stop a synchronous worker. Runtime reports incomplete
+cleanup while any worker remains, even if that worker's TaskResult has already
+been cancelled or timed out. It does not forcefully interrupt worker threads.
+See [R8 unit19](architecture/r8-unit19.md) and its
+[migration notes](migrations/r8-unit19.md) for the shutdown budget and result rules.
+
 `Runtime#shutdown` is terminal for that Runtime. It drains/terminates the
 Runtime-owned EventLoop, then closes pools and timers according to the Runtime
 shutdown contract.
 
+Internal subsystems can register one shutdown participant per Runtime-local key
+through `Runtime#__register_shutdown_participant`. This is an internal lifecycle
+contract, not a public extension API or an execution registry. Runtime does not
+construct participants or interpret their admission rules.
+
+Each participant implements two required operations:
+
+- `begin_draining` closes admission under the participant's admission lock. It
+  must be idempotent, short and nonblocking, and must not call back into Runtime.
+  Runtime invokes it under its lifecycle lock when shutdown starts or EventLoop
+  fails, so no participant can be registered after closure begins.
+- `wait_until_idle(deadline)` returns whether admitted calls have finished before
+  the shared absolute monotonic deadline. Runtime closes every participant before
+  waiting, and waits without holding its lifecycle lock. A timeout or failed hook
+  makes cleanup incomplete; other participants, pools and timers still receive
+  their shutdown calls. Incomplete cleanup prevents default Runtime replacement.
+
+Participants may also implement `after_runtime_shutdown`. Runtime calls it
+outside its lifecycle lock after every wait succeeds, EventLoop has stopped,
+and pools/timers have shut down successfully. The hook must be idempotent,
+short, and perform no I/O; its return value is ignored. A hook exception marks
+cleanup incomplete, retains the first failure, and does not skip later hooks.
+Completed releases are not rolled back; repeated shutdown returns its cached
+result without retrying hooks. A prior closure/wait failure, timeout, or worker
+shutdown failure skips finalization entirely.
+
+`Runtime#__shutdown_participant(key:)` only retrieves an existing participant,
+including during/after shutdown. Registration still requires a running Runtime,
+even for an existing key. Agent/Team `get` uses lookup without registration;
+feature gates reject new ownership changes through retained registries after
+closure. Already admitted transitions may finish. Identity registries wait only
+for active construction/purge, then detach Agent references or clear Team
+owners at finalization; live idle objects do not themselves prolong shutdown.
+
+`MultiAgent::AdmissionRegistry.for(runtime)` constructs and registers the shared
+coordination admission registry. MultiAgent::HandoffRunner and TeamCoordinator retain that
+registry, admit each synchronous call directly and release it in `ensure` after
+successful admission. The registry closes admission atomically with respect to
+`admit!`; a call admitted before closure is included in the wait, and a call after
+closure raises `RuntimeShutdownError`, including after EventLoop failure. The
+existing `HandoffError` for duplicate admission remains unchanged.
+
+This tracks the current synchronous Handoff/Team call, not the lifetime or
+completion of a durable AgentExecution or TeamExecution. Multi-Agent policy stays
+in `multi_agent`; Runtime depends only on the shutdown operations. Application
+authors do not register these participants themselves.
+
 Workflow durable admission participates in EventLoop idleness: a Workflow whose
 FSMSession has ended but whose durable save is still in flight remains owned until
 that save completes and owner-aware admission is released.

data/lib/phronomy/agent/admission.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Phronomy
+  module Agent
+    # The short durable phase of an Agent's already acquired runtime admission.
+    # A coordinator may join it to its reservation check; it cannot start an FSM,
+    # publish a provisional result or make the Agent interpret a parent's schema.
+    # @api public
+    class Admission
+      attr_reader :agent_id, :execution_id, :correlation
+
+      # Constructed by Agent execution, never restored from a durable record.
+      # @api private
+      def initialize(persistence:, root:, input:, config:, preparation_metadata:)
+        @persistence, @root, @input, @config = persistence, root, input, config
+        @preparation_metadata = preparation_metadata
+        @agent_id = root.agent_id
+        @execution_id = (config[:phronomy_reserved_execution_id] || SecureRandom.uuid).to_s.freeze
+        @correlation = Phronomy::Values::Immutable.copy(config[:phronomy_reservation])
+        @thread = Thread.current
+      end
+
+      # Own a standalone admission transaction.
+      # @api public
+      def accept
+        @persistence.coordinator.atomic { |scope| accept_in(scope) }
+        nil
+      end
+
+      # Participate without committing or publishing live state.
+      # @api public
+      def accept_in(scope)
+        check_thread!
+        raise Phronomy::ConfigurationError, "Agent admission is single-use" if @scope
+        @scope = scope
+        @persistence.participate(scope) do |records|
+          raise Phronomy::Error, "agent is closed: #{agent_id}" if @root.lifecycle_status == :closed
+          input_ref = records.contents.put_text(@input)
+          context_ref = records.contents.put_json(@config.fetch(:durable_context)) if @config.key?(:durable_context)
+          input_record = JournalRecord.new(agent_id: agent_id, kind: :input_received,
+            channel: :external, role: :user, content_ref: input_ref,
+            context_generation: @root.transcript_generation, context_candidate: false)
+          execution = AgentExecution.start(agent_root: @root, input_record: input_record,
+            execution_id: execution_id, metadata: {
+              "reservation" => correlation, "current_input_ref" => input_ref,
+              "durable_context_ref" => context_ref,
+              "execution_extension" => @config[:phronomy_execution_participant]&.binding&.to_h
+            }.merge(@preparation_metadata).compact)
+          input_record = JournalRecord.from_h(input_record.to_h.merge("execution_id" => execution_id))
+          execution = execution.with(execution_revision: 0, working_records: [input_record])
+          records.executions.create_active(execution)
+          next_root = @root.with(agent_revision: @root.agent_revision + 1, lifecycle_status: :active)
+          records.agents.save(agent_id, expected_revision: @root.agent_revision, root: next_root)
+          @result = [execution, next_root].freeze
+        end
+        nil
+      end
+
+      # Available to Agent execution only after the outermost successful response.
+      # @api private
+      def result
+        check_thread!
+        unless @result && @scope&.committed?
+          raise Phronomy::Persistence::TransactionError, "Agent admission has not committed"
+        end
+        @result
+      end
+
+      private
+
+      def check_thread!
+        raise Phronomy::Persistence::TransactionError, "Agent admission belongs to another execution context" unless @thread.equal?(Thread.current)
+      end
+    end
+  end
+end

data/lib/phronomy/{agent_already_exists_error.rb → agent/agent_already_exists_error.rb}

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../common/error"
+
 module Phronomy
   class AgentAlreadyExistsError < Phronomy::Error; end
 end

data/lib/phronomy/{agent_busy_error.rb → agent/agent_busy_error.rb}

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../common/error"
+
 module Phronomy
   class AgentBusyError < Phronomy::Error; end
 end

data/lib/phronomy/{agent_purged_error.rb → agent/agent_purged_error.rb}

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../common/error"
+
 module Phronomy
   class AgentPurgedError < Phronomy::Error; end
 end

data/lib/phronomy/agent/api/agent.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    StreamEvent = Data.define(:type, :payload)
+  end
+end
+
+require_relative "../async_event_api"
+
+unless Phronomy::Agent::Base < Phronomy::Agent::AsyncEventApi
+  Phronomy::Agent::Base.prepend(Phronomy::Agent::AsyncEventApi)
+end
+
+# Durable Agent Recovery and Agent-incarnation event binding.
+require_relative "../recovery/recovery_support"
+require_relative "../recovery/recovery_coordinator"

data/lib/phronomy/{execution_rehydration_required_error.rb → agent/api/execution_rehydration_required_error.rb}

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../../common/error"
+
 module Phronomy
   class ExecutionRehydrationRequiredError < Phronomy::Error; end
 end

data/lib/phronomy/agent/async_event_api.rb

@@ -12,6 +12,35 @@ module Phronomy
     # - approval notifications share the Agent listener as :approval_required;
     # - Recovery resolution uses resolve/resolve_async.
     module AsyncEventApi
+      def start_reserved_async(reservation:, input:, config: {})
+        unless reservation.is_a?(ReservedExecution) && reservation.agent_id == agent_id
+          raise ArgumentError, "reservation must belong to this Agent"
+        end
+        config = __invocation_config(_prepare_invocation_config(config, nil))
+        ExactExecution.start(agent: self, execution_id: reservation.execution_id, input: input,
+          config: config.merge(phronomy_reservation: reservation.correlation))
+      end
+
+      def resume_async(execution_id, config: {})
+        config = __invocation_config(_prepare_invocation_config(config, nil))
+        ExactExecution.start(agent: self, execution_id: execution_id, input: nil, config: config, resume_only: true)
+      end
+
+      def resume(execution_id, config: {})
+        _check_event_loop_reentrancy(:resume, :resume_async)
+        resume_async(execution_id, config: config).wait_result
+      end
+
+      def cancel_async(execution_id)
+        __assert_live_agent!
+        environment = __execution_environment
+        environment.submit(on_full: :raise) do
+          requested = persistence.request_cancellation(agent_id: agent_id, execution_id: execution_id)
+          ExecutionCancellation.signal(execution_id, agent_id, environment: environment) if requested
+          persistence.observe_execution(agent_id: agent_id, execution_id: execution_id)
+        end
+      end
+
       def invoke(
         input,
         config: {},
@@ -96,7 +125,7 @@ module Phronomy
 
       def approve_async(execution_id, approval_request_id:, approved: true, config: {})
         _reject_removed_generic_identity_keys!(config)
-        owner = Phronomy::Runtime.instance.__agent_execution_owner(execution_id)
+        owner = Phronomy::Agent::ExecutionRegistry.existing_current&.agent_execution_owner(execution_id)
         coordinator = if owner&.agent&.equal?(self)
           owner.coordinator
         else
@@ -115,8 +144,8 @@ module Phronomy
         expected_execution_revision:,
         subject:,
         outcome:,
-        result: Phronomy::Recovery::MISSING,
-        error: Phronomy::Recovery::MISSING
+        result: Phronomy::Agent::RecoveryRules::MISSING,
+        error: Phronomy::Agent::RecoveryRules::MISSING
       )
         _check_event_loop_reentrancy(:resolve, :resolve_async)
         resolve_async(
@@ -134,8 +163,8 @@ module Phronomy
         expected_execution_revision:,
         subject:,
         outcome:,
-        result: Phronomy::Recovery::MISSING,
-        error: Phronomy::Recovery::MISSING
+        result: Phronomy::Agent::RecoveryRules::MISSING,
+        error: Phronomy::Agent::RecoveryRules::MISSING
       )
         Phronomy::Agent::RecoveryCoordinator.new(self).resolve(
           execution_id,
@@ -149,26 +178,9 @@ module Phronomy
 
       private
 
-      # Framework-private execution-local event routing. This is intentionally
-      # not a public compatibility path for invoke_async(..., on_event:).
-      def __invoke_async_with_event_sink(
-        input,
-        on_event:, config: {},
-        invocation_context: nil
-      )
-        raise ArgumentError, "on_event is required" unless on_event
-
-        config = _prepare_invocation_config(config, invocation_context)
-        _start_agent_operation(
-          input,
-          config: config,
-          mode: :invoke,
-          listener: on_event
-        )
-      end
-
       def _start_agent_operation(input, config:, mode:, listener:)
-        config = _snapshot_durable_context(config)
+        config = __invocation_config(_snapshot_durable_context(config))
+        @_phronomy_execution_wiring = config.dup.freeze
         approval = _approval_configuration_snapshot(nil)
         execution_coordinator_for(config).start(
           input,
@@ -190,7 +202,7 @@ module Phronomy
         end
 
         bytes = Phronomy::CanonicalJSON.dump(value)
-        snapshot = Phronomy::Agent::Immutable.copy(
+        snapshot = Phronomy::Values::Immutable.copy(
           Phronomy::CanonicalJSON.load(bytes)
         )
         config.merge(durable_context: snapshot)
@@ -220,14 +232,7 @@ module Phronomy
         @execution_coordinator ||= Agent::ExecutionCoordinator.new(self)
       end
 
-      def execution_coordinator_for(config)
-        multi_agent = config.key?(:phronomy_handoff_bindings) ||
-          config.key?(:phronomy_handoff_context)
-        return execution_coordinator unless multi_agent
-
-        @multi_agent_execution_coordinator ||=
-          Phronomy::Agent::HandoffExecutionCoordinator.new(self)
-      end
+      def execution_coordinator_for(_config) = execution_coordinator
     end
   end
 end