phronomy 0.23.0 → 0.24.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffed6b796d049192f4f782aea75353504c166b23c5b6e1f336ab73eb90bbeb54
-  data.tar.gz: 5655635e8ef6331496d0bb057dad602b2154cabae97ec87f4906123824b8c45d
+  metadata.gz: eb31ae2fdc7b102461fd91480ea2e2aaeda618fb65cc3eb885a9525ca1e985e2
+  data.tar.gz: 2ede56b656b789ff195561ac72cac5df2f51dba410dbee8e3025437985509e61
 SHA512:
-  metadata.gz: 242dcb66e87b5beaaa55e19541fc852821adccf971cad68c06d65bcf705352a670b67012fa8c706ea0263f69eb03793a9b67d0bc3d61df422d201b3e3b6aa1c2
-  data.tar.gz: 0b889a029056ad0a458a7318eacf0d3813072adf0f6b7ef8a448a02dd0a476b9146fcbdf90d4170ea3823058ba51a82aa4a0b7fb31e24f7e031404d9b7b27924
+  metadata.gz: fe717ea7a31272ad7d7247f214c59ca8c5370a80ce80e67d69d8bb14f5e285d779004545e56f3298e85d63ca7352ba430f2912e967453b899c1181e8d00fb77e
+  data.tar.gz: e3a45c05b4b8f129e61fa09ae7e23be8916aeae762642f5333fb3876c6d142091d836c8c33d3dcb0a3908d1d1d6d99261bffde3e07d8ad505aa136a0df9f9097

data/.mutant.yml

@@ -17,6 +17,6 @@ matcher:
     - Phronomy::Agent::ContextPolicies::Default
     - Phronomy::Agent::ContextPolicyInputBuilder
     - Phronomy::Agent::ContextPlanValidator
-    - Phronomy::MultiAgent::HandoffPolicy
-    - Phronomy::MultiAgent::HandoffProjection
+    - Phronomy::Agent::HandoffPolicy
+    - Phronomy::Agent::HandoffProjection
     - Phronomy::VectorStore::InMemory

data/CHANGELOG.md

@@ -12,6 +12,24 @@ Release history for 0.14.0 and earlier is archived in
 
 ## [Unreleased]
 
+### Fixed
+
+- Add runtime dependency constraint `json < 3` to prevent Faraday/RubyLLM JSON
+  parser incompatibilities from resolving in consumer environments.
+
+- Run recovered output filtering inside the ordinary Agent FSM so filter
+  exceptions commit a failed execution and release admission, including after
+  another restart. Preserve explicit filter blocking as the `blocked` status.
+- Propagate a coordinator's blocked outcome, and a worker's blocked outcome
+  under `on_error: :raise`, to Team failure. Preserve skipped worker errors and
+  committed failure precedence over later cancellation across restart.
+- Keep Recovery content materialization, approval restoration reads, and F1
+  resolution readback off EventLoop. Apply prepared invocation state only on
+  EventLoop, reject stale results, and retain confirmed resolution facts when
+  later content reads fail.
+- Avoid reading Orchestrator Knowledge again while constructing invocation-owned
+  Tools; those children inherit the Knowledge already saved with their slots.
+
 ---
 
 ## [0.23.0] - 2026-08-29

data/CONTRIBUTING.md

@@ -225,8 +225,8 @@ The authoritative subject list is `.mutant.yml`. It currently includes:
 - `Phronomy::Agent::ContextPolicies::Default`
 - `Phronomy::Agent::ContextPolicyInputBuilder`
 - `Phronomy::Agent::ContextPlanValidator`
-- `Phronomy::MultiAgent::HandoffPolicy`
-- `Phronomy::MultiAgent::HandoffProjection`
+- `Phronomy::Agent::HandoffPolicy`
+- `Phronomy::Agent::HandoffProjection`
 - `Phronomy::VectorStore::InMemory`
 
 The nightly mutation matrix mirrors this authoritative list so each subject can

data/README.md

@@ -19,7 +19,7 @@ tracking `main` directly.
 - **Persistence** — unified durable backend for Agent state and Workflow `workflow_states`.
 - **Workflow** — state-machine-driven application workflow with explicit events and wait states.
 - **Tool / Capability** — callable application capability exposed to an Agent; application-defined Tools subclass `Phronomy::Tool::Base`.
-- **Multi-Agent Handoff** — semantic Source-to-Target responsibility transfer with policy-bounded Context projection and Runtime-local active-Agent continuity.
+- **Multi-Agent Handoff** — semantic Source-to-Target responsibility transfer with policy-bounded Context projection and persisted active responsibility and exact Target recovery within one Persistence domain.
 - **EventLoop + FSMSession** — the framework control plane for logical lifecycle coordination.
 - **OffloadPool** — bounded operating-system-thread execution boundary for synchronous work that must not run on EventLoop.
 - **Task** — the common thread-free completion handle returned by Phronomy asynchronous APIs, including OffloadPool-backed work.

data/docs/architecture/multi-agent-handoff.md

@@ -20,19 +20,19 @@ returns control to the caller. Handoff changes the active Agent for the current
 coordination lifetime.
 
 Normative Handoff intent is
-[ADR-016](../decisions/016-semantic-multi-agent-handoff.md).
+[ADR-030](../decisions/030-agent-handoff-domain-and-durable-responsibility.md).
 
 ## 2. Public API
 
 ```ruby
-handoff = Phronomy::MultiAgent::Handoff.new(
+handoff = Phronomy::Agent::Handoff.new(
   source_agent: triage,
   target_agent: billing,
   description: "Transfer billing responsibility",
   policy: policy
 )
 
-runner = Phronomy::MultiAgent::Runner.new(
+runner = Phronomy::Agent::HandoffRunner.new(
   main_agent: triage,
   handoffs: [handoff]
 )
@@ -113,40 +113,35 @@ state changes only through normal Target-owned execution/mutation paths.
 A Target Agent execution has its own `execution_id`; Source execution identity is
 provenance/audit context, not Target execution identity.
 
-## 9. Next-turn continuity and durability
-
-The same `main_agent` instance plus the same Runtime define one coordination
-lifetime.
-
-Within that lifetime, the active Target remains active on later turns and across
-Runner-facade recreation. Runtime admission rejects racing concurrent turns for
-the same coordination lifetime.
-
-Active routing is **not durably rehydrated**. Runtime/process reset starts a new
-coordination lifetime at `main_agent`. Historical Handoff audit facts do not
-reconstruct active Target ownership.
-
-## 10. Cancellation and tracing
-
-Handoff does not create a separate cancellation domain; active Agent execution
-uses normal Agent semantics.
-
-One Runner user turn is automatically observable as `multi_agent.turn`. Source
-and Target Agent/LLM/Tool logical operations keep their own automatic spans and
-semantic IDs. Handoff adds no generic correlation identity or cross-Runtime
-parent-span guarantee.
-
-See [Tracing](tracing.md).
-
-## 11. Safety and removed API
-
-`Phronomy::MultiAgent::Runner::MAX_HANDOFFS` bounds transfers in one user turn.
-
-Not current contracts:
-
-- sentinel Handoff Tool results;
-- `Phronomy::Agent::Runner`;
-- `agents:` / `routes:` Runner configuration;
-- Agent-owned Handoff Tool registration;
-- generated Tool-name identity;
-- blanket Source history/Knowledge copying.
+## 9. Persisted responsibility and recovery
+
+The original main Agent ID anchors `HandoffState`; the active Agent is retained
+across compatible Runtime restarts. The graph must use one Persistence instance.
+Source `handed_off`, its journal/root transition, immutable HandoffContext and the
+reserved Target execution ID commit atomically. The Target is admitted under
+that ID only after an authoritative absence read and the usual Agent admission.
+An active exact Target uses Agent Recovery; a terminal Target result is reused.
+Target terminal settlement and routing stabilization share a transaction.
+
+A new Runtime supplies the graph/current definitions again. Tool transport names
+are deterministic from stable Source/Target Agent IDs and are resolved from that
+graph, without a global class registry. Persisted Context is not reprojected under
+current policy. Missing graph edges/definitions or a different Persistence domain
+fail before semantic continuation.
+
+`HandoffRunner#result(source_execution_id)` follows retained transfer links.
+`cancel(execution_id)` records a request against that exact turn; pending absent
+Targets are stopped without admission, active Targets use their existing Agent
+cancellation token, terminal outcomes remain immutable. No cancellation or
+observer loss rewinds active responsibility to the main Agent. Cancellation is
+not compensation for external effects; unresolved X0 still needs Agent Recovery.
+
+F1 commit response loss is resolved by exact readback. Read/decode failure is not
+absence. F4 recovery requires retained storage and compatible current wiring.
+`on_event` is Runtime-only; terminal results can be read without redelivery.
+
+Current graph objects and observers are not durably rehydrated; Application
+supplies compatible wiring. Source execution identity links each completed
+transfer to its exact reserved Target execution, independently of later turns.
+`Persistence#handoff_result(source_execution_id)` reads that turn without loading
+Agent owners, graph definitions, or listeners.

data/docs/architecture/persistence.md

@@ -12,14 +12,16 @@
 `Phronomy::Persistence` is the single durable-state backend abstraction for
 stateful Agents and durable Workflows.
 
-```text
-Persistence
-├─ contents
-├─ agents
-├─ journals
-├─ executions
-└─ workflow_states
-```
+| Repository | Durable authority |
+|---|---|
+| `contents` | Immutable content and manifests |
+| `agents` | AgentRoot |
+| `journals` | Append-only Agent journal |
+| `executions` | AgentExecution and owned child coordination |
+| `workflow_states` | Workflow snapshots |
+| `handoff_states` | Active responsibility and exact Target reservation |
+| `teams` | TeamRoot |
+| `team_executions` | Team tasks, assignments and outcomes |
 
 Persistence stores defined durable logical state. It is not serialization of the
 currently running Runtime object graph.
@@ -173,3 +175,12 @@ Therefore:
 
 InMemory implementation mechanisms do not become requirements for external
 backends unless the Backend SPI states the corresponding semantic property.
+
+## Durable semantic coordination extension
+
+ADR-031 extends the single transaction domain to `handoff_states`, `teams` and
+`team_executions`, alongside the existing five repositories. Current root and
+transaction views require all eight. Explicit identity/revision/admission metadata
+remains separate from opaque DurableRecord payloads. See the normative
+[backend contract](../persistence-backends.md) and
+[recovery clarifications](../design/durable-semantic-coordination/RECOVERY_CONTRACT_CLARIFICATIONS.md).

data/docs/architecture.md

@@ -50,7 +50,7 @@ explicit compatibility decision.
 | Journal-backed Knowledge and retrieval integration | [Knowledge and RAG](architecture/knowledge-and-rag.md) |
 | Filter, Context trust policy, approval, and isolation boundaries | [Security Boundaries](architecture/security-boundaries.md) |
 | Automatic logical-operation tracing and custom tracer SPI | [Tracing](architecture/tracing.md) |
-| Semantic Source-to-Target responsibility transfer | [Multi-Agent Handoff](architecture/multi-agent-handoff.md) |
+| Durable Agent-domain responsibility transfer | [Multi-Agent Handoff](architecture/multi-agent-handoff.md) |
 | Durable state, Runtime ownership, recovery, and codec boundaries | [Persistence](architecture/persistence.md) |
 | Request-scoped pre-Manifest customization | [before_llm_input](architecture/before-llm-input.md) |
 | Removed Agent Context / Memory architectures that must not return | [Removed Agent Context Architecture](architecture/removed/agent-context.md) |
@@ -80,3 +80,10 @@ It must not be used as a current implementation or compatibility contract.
 
 The old `spec/design/` documentation location is not part of the current
 documentation architecture.
+
+Durable multi-agent coordination is described by [ADR-029](decisions/029-semantic-completion-and-application-effect-boundary.md),
+[ADR-030](decisions/030-agent-handoff-domain-and-durable-responsibility.md) and
+[ADR-031](decisions/031-durable-multi-agent-coordination.md).
+TeamExecution is a purpose-specific CAS authority delegating coordinator/workers
+to ordinary Agents, with no Team FSMSession or second Workflow engine.
+Static subagent reservation lives in the existing parent AgentExecution metadata.

data/docs/decisions/016-semantic-multi-agent-handoff.md

@@ -2,7 +2,9 @@
 
 ## Status
 
-Accepted.
+Superseded by [ADR-030](030-agent-handoff-domain-and-durable-responsibility.md).
+The semantic Context-transfer rationale is retained in ADR-030; the namespace and
+Runtime-only routing contract below are historical.
 
 ## Context
 

data/docs/decisions/028-preparing-recovery-replay-contract.md

@@ -0,0 +1,106 @@
+# ADR-028: Replay-safe recovery for durably admitted `:preparing` Agent executions
+
+Status: Accepted
+
+## Context
+
+ADR-018 defines Agent execution resumption as continuation of the same logical
+`execution_id` from durable recovery state when there is no unresolved semantic
+operation that prevents safe continuation. The implementation already persists a
+new `AgentExecution` in `status: :preparing, phase: :preparing` before input
+filters, `before_llm_input`, Context Policy, and Manifest finalization run.
+
+Before this decision, process loss in that window left a durable active execution
+with no automatic continuation path.
+
+## Decision
+
+A `:preparing` execution may be resumed automatically only when the framework
+durably recorded `preparation_replayable == true`. Missing, false, or unsupported
+values fail closed. The recovered continuation keeps the same `execution_id`.
+
+The preparation region is **replay-safe, not deterministic**. Input filtering,
+`before_llm_input`, Context Policy, retrieval, and other preparation work may be
+executed again after process loss. Applications must ensure those callbacks are
+safe under at-least-once execution. The framework does not require repeated
+preparation to produce byte-identical results.
+
+Before Manifest finalization, preparation results may be recomputed. After the
+Manifest is durably committed, the Manifest is the authority and existing
+post-Manifest recovery rules apply.
+
+### Durable application context
+
+`config` remains a runtime/application Hash and is not generally durable. An
+Application value that affects preparation semantics and must survive restart is
+placed under one reserved key:
+
+```ruby
+config: {
+  durable_context: {
+    "tenant" => "A",
+    "search_profile" => "legal"
+  }
+}
+```
+
+`config[:durable_context]`, when present, must be a Hash accepted by
+`Phronomy::CanonicalJSON`. The framework performs a Canonical JSON round trip
+before execution admission and uses the detached immutable snapshot for both the
+initial run and any recovery replay. `durable_context: nil` and non-Hash values
+are rejected before an `AgentExecution` is created. Missing and explicit `{}` are
+distinct.
+
+The snapshot is stored in the Content Store and the execution retains only
+`durable_context_ref`.
+
+### Conservative replay eligibility
+
+This change intentionally does not add a new arbitrary raw-input serialization
+format. Current initial admission stores `extract_message(input)` as text, while
+filters and instruction construction may inspect the original Ruby input.
+Therefore automatic `:preparing` replay is enabled only for String invocation
+inputs. Non-String inputs fail closed after process loss at this phase.
+
+Automatic preparation replay is also disabled when the framework can see a
+Runtime-only semantic dependency that it cannot reconstruct, including:
+
+- Multi-Agent handoff/routing wiring;
+- a custom Agent invocation approval policy;
+- invocation-context approval/redaction/token-budget policy values.
+
+These conditions are represented by the single durable boolean
+`preparation_replayable`; the framework does not persist those Runtime objects.
+A true value records that no framework-known blocker was present; it does not
+replace the Application replay-safety contract for callbacks or custom config.
+
+Applications that use other ordinary `config` entries to influence preparation,
+Provider-adapter, Tool, or other continuation semantics are responsible for moving
+restart-required values into `config[:durable_context]` and reading them from that
+sub-Hash after recovery.
+
+### Agent definition compatibility
+
+Existing `agent_definition_id` / `agent_definition_version` load validation
+continues to guard runtime definition compatibility. Applications must increment
+the Agent definition version when a change to filters, hooks, Context Policy, or
+other preparation behavior is not recovery-compatible.
+
+## Non-goals
+
+This decision does not add:
+
+- recovery of caller `Task` objects;
+- durable Multi-Agent active routing or Handoff Context;
+- a durable execution-query API;
+- a new Recovery event;
+- Content Store garbage collection;
+- Workflow checkpoint changes;
+- deterministic replay of Application callbacks.
+
+## Consequences
+
+Direct, replay-safe String invocations can continue the same durable logical
+execution after process loss in the initial preparation window. Unsupported or
+ambiguous cases remain fail-closed rather than being guessed or silently
+abandoned.

data/docs/decisions/029-semantic-completion-and-application-effect-boundary.md

@@ -0,0 +1,220 @@
+# ADR-029: Semantic Completion and Application Effect Boundary
+
+## Status
+
+Accepted. V2 revision 2, 2026-09-06.
+
+User approval covers the V2 boundary and the five recovery-contract clarifications.
+Acceptance is design authority; it is not a claim of repository integration or test success.
+
+## Date
+
+2026-09-06
+
+## Context
+
+Phronomy durably records Agent semantic execution progress and terminal outcomes.
+After a terminal durable commit, Runtime may notify Application code through
+`on_event` and settle process-local caller Tasks.
+
+A previous proposal attempted to make terminal callback delivery itself durable
+across process loss by storing a pending-delivery descriptor, rediscovering
+pending callbacks on `Agent.load`, and durably acknowledging callback attempts.
+
+That approach crossed an architectural boundary.
+
+An arbitrary Application callback may perform an external effect outside
+Phronomy's Persistence transaction domain. Phronomy cannot make that effect
+exactly once. A process can die after the callback has produced an effect but
+before Phronomy records an acknowledgement, so retrying the callback still
+requires Application-level idempotency.
+
+Maintaining a framework outbox/ACK protocol therefore does not remove the
+Application responsibility that matters most, while it adds persistence indexes,
+recovery ordering, acknowledgement reconciliation and callback-specific state to
+the Agent execution engine.
+
+## Decision
+
+### 1. Semantic terminal state remains the durable boundary
+
+The existing AgentExecution terminal statuses remain semantic terminal states:
+
+```text
+completed
+handed_off
+failed
+cancelled
+rejected
+blocked
+```
+
+Phronomy does not add a callback-only `:completing` status.
+
+A known-successful terminal durable transition ends the logical AgentExecution and
+releases normal Agent admission according to ADR-025.
+
+### 2. Terminal semantic result/error evidence is durable
+
+The terminal transaction continues to persist the canonical semantic evidence
+already required by Agent durability, including as applicable:
+
+```text
+terminal AgentExecution
+AgentRoot revision/lifecycle state
+Journal terminal facts
+result_ref / error_ref
+Provider / Tool durable evidence already owned by Agent execution
+```
+
+Process loss after this commit must not cause the semantic execution to be rerun
+merely because the Application did not observe its completion callback.
+
+### 3. `on_event` is a process-local observation contract
+
+Application `on_event` callbacks are Runtime observations.
+
+Phronomy invokes them in the current process according to the existing callback
+error policy, but does not create a restart-spanning delivery obligation.
+
+Phronomy does not persist:
+
+```text
+terminal_delivery
+delivery_pending
+callback attempt_count
+callback acknowledgement state
+callback/Proc/Task references
+```
+
+`Agent.load` does not scan for or redeliver missed terminal callbacks.
+
+### 4. Callback loss after process loss is allowed
+
+The following failure is explicitly permitted:
+
+```text
+terminal semantic commit succeeds
+  -> process dies before Application callback
+  -> callback is not reconstructed/redelivered
+```
+
+The semantic outcome remains authoritative and must not be replayed.
+
+An Application that requires restart-spanning notification must implement that
+requirement in an Application-owned durable mechanism such as:
+
+```text
+outbox
+job queue
+database transaction/status row
+idempotency key
+Application Workflow
+```
+
+### 5. Callback effects are outside Phronomy's exactly-once guarantee
+
+Phronomy does not claim exactly-once semantics for:
+
+```text
+email
+webhook
+external database mutation
+message-broker publication
+arbitrary Application callback side effect
+```
+
+Applications own idempotency/deduplication appropriate to those systems.
+
+### 6. Caller Tasks remain Runtime-only
+
+A caller-facing Task can observe same-process success/failure and callback policy.
+It is not rehydrated after process loss.
+
+No durable state exists solely to recreate or settle a lost caller Task.
+
+### 7. Handoff routing is independent from callback delivery
+
+A Source Agent may terminalize as `:handed_off`.
+
+Durable Handoff responsibility transfer is governed by ADR-030 and does not depend
+on whether a local `:handoff` Application event was observed.
+
+Losing the local callback must not lose the Target routing state.
+
+### 8. Read-only outcome access and execution discovery
+
+Applications must be able to query an execution's owner, status and durable
+result/error by exact semantic execution ID without invoking/recovering it or
+redelivering callbacks. If admission committed before the caller received its ID,
+a public discovery path from the known Agent/Team identity must cover retained
+terminal as well as active executions. Candidate discovery does not guarantee
+request deduplication or unambiguous correlation. Existing retention applies.
+
+Reuse existing APIs where they meet this contract; map missing capabilities only
+after baseline inspection. Do not invent a framework outbox or request registry.
+See [RC-01](RECOVERY_CONTRACT_CLARIFICATIONS.md#1-rc-01--確定結果の参照と実行の発見).
+
+### 9. Unknown commit outcome and cancellation
+
+A failed read is not proof of absence. A lost commit acknowledgement requires
+readback with the same operation/reserved identities before new semantic work.
+Unresolved storage uncertainty follows existing Persistence error/retry rules,
+not Application factual invention (RC-02).
+
+Stopping observation, losing a caller, or shutting down Runtime does not by
+itself request semantic cancellation. Explicit semantic cancellation uses the
+existing Agent contract and preserves exact child identities and confirmed
+outcomes through its existing terminal/settlement boundaries (RC-04).
+
+The guarantee is reuse of confirmed durable outcomes and recovery of unfinished
+executions under the same semantic identity. Unknown external Provider/Tool
+effects follow existing Agent Recovery; external effects are not exactly once
+(RC-05).
+
+## Persistence / Runtime boundary
+
+The ordering remains:
+
+```text
+EventLoop-owned live authority
+  -> OffloadPool durable semantic transaction
+  -> Persistence commit
+  -> EventLoop apply / release admission
+  -> optional current-process Application callback
+  -> current-process Task settlement
+```
+
+No callback acknowledgement transaction follows.
+
+## Relationship to existing ADRs
+
+- Clarifies ADR-018 X0 boundaries: Application effects remain external.
+- Preserves ADR-023: Runtime routing identities remain non-durable.
+- Preserves ADR-024: EventLoop remains live-state writer.
+- Preserves ADR-025: AgentExecution lifetime ends at semantic terminal commit.
+- Does not alter ADR-028 preparation replay rules.
+- ADR-030/031 may persist additional **semantic coordination facts**, but not
+  restart-spanning Application callback delivery.
+
+## Required invariants
+
+1. Known terminal semantic work is never replayed merely because a callback may
+   have been lost.
+2. No terminal callback-delivery metadata/index/ACK protocol is required.
+3. Callbacks, Tasks and external side effects remain Runtime/Application concerns.
+4. Agent terminal statuses remain semantic states, not notification states.
+5. Phronomy does not claim exactly-once external effects.
+6. Read-only result access and retained execution discovery do not trigger work.
+7. Read/commit uncertainty and observation loss do not authorize replacement work.
+
+## Non-goals
+
+This ADR does not:
+
+- provide restart-spanning callback delivery;
+- provide arbitrary callback-side-effect deduplication;
+- recover caller Tasks;
+- introduce an Application outbox inside Persistence;
+- change Handoff routing semantics;
+- change cross-process ownership guarantees.