phronomy 0.22.0 → 0.24.0

data/lib/phronomy.rb

@@ -113,3 +113,9 @@ module Phronomy
     end
   end
 end
+
+# Shared Recovery primitives and Workflow Persistence F1 reconciliation.
+# Entity-specific Agent Recovery is loaded from lib/phronomy/agent.rb when the
+# Agent namespace is materialized.
+require_relative "phronomy/recovery"
+require_relative "phronomy/workflow_recovery"

data/scripts/api_snapshot.rb

@@ -19,12 +19,24 @@ require_relative "../lib/phronomy"
 PUBLIC_API_ENTRIES = [
   # Stable
   Phronomy::Agent::Base,
+  Phronomy::Agent::ContextPolicy,
+  Phronomy::Agent::ContextPolicyInput,
+  Phronomy::Agent::ContextPolicyInput::Provenance,
+  Phronomy::Agent::ContextPolicyInput::InstructionItem,
+  Phronomy::Agent::ContextPolicyInput::KnowledgeItem,
+  Phronomy::Agent::ContextPolicyInput::ToolItem,
+  Phronomy::Agent::ContextPolicyInput::ConversationItem,
+  Phronomy::Agent::ContextPlan,
+  Phronomy::InvocationContext,
   Phronomy::Agent::Context::Capability::Base,
   Phronomy::Workflow,
   Phronomy::WorkflowContext,
   Phronomy::Runnable,
   Phronomy::Agent::Context::Instruction::PromptTemplate,
   # Beta
+  Phronomy::Agent::Handoff,
+  Phronomy::Agent::HandoffPolicy,
+  Phronomy::Agent::HandoffRunner,
   Phronomy::MultiAgent::Orchestrator,
   Phronomy::MultiAgent::TeamCoordinator,
   Phronomy::Filter::Base,

data/sig/phronomy/agent.rbs

@@ -1,5 +1,184 @@
 module Phronomy
   module Agent
+    interface _BeforeLLMInputHook
+      def call: (LLMInputBuildContext context) -> LLMInputPatch?
+    end
+
+    class LLMInputPatch
+      attr_reader model_config_patch: Hash[untyped, untyped]?
+      attr_reader segment_candidates: Array[untyped]?
+
+      def initialize: (?model_config_patch: Hash[untyped, untyped]?, ?segment_candidates: Array[untyped]?) -> void
+      def self.empty: () -> LLMInputPatch
+    end
+
+    class LLMInputBuildContext
+      attr_reader agent_id: String
+      attr_reader agent_definition_id: String
+      attr_reader agent_definition_version: Integer
+      attr_reader config: Hash[untyped, untyped]
+      attr_reader call_sequence: Integer
+
+      def initialize: (agent_id: String, agent_definition_id: String, agent_definition_version: Integer, ?config: Hash[untyped, untyped], call_sequence: Integer) -> void
+    end
+
+    class ToolApprovalRequest
+      class Item
+        attr_reader tool_invocation_id: String
+        attr_reader tool_call_id: String?
+        attr_reader tool_name: String
+        attr_reader arguments: Hash[untyped, untyped]
+        attr_reader facts: Hash[untyped, untyped]
+        attr_reader reason: String?
+        attr_reader origin: Symbol
+        attr_reader metadata: Hash[untyped, untyped]
+
+        def initialize: (tool_invocation_id: String, tool_call_id: String?, tool_name: String, arguments: Hash[untyped, untyped], facts: Hash[untyped, untyped], reason: String?, origin: Symbol, metadata: Hash[untyped, untyped]) -> void
+        def self.from_h: (Hash[untyped, untyped]) -> Item
+        def to_h: () -> Hash[Symbol, untyped]
+      end
+
+      attr_reader id: String
+      attr_reader execution_id: String
+      attr_reader items: Array[Item]
+      attr_reader created_at: untyped
+
+      def initialize: (execution_id: String, items: Array[Item], ?id: String, ?created_at: untyped) -> void
+      def self.from_h: (Hash[untyped, untyped]) -> ToolApprovalRequest
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class ApprovalEvaluationRequest
+      attr_reader agent_id: String
+      attr_reader agent_definition_id: String
+      attr_reader agent_definition_version: Integer
+      attr_reader execution_id: String
+      attr_reader tool_name: String
+      attr_reader tool_schema: Hash[untyped, untyped]
+      attr_reader tool_invocation_id: String
+      attr_reader tool_call_id: String?
+      attr_reader arguments: Hash[untyped, untyped]
+      attr_reader facts: Hash[untyped, untyped]
+      attr_reader invocation_context: Hash[untyped, untyped]
+      attr_reader origin: Symbol
+      attr_reader metadata: Hash[untyped, untyped]
+      attr_reader default_decision: Symbol?
+
+      def initialize: (agent_id: String, agent_definition_id: String, agent_definition_version: Integer, execution_id: String, tool_name: String, tool_schema: Hash[untyped, untyped], tool_invocation_id: String, tool_call_id: String?, arguments: Hash[untyped, untyped], ?facts: Hash[untyped, untyped], ?invocation_context: Hash[untyped, untyped], ?origin: Symbol, ?metadata: Hash[untyped, untyped], ?default_decision: Symbol?) -> void
+    end
+
+    class LLMInputManifest
+      VERSION: String
+      CALL_MODES: Array[Symbol]
+      SEGMENT_DELIVERIES: Array[String]
+
+      def self.from_h: (Hash[String, untyped] hash) -> LLMInputManifest
+      def version: () -> String
+      def to_h: () -> Hash[String, untyped]
+    end
+
+    class ContextPolicyInput
+      class Provenance
+        attr_reader origin: Symbol
+        attr_reader content_ref: String?
+        attr_reader record_id: String?
+        attr_reader agent_id: String?
+        attr_reader execution_id: String?
+        attr_reader llm_call_id: String?
+        def initialize: (origin: Symbol, ?content_ref: String?, ?record_id: String?, ?agent_id: String?, ?execution_id: String?, ?llm_call_id: String?) -> void
+      end
+
+      class InstructionItem
+        attr_reader id: String
+        attr_reader kind: Symbol
+        attr_reader role: Symbol?
+        attr_reader content: untyped
+        attr_reader content_format: Symbol
+        attr_reader estimated_tokens: Integer
+        attr_reader required: bool
+        attr_reader provenance: Provenance
+        attr_reader metadata: Hash[untyped, untyped]
+        def initialize: (id: String, kind: Symbol, ?role: Symbol?, content: untyped, ?content_format: Symbol?, ?estimated_tokens: Integer?, ?required: bool?, ?provenance: Provenance?, ?metadata: Hash[untyped, untyped]) -> void
+        def required?: () -> bool
+      end
+
+      class KnowledgeItem
+        attr_reader id: String
+        attr_reader kind: Symbol
+        attr_reader role: Symbol?
+        attr_reader content: untyped
+        attr_reader content_format: Symbol
+        attr_reader estimated_tokens: Integer
+        attr_reader required: bool
+        attr_reader provenance: Provenance
+        attr_reader metadata: Hash[untyped, untyped]
+        def initialize: (id: String, kind: Symbol, ?role: Symbol?, content: untyped, ?content_format: Symbol?, ?estimated_tokens: Integer?, ?required: bool?, ?provenance: Provenance?, ?metadata: Hash[untyped, untyped]) -> void
+        def required?: () -> bool
+      end
+
+      class ToolItem
+        attr_reader id: String
+        attr_reader definition: Hash[untyped, untyped]
+        attr_reader estimated_tokens: Integer
+        attr_reader required: bool
+        attr_reader provenance: Provenance
+        attr_reader metadata: Hash[untyped, untyped]
+        def initialize: (id: String, definition: Hash[untyped, untyped], ?estimated_tokens: Integer?, ?required: bool?, ?provenance: Provenance?, ?metadata: Hash[untyped, untyped]) -> void
+        def required?: () -> bool
+      end
+
+      class ConversationItem
+        attr_reader id: String
+        attr_reader kind: Symbol
+        attr_reader role: Symbol?
+        attr_reader content: untyped
+        attr_reader content_format: Symbol
+        attr_reader sequence: Integer?
+        attr_reader estimated_tokens: Integer
+        attr_reader required: bool
+        attr_reader provenance: Provenance
+        attr_reader tool_call_id: String?
+        attr_reader tool_call_ids: Array[String]
+        attr_reader delivery: Symbol
+        attr_reader metadata: Hash[untyped, untyped]
+        def initialize: (id: String, kind: Symbol, ?role: Symbol?, content: untyped, ?content_format: Symbol?, ?sequence: Integer?, ?estimated_tokens: Integer?, ?required: bool?, ?provenance: Provenance?, ?tool_call_id: String?, ?tool_call_ids: Array[String], ?delivery: Symbol, ?metadata: Hash[untyped, untyped]) -> void
+        def required?: () -> bool
+        def with_required: (bool required) -> ConversationItem
+      end
+
+      attr_reader agent_id: String
+      attr_reader execution_id: String?
+      attr_reader call_sequence: Integer
+      attr_reader call_mode: Symbol
+      attr_reader instruction: Array[InstructionItem]
+      attr_reader knowledge: Array[KnowledgeItem]
+      attr_reader tools: Array[ToolItem]
+      attr_reader conversation: Array[Array[ConversationItem]]
+      attr_reader token_budget: untyped
+      attr_reader model_config: Hash[untyped, untyped]
+      attr_reader previous_manifest: LLMInputManifest?
+      attr_reader metadata: Hash[untyped, untyped]
+      def initialize: (agent_id: String, ?execution_id: String?, call_sequence: Integer, call_mode: Symbol, ?instruction: Array[InstructionItem], ?knowledge: Array[KnowledgeItem], ?tools: Array[ToolItem], ?conversation: Array[Array[ConversationItem]], token_budget: untyped, ?model_config: Hash[untyped, untyped], previous_manifest: LLMInputManifest?, ?metadata: Hash[untyped, untyped]) -> void
+    end
+
+    class ContextPlan
+      attr_reader instruction: Array[ContextPolicyInput::InstructionItem]
+      attr_reader knowledge: Array[ContextPolicyInput::KnowledgeItem]
+      attr_reader tools: Array[ContextPolicyInput::ToolItem]
+      attr_reader conversation: Array[Array[ContextPolicyInput::ConversationItem]]
+      attr_reader metadata: Hash[untyped, untyped]
+      def initialize: (?instruction: Array[ContextPolicyInput::InstructionItem], ?knowledge: Array[ContextPolicyInput::KnowledgeItem], ?tools: Array[ContextPolicyInput::ToolItem], ?conversation: Array[Array[ContextPolicyInput::ConversationItem]], ?metadata: Hash[untyped, untyped]) -> void
+    end
+
+    class ContextPolicy
+      def call: (ContextPolicyInput input) -> ContextPlan
+
+      def instruction_item: (content: untyped, ?role: Symbol, ?kind: Symbol, ?content_format: Symbol?, ?required: bool, ?metadata: Hash[untyped, untyped]) -> ContextPolicyInput::InstructionItem
+      def knowledge_item: (content: untyped, ?role: Symbol, ?kind: Symbol, ?content_format: Symbol?, ?required: bool, ?metadata: Hash[untyped, untyped]) -> ContextPolicyInput::KnowledgeItem
+      def conversation_item: (content: untyped, role: Symbol, ?kind: Symbol, ?content_format: Symbol?, ?sequence: Integer?, ?required: bool, ?tool_call_id: String?, ?tool_call_ids: Array[String], ?delivery: Symbol, ?metadata: Hash[untyped, untyped]) -> ContextPolicyInput::ConversationItem
+      def plan: (?instruction: Array[ContextPolicyInput::InstructionItem], ?knowledge: Array[ContextPolicyInput::KnowledgeItem], ?tools: Array[ContextPolicyInput::ToolItem], ?conversation: Array[Array[ContextPolicyInput::ConversationItem]], ?metadata: Hash[untyped, untyped]) -> ContextPlan
+    end
+
     class Base
       def self.model: (?String name) -> String?
       def self.instructions: (?untyped text) { (untyped) -> untyped } -> untyped
@@ -12,18 +191,41 @@ module Phronomy
       def self.cache_instructions: (?bool enabled) -> bool?
       def self.max_output_tokens: (?Integer value) -> Integer?
       def self.context_window: (?Integer value) -> Integer?
-      def self.agent_definition: (?id: String?, ?version: Integer?) -> Hash[Symbol, untyped]
-      def self.create: (?agent_id: String, ?context: untyped, ?knowledge: Array[untyped], ?persistence: Persistence?, ?metadata: Hash[untyped, untyped]) -> instance
-      def self.load: (String agent_id, persistence: Persistence) -> instance
+      def self.context_policy: () -> ContextPolicy
+                             | (ContextPolicy policy) -> ContextPolicy
+      def self.agent_definition: () -> Hash[Symbol, untyped]
+                               | (version: Integer, ?id: String?) -> Hash[Symbol, untyped]
+      def self.before_llm_input: (?_BeforeLLMInputHook callable) ?{ (LLMInputBuildContext context) -> LLMInputPatch? } -> _BeforeLLMInputHook?
+
+      # on_event is bound once to the live Agent Runtime incarnation. The block
+      # is an alternative spelling of on_event; supplying both is an error.
+      def self.create: (?agent_id: String, ?context: untyped, ?knowledge: Array[untyped], ?persistence: Persistence?, ?metadata: Hash[untyped, untyped], ?on_event: ^(untyped) -> void) ?{ (untyped event) -> void } -> instance
+      def self.load: (String agent_id, persistence: Persistence, ?on_event: ^(untyped) -> void) ?{ (untyped event) -> void } -> instance
+      def self.get: (String agent_id) -> instance?
       def self.live_for_execution: (String execution_id) -> instance
 
+      def initialize: (?agent_id: String?, ?context: untyped, ?knowledge: Array[untyped], ?persistence: Persistence?, ?metadata: Hash[untyped, untyped], ?on_event: ^(untyped) -> void) ?{ (untyped event) -> void } -> void
+
       attr_reader agent_id: String
       attr_reader persistence: Persistence
+      attr_accessor before_llm_input: _BeforeLLMInputHook?
+
+      # Public operation methods no longer accept per-invocation event listeners
+      # or event-listener blocks.
+      def invoke: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> Hash[Symbol, untyped]
+      def invoke_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> Task[Hash[Symbol, untyped]]
+      def stream: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> Hash[Symbol, untyped]
+      def stream_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> Task[Hash[Symbol, untyped]]
+
+      def approve: (String execution_id, approval_request_id: String, ?approved: bool, ?config: Hash[untyped, untyped]) -> untyped
+      def approve_async: (String execution_id, approval_request_id: String, ?approved: bool, ?config: Hash[untyped, untyped]) -> Task[untyped]
+
+      # Resolves a factual Recovery ambiguity. result: is meaningful for
+      # :succeeded; error: is required for :failed; neither is used by
+      # :not_performed.
+      def resolve: (String execution_id, expected_execution_revision: Integer, subject: Hash[Symbol, untyped], outcome: Symbol, ?result: untyped, ?error: Exception) -> untyped
+      def resolve_async: (String execution_id, expected_execution_revision: Integer, subject: Hash[Symbol, untyped], outcome: Symbol, ?result: untyped, ?error: Exception) -> Task[untyped]
 
-      def invoke: (untyped input, **untyped) -> Hash[Symbol, untyped]
-      def invoke_async: (untyped input, **untyped) -> Task[Hash[Symbol, untyped]]
-      def stream: (untyped input, **untyped) { (untyped event) -> void } -> Hash[Symbol, untyped]
-      def stream_async: (untyped input, **untyped) -> Task[Hash[Symbol, untyped]]
       def transcript: () -> Array[untyped]
       def add_knowledge: (untyped content, ?metadata: Hash[untyped, untyped]) -> self
       def clear_transcript!: () -> untyped

data/sig/phronomy/handoff.rbs

@@ -0,0 +1,41 @@
+module Phronomy
+  module Agent
+    class Handoff
+      attr_reader source_agent: ::Phronomy::Agent::Base
+      attr_reader target_agent: ::Phronomy::Agent::Base
+      attr_reader policy: HandoffPolicy
+      attr_reader description: String
+
+      def initialize: (source_agent: ::Phronomy::Agent::Base, target_agent: ::Phronomy::Agent::Base, ?policy: HandoffPolicy, ?description: String?) -> void
+    end
+
+    class HandoffPolicy
+      CATEGORIES: Array[Symbol]
+      MODES: Array[Symbol]
+      DEFAULTS: Array[Symbol]
+
+      def self.define: () { () -> void } -> HandoffPolicy
+      def self.default: () -> HandoffPolicy
+
+      def rule: (Symbol | String) -> untyped
+      def required?: (Symbol | String) -> bool
+      def forbidden?: (Symbol | String) -> bool
+      def selectable?: (Symbol | String) -> bool
+      def default_include?: (Symbol | String) -> bool
+      def selectable_categories: () -> Array[Symbol]
+      def to_h: () -> Hash[String, Hash[String, String]]
+    end
+
+    class HandoffRunner
+      MAX_HANDOFFS: Integer
+
+      attr_reader main_agent: ::Phronomy::Agent::Base
+      attr_reader handoffs: Array[Handoff]
+
+      def initialize: (main_agent: ::Phronomy::Agent::Base, ?handoffs: Array[Handoff]) -> void
+      def invoke: (untyped input, ?config: Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+      def result: (String execution_id) -> Hash[Symbol, untyped]
+      def cancel: (String execution_id) -> Hash[Symbol, untyped]
+    end
+  end
+end

data/sig/phronomy/multi_agent.rbs

@@ -0,0 +1,35 @@
+module Phronomy
+  module MultiAgent
+    class Orchestrator < ::Phronomy::Agent::Base
+      def self.subagent: (Symbol | String name, singleton(::Phronomy::Agent::Base) agent_class, ?on_error: Symbol, ?inherit_knowledge: bool) -> untyped
+      def self.registered_subagents: () -> Hash[Symbol | String, untyped]
+      def resume: (String execution_id, ?config: Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+      def dispatch_parallel: (*Hash[Symbol, untyped] tasks, ?max_concurrency: Integer?, ?on_error: Symbol, ?timeout: Numeric?, ?cancellation_token: untyped, ?invocation_context: untyped, ?inherit_knowledge: bool) -> Array[untyped]
+      def dispatch_parallel_async: (*Hash[Symbol, untyped] tasks, ?max_concurrency: Integer?, ?on_error: Symbol, ?timeout: Numeric?, ?cancellation_token: untyped, ?invocation_context: untyped, ?inherit_knowledge: bool) -> ::Phronomy::Task[untyped]
+      def fan_out: (agent: singleton(::Phronomy::Agent::Base), inputs: Array[untyped], ?config: Hash[Symbol, untyped], ?max_concurrency: Integer?, ?on_error: Symbol, ?timeout: Numeric?, ?cancellation_token: untyped, ?invocation_context: untyped, ?inherit_knowledge: bool) -> Array[untyped]
+      def fan_out_async: (agent: singleton(::Phronomy::Agent::Base), inputs: Array[untyped], ?config: Hash[Symbol, untyped], ?max_concurrency: Integer?, ?on_error: Symbol, ?timeout: Numeric?, ?cancellation_token: untyped, ?invocation_context: untyped, ?inherit_knowledge: bool) -> ::Phronomy::Task[untyped]
+    end
+
+    class TeamCoordinator
+      attr_reader team_id: String
+      attr_reader persistence: ::Phronomy::Persistence
+      def self.team_definition: (?id: String?, ?version: Integer?) -> Hash[Symbol, String | Integer]
+      def self.coordinator_model: (?String? value) -> String?
+      def self.coordinator_instructions: (?String? value) -> String?
+      def self.coordinator_provider: (?Symbol? value) -> Symbol?
+      def self.pool: (size: Integer, agent: singleton(::Phronomy::Agent::Base), ?on_error: Symbol) -> untyped
+      def self.schedule: () { (Array[untyped]) -> untyped } -> untyped
+      def self.aggregate: () { (Array[Hash[Symbol, untyped]]) -> untyped } -> untyped
+      def self.new: (?team_id: String, ?persistence: ::Phronomy::Persistence?, ?metadata: Hash[String, untyped], ?on_event: ^(untyped) -> untyped) -> instance
+      def self.create: (**untyped options) -> instance
+      def self.load: (String team_id, persistence: ::Phronomy::Persistence, ?on_event: ^(untyped) -> untyped) -> instance
+      def self.get: (String team_id) -> instance?
+      def invoke: (untyped input, ?config: Hash[Symbol, untyped]) -> untyped
+      def stream: (untyped input, ?config: Hash[Symbol, untyped]) ?{ (Hash[Symbol, untyped]) -> untyped } -> untyped
+      def resume: (String team_execution_id, ?config: Hash[Symbol, untyped]) -> untyped
+      def result: (String team_execution_id) -> Hash[Symbol, untyped]
+      def executions: (?after: String?, ?limit: Integer) -> Array[untyped]
+      def cancel: (String team_execution_id) -> Hash[Symbol, untyped]
+    end
+  end
+end

data/sig/phronomy/persistence.rbs

@@ -5,6 +5,7 @@ module Phronomy
     def exist?: (String content_id) -> bool
   end
 
+  # Runtime/domain-facing repository interfaces.
   interface _AgentRepository
     def create: (untyped root) -> untyped
     def load: (String agent_id) -> untyped
@@ -24,15 +25,102 @@ module Phronomy
     def load: (String execution_id) -> untyped
     def save: (String execution_id, expected_revision: Integer, execution: untyped) -> untyped
     def list_active: (String agent_id) -> Array[untyped]
+    def list: (String agent_id, ?after: String?, ?limit: Integer) -> Array[untyped]
     def delete: (String execution_id) -> untyped
     def delete_for_agent: (String agent_id) -> untyped
     def assert_idle!: (String agent_id) -> untyped
   end
 
   interface _WorkflowStateRepository
-    def load: (String thread_id) -> Hash[untyped, untyped]?
-    def save: (String thread_id, expected_revision: Integer?, snapshot: Hash[untyped, untyped]) -> untyped
-    def delete: (String thread_id, expected_revision: Integer) -> untyped
+    def load: (String workflow_instance_id) -> Hash[untyped, untyped]?
+    def save: (String workflow_instance_id, expected_revision: Integer?, snapshot: Hash[untyped, untyped]) -> Integer
+    def delete: (String workflow_instance_id, expected_revision: Integer) -> untyped
+  end
+
+  # Backend-side record repository interfaces. DurableRecord is the opaque data
+  # carrier. Identity/revision/index metadata is passed separately so backends do
+  # not need to interpret DurableRecord#payload.
+  interface _BackendAgentRecordRepository
+    def create: (agent_id: String, agent_revision: Integer, record: Persistence::DurableRecord) -> Persistence::DurableRecord
+    def load: (String agent_id) -> Persistence::DurableRecord
+    def save: (String agent_id, expected_revision: Integer, next_revision: Integer, record: Persistence::DurableRecord) -> Persistence::DurableRecord
+    def delete: (String agent_id) -> untyped
+  end
+
+  interface _BackendJournalRecordRepository
+    def append: (String agent_id, expected_position: Integer, records: Array[Persistence::DurableRecord], record_ids: Array[String]) -> Array[Persistence::DurableRecord]
+    def read: (String agent_id, ?after: Integer?, ?limit: Integer?) -> Array[Persistence::DurableRecord]
+    def head: (String agent_id) -> Integer
+    def delete: (String agent_id) -> untyped
+  end
+
+  interface _BackendExecutionRecordRepository
+    def create_active: (execution_id: String, agent_id: String, execution_revision: Integer, record: Persistence::DurableRecord) -> Persistence::DurableRecord
+    def load: (String execution_id) -> Persistence::DurableRecord
+    def save: (String execution_id, expected_revision: Integer, next_revision: Integer, agent_id: String, active: bool, record: Persistence::DurableRecord) -> Persistence::DurableRecord
+    def list_active: (String agent_id) -> Array[Persistence::DurableRecord]
+    def list: (String agent_id, ?after: String?, ?limit: Integer) -> Array[Persistence::DurableRecord]
+    def delete: (String execution_id) -> untyped
+    def delete_for_agent: (String agent_id) -> untyped
+    def assert_idle!: (String agent_id) -> untyped
+  end
+
+  interface _BackendWorkflowStateRecordRepository
+    def load: (String workflow_instance_id) -> Persistence::DurableRecord?
+    def save: (String workflow_instance_id, expected_revision: Integer?, next_revision: Integer, record: Persistence::DurableRecord) -> Persistence::DurableRecord
+    def delete: (String workflow_instance_id, expected_revision: Integer) -> untyped
+  end
+
+  interface _HandoffStateRepository
+    def load: (String main_agent_id) -> untyped
+    def save: (String main_agent_id, expected_revision: Integer?, state: untyped) -> untyped
+    def delete: (String main_agent_id, expected_revision: Integer) -> untyped
+  end
+
+  interface _TeamRepository
+    def create: (untyped root) -> untyped
+    def load: (String team_id) -> untyped
+    def save: (String team_id, expected_revision: Integer, root: untyped) -> untyped
+    def delete: (String team_id) -> untyped
+  end
+
+  interface _TeamExecutionRepository
+    def create_active: (untyped execution) -> untyped
+    def load: (String team_execution_id) -> untyped
+    def save: (String team_execution_id, expected_revision: Integer, execution: untyped) -> untyped
+    def list_active: (String team_id) -> Array[untyped]
+    def list: (String team_id, ?after: String?, ?limit: Integer) -> Array[untyped]
+    def delete: (String team_execution_id) -> untyped
+    def delete_for_team: (String team_id) -> untyped
+    def assert_idle!: (String team_id) -> untyped
+  end
+
+  interface _BackendHandoffStateRecordRepository
+    def load: (String main_agent_id) -> Persistence::DurableRecord?
+    def save: (String main_agent_id, expected_revision: Integer?, next_revision: Integer, active_agent_id: String, record: Persistence::DurableRecord) -> Persistence::DurableRecord
+    def delete: (String main_agent_id, expected_revision: Integer) -> untyped
+  end
+
+  interface _BackendTeamRecordRepository
+    def create: (team_id: String, team_revision: Integer, record: Persistence::DurableRecord) -> Persistence::DurableRecord
+    def load: (String team_id) -> Persistence::DurableRecord
+    def save: (String team_id, expected_revision: Integer, next_revision: Integer, record: Persistence::DurableRecord) -> Persistence::DurableRecord
+    def delete: (String team_id) -> untyped
+  end
+
+  interface _BackendTeamExecutionRecordRepository
+    def create_active: (team_execution_id: String, team_id: String, execution_revision: Integer, record: Persistence::DurableRecord) -> Persistence::DurableRecord
+    def load: (String team_execution_id) -> Persistence::DurableRecord
+    def save: (String team_execution_id, expected_revision: Integer, next_revision: Integer, team_id: String, active: bool, record: Persistence::DurableRecord) -> Persistence::DurableRecord
+    def list_active: (String team_id) -> Array[Persistence::DurableRecord]
+    def list: (String team_id, ?after: String?, ?limit: Integer) -> Array[Persistence::DurableRecord]
+    def delete: (String team_execution_id) -> untyped
+    def delete_for_team: (String team_id) -> untyped
+    def assert_idle!: (String team_id) -> untyped
+  end
+
+  interface _BackendWatermark
+    def assert_agent_watermark!: (agent_id: String, agent_revision: Integer, journal_position: Integer) -> true
   end
 
   interface _PersistenceTransactionView
@@ -41,6 +129,9 @@ module Phronomy
     def journals: () -> _JournalRepository
     def executions: () -> _ExecutionRepository
     def workflow_states: () -> _WorkflowStateRepository
+    def handoff_states: () -> _HandoffStateRepository
+    def teams: () -> _TeamRepository
+    def team_executions: () -> _TeamExecutionRepository
     def assert_agent_watermark!: (agent_id: String, agent_revision: Integer, journal_position: Integer) -> true
   end
 
@@ -54,6 +145,25 @@ module Phronomy
     class SerializationError < Phronomy::Error
     end
 
+    class DurableRecord
+      FORMAT_VERSION_PATTERN: Regexp
+      attr_reader record_type: String
+      attr_reader format_version: String
+      attr_reader payload: Hash[String, untyped]
+      def initialize: (record_type: String, format_version: String, payload: Hash[String, untyped]) -> void
+      def copy: () -> DurableRecord
+    end
+
+    module Migration
+      module InitialFormatMigration
+        def self.agent_root: (Hash[untyped, untyped] hash) -> DurableRecord
+        def self.agent_execution: (Hash[untyped, untyped] hash) -> DurableRecord
+        def self.journal_record: (Hash[untyped, untyped] hash) -> DurableRecord
+        def self.workflow_state: (workflow_instance_id: String, revision: Integer, snapshot: Hash[untyped, untyped]) -> DurableRecord
+        def self.llm_input_manifest: (Hash[untyped, untyped] hash) -> Hash[String, untyped]
+      end
+    end
+
     REQUIRED_CAPABILITIES: Hash[Symbol, bool]
 
     attr_reader contents: _ContentRepository
@@ -61,10 +171,19 @@ module Phronomy
     attr_reader journals: _JournalRepository
     attr_reader executions: _ExecutionRepository
     attr_reader workflow_states: _WorkflowStateRepository
+    attr_reader handoff_states: _HandoffStateRepository
+    attr_reader teams: _TeamRepository
+    attr_reader team_executions: _TeamExecutionRepository
+    def handoff_result: (String execution_id, ?main_agent_id: String?) -> Hash[Symbol, untyped]
+    def execution_result: (String execution_id) -> Hash[Symbol, untyped]
+    def list_executions: (String agent_id, ?after: String?, ?limit: Integer) -> Array[untyped]
+    def team_execution_result: (String team_execution_id) -> Hash[Symbol, untyped]
+    def list_team_executions: (String team_id, ?after: String?, ?limit: Integer) -> Array[untyped]
 
-    def initialize: (contents: _ContentRepository, agents: _AgentRepository, journals: _JournalRepository, executions: _ExecutionRepository, workflow_states: _WorkflowStateRepository) -> void
+    def initialize: (contents: _ContentRepository, agents: _BackendAgentRecordRepository, journals: _BackendJournalRecordRepository, executions: _BackendExecutionRecordRepository, workflow_states: _BackendWorkflowStateRecordRepository, handoff_states: _BackendHandoffStateRecordRepository, teams: _BackendTeamRecordRepository, team_executions: _BackendTeamExecutionRecordRepository) -> void
     def capabilities: () -> Hash[Symbol, bool]
     def transaction: () { (_PersistenceTransactionView) -> untyped } -> untyped
+    def build_transaction_view: (contents: _ContentRepository, agents: _BackendAgentRecordRepository, journals: _BackendJournalRecordRepository, executions: _BackendExecutionRecordRepository, workflow_states: _BackendWorkflowStateRecordRepository, handoff_states: _BackendHandoffStateRecordRepository, teams: _BackendTeamRecordRepository, team_executions: _BackendTeamExecutionRecordRepository, watermark: _BackendWatermark) -> _PersistenceTransactionView
     def assert_agent_watermark!: (agent_id: String, agent_revision: Integer, journal_position: Integer) -> true
   end
 end

data/sig/phronomy/runtime.rbs

@@ -26,18 +26,15 @@ end
 
 module Phronomy
   class InvocationContext
-    attr_reader thread_id: String?
-    attr_reader session_id: String?
     attr_reader user_id: String?
     attr_reader cancellation_token: Concurrency::CancellationToken?
     attr_reader deadline: untyped
-    attr_reader tracer_span: untyped
     attr_reader token_budget: Integer?
     attr_reader approval_policy: untyped
     attr_reader redaction_policy: untyped
     attr_reader task_id: String?
     attr_reader parent_task_id: String?
 
-    def initialize: (?thread_id: String?, ?session_id: String?, ?user_id: String?, ?cancellation_token: Concurrency::CancellationToken?, ?deadline: untyped, ?tracer_span: untyped, ?token_budget: Integer?, ?approval_policy: untyped, ?redaction_policy: untyped, ?task_id: String?, ?parent_task_id: String?) -> void
+    def initialize: (?user_id: String?, ?cancellation_token: Concurrency::CancellationToken?, ?deadline: untyped, ?token_budget: Integer?, ?approval_policy: untyped, ?redaction_policy: untyped, ?task_id: String?, ?parent_task_id: String?) -> void
   end
 end

data/sig/phronomy/workflow.rbs

@@ -2,7 +2,7 @@ module Phronomy
   module WorkflowContext
     def phase: () -> Symbol
     def halted?: () -> bool
-    def thread_id: () -> String?
+    def workflow_instance_id: () -> String?
     def merge: (Hash[Symbol, untyped] updates) -> self
     def to_h: () -> Hash[Symbol, untyped]
   end
@@ -15,7 +15,7 @@ module Phronomy
     def stream: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) { (untyped) -> void } -> untyped
     def resume: (state: untyped, ?input: untyped) -> untyped
     def send_event: (state: untyped, event: Symbol, ?input: untyped) -> untyped
-    def signal: (thread_id: String, event: Symbol, ?payload: untyped) -> bool
+    def signal: (workflow_instance_id: String, event: Symbol, ?payload: untyped) -> bool
 
     class Builder
       def initial: (Symbol state_name) -> untyped

data/sig/phronomy.rbs

@@ -19,6 +19,9 @@ module Phronomy
   class ConfigurationError < Error
   end
 
+  class HandoffError < Error
+  end
+
   class TransportError < Error
   end
 
@@ -37,6 +40,12 @@ module Phronomy
   class EventLoopReentrancyError < Error
   end
 
+  class AgentAlreadyExistsError < Error
+  end
+
+  class AgentPurgedError < Error
+  end
+
   class PoolShutdownError < Error
   end
 
@@ -45,6 +54,7 @@ module Phronomy
 
   class Configuration
     attr_accessor llm_adapter: LLMAdapter::Base
+    attr_accessor before_llm_input: Agent::_BeforeLLMInputHook?
   end
 
   def self.configuration: () -> Configuration