phronomy 0.22.0 → 0.24.0

data/docs/migrations/0.22.md

@@ -0,0 +1,390 @@
+# Migration to 0.22
+
+Phronomy 0.22 includes clean-break Agent definition identity normalization and
+semantic Multi-Agent Handoff changes.
+
+## Agent definition identity and revision
+
+Agent instance identity and Agent definition identity are separate:
+
+```text
+Agent instance                  agent_id
+Agent definition lineage       agent_definition_id
+Agent definition revision      agent_definition_version
+```
+
+A named concrete Agent may now use its fully-qualified Ruby class name as the
+default definition lineage:
+
+```ruby
+module Billing
+  class Agent < Phronomy::Agent::Base
+    agent_definition version: 2
+  end
+end
+```
+
+The definition ID above is `Billing::Agent`. An explicit stable lineage remains
+supported:
+
+```ruby
+agent_definition id: "billing-agent", version: 2
+```
+
+Concrete subclasses do not implicitly inherit a parent's definition revision.
+Anonymous Agent subclasses cannot derive a fully-qualified class-name lineage
+and therefore require explicit `id:` when declaring their definition identity.
+
+The semantic revision field is a clean rename:
+
+```text
+AgentRoot#definition_version
+  -> AgentRoot#agent_definition_version
+
+AgentRoot durable key "definition_version"
+  -> "agent_definition_version"
+
+LLMInputBuildContext#definition_version
+  -> #agent_definition_version
+```
+
+No deprecated field alias or legacy AgentRoot backward decoder is provided.
+Persisted AgentRoot hashes that contain only `"definition_version"` must be
+migrated by the application before they are loaded by 0.22. Phronomy does not
+rewrite existing AgentRoot data automatically in this change.
+
+Existing `agent_id` values keep their identity semantics. Agent loading still
+uses the current exact-match policy for `(agent_definition_id,
+agent_definition_version)`. This semantic definition revision is not a
+Persistence codec/schema/format version.
+
+## Multi-Agent Handoff
+
+Multi-Agent Handoff changes from Tool-result/sentinel routing to an explicit
+framework control-transfer model. This is also a clean break: compatibility
+aliases for the removed Runner and Handoff routing API are intentionally not
+provided.
+
+## Runner API
+
+Before:
+
+```ruby
+runner = Phronomy::Agent::Runner.new(
+  agents: [triage, billing],
+  routes: {triage => [billing]}
+)
+```
+
+After:
+
+```ruby
+handoff = Phronomy::MultiAgent::Handoff.new(
+  source_agent: triage,
+  target_agent: billing
+)
+
+runner = Phronomy::MultiAgent::Runner.new(
+  main_agent: triage,
+  handoffs: [handoff]
+)
+```
+
+Removed public surface:
+
+- `Phronomy::Agent::Runner`
+- Runner constructor keywords `agents:` and `routes:`
+- Runner `#agents`
+- sentinel-based routing internals as a public compatibility boundary
+
+## Handoff model
+
+`Phronomy::MultiAgent::Handoff` now represents one semantic Source-to-Target
+edge between concrete live Agent instances:
+
+```ruby
+handoff = Phronomy::MultiAgent::Handoff.new(
+  source_agent: triage,
+  target_agent: billing,
+  description: "Transfer billing responsibility"
+)
+```
+
+Generated Tool names are transport details only. Applications must not persist,
+inspect, or route by those generated names. `Handoff#tool_name`,
+`Handoff#sentinel`, and `Handoff#to_tool_class` are not part of the new API.
+
+A Handoff request contains a required `responsibility` string. It is intercepted
+before ordinary Tool execution, so no synthetic Tool result is inserted merely
+to signal routing.
+
+One Provider outcome may contain either ordinary Tool Calls or one Handoff
+request. Mixing Handoff with ordinary Tool Calls, or returning multiple Handoff
+requests in one Provider outcome, raises `Phronomy::HandoffError`.
+
+## Handoff Policy and Context transfer
+
+`Phronomy::MultiAgent::HandoffPolicy` controls what may cross the Agent ownership
+boundary. The initial categories are:
+
+- `current_request`
+- `history`
+- `knowledge`
+- `tool_exchanges`
+
+Each category is `required`, `forbidden`, or `selectable`. Selectable categories
+have an Application-defined default of include or exclude. Required and forbidden
+categories are not exposed to the Source Agent as switches.
+
+The default policy requires the current request, includes history and Tool
+exchanges by default, and keeps persistent Knowledge opt-in.
+
+Transferred material is immutable request-scoped Handoff Context. It is not
+adopted automatically into the Target Journal or Target Knowledge. Provenance is
+preserved across multi-hop transfers.
+
+Handoff Policy and Context Policy have different authority:
+
+```text
+Handoff Policy
+  -> decides what may cross Source -> Target
+
+Target Context Policy
+  -> decides what is used for one Target LLM call
+```
+
+Transferred items therefore enter Target context assembly as ordinary selectable
+Context candidates before Target Context Policy runs.
+
+## Active Agent continuity
+
+The `main_agent` instance anchors one Runtime-local coordination lifetime. After
+a successful Handoff, the Target remains active for later user turns while the
+same main Agent instance and Runtime remain alive. Recreating only the
+`MultiAgent::Runner` facade does not reset that state.
+
+This active-Agent ownership is deliberately not durable. A process or Runtime
+reset starts a new coordination lifetime at `main_agent`; Phronomy does not infer
+active-Agent continuation from historical Handoff audit records.
+
+## Source execution outcome
+
+A Source Agent execution that transfers responsibility terminates explicitly as
+`handed_off`. The complete Provider outcome is retained for audit, but the
+Handoff control Tool Call is not made a future conversational Context candidate
+and no ordinary Handoff Tool result is generated.
+
+## Context Policy clean break (ACS-04)
+
+ACS-04 replaces the intermediate Context selection composition API with the
+final four-category Context Policy SPI. Application-defined policies receive an
+immutable `Phronomy::Agent::ContextPolicyInput` and return an immutable
+`Phronomy::Agent::ContextPlan`, each organized as `instruction`, `knowledge`,
+`tools`, and grouped `conversation`.
+
+Agent classes bind one Application-constructed Policy instance:
+
+```ruby
+class ResearchAgent < Phronomy::Agent::Base
+  context_policy RESEARCH_CONTEXT_POLICY
+end
+```
+
+The following intermediate APIs/internals are removed without compatibility
+aliases:
+
+- `ContextRequest`
+- `ContextPolicyDescriptor` / `ContextPolicyRegistry`
+- `DerivedContentSpec` and `ContextPlan#derived_contents`
+- `ContextPlan#selected_unit_ids`, `#ordering_hints`, `#policy_descriptor`
+- `Selection::Unit` / `Selection::Validator`
+- `DependencyAwareUnitBuilder`
+- `RequiredContextResolver`
+- `RecentFirstSelector`
+- `TokenBudgetPacker`
+- public Policy `parts` composition
+
+`Selection::Candidate` and `Selection::Constraint` remain internal normalization
+mechanisms while `ContextPolicyInput` is built; they are not the Application
+Policy SPI.
+
+ContextPolicy is Application code/runtime wiring rather than durable Agent
+state. The Policy object/descriptor is not persisted or reconstructed. A
+finalized `LLMInputManifest` remains the Recovery authority for an already-fixed
+Provider input.
+
+No Phronomy Persistence transaction spans `ContextPolicy#call`. Context is
+prepared from an immutable snapshot outside the transaction, then the durable
+base/revision is revalidated before the short Manifest/execution commit.
+
+The Context assembly policy version is now `8` because the semantic input/Plan
+contract, Tool subset handling, Policy-generated current-call material, and
+transaction boundary changed. Persisted Manifest readers that validate this
+version should accept version 8.
+
+## Workflow instance identity
+
+Workflow durable identity is a clean rename:
+
+```text
+thread_id
+  -> workflow_instance_id
+```
+
+The new name identifies one logical Workflow instance and is also the logical
+key supplied to `Persistence#workflow_states`.
+
+Application code must change Workflow invocation configuration and live signals:
+
+```ruby
+workflow.invoke(
+  input,
+  config: {workflow_instance_id: "order-123"}
+)
+
+workflow.signal(
+  workflow_instance_id: "order-123",
+  event: :external_result,
+  payload: result
+)
+```
+
+`WorkflowContext#thread_id` is removed and replaced by
+`WorkflowContext#workflow_instance_id`. No deprecated alias is provided.
+Supplying the old Workflow config key `:thread_id` raises `ArgumentError`
+instead of silently allocating a new Workflow identity.
+
+`workflow_instance_id` is framework-owned WorkflowContext metadata and is now a
+reserved application field name. If an existing context declares
+`field :workflow_instance_id`, rename that application field before upgrading;
+0.22 rejects the declaration with `ArgumentError`.
+
+The identifier value itself does not change. Existing durable key value
+`"order-123"` remains `"order-123"` and is interpreted as the same
+`workflow_instance_id`. Custom Persistence backends must rename the logical
+parameter in their Workflow repository SPI, but a database adapter does not need
+to rename a physical column solely for this migration.
+
+`InvocationContext#thread_id` is not used as an implicit Workflow identity after
+this change. CG-01 established the Workflow identity boundary; the generic Agent
+invocation identity cleanup described below completes the separate Agent-side
+removal.
+
+## Generic Agent invocation identity
+
+Agent-side generic invocation correlation is removed as a clean break.
+
+Removed public surface:
+
+```text
+InvocationContext#thread_id
+InvocationContext#session_id
+Agent#invoke(thread_id:)
+Agent#invoke_async(thread_id:)
+Agent#stream(thread_id:)
+Agent#stream_async(thread_id:)
+MultiAgent::Orchestrator#fan_out(thread_id:)
+MultiAgent::Orchestrator#fan_out_async(thread_id:)
+MultiAgent::Orchestrator#subagent(thread_id:)
+```
+
+No `correlation_id`, `conversation_id`, or `application_session_id` replacement
+is introduced. Applications that need correlation should keep it in their own
+tracing/observability metadata or use the purpose-specific domain identifier
+that owns the relevant lifecycle.
+
+`InvocationContext#task_id` and `#parent_task_id` remain tracing/observability
+identifiers. They are not Agent, Workflow, Tool, or Runtime routing identity.
+
+Agent invocation config also rejects the removed `thread_id` and `session_id`
+keys so the old generic identity cannot survive through an untyped config
+backdoor.
+
+The later CG-03b / ACS-10 Runtime foundation removes the shared generic
+FSMSession graph-identity metadata bridge. Agent, Tool, and Multi-Agent routing
+now uses concrete session-local sinks; Workflow metadata is passed explicitly as
+`workflow_instance_id` while its admission-owner redesign remains ACS-13 work.
+
+`JournalRecord#correlation_id` is also removed from the current canonical
+Journal model and `JournalRecord#to_h` representation. New approval and
+execution Journal records do not populate a generic correlation field.
+
+Existing durable Journal Hashes are not rewritten merely to remove the legacy
+key. `JournalRecord.from_h` accepts a legacy `correlation_id` key and ignores it
+while restoring the current canonical fields. The same rule applies to legacy
+Journal records nested in `AgentExecution#working_records`, because
+`AgentExecution.from_h` delegates their reconstruction to `JournalRecord.from_h`.
+
+Custom Persistence backends should stop producing `correlation_id` in new
+canonical Journal representations. A backend does not need to rewrite every
+existing stored row or drop a physical legacy column solely for this migration;
+old values may remain backend-internal while legacy records are decoded into the
+current correlation-free domain model.
+
+## Agent execution parent identity
+
+Tool and approval work now identifies its owning Agent execution with
+`execution_id`. The old `agent_invocation_id` terminology is not retained as a
+deprecated alias.
+
+Application-facing changes:
+
+```text
+ToolApprovalRequest#agent_invocation_id
+  -> ToolApprovalRequest#execution_id
+
+ToolApprovalRequest#to_h[:agent_invocation_id]
+  -> ToolApprovalRequest#to_h[:execution_id]
+
+ApprovalEvaluationRequest#agent_invocation_id
+  -> ApprovalEvaluationRequest#execution_id
+```
+
+ACS-11 also makes Tool approval-policy input a value-only worker-boundary
+contract. The live-object accessors are removed as a clean break:
+
+```text
+ApprovalEvaluationRequest#agent
+  -> #agent_id / #agent_definition_id / #agent_definition_version
+
+ApprovalEvaluationRequest#tool
+  -> #tool_name / #tool_schema / #origin / #metadata
+```
+
+The authorization worker captures Tool approval behavior before offload and
+does not receive a live Agent, Tool, or ToolInvocation object. Application
+approval/facts/requirement callables remain supported as Application-owned
+behavior handles.
+
+`tool_invocation_id`, provider `tool_call_id`, and the approval request's own
+`id` remain separate purpose-specific identifiers.
+
+Agent invocation config also rejects `agent_invocation_id` so application code
+cannot continue controlling the temporary Runtime routing identifier through an
+untyped config key.
+
+Suspended `AgentExecution` records created by an older version may contain
+`approval_request["agent_invocation_id"]`. `AgentExecution.from_h` accepts that
+legacy embedded shape, discards the old Runtime-oriented value, and derives the
+current logical parent from the enclosing execution's own `execution_id`. It
+does not reinterpret the historical `agent_invocation_id` value as an execution
+ID.
+
+Existing content-addressed approval audit bodies are not rewritten and may
+retain their historical key. New approval request writes use `execution_id`.
+This targeted compatibility handling does not define the general Persistence
+schema/versioning policy.
+
+CG-03b / ACS-10 now advances the Runtime routing half. `AgentInvocation` has no
+independent routing ID or duplicate `session_id`; `ToolInvocation#id` remains
+only the Tool lifecycle identity; and the private `parent_agent_invocation_id`
+routing carrier is removed. Agent, Tool, and Multi-Agent concrete sessions use
+fresh FSMSession IDs and session-local event sinks. Provider completion is routed
+to the owning FSMSession and carries `llm_call_id` before any live result apply.
+
+ACS-11 removes `AgentExecutionActivation` / `ActivationRegistry`: EventLoop is the
+single writer of Phronomy-managed live Agent execution state, and operation-
+specific Offload results are validated against current FSMSession/FSM state and
+semantic IDs before apply. Together with ADR-023, this closes the Agent/Tool
+CG-03 Runtime-foundation gap. Workflow opaque admission ownership remains
+separate ACS-13 work.

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

