phronomy 0.27.0 → 0.29.0

data/sig/phronomy/agent/execution_contract.rbs

@@ -0,0 +1,132 @@
+module Phronomy
+
+  module Agent
+    type execution_wiring = { ?phronomy_execution_participant: _ExecutionParticipant, ?phronomy_control_bindings: Array[_ControlCapability], ?phronomy_transfer_context: TransferContext, ?phronomy_admission: _AdmissionOwner, ?phronomy_reservation: Hash[String, json_value] }
+    type execution_result = { agent_id: String, execution_id: String, status: Symbol, result: String?, output: String?, error: Hash[String, json_value]? }
+
+    class ReservedExecution < Data
+      attr_reader agent_id: String
+      attr_reader execution_id: String
+      attr_reader correlation: Hash[String, json_value]?
+      def self.new: (agent_id: String, execution_id: String, ?correlation: Hash[String, json_value]?) -> instance
+    end
+
+    class ExecutionObservation < Data
+      attr_reader agent_id: String
+      attr_reader execution_id: String
+      attr_reader status: Symbol
+      attr_reader result: String?
+      attr_reader error: Hash[String, json_value]?
+      attr_reader reservation: ReservedExecution?
+      attr_reader transfer_receipt: Hash[String, json_value]?
+      attr_reader cancellation_requested: bool
+      def self.new: (agent_id: String, execution_id: String, status: Symbol, result: String?, error: Hash[String, json_value]?, reservation: ReservedExecution?, transfer_receipt: Hash[String, json_value]?, cancellation_requested: bool) -> instance
+      def self.from_result: (execution_result) -> instance
+      def absent?: () -> bool
+      def terminal?: () -> bool
+      def active?: () -> bool
+      def continuable?: () -> bool
+      def value!: () -> execution_result
+      def to_result: () -> execution_result
+    end
+
+    class ExecutionExtensionState < Data
+      attr_reader binding_key: String
+      attr_reader binding_version: Integer
+      attr_reader state_ref: String?
+      def self.new: (binding_key: String, binding_version: Integer, ?state_ref: String?) -> instance
+      def self.from_h: (Hash[String, json_value]) -> instance
+      def to_h: () -> Hash[String, json_value]
+    end
+
+    class KnowledgeItem < Data
+      attr_reader content: String
+      attr_reader metadata: Hash[String, json_value]
+      def self.new: (content: String, ?metadata: Hash[String, json_value]) -> instance
+    end
+
+    class Retention < Data
+      attr_reader agent_id: String
+      attr_reader execution_id: String?
+      attr_reader owner_key: String
+      def self.new: (agent_id: String, owner_key: String, ?execution_id: String?) -> instance
+      def to_h: () -> Hash[String, json_value]
+    end
+
+    class ControlRequest < Data
+      attr_reader target_agent_id: String
+      attr_reader responsibility: String
+      attr_reader selection: Hash[Symbol, bool]
+      attr_reader llm_call_id: String?
+      attr_reader tool_call_id: String?
+      def self.new: (target_agent_id: String, responsibility: String, selection: Hash[Symbol, bool], ?llm_call_id: String?, ?tool_call_id: String?) -> instance
+    end
+
+    interface _ControlCapability
+      def source_agent_id: () -> String
+      def request: (arguments: Hash[String, json_value], llm_call_id: String?, tool_call_id: String?) -> ControlRequest
+    end
+
+    interface _ExecutionParticipant
+      def binding: () -> ExecutionExtensionState
+      def guard_change: (ExecutionChange change, ::Phronomy::Persistence::Transaction scope) -> void
+      def change_evidence: (ExecutionChange change, ::Phronomy::Persistence::Transaction scope) -> json_value
+      def commit: (ExecutionChange change) -> void
+    end
+
+    class ExecutionChange
+      attr_reader kind: :dispatch | :terminal
+      attr_reader agent_id: String
+      attr_reader execution_id: String
+      attr_reader extension: ExecutionExtensionState?
+      attr_reader operations: Array[Store::AuthorizedOperation]
+      attr_reader control_request: ControlRequest?
+      attr_reader cancel_requested: bool
+      attr_reader recovery_required: bool
+      attr_reader durable_context: Hash[String, json_value]?
+      attr_reader correlation: Hash[String, json_value]?
+      attr_reader coordinator: ::Phronomy::Persistence
+      def finishing?: () -> bool
+      def prepare_in: (::Phronomy::Persistence::Transaction scope) -> nil
+      def commit_in: (::Phronomy::Persistence::Transaction scope, ?state: ExecutionExtensionState?, ?transfer_receipt: Hash[String, json_value]?, ?pending: bool) -> nil
+      def transfer_context: (::Phronomy::Persistence::Transaction scope) -> TransferContext
+    end
+
+    class TransferContext
+      attr_reader responsibility: String
+      attr_reader items: Array[Item]
+      def self.from_h: (Hash[String, json_value]) -> instance
+      def initialize: (responsibility: String, ?items: Array[Item]) -> void
+      def to_h: () -> Hash[String, json_value]
+      class Item < Data
+        attr_reader candidate_category: Symbol
+        attr_reader policy_category: Symbol
+        attr_reader role: Symbol?
+        attr_reader content: json_value
+        attr_reader content_format: Symbol
+        attr_reader tool_call_id: String?
+        attr_reader provenance: Provenance
+        attr_reader metadata: Hash[String, json_value]
+      end
+      class Provenance < Data
+        attr_reader origin_agent_id: String?
+        attr_reader origin_record_id: String?
+        attr_reader origin_execution_id: String?
+        attr_reader origin_llm_call_id: String?
+        attr_reader origin_tool_call_id: String?
+        attr_reader transfer_path: Array[String]
+        def forwarded_to: (String agent_id) -> instance
+        def to_h: () -> Hash[String, json_value]
+      end
+    end
+  end
+
+  class Persistence
+    class SaveOutcome < Data
+      attr_reader disposition: :committed | :not_committed | :unknown
+      attr_reader original_error: Exception?
+      attr_reader read_error: Exception?
+      def self.compare: [V] (before: V, after: V, ?original_error: Exception?) { () -> V } -> instance
+    end
+  end
+end

data/sig/phronomy/agent/execution_environment.rbs

@@ -0,0 +1,20 @@
+module Phronomy
+  module Agent
+    # Private composition port; serial ownership and routing are process-local.
+    class ExecutionEnvironment
+      def self.install_provider: (^() -> ExecutionEnvironment provider) -> untyped
+      def self.current: () -> ExecutionEnvironment
+      def registry: () -> untyped
+      def existing_registry: () -> untyped
+      def ownership: () -> untyped
+      def existing_ownership: () -> untyped
+      def executing?: () -> bool
+      def session_phase: (String id) -> Symbol?
+      def submit: [V] (**untyped options) { () -> V } -> TaskResult[V]
+      def submit_authorization: [V] (timeout: Numeric?, cancellation_token: Concurrency::CancellationToken?) { () -> V } -> TaskResult[V]
+      def build_agent_session: (invocation: untyped, ?resume_event: Symbol?, ?resume_phase: Symbol?) -> untyped
+      def build_tool_session: (invocation: untyped, parent_sink: untyped, ?resume_event: Symbol?, ?resume_phase: Symbol?) -> untyped
+      def register_session: (untyped session, completion: TaskResult[untyped]) -> untyped
+    end
+  end
+end

data/sig/phronomy/agent/store.rbs

@@ -0,0 +1,73 @@
+module Phronomy
+  interface _AgentRepository
+    def create: (untyped root) -> untyped
+    def load: (String agent_id) -> untyped
+    def save: (String agent_id, expected_revision: Integer, root: untyped) -> untyped
+    def delete: (String agent_id) -> untyped
+  end
+
+  interface _JournalRepository
+    def append: (String agent_id, expected_position: Integer, records: Array[untyped]) -> Array[untyped]
+    def read: (String agent_id, ?after: Integer?, ?limit: Integer?) -> Array[untyped]
+    def head: (String agent_id) -> Integer
+    def delete: (String agent_id) -> untyped
+  end
+
+  interface _ExecutionRepository
+    def create_active: (untyped execution) -> untyped
+    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
+
+  module Agent
+    interface _Records
+      def contents: () -> _ContentRepository
+      def agents: () -> _AgentRepository
+      def journals: () -> _JournalRepository
+      def executions: () -> _ExecutionRepository
+      def guard_agent!: (String agent_id) -> untyped
+      def assert_agent_watermark!: (agent_id: String, agent_revision: Integer, journal_position: Integer) -> true
+    end
+
+    class Store
+      class AuthorizedOperation < Data
+        attr_reader invocation_id: String
+        attr_reader name: String
+        attr_reader arguments: Hash[String, json_value]
+        def self.new: (invocation_id: String, name: String, arguments: Hash[String, json_value]) -> instance
+      end
+
+      attr_reader coordinator: ::Phronomy::Persistence
+      attr_reader contents: _ContentRepository
+      attr_reader agents: _AgentRepository
+      attr_reader journals: _JournalRepository
+      attr_reader executions: _ExecutionRepository
+      def initialize: (coordinator: ::Phronomy::Persistence, records: ::Phronomy::Persistence::_Participant[_Records]) -> void
+      def transaction: [R] () { (_Records, ::Phronomy::Persistence::Transaction) -> R } -> R
+      def participate: [R] (::Phronomy::Persistence::Transaction scope) { (_Records) -> R } -> R
+      def exist?: (String agent_id) -> bool
+      def authorized_operations: (::Phronomy::Persistence::Transaction scope, agent_id: String, execution_id: String, invocation_id: String, name: String, arguments: Hash[String, untyped], names: Array[String]) -> Array[AuthorizedOperation]
+      def result: (String execution_id) -> Hash[Symbol, untyped]
+      def runs: (String owner_id, ?after: String?, ?limit: Integer) -> Array[untyped]
+      def observe_execution: (agent_id: String, execution_id: String, ?scope: ::Phronomy::Persistence::Transaction?) -> ExecutionObservation
+      def active_executions: (agent_id: String, ?scope: ::Phronomy::Persistence::Transaction?) -> Array[ExecutionObservation]
+      def definition: (agent_id: String, ?scope: ::Phronomy::Persistence::Transaction?) -> { id: String, version: Integer }
+      def knowledge_snapshot: (agent_id: String, ?scope: ::Phronomy::Persistence::Transaction?) -> Array[KnowledgeItem]
+      def execution_extension: (agent_id: String, execution_id: String, binding_key: String, ?scope: ::Phronomy::Persistence::Transaction?) -> ExecutionExtensionState?
+      def guard_agents: (::Phronomy::Persistence::Transaction scope, agent_ids: Array[String]) -> nil
+      def remove_execution_extension: (agent_id: String, execution_id: String, binding_key: String, scope: ::Phronomy::Persistence::Transaction) -> nil
+      def execution_identity: (String execution_id, ?scope: ::Phronomy::Persistence::Transaction?) -> ReservedExecution
+      def retained_references: (agent_id: String, ?scope: ::Phronomy::Persistence::Transaction?) -> Array[Retention]
+      def retain: (Retention retention, ?scope: ::Phronomy::Persistence::Transaction?) -> Retention
+      def release_retention: (agent_id: String, owner_key: String, scope: ::Phronomy::Persistence::Transaction) -> nil
+      def request_cancellation: (agent_id: String, execution_id: String, ?scope: ::Phronomy::Persistence::Transaction?) -> bool
+      def cancellation_requested?: (agent_id: String, execution_id: String, ?scope: ::Phronomy::Persistence::Transaction?) -> bool
+      def assert_agent_watermark!: (agent_id: String, agent_revision: Integer, journal_position: Integer) -> true
+    end
+  end
+end

data/sig/phronomy/agent/stream_callback_error.rbs

@@ -0,0 +1,8 @@
+module Phronomy
+  class StreamCallbackError < Error
+    attr_reader event_type: Symbol
+    attr_reader original_error: Exception
+    attr_reader result: untyped
+    def initialize: (event_type: Symbol, original_error: Exception, ?result: untyped, ?code: String?) -> void
+  end
+end

data/sig/phronomy/agent.rbs

@@ -1,25 +1,23 @@
 module Phronomy
   module Agent
-    interface _BeforeLLMInputHook
-      def call: (LLMInputBuildContext context) -> LLMInputPatch?
+    # The block's TaskResult is awaited and unwrapped; Scope itself is process-local.
+    def self.open_scope: [R] () { (Scope) -> (R | Phronomy::TaskResult[R]) } -> R
+
+    class Scope
+      def create: (singleton(Base) agent_class, **untyped options) ?{ (untyped event) -> void } -> Base
+      def create_async: (singleton(Base) agent_class, **untyped options) ?{ (untyped event) -> void } -> Phronomy::TaskResult[Base]
+      def load: (singleton(Base) agent_class, String agent_id, persistence: Store, **untyped options) ?{ (untyped event) -> void } -> Base
+      def load_async: (singleton(Base) agent_class, String agent_id, persistence: Store, **untyped options) ?{ (untyped event) -> void } -> Phronomy::TaskResult[Base]
     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
+    class ScopeCleanupError < Phronomy::Error
+      attr_reader failures: Array[{ agent_id: String, error: Exception }]
+      attr_reader result: untyped
+      def initialize: (failures: Array[{ agent_id: String, error: Exception }], result: untyped) -> void
     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
+    interface _BeforeLLMInputHook
+      def call: (Phronomy::Context::LLMInputBuildContext context) -> Phronomy::Context::LLMInputPatch?
     end
 
     class ToolApprovalRequest
@@ -67,118 +65,6 @@ module Phronomy
       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
@@ -190,23 +76,29 @@ module Phronomy
       def self.max_iterations: (?Integer value) -> Integer
       def self.cache_instructions: (?bool enabled) -> bool?
       def self.max_output_tokens: (?Integer value) -> Integer?
-      def self.context_policy: () -> ContextPolicy
-                             | (ContextPolicy policy) -> ContextPolicy
+      def self.context_policy: () -> Phronomy::Context::ContextPolicy
+                             | (Phronomy::Context::ContextPolicy policy) -> Phronomy::Context::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?
+      def self.before_llm_input: (?_BeforeLLMInputHook callable) ?{ (Phronomy::Context::LLMInputBuildContext context) -> Phronomy::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.create: (?agent_id: String, ?context: untyped, ?knowledge: Array[KnowledgeItem], ?retention: Retention?, ?persistence: Store?, ?metadata: Hash[untyped, untyped], ?on_event: ^(untyped) -> void) ?{ (untyped event) -> void } -> instance
+      def self.load: (String agent_id, persistence: Store, ?execution_wiring: execution_wiring, ?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
+      def initialize: (?agent_id: String?, ?context: untyped, ?knowledge: Array[KnowledgeItem], ?retention: Retention?, ?persistence: Store?, ?metadata: Hash[untyped, untyped], ?on_event: ^(untyped) -> void) ?{ (untyped event) -> void } -> void
 
       attr_reader agent_id: String
-      attr_reader persistence: Persistence
+      attr_reader persistence: Store
+      def knowledge_snapshot: () -> Array[KnowledgeItem]
+      def event_listener: () -> (^(Object) -> void)?
+      def start_reserved_async: (reservation: ReservedExecution, input: String, ?config: Hash[Symbol, Object]) -> TaskResult[execution_result]
+      def resume_async: (String execution_id, ?config: Hash[Symbol, Object]) -> TaskResult[execution_result]
+      def resume: (String execution_id, ?config: Hash[Symbol, Object]) -> execution_result
+      def cancel_async: (String execution_id) -> TaskResult[ExecutionObservation]
       attr_accessor before_llm_input: _BeforeLLMInputHook?
 
       # Public operation methods no longer accept per-invocation event listeners
@@ -232,6 +124,8 @@ module Phronomy
       def reset_context!: () -> untyped
       def close!: () -> untyped
       def purge!: () -> bool
+      def unload_async: () -> Phronomy::TaskResult[bool]
+      def unload!: (?timeout: Numeric?) -> bool
     end
   end
 end

data/sig/phronomy/common.rbs

@@ -0,0 +1,7 @@
+module Phronomy
+  type json_value = nil | bool | String | Integer | Float | Array[json_value] | Hash[String, json_value]
+  # Synchronous backends need only cooperative cancellation, not Runtime services.
+  interface _CancellationSignal
+    def raise_if_cancelled!: (?String message) -> nil
+  end
+end

data/sig/phronomy/content_store/contracts.rbs

@@ -0,0 +1,13 @@
+module Phronomy
+  interface _ContentRepository
+    def put: (String bytes, canonicalization_version: untyped) -> String
+    def fetch: (String content_id) -> String
+    def exist?: (String content_id) -> bool
+    def put_text: (String text) -> String
+    def put_json: (untyped value) -> String
+    def fetch_text: (String content_id) -> String
+    def fetch_json: (String content_id) -> untyped
+    def fetch_many: (Array[String] content_ids) -> Hash[String, String]
+  end
+
+end

data/sig/phronomy/context.rbs

@@ -0,0 +1,152 @@
+module Phronomy
+  module Context
+    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 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 BudgetExceededError < Phronomy::Error
+    end
+    class ManifestError < Phronomy::Error
+    end
+    class Assembly
+      @tracer: Phronomy::Tracing::Base
+      def initialize: (?tracer: Phronomy::Tracing::Base) -> void
+      class Prepared
+        attr_reader input: ContextPolicyInput
+        attr_reader plan: ContextPlan
+        attr_reader adapter_identity: Hash[String, String?]
+      end
+      def prepare: (input: ContextPolicyInput, policy: ContextPolicy, adapter_identity: Hash[String, String?]) -> Prepared
+      def store: (Prepared prepared, contents: Phronomy::_ContentRepository) -> [LLMInputManifest, String]
+    end
+    class DefaultPolicy < ContextPolicy
+      def self.instance: () -> DefaultPolicy
+    end
+  end
+end

data/sig/phronomy/embeddings/async/async_client.rbs

@@ -0,0 +1,9 @@
+module Phronomy
+  module Embeddings
+    class AsyncClient
+      def initialize: (adapter: Base, ?pool: untyped) -> void
+      def embed_async: (String text, ?Concurrency::CancellationToken? cancellation_token, ?timeout: Numeric?) -> TaskResult[Array[Float]]
+    end
+  end
+
+end

data/sig/phronomy/embeddings/base.rbs

@@ -0,0 +1,23 @@
+module Phronomy
+  module Embeddings
+    class InvalidResultError < Phronomy::Error
+    end
+
+    class TransportError < Phronomy::Error
+    end
+
+    class AuthenticationError < TransportError
+    end
+
+    class RateLimitError < TransportError
+    end
+
+    class Base
+      def embed: (String text, ?_CancellationSignal? cancellation_token) -> Array[Float]
+
+      # Protected extension SPI at runtime; RBS has no protected visibility.
+      private
+      def perform_embed: (String text, ?_CancellationSignal? cancellation_token) -> Array[Numeric]
+    end
+  end
+end