@@ -0,0 +1,65 @@
+# Durable semantic coordination V2 migration
+
+This Beta clean break applies to baseline `5472116cd99a63ec27875024c955ea82be612d6b`.
+
+| Previous surface | Current surface |
+|---|---|
+| `MultiAgent::Handoff`, `HandoffPolicy`, `Runner` | `Agent::Handoff`, `HandoffPolicy`, `HandoffRunner` (no aliases) |
+| Runtime-local Handoff routing | HandoffState at original main Agent ID; same Persistence domain required |
+| Anonymous Team/new Runtime queue | Explicit `team_definition id:, version:` and stable `team_id`; TeamRoot/TeamExecution |
+| Arbitrary aggregate object/error exception result | Pure replay-safe aggregate, canonical JSON result/error data |
+| Five backend repositories | Eight mandatory repositories; extend root and transaction views |
+| Direct standalone fan-out | Remains Runtime-only; no synthetic parent AgentExecution |
+
+```ruby
+class WorkTeam < Phronomy::MultiAgent::TeamCoordinator
+  team_definition id: "work-team", version: 1
+  coordinator_model "gpt-4o-mini"
+  coordinator_provider :openai
+  pool size: 2, agent: WorkerAgent
+  aggregate { |assignments| assignments.map { |a| a[:result] }.compact.join("\n") }
+end
+
+team = WorkTeam.create(team_id: "team-42", persistence: store)
+value = team.invoke("Prepare the report")
+runs = store.list_team_executions("team-42")
+run_id = runs.first.team_execution_id
+retained = store.team_execution_result(run_id)
+# After a restart with the same declared Team and worker definitions:
+team = WorkTeam.load("team-42", persistence: store, on_event: recovery_listener)
+value = team.resume(run_id)
+```
+
+`resume` consumes a stored terminal outcome without running the aggregator again.
+For unfinished runs, stored input/context/assignments and child reservations win.
+Compatible current Agent/Team classes, static registrations and Handoff graph are
+execution wiring, not serialized objects. Version matching checks declarations;
+Application must change versions for incompatible behavior and retain compatible
+wiring for old runs. It is not a source-code hash or automatic migration system.
+
+Use `Persistence#execution_result(id)` and owner-scoped `list_executions` for Agent
+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
+`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
+invoke remains the existing Agent execution cancellation mechanism; it does not
+promise rollback of external effects. Persisted pending child IDs remain
+available for recovery when external factual resolution is required.
+
+Callbacks and streaming progress may be lost after Runtime/process loss.
+Application notifications, outboxes, retries and external-effect deduplication
+belong to Application. No callback delivery ACK or restart replay is added.
+InMemory is useful for tests but a durable backend is required for actual F4
+storage retention. See ADR-018 and the V2 RC contract for guarantee limits.
+
+The existing `Agent#purge!` removes its own Handoff anchor atomically with its
+Agent records, after the anchor has no pending/active turn. Referenced outcomes
+deleted through retention/purge are unavailable, not evidence of a new reservation.
+Do not purge participating child/Target owners while their coordination is active.
+Team `stream` observes committed assignment progress; the construction `on_event`
+listener is passed to hidden Agents for their current Runtime events and Recovery.
+There is no additional Team callback delivery subsystem.