phronomy 0.26.0 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (557) hide show
  1. checksums.yaml +4 -4
  2. data/.mutant.yml +9 -9
  3. data/CHANGELOG.md +92 -0
  4. data/CONTRIBUTING.md +8 -8
  5. data/README.md +13 -3
  6. data/VERIFY.sh +27 -27
  7. data/benchmark/bench_agent_invoke.rb +26 -47
  8. data/benchmark/bench_context_assembler.rb +17 -15
  9. data/benchmark/bench_regression.rb +1 -1
  10. data/benchmark/bench_tool_schema.rb +1 -1
  11. data/docs/architecture/agent-chat-and-state-ownership.md +153 -0
  12. data/docs/architecture/agent-configuration-and-tool-binding.md +139 -0
  13. data/docs/architecture/agent-context.md +4 -2
  14. data/docs/architecture/agent-transition-ownership.md +13 -0
  15. data/docs/architecture/backend-groups.md +152 -0
  16. data/docs/architecture/before-llm-input.md +9 -3
  17. data/docs/architecture/context-management.md +31 -1
  18. data/docs/architecture/context-preparation-steps.md +90 -0
  19. data/docs/architecture/entry-action-and-team-wording.md +72 -0
  20. data/docs/architecture/execution-abstraction-review.md +88 -0
  21. data/docs/architecture/execution-boundaries.md +28 -0
  22. data/docs/architecture/execution-metadata-and-values.md +86 -0
  23. data/docs/architecture/generator-verifier-ownership.md +111 -0
  24. data/docs/architecture/multi-agent-handoff.md +11 -4
  25. data/docs/architecture/persistence-refactoring-plan.md +50 -0
  26. data/docs/architecture/persistence.md +45 -4
  27. data/docs/architecture/r8-unit1.md +104 -0
  28. data/docs/architecture/r8-unit10.md +72 -0
  29. data/docs/architecture/r8-unit11.md +71 -0
  30. data/docs/architecture/r8-unit12.md +67 -0
  31. data/docs/architecture/r8-unit13.md +61 -0
  32. data/docs/architecture/r8-unit14.md +72 -0
  33. data/docs/architecture/r8-unit15.md +65 -0
  34. data/docs/architecture/r8-unit16.md +54 -0
  35. data/docs/architecture/r8-unit17.md +73 -0
  36. data/docs/architecture/r8-unit18.md +92 -0
  37. data/docs/architecture/r8-unit19.md +61 -0
  38. data/docs/architecture/r8-unit2.md +55 -0
  39. data/docs/architecture/r8-unit20.md +51 -0
  40. data/docs/architecture/r8-unit21.md +79 -0
  41. data/docs/architecture/r8-unit22.md +74 -0
  42. data/docs/architecture/r8-unit23.md +81 -0
  43. data/docs/architecture/r8-unit3.md +130 -0
  44. data/docs/architecture/r8-unit4.md +79 -0
  45. data/docs/architecture/r8-unit5.md +115 -0
  46. data/docs/architecture/r8-unit6.md +71 -0
  47. data/docs/architecture/r8-unit7.md +70 -0
  48. data/docs/architecture/r8-unit8.md +78 -0
  49. data/docs/architecture/r8-unit9.md +73 -0
  50. data/docs/architecture/refactoring-closure.md +343 -0
  51. data/docs/architecture/remaining-refactoring-plan.md +390 -0
  52. data/docs/architecture/rubyllm-2-token-ownership.md +82 -0
  53. data/docs/architecture/storage-execution-boundaries.md +54 -0
  54. data/docs/architecture/tool-schema-recording-gap.md +56 -0
  55. data/docs/architecture/tracing.md +2 -2
  56. data/docs/architecture/workflow-terminal-ownership-design.md +104 -0
  57. data/docs/architecture.md +222 -0
  58. data/docs/decisions/014-unified-persistence-durable-state.md +11 -0
  59. data/docs/decisions/015-tool-public-facade-and-rbs-boundary.md +3 -3
  60. data/docs/decisions/024-event-loop-single-writer-agent-runtime.md +5 -1
  61. data/docs/decisions/025-process-local-agent-ownership-and-runtime-admission.md +13 -3
  62. data/docs/decisions/026-workflow-runtime-admission-and-durable-terminal-barrier.md +5 -1
  63. data/docs/decisions/027-llm-adapter-provider-boundary.md +2 -0
  64. data/docs/decisions/030-agent-handoff-domain-and-durable-responsibility.md +7 -0
  65. data/docs/decisions/031-durable-multi-agent-coordination.md +7 -0
  66. data/docs/decisions/032-storage-backend-composition.md +85 -0
  67. data/docs/decisions/033-domain-persistence-ownership.md +79 -0
  68. data/docs/decisions/034-handoff-runner-coordination-ownership.md +78 -0
  69. data/docs/decisions/035-tool-executor-capability-ownership.md +68 -0
  70. data/docs/decisions/036-context-contract-ownership.md +86 -0
  71. data/docs/decisions/037-common-definition-ownership.md +62 -0
  72. data/docs/decisions/038-responsibility-based-source-layout.md +145 -0
  73. data/docs/decisions/039-runtime-configuration-lifecycle-ownership.md +82 -0
  74. data/docs/decisions/040-configuration-default-composition.md +105 -0
  75. data/docs/decisions/041-feature-owned-identity-registries.md +100 -0
  76. data/docs/decisions/042-feature-owned-execution-state.md +106 -0
  77. data/docs/decisions/043-storage-execution-constraint-notifications.md +75 -0
  78. data/docs/decisions/044-agent-default-and-one-shot-composition.md +106 -0
  79. data/docs/decisions/045-worker-input-restriction-ownership.md +104 -0
  80. data/docs/decisions/046-agent-responsibility-layout-and-shared-records.md +110 -0
  81. data/docs/decisions/047-recovered-execution-continuation-contract.md +116 -0
  82. data/docs/decisions/048-dispatch-preparation-worker-ownership.md +120 -0
  83. data/docs/decisions/049-initial-preparation-worker-ownership.md +111 -0
  84. data/docs/decisions/050-approval-resume-snapshot-and-commit-ownership.md +98 -0
  85. data/docs/decisions/051-execution-outcome-worker-ownership.md +153 -0
  86. data/docs/decisions/052-tool-invocation-restoration-ownership.md +92 -0
  87. data/docs/decisions/053-shared-state-coordination-ownership.md +71 -0
  88. data/docs/decisions/054-workflow-terminal-save-single-owner.md +76 -0
  89. data/docs/decisions/055-terminal-observer-failure-settlement.md +60 -0
  90. data/docs/decisions/056-workflow-terminal-policy-ownership.md +87 -0
  91. data/docs/decisions/057-storage-transaction-boundaries.md +73 -0
  92. data/docs/decisions/058-neutral-storage-primitives.md +83 -0
  93. data/docs/decisions/059-backend-contracts-and-async-clients.md +74 -0
  94. data/docs/decisions/060-runtime-settings-and-application-configuration.md +86 -0
  95. data/docs/decisions/061-persistence-failure-contracts.md +89 -0
  96. data/docs/decisions/062-content-store-service.md +52 -0
  97. data/docs/decisions/063-execution-contracts-and-services.md +88 -0
  98. data/docs/decisions/064-agent-execution-and-multi-agent-responsibility.md +36 -0
  99. data/docs/decisions/065-vector-and-embeddings-common-operations.md +38 -0
  100. data/docs/decisions/066-llm-and-tool-operation-contracts.md +20 -0
  101. data/docs/decisions/067-agent-progress-and-engine-connection.md +29 -0
  102. data/docs/decisions/068-agent-tool-child-progress-and-tool-operation.md +36 -0
  103. data/docs/decisions/README.md +52 -6
  104. data/docs/design/durable-semantic-coordination/IMPLEMENTATION_DESIGN_V2.md +6 -0
  105. data/docs/design/durable-semantic-coordination/IMPLEMENTATION_REPORT.md +6 -0
  106. data/docs/execution-boundaries-preview.md +45 -0
  107. data/docs/features.md +16 -5
  108. data/docs/getting-started.md +11 -8
  109. data/docs/migrations/0.15.md +5 -0
  110. data/docs/migrations/0.22.md +2 -2
  111. data/docs/migrations/durable-semantic-coordination-v2.md +8 -0
  112. data/docs/migrations/handoff-runner-multi-agent.md +37 -0
  113. data/docs/migrations/neutral-storage-spi.md +43 -0
  114. data/docs/migrations/parallel-tool-chat-removal.md +49 -0
  115. data/docs/migrations/persistence-failure-contracts.md +67 -0
  116. data/docs/migrations/r8-unit10.md +36 -0
  117. data/docs/migrations/r8-unit11.md +33 -0
  118. data/docs/migrations/r8-unit12.md +31 -0
  119. data/docs/migrations/r8-unit13.md +36 -0
  120. data/docs/migrations/r8-unit14.md +31 -0
  121. data/docs/migrations/r8-unit15.md +31 -0
  122. data/docs/migrations/r8-unit16.md +26 -0
  123. data/docs/migrations/r8-unit17.md +28 -0
  124. data/docs/migrations/r8-unit18.md +29 -0
  125. data/docs/migrations/r8-unit19.md +28 -0
  126. data/docs/migrations/r8-unit20.md +24 -0
  127. data/docs/migrations/r8-unit21.md +28 -0
  128. data/docs/migrations/r8-unit22.md +29 -0
  129. data/docs/migrations/r8-unit23.md +20 -0
  130. data/docs/migrations/r8-unit4.md +67 -0
  131. data/docs/migrations/r8-unit5.md +75 -0
  132. data/docs/migrations/r8-unit6.md +109 -0
  133. data/docs/migrations/r8-unit7.md +31 -0
  134. data/docs/migrations/r8-unit8.md +33 -0
  135. data/docs/migrations/r8-unit9.md +28 -0
  136. data/docs/migrations/shared-state-multi-agent.md +44 -0
  137. data/docs/migrations/storage-async-client.md +103 -0
  138. data/docs/migrations/storage-backend-composition.md +117 -0
  139. data/docs/migrations/storage-transaction-boundaries.md +74 -0
  140. data/docs/migrations/vector-async-clients.md +110 -0
  141. data/docs/persistence-backends.md +190 -215
  142. data/docs/runtime-and-concurrency.md +142 -32
  143. data/lib/phronomy/agent/admission.rb +78 -0
  144. data/lib/phronomy/{agent_already_exists_error.rb → agent/agent_already_exists_error.rb} +2 -0
  145. data/lib/phronomy/{agent_busy_error.rb → agent/agent_busy_error.rb} +2 -0
  146. data/lib/phronomy/{agent_purged_error.rb → agent/agent_purged_error.rb} +2 -0
  147. data/lib/phronomy/agent/api/agent.rb +17 -0
  148. data/lib/phronomy/{execution_rehydration_required_error.rb → agent/api/execution_rehydration_required_error.rb} +2 -0
  149. data/lib/phronomy/agent/async_event_api.rb +38 -33
  150. data/lib/phronomy/agent/base.rb +106 -294
  151. data/lib/phronomy/agent/before_llm_input.rb +64 -0
  152. data/lib/phronomy/{agent.rb → agent/composition/run_once.rb} +4 -13
  153. data/lib/phronomy/agent/context_candidate_resolver.rb +2 -2
  154. data/lib/phronomy/agent/context_importer.rb +2 -2
  155. data/lib/phronomy/agent/{context_assembler.rb → context_preparation.rb} +157 -288
  156. data/lib/phronomy/agent/control_request.rb +21 -0
  157. data/lib/phronomy/agent/{agent_execution.rb → execution/agent_execution.rb} +8 -4
  158. data/lib/phronomy/agent/{agent_invocation.rb → execution/agent_invocation.rb} +32 -63
  159. data/lib/phronomy/agent/execution/approval_resume_commit.rb +108 -0
  160. data/lib/phronomy/agent/execution/dispatch_preparation.rb +195 -0
  161. data/lib/phronomy/agent/{exact_execution.rb → execution/exact_execution.rb} +43 -23
  162. data/lib/phronomy/agent/{execution_cancellation.rb → execution/execution_cancellation.rb} +8 -5
  163. data/lib/phronomy/agent/execution/execution_coordinator.rb +1744 -0
  164. data/lib/phronomy/agent/execution/execution_failure.rb +30 -0
  165. data/lib/phronomy/agent/execution/execution_metadata.rb +54 -0
  166. data/lib/phronomy/agent/execution/execution_outcome_committer.rb +288 -0
  167. data/lib/phronomy/agent/execution/execution_registry.rb +463 -0
  168. data/lib/phronomy/agent/execution/execution_session_runner.rb +113 -0
  169. data/lib/phronomy/agent/execution/initial_preparation.rb +323 -0
  170. data/lib/phronomy/agent/execution/invocation_actions.rb +368 -0
  171. data/lib/phronomy/agent/execution/invocation_transitions.rb +124 -0
  172. data/lib/phronomy/agent/execution/runtime_record_encoder.rb +210 -0
  173. data/lib/phronomy/agent/execution_change.rb +161 -0
  174. data/lib/phronomy/agent/execution_environment.rb +36 -0
  175. data/lib/phronomy/agent/execution_extension_state.rb +21 -0
  176. data/lib/phronomy/agent/execution_observation.rb +35 -0
  177. data/lib/phronomy/agent/filterable.rb +182 -0
  178. data/lib/phronomy/agent/{handoff_context.rb → handoff/transfer_context.rb} +6 -6
  179. data/lib/phronomy/agent/{handoff_projection.rb → handoff/transfer_projection.rb} +14 -33
  180. data/lib/phronomy/agent/handoff_error.rb +7 -0
  181. data/lib/phronomy/agent/{journal_projection.rb → journal/journal_projection.rb} +4 -0
  182. data/lib/phronomy/agent/{journal_record.rb → journal/journal_record.rb} +3 -3
  183. data/lib/phronomy/agent/{llm_call_record.rb → journal/llm_call_record.rb} +2 -2
  184. data/lib/phronomy/agent/knowledge_item.rb +13 -0
  185. data/lib/phronomy/agent/{agent_root.rb → lifecycle/agent_root.rb} +6 -2
  186. data/lib/phronomy/agent/lifecycle/default_persistence.rb +29 -0
  187. data/lib/phronomy/{engine/runtime/agent_ownership_registry.rb → agent/lifecycle/ownership_registry.rb} +24 -15
  188. data/lib/phronomy/agent/persistence/agent_repository.rb +69 -0
  189. data/lib/phronomy/agent/persistence/cancellation_repository.rb +51 -0
  190. data/lib/phronomy/agent/persistence/codec.rb +338 -0
  191. data/lib/phronomy/agent/persistence/execution_repository.rb +124 -0
  192. data/lib/phronomy/agent/persistence/journal_repository.rb +63 -0
  193. data/lib/phronomy/agent/persistence/records.rb +33 -0
  194. data/lib/phronomy/agent/persistence/retention_repository.rb +70 -0
  195. data/lib/phronomy/agent/persistence/storage_schema.rb +29 -0
  196. data/lib/phronomy/agent/persistence/watermark.rb +29 -0
  197. data/lib/phronomy/agent/recovery/invocation_restorer.rb +124 -0
  198. data/lib/phronomy/agent/{recovery_coordinator → recovery/recovery_coordinator}/continuation.rb +28 -51
  199. data/lib/phronomy/agent/{recovery_coordinator → recovery/recovery_coordinator}/installation.rb +50 -55
  200. data/lib/phronomy/agent/{recovery_coordinator → recovery/recovery_coordinator}/resolution.rb +38 -43
  201. data/lib/phronomy/agent/{recovery_coordinator.rb → recovery/recovery_coordinator.rb} +26 -23
  202. data/lib/phronomy/agent/recovery/recovery_rules.rb +119 -0
  203. data/lib/phronomy/agent/recovery/recovery_support.rb +224 -0
  204. data/lib/phronomy/agent/reserved_execution.rb +16 -0
  205. data/lib/phronomy/agent/retention.rb +17 -0
  206. data/lib/phronomy/agent/runtime_binding/engine_environment.rb +60 -0
  207. data/lib/phronomy/agent/runtime_binding/engine_session_builder.rb +34 -0
  208. data/lib/phronomy/agent/runtime_binding/phase_machine_builder.rb +64 -0
  209. data/lib/phronomy/agent/runtime_binding/tool_session_builder.rb +34 -0
  210. data/lib/phronomy/agent/{ruby_llm_materializer.rb → runtime_input.rb} +19 -39
  211. data/lib/phronomy/agent/saved_context_reader.rb +55 -0
  212. data/lib/phronomy/agent/settings.rb +47 -0
  213. data/lib/phronomy/agent/state_writer.rb +166 -0
  214. data/lib/phronomy/agent/store.rb +253 -0
  215. data/lib/phronomy/{stream_callback_error.rb → agent/stream_callback_error.rb} +2 -0
  216. data/lib/phronomy/agent/{approval_evaluation_request.rb → tool_execution/approval_evaluation_request.rb} +1 -12
  217. data/lib/phronomy/agent/{tool_approval_request.rb → tool_execution/tool_approval_request.rb} +1 -10
  218. data/lib/phronomy/agent/tool_execution/tool_binding.rb +30 -0
  219. data/lib/phronomy/agent/{tool_invocation.rb → tool_execution/tool_invocation.rb} +114 -248
  220. data/lib/phronomy/agent/tool_execution/tool_invocation_actions.rb +107 -0
  221. data/lib/phronomy/agent/tool_execution/tool_invocation_transitions.rb +70 -0
  222. data/lib/phronomy/common/configuration_error.rb +7 -0
  223. data/lib/phronomy/common/error.rb +5 -0
  224. data/lib/phronomy/{agent → common/values}/immutable.rb +9 -1
  225. data/lib/phronomy/common/values/serializable.rb +32 -0
  226. data/lib/phronomy/configuration/runtime_settings.rb +49 -0
  227. data/lib/phronomy/content_store/storage_schema.rb +12 -0
  228. data/lib/phronomy/content_store/stored_contents.rb +44 -0
  229. data/lib/phronomy/context/assembly.rb +202 -0
  230. data/lib/phronomy/{context_budget_exceeded_error.rb → context/budget_exceeded_error.rb} +5 -1
  231. data/lib/phronomy/context/candidate.rb +51 -0
  232. data/lib/phronomy/context/constraint.rb +47 -0
  233. data/lib/phronomy/{agent → context}/context_plan.rb +2 -2
  234. data/lib/phronomy/{agent → context}/context_plan_validator.rb +3 -3
  235. data/lib/phronomy/{agent → context}/context_policy.rb +1 -1
  236. data/lib/phronomy/{agent → context}/context_policy_input.rb +7 -7
  237. data/lib/phronomy/{agent → context}/context_policy_input_builder.rb +1 -1
  238. data/lib/phronomy/context/default_policy.rb +140 -0
  239. data/lib/phronomy/context/final_budget_validator.rb +33 -0
  240. data/lib/phronomy/{agent → context}/llm_input_build_context.rb +2 -2
  241. data/lib/phronomy/{agent → context}/llm_input_manifest.rb +21 -21
  242. data/lib/phronomy/{agent → context}/llm_input_patch.rb +3 -3
  243. data/lib/phronomy/context/manifest_error.rb +10 -0
  244. data/lib/phronomy/context/prompt_template.rb +98 -0
  245. data/lib/phronomy/{vector_store → documents}/loader/base.rb +1 -1
  246. data/lib/phronomy/{vector_store → documents}/loader/csv_loader.rb +2 -2
  247. data/lib/phronomy/{vector_store → documents}/loader/markdown_loader.rb +3 -3
  248. data/lib/phronomy/{vector_store → documents}/loader/plain_text_loader.rb +2 -2
  249. data/lib/phronomy/{vector_store → documents}/splitter/base.rb +1 -1
  250. data/lib/phronomy/{vector_store → documents}/splitter/fixed_size_splitter.rb +2 -2
  251. data/lib/phronomy/{vector_store → documents}/splitter/recursive_splitter.rb +2 -2
  252. data/lib/phronomy/embeddings/async/async_client.rb +44 -0
  253. data/lib/phronomy/embeddings/backends/ruby_llm_embeddings.rb +48 -0
  254. data/lib/phronomy/embeddings/base.rb +43 -0
  255. data/lib/phronomy/embeddings/invalid_result_error.rb +11 -0
  256. data/lib/phronomy/embeddings/transport_error.rb +11 -0
  257. data/lib/phronomy/engine/concurrency/offload_pool.rb +39 -20
  258. data/lib/phronomy/engine/concurrency/pool_registry.rb +47 -12
  259. data/lib/phronomy/{diagnostics.rb → engine/diagnostics.rb} +1 -1
  260. data/lib/phronomy/engine/event_loop.rb +164 -630
  261. data/lib/phronomy/engine/execution_binding.rb +23 -0
  262. data/lib/phronomy/engine/execution_receiver_binding.rb +43 -0
  263. data/lib/phronomy/engine/fsm_protocol.rb +9 -0
  264. data/lib/phronomy/engine/fsm_session.rb +37 -30
  265. data/lib/phronomy/engine/metrics.rb +28 -0
  266. data/lib/phronomy/engine/runtime/timer_queue.rb +1 -1
  267. data/lib/phronomy/engine/runtime.rb +104 -95
  268. data/lib/phronomy/engine/terminal_decision.rb +7 -0
  269. data/lib/phronomy/execution/async_operation.rb +41 -0
  270. data/lib/phronomy/execution/backpressure_error.rb +7 -0
  271. data/lib/phronomy/{blocking.rb → execution/blocking.rb} +2 -2
  272. data/lib/phronomy/execution/cancellation_error.rb +7 -0
  273. data/lib/phronomy/{engine → execution}/concurrency/cancellation_token.rb +5 -1
  274. data/lib/phronomy/{engine → execution}/concurrency/deadline.rb +0 -17
  275. data/lib/phronomy/{engine → execution}/concurrency/physical_completion_task.rb +1 -1
  276. data/lib/phronomy/{engine → execution}/concurrency/result_collector.rb +1 -1
  277. data/lib/phronomy/{engine → execution}/concurrency/result_composition.rb +33 -12
  278. data/lib/phronomy/{engine/concurrency/subscriptions.rb → execution/concurrency/result_subscriptions.rb} +14 -18
  279. data/lib/phronomy/execution/concurrency/subscriptions.rb +25 -0
  280. data/lib/phronomy/execution/concurrency/worker_input_restricted.rb +14 -0
  281. data/lib/phronomy/execution/event_loop_reentrancy_error.rb +8 -0
  282. data/lib/phronomy/{execution.rb → execution/execution.rb} +57 -30
  283. data/lib/phronomy/{execution_cancellation_error.rb → execution/execution_cancellation_error.rb} +2 -0
  284. data/lib/phronomy/execution/execution_receiver.rb +78 -0
  285. data/lib/phronomy/execution/execution_scope_state.rb +35 -0
  286. data/lib/phronomy/{execution_timeout_error.rb → execution/execution_timeout_error.rb} +2 -0
  287. data/lib/phronomy/{invalid_async_entry_action_error.rb → execution/invalid_async_entry_action_error.rb} +2 -0
  288. data/lib/phronomy/{invalid_async_transition_action_error.rb → execution/invalid_async_transition_action_error.rb} +2 -0
  289. data/lib/phronomy/{invalid_async_workflow_action_error.rb → execution/invalid_async_workflow_action_error.rb} +2 -0
  290. data/lib/phronomy/{invocation_context.rb → execution/invocation_context.rb} +0 -15
  291. data/lib/phronomy/execution/invocation_controls.rb +73 -0
  292. data/lib/phronomy/execution/pool_shutdown_error.rb +7 -0
  293. data/lib/phronomy/execution/recursion_limit_error.rb +7 -0
  294. data/lib/phronomy/execution/runnable.rb +24 -0
  295. data/lib/phronomy/execution/runtime_shutdown_error.rb +7 -0
  296. data/lib/phronomy/execution/runtime_shutdown_reentrancy_error.rb +7 -0
  297. data/lib/phronomy/execution/scheduler_reentrancy_error.rb +9 -0
  298. data/lib/phronomy/{engine → execution}/task_result.rb +7 -3
  299. data/lib/phronomy/execution/timeout_error.rb +7 -0
  300. data/lib/phronomy/execution/wait_policy.rb +24 -0
  301. data/lib/phronomy/filter/filter_block_error.rb +14 -0
  302. data/lib/phronomy/generation/generator_verifier/agent_operation.rb +65 -0
  303. data/lib/phronomy/generation/generator_verifier/agent_result_receiver.rb +89 -0
  304. data/lib/phronomy/generation/generator_verifier/default_parser.rb +27 -0
  305. data/lib/phronomy/generation/generator_verifier/pipeline_state.rb +57 -0
  306. data/lib/phronomy/generation/generator_verifier/workflow_builder.rb +112 -0
  307. data/lib/phronomy/generation/generator_verifier.rb +118 -0
  308. data/lib/phronomy/generation/low_confidence_error.rb +14 -0
  309. data/lib/phronomy/llm_adapter/async/async_client.rb +47 -0
  310. data/lib/phronomy/llm_adapter/authentication_error.rb +9 -0
  311. data/lib/phronomy/llm_adapter/backends/ruby_llm.rb +183 -0
  312. data/lib/phronomy/llm_adapter/base.rb +49 -68
  313. data/lib/phronomy/llm_adapter/context_length_error.rb +9 -0
  314. data/lib/phronomy/llm_adapter/invalid_result_error.rb +10 -0
  315. data/lib/phronomy/llm_adapter/message.rb +62 -0
  316. data/lib/phronomy/llm_adapter/rate_limit_error.rb +9 -0
  317. data/lib/phronomy/llm_adapter/request.rb +79 -0
  318. data/lib/phronomy/llm_adapter/response.rb +36 -0
  319. data/lib/phronomy/llm_adapter/stream_chunk.rb +18 -0
  320. data/lib/phronomy/llm_adapter/token_usage.rb +64 -0
  321. data/lib/phronomy/llm_adapter/transport_error.rb +9 -0
  322. data/lib/phronomy/llm_adapter.rb +3 -16
  323. data/lib/phronomy/llm_context_window/token_budget.rb +6 -7
  324. data/lib/phronomy/multi_agent/admission_registry.rb +15 -2
  325. data/lib/phronomy/multi_agent/durable_subagent_coordinator.rb +108 -84
  326. data/lib/phronomy/multi_agent/execution_environment.rb +29 -0
  327. data/lib/phronomy/{agent → multi_agent}/handoff.rb +2 -2
  328. data/lib/phronomy/{agent → multi_agent}/handoff_capability_factory.rb +21 -2
  329. data/lib/phronomy/multi_agent/handoff_participant.rb +79 -0
  330. data/lib/phronomy/{agent → multi_agent}/handoff_policy.rb +1 -1
  331. data/lib/phronomy/multi_agent/handoff_runner.rb +156 -0
  332. data/lib/phronomy/{agent → multi_agent}/handoff_state.rb +2 -2
  333. data/lib/phronomy/multi_agent/orchestrator.rb +61 -75
  334. data/lib/phronomy/multi_agent/persistence/codec.rb +75 -0
  335. data/lib/phronomy/multi_agent/persistence/handoff_state_repository.rb +77 -0
  336. data/lib/phronomy/multi_agent/persistence/records.rb +27 -0
  337. data/lib/phronomy/multi_agent/persistence/storage_schema.rb +21 -0
  338. data/lib/phronomy/multi_agent/persistence/team_execution_repository.rb +124 -0
  339. data/lib/phronomy/multi_agent/persistence/team_repository.rb +69 -0
  340. data/lib/phronomy/multi_agent/reserved_child_admission.rb +88 -0
  341. data/lib/phronomy/multi_agent/runtime_binding/engine_environment.rb +35 -0
  342. data/lib/phronomy/{agent → multi_agent}/shared_state.rb +56 -39
  343. data/lib/phronomy/multi_agent/store.rb +156 -0
  344. data/lib/phronomy/multi_agent/team_coordinator.rb +87 -75
  345. data/lib/phronomy/multi_agent/team_execution.rb +1 -1
  346. data/lib/phronomy/{engine/runtime → multi_agent}/team_ownership_registry.rb +5 -5
  347. data/lib/phronomy/multi_agent/team_root.rb +1 -1
  348. data/lib/phronomy/output_parser/parse_error.rb +7 -0
  349. data/lib/phronomy/persistence/content_repository.rb +26 -0
  350. data/lib/phronomy/persistence/errors.rb +16 -0
  351. data/lib/phronomy/persistence/migration/initial_format_migration.rb +21 -21
  352. data/lib/phronomy/persistence/persistence.rb +23 -0
  353. data/lib/phronomy/persistence/save_outcome.rb +24 -0
  354. data/lib/phronomy/persistence/snapshot_comparison.rb +81 -0
  355. data/lib/phronomy/persistence/storage_boundary.rb +32 -0
  356. data/lib/phronomy/persistence/transaction.rb +86 -0
  357. data/lib/phronomy/persistence_composition/storage_schema.rb +29 -0
  358. data/lib/phronomy/persistence_composition/stores.rb +34 -0
  359. data/lib/phronomy/persistence_composition/unit4_migration.rb +276 -0
  360. data/lib/phronomy/runtime_composition/agent_defaults.rb +11 -0
  361. data/lib/phronomy/runtime_composition/configuration.rb +146 -0
  362. data/lib/phronomy/runtime_composition/configuration_defaults.rb +9 -0
  363. data/lib/phronomy/runtime_composition/evaluation_defaults.rb +7 -0
  364. data/lib/phronomy/runtime_composition/execution_defaults.rb +5 -0
  365. data/lib/phronomy/runtime_composition/generation_defaults.rb +6 -0
  366. data/lib/phronomy/runtime_composition/global_configuration.rb +38 -0
  367. data/lib/phronomy/runtime_composition/global_runtime.rb +19 -0
  368. data/lib/phronomy/runtime_composition/multi_agent_defaults.rb +9 -0
  369. data/lib/phronomy/runtime_composition/workflow_defaults.rb +4 -0
  370. data/lib/phronomy/storage/async/async_client.rb +60 -0
  371. data/lib/phronomy/storage/backend.rb +107 -0
  372. data/lib/phronomy/storage/backends/in_memory.rb +157 -0
  373. data/lib/phronomy/storage/blob_conflict_error.rb +10 -0
  374. data/lib/phronomy/storage/blobs.rb +31 -0
  375. data/lib/phronomy/storage/condition.rb +25 -0
  376. data/lib/phronomy/storage/condition_failed_error.rb +16 -0
  377. data/lib/phronomy/storage/conflict_error.rb +9 -0
  378. data/lib/phronomy/{persistence → storage}/durable_record.rb +12 -12
  379. data/lib/phronomy/storage/entry.rb +33 -0
  380. data/lib/phronomy/storage/guard_ref.rb +13 -0
  381. data/lib/phronomy/storage/not_found_error.rb +9 -0
  382. data/lib/phronomy/storage/record_codec.rb +177 -0
  383. data/lib/phronomy/storage/records.rb +61 -0
  384. data/lib/phronomy/storage/resource.rb +126 -0
  385. data/lib/phronomy/storage/scope.rb +25 -0
  386. data/lib/phronomy/storage/serialization_error.rb +9 -0
  387. data/lib/phronomy/storage/streams.rb +44 -0
  388. data/lib/phronomy/storage/transaction_error.rb +10 -0
  389. data/lib/phronomy/storage/unique_constraint_error.rb +17 -0
  390. data/lib/phronomy/storage/unsupported_backend_error.rb +9 -0
  391. data/lib/phronomy/storage/validation.rb +53 -0
  392. data/lib/phronomy/storage/view.rb +131 -0
  393. data/lib/phronomy/testing/eval/metrics.rb +1 -1
  394. data/lib/phronomy/testing/eval/scorer/llm_judge.rb +19 -3
  395. data/lib/phronomy/testing/persistence_contract/a_content_store.rb +1 -1
  396. data/lib/phronomy/testing/persistence_contract/a_journal_repository.rb +2 -2
  397. data/lib/phronomy/testing/persistence_contract/a_persistence_backend.rb +54 -48
  398. data/lib/phronomy/testing/persistence_contract/a_workflow_state_repository.rb +1 -1
  399. data/lib/phronomy/testing/persistence_contract/an_agent_repository.rb +1 -1
  400. data/lib/phronomy/testing/persistence_contract/an_execution_repository.rb +5 -5
  401. data/lib/phronomy/testing/persistence_contract/coordination_repositories.rb +52 -46
  402. data/lib/phronomy/testing/persistence_contract/neutral_storage_primitives.rb +263 -0
  403. data/lib/phronomy/testing/persistence_contract/storage_transaction_boundaries.rb +124 -0
  404. data/lib/phronomy/testing/persistence_contract.rb +4 -0
  405. data/lib/phronomy/tool/authorization.rb +77 -0
  406. data/lib/phronomy/tool/base.rb +549 -9
  407. data/lib/phronomy/tool/call_request.rb +40 -0
  408. data/lib/phronomy/{agent/tool_definition_set.rb → tool/definition_set.rb} +16 -12
  409. data/lib/phronomy/tool/operation.rb +88 -0
  410. data/lib/phronomy/tool/schema.rb +214 -0
  411. data/lib/phronomy/tool/settings.rb +31 -0
  412. data/lib/phronomy/tool/tool_error.rb +7 -0
  413. data/lib/phronomy/{agent → tool}/tool_executor.rb +10 -7
  414. data/lib/phronomy/tools/agent.rb +22 -90
  415. data/lib/phronomy/tools/mcp.rb +21 -14
  416. data/lib/phronomy/tools/vector_search.rb +4 -4
  417. data/lib/phronomy/tracing/automatic.rb +11 -6
  418. data/lib/phronomy/tracing/base.rb +1 -1
  419. data/lib/phronomy/tracing/observation.rb +37 -0
  420. data/lib/phronomy/tracing/settings.rb +36 -0
  421. data/lib/phronomy/vector_store/{async_backend.rb → async/async_client.rb} +35 -29
  422. data/lib/phronomy/vector_store/{in_memory.rb → backends/in_memory.rb} +12 -10
  423. data/lib/phronomy/vector_store/{pgvector.rb → backends/pgvector.rb} +44 -16
  424. data/lib/phronomy/vector_store/{redis_search.rb → backends/redis_search.rb} +74 -37
  425. data/lib/phronomy/vector_store/base.rb +118 -49
  426. data/lib/phronomy/vector_store/invalid_result_error.rb +12 -0
  427. data/lib/phronomy/vector_store.rb +2 -17
  428. data/lib/phronomy/version.rb +1 -1
  429. data/lib/phronomy/workflow/completion.rb +11 -0
  430. data/lib/phronomy/{workflow.rb → workflow/execution/workflow.rb} +10 -8
  431. data/lib/phronomy/workflow/execution/workflow_action_rules.rb +67 -0
  432. data/lib/phronomy/{workflow_context.rb → workflow/execution/workflow_context.rb} +5 -1
  433. data/lib/phronomy/workflow/execution/workflow_context_ownership_error.rb +7 -0
  434. data/lib/phronomy/workflow/execution/workflow_execution_environment.rb +27 -0
  435. data/lib/phronomy/workflow/execution/workflow_execution_registry.rb +186 -0
  436. data/lib/phronomy/{workflow_runner.rb → workflow/execution/workflow_runner.rb} +145 -115
  437. data/lib/phronomy/workflow/execution/workflow_settings.rb +28 -0
  438. data/lib/phronomy/workflow/persistence/codec.rb +153 -0
  439. data/lib/phronomy/workflow/persistence/state_repository.rb +63 -0
  440. data/lib/phronomy/workflow/persistence/storage_schema.rb +13 -0
  441. data/lib/phronomy/workflow/runtime_binding/workflow_engine_environment.rb +38 -0
  442. data/lib/phronomy/workflow/runtime_binding/workflow_phase_machine_builder.rb +156 -0
  443. data/lib/phronomy/workflow/runtime_binding/workflow_terminal_policy.rb +40 -0
  444. data/lib/phronomy.rb +97 -98
  445. data/scripts/api_snapshot.rb +36 -16
  446. data/scripts/storage_spi_snapshot.rb +36 -0
  447. data/sig/_private/phronomy/agent/settings.rbs +19 -0
  448. data/sig/_private/phronomy/configuration/runtime_settings.rbs +20 -0
  449. data/sig/_private/phronomy/llm_adapter/async/async_client.rbs +10 -0
  450. data/sig/_private/phronomy/multi_agent/store.rbs +8 -0
  451. data/sig/_private/phronomy/persistence/storage_boundary.rbs +7 -0
  452. data/sig/_private/phronomy/tool/settings.rbs +13 -0
  453. data/sig/_private/phronomy/tracing/settings.rbs +15 -0
  454. data/sig/_private/phronomy/workflow/execution/workflow_settings.rbs +13 -0
  455. data/sig/phronomy/agent/admission.rbs +19 -0
  456. data/sig/phronomy/agent/execution_contract.rbs +132 -0
  457. data/sig/phronomy/agent/execution_environment.rbs +20 -0
  458. data/sig/phronomy/agent/store.rbs +73 -0
  459. data/sig/phronomy/agent.rbs +14 -139
  460. data/sig/phronomy/common.rbs +7 -0
  461. data/sig/phronomy/content_store/contracts.rbs +13 -0
  462. data/sig/phronomy/context.rbs +152 -0
  463. data/sig/phronomy/embeddings/async/async_client.rbs +9 -0
  464. data/sig/phronomy/embeddings/base.rbs +17 -0
  465. data/sig/phronomy/engine/concurrency/timer_bindings.rbs +22 -0
  466. data/sig/phronomy/engine/control_bindings.rbs +11 -0
  467. data/sig/phronomy/engine/control_protocols.rbs +23 -0
  468. data/sig/phronomy/engine/execution_binding.rbs +6 -0
  469. data/sig/phronomy/engine/execution_receiver.rbs +15 -0
  470. data/sig/phronomy/engine/observability.rbs +13 -0
  471. data/sig/phronomy/execution/async_operation.rbs +7 -0
  472. data/sig/phronomy/execution/blocking.rbs +5 -0
  473. data/sig/phronomy/execution/concurrency/cancellation_token.rbs +13 -0
  474. data/sig/phronomy/execution/concurrency/deadline.rbs +10 -0
  475. data/sig/phronomy/execution/concurrency/result_composition.rbs +7 -0
  476. data/sig/phronomy/execution/control_protocols.rbs +18 -0
  477. data/sig/phronomy/execution/errors.rbs +7 -0
  478. data/sig/phronomy/execution/execution.rbs +41 -0
  479. data/sig/phronomy/execution/execution_receiver.rbs +40 -0
  480. data/sig/phronomy/execution/execution_scope_state.rbs +9 -0
  481. data/sig/phronomy/execution/invocation_context.rbs +18 -0
  482. data/sig/phronomy/execution/invocation_controls.rbs +13 -0
  483. data/sig/phronomy/execution/task_result.rbs +29 -0
  484. data/sig/phronomy/extensions.rbs +0 -21
  485. data/sig/phronomy/handoff.rbs +12 -4
  486. data/sig/phronomy/llm_adapter/backends/ruby_llm.rbs +6 -0
  487. data/sig/phronomy/llm_adapter/base.rbs +14 -0
  488. data/sig/phronomy/llm_adapter/usage.rbs +14 -0
  489. data/sig/phronomy/llm_adapter/values.rbs +43 -0
  490. data/sig/phronomy/llm_context_window.rbs +10 -0
  491. data/sig/phronomy/multi_agent/reserved_child_admission.rbs +8 -0
  492. data/sig/phronomy/multi_agent/store.rbs +54 -0
  493. data/sig/phronomy/multi_agent.rbs +24 -3
  494. data/sig/phronomy/persistence/errors.rbs +18 -0
  495. data/sig/phronomy/persistence/migration.rbs +13 -0
  496. data/sig/phronomy/persistence/transaction.rbs +19 -0
  497. data/sig/phronomy/persistence.rbs +3 -185
  498. data/sig/phronomy/persistence_composition.rbs +19 -0
  499. data/sig/phronomy/runtime_composition/configuration.rbs +36 -0
  500. data/sig/phronomy/storage/async/async_client.rbs +8 -0
  501. data/sig/phronomy/storage/backends/in_memory.rbs +9 -0
  502. data/sig/phronomy/storage/contracts.rbs +160 -0
  503. data/sig/phronomy/tool.rbs +58 -5
  504. data/sig/phronomy/tracing/observation.rbs +7 -0
  505. data/sig/phronomy/vector_store/async/async_client.rbs +13 -0
  506. data/sig/phronomy/vector_store/base.rbs +23 -0
  507. data/sig/phronomy/workflow/execution/workflow_execution_environment.rbs +14 -0
  508. data/sig/phronomy/workflow/runtime_binding/workflow_terminal_policy.rbs +7 -0
  509. data/sig/phronomy/workflow/store.rbs +8 -0
  510. data/sig/phronomy/workflow.rbs +1 -1
  511. data/sig/phronomy.rbs +0 -49
  512. metadata +462 -130
  513. data/lib/phronomy/agent/agent_invocation_session_builder.rb +0 -584
  514. data/lib/phronomy/agent/concerns/before_llm_input.rb +0 -66
  515. data/lib/phronomy/agent/concerns/error_translation.rb +0 -45
  516. data/lib/phronomy/agent/concerns/filterable.rb +0 -184
  517. data/lib/phronomy/agent/context/capability/base.rb +0 -507
  518. data/lib/phronomy/agent/context/instruction/prompt_template.rb +0 -102
  519. data/lib/phronomy/agent/context_parts/validators/final_budget_validator.rb +0 -37
  520. data/lib/phronomy/agent/context_policies/default.rb +0 -142
  521. data/lib/phronomy/agent/execution_coordinator.rb +0 -3151
  522. data/lib/phronomy/agent/handoff_execution_coordinator.rb +0 -143
  523. data/lib/phronomy/agent/handoff_request.rb +0 -45
  524. data/lib/phronomy/agent/handoff_runner.rb +0 -178
  525. data/lib/phronomy/agent/phase_machine_builder.rb +0 -152
  526. data/lib/phronomy/agent/provider_call_outcome.rb +0 -106
  527. data/lib/phronomy/agent/recovery_support.rb +0 -504
  528. data/lib/phronomy/agent/selection/candidate.rb +0 -53
  529. data/lib/phronomy/agent/selection/constraint.rb +0 -49
  530. data/lib/phronomy/agent/token_budget_resolver.rb +0 -70
  531. data/lib/phronomy/agent/tool_call_intercepted.rb +0 -29
  532. data/lib/phronomy/agent/tool_invocation_session_builder.rb +0 -276
  533. data/lib/phronomy/configuration.rb +0 -59
  534. data/lib/phronomy/engine/concurrency/cancellation_scope.rb +0 -124
  535. data/lib/phronomy/engine/concurrency/operation_binding.rb +0 -43
  536. data/lib/phronomy/generator_verifier.rb +0 -369
  537. data/lib/phronomy/invalid_context_budget_configuration_error.rb +0 -8
  538. data/lib/phronomy/llm_adapter/ruby_llm.rb +0 -47
  539. data/lib/phronomy/metrics.rb +0 -26
  540. data/lib/phronomy/multi_agent/parallel_tool_chat.rb +0 -116
  541. data/lib/phronomy/persistence/durable_codec.rb +0 -706
  542. data/lib/phronomy/persistence/in_memory.rb +0 -690
  543. data/lib/phronomy/persistence/repository_facades.rb +0 -535
  544. data/lib/phronomy/persistence.rb +0 -276
  545. data/lib/phronomy/recovery.rb +0 -186
  546. data/lib/phronomy/ruby_llm_patches.rb +0 -24
  547. data/lib/phronomy/runnable.rb +0 -54
  548. data/lib/phronomy/token_usage.rb +0 -85
  549. data/lib/phronomy/vector_store/embeddings/base.rb +0 -44
  550. data/lib/phronomy/vector_store/embeddings/ruby_llm_embeddings.rb +0 -47
  551. data/lib/phronomy/workflow/phase_machine_builder.rb +0 -205
  552. data/lib/phronomy/workflow_recovery.rb +0 -123
  553. data/sig/phronomy/llm_adapter.rbs +0 -11
  554. data/sig/phronomy/runtime.rbs +0 -76
  555. /data/lib/phronomy/agent/{llm_operation_result.rb → execution/llm_operation_result.rb} +0 -0
  556. /data/lib/phronomy/{canonical_json.rb → common/canonical_json.rb} +0 -0
  557. /data/lib/phronomy/{event.rb → engine/event.rb} +0 -0
@@ -0,0 +1,41 @@
1
+ module Phronomy
2
+ interface _ExecutionSubmitter
3
+ def submit: [V] (?cancellation_token: Concurrency::CancellationToken?, ?on_full: Symbol) { () -> V } -> TaskResult[V]
4
+ end
5
+
6
+ interface _ExecutionPool
7
+ def submit: [V] (?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?, ?on_full: Symbol) { () -> V } -> TaskResult[V]
8
+ end
9
+
10
+ interface _ExecutionRuntime
11
+ def offload: () -> _ExecutionPool
12
+ def pool: (Symbol name, size: Integer, queue_size: Integer) -> _ExecutionPool
13
+ end
14
+
15
+ interface _ExecutionBackend
16
+ def submit: [V] (?pool: _ExecutionPool?, ?runtime: _ExecutionRuntime?, ?pool_name: Symbol?, ?size: Integer, ?queue_size: Integer, ?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?, ?on_full: Symbol) { () -> V } -> TaskResult[V]
17
+ def after: (Numeric seconds) { () -> void } -> ^() -> untyped
18
+ end
19
+ class Execution
20
+ def self.backend_provider=: (^() -> _ExecutionBackend provider) -> ^() -> _ExecutionBackend
21
+ def self.submit: [V] (?pool: _ExecutionPool?, ?runtime: _ExecutionRuntime?, ?pool_name: Symbol?, ?size: Integer, ?queue_size: Integer, ?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?, ?on_full: Symbol) { () -> V } -> TaskResult[V]
22
+ def self.after: (Numeric seconds) { () -> void } -> ^() -> untyped
23
+ attr_reader invocation_context: InvocationContext
24
+
25
+ def self.run_async: [I, V] (Array[I] inputs, ?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?, ?invocation_context: InvocationContext?, ?max_concurrency: Integer?) { (I, Execution) -> TaskResult[V] } -> TaskResult[Array[TaskResult::Outcome[V]]]
26
+ def self.run: [I, V] (Array[I] inputs, ?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?, ?invocation_context: InvocationContext?, ?max_concurrency: Integer?) { (I, Execution) -> TaskResult[V] } -> Array[TaskResult::Outcome[V]]
27
+ def start_child: [V] (?invocation_context: InvocationContext?, ?cancellation_token: Concurrency::CancellationToken?, ?parent_task_id: String?) { (InvocationContext, Concurrency::CancellationToken) -> TaskResult[V] } -> TaskResult[V]
28
+ def observe: [V] (TaskResult[V] source_result) -> TaskResult[V]
29
+ end
30
+
31
+ class ExecutionTimeoutError < TimeoutError
32
+ attr_reader outcomes: Array[TaskResult::Outcome[untyped]]
33
+ def initialize: (?String message, outcomes: Array[TaskResult::Outcome[untyped]]) -> void
34
+ end
35
+
36
+ class ExecutionCancellationError < CancellationError
37
+ attr_reader outcomes: Array[TaskResult::Outcome[untyped]]
38
+ def initialize: (?String message, outcomes: Array[TaskResult::Outcome[untyped]]) -> void
39
+ end
40
+
41
+ end
@@ -0,0 +1,40 @@
1
+ module Phronomy
2
+ interface _ExecutionReceiver
3
+ def idle?: () -> bool
4
+ def deliver: (untyped message) -> untyped
5
+ def shutdown: (error: Exception?) -> untyped
6
+ def session_retired: (String session_id, reason: Symbol) -> untyped
7
+ end
8
+
9
+ interface _ExecutionChannel
10
+ def bound_to?: (untyped owner) -> bool
11
+ def current?: () -> bool
12
+ def synchronize: [V] () { () -> V } -> V
13
+ def admit: [V] (ExecutionReceiver receiver) { () -> V } -> V
14
+ def post: (ExecutionReceiver receiver, untyped message, admission: bool, completion: TaskResult[untyped]?) -> bool
15
+ def route: (ExecutionReceiver receiver, type: Symbol, payload: untyped) { () -> String? } -> bool
16
+ end
17
+
18
+ # Internal serial-owner contract; composition supplies the transport.
19
+ class ExecutionReceiver
20
+ def self.install_binding: (^() -> untyped provider) -> untyped
21
+ def self.binding: () -> untyped
22
+ def self.for: (untyped owner) -> instance
23
+ def self.existing_for: (untyped owner) -> instance?
24
+ def initialize: (channel: _ExecutionChannel) -> void
25
+ def __bound_to?: (untyped owner) -> bool
26
+ def idle?: () -> bool
27
+ def deliver: (untyped message) -> untyped
28
+ def shutdown: (error: Exception?) -> untyped
29
+ def session_retired: (String fsm_session_id, reason: Symbol) -> untyped
30
+
31
+ private
32
+
33
+ def synchronize: [V] () { () -> V } -> V
34
+ def admit: [V] () { () -> V } -> V
35
+ def post_message: (untyped message, ?admission: bool, ?completion: TaskResult[untyped]?) -> bool
36
+ def route_event: (type: Symbol, ?payload: untyped) { () -> String? } -> bool
37
+ def assert_event_loop_thread!: () -> void
38
+ end
39
+
40
+ end
@@ -0,0 +1,9 @@
1
+ module Phronomy
2
+ class ExecutionScopeState
3
+ def __while_open: [V] () { () -> V } -> V?
4
+ def __open?: () -> bool
5
+ def __cancellation_token: () -> Concurrency::CancellationToken
6
+ def __cancellation_error: () -> Exception
7
+ def __set_cancellation_error: (Exception error) -> Exception
8
+ end
9
+ end
@@ -0,0 +1,18 @@
1
+ module Phronomy
2
+ class InvocationContext
3
+ @execution_scope: _ExecutionScope?
4
+ def __bind_execution: (_ExecutionScope? scope) -> self
5
+ def __execution_scope: () -> _ExecutionScope?
6
+
7
+ attr_reader user_id: String?
8
+ attr_reader cancellation_token: Concurrency::CancellationToken?
9
+ attr_reader deadline: Concurrency::Deadline?
10
+ attr_reader token_budget: Integer?
11
+ attr_reader approval_policy: untyped
12
+ attr_reader redaction_policy: untyped
13
+ attr_reader task_id: String?
14
+ attr_reader parent_task_id: String?
15
+
16
+ def initialize: (?user_id: String?, ?cancellation_token: Concurrency::CancellationToken?, ?deadline: Concurrency::Deadline?, ?token_budget: Integer?, ?approval_policy: untyped, ?redaction_policy: untyped, ?task_id: String?, ?parent_task_id: String?) -> void
17
+ end
18
+ end
@@ -0,0 +1,13 @@
1
+ module Phronomy
2
+ class InvocationControls
3
+ @scope: _ExecutionScope?
4
+ attr_reader token: Concurrency::CancellationToken?
5
+ def self.attach: [V] (TaskResult[V] result, invocation_context: InvocationContext?, cancellation_token: Concurrency::CancellationToken?) -> instance
6
+ def initialize: (invocation_context: InvocationContext?, cancellation_token: Concurrency::CancellationToken?) -> void
7
+ def check_start!: () -> nil
8
+ def bind: [V] (TaskResult[V] result) -> TaskResult[V]
9
+ def track: [V] (TaskResult[V] result) -> TaskResult[V]
10
+ def close: () -> untyped
11
+ def self.effective_timeout_token: (InvocationContext context) -> Concurrency::CancellationToken?
12
+ end
13
+ end
@@ -0,0 +1,29 @@
1
+ module Phronomy
2
+ class TaskResult[A]
3
+ @execution_scope: _ExecutionScope?
4
+ def __bind_execution: (_ExecutionScope? scope) -> self
5
+ def __execution_scope: () -> _ExecutionScope?
6
+ class Outcome[V]
7
+ attr_reader index: Integer
8
+ attr_reader status: (:completed | :failed | :cancelled | :unfinished)
9
+ attr_reader value: V?
10
+ attr_reader error: Exception?
11
+ end
12
+
13
+ def self.completed: [V] (V value, ?name: String?) -> TaskResult[V]
14
+ | (?name: String?) -> TaskResult[nil]
15
+ def self.failed: (Exception error, ?name: String?) -> TaskResult[untyped]
16
+ def self.all_settled: [V] (Array[TaskResult[V]] results) -> TaskResult[Array[Outcome[V]]]
17
+ attr_reader name: String?
18
+ attr_reader parent: TaskResult[untyped]?
19
+
20
+ def status: () -> (:pending | :completed | :failed | :cancelled)
21
+ def done?: () -> bool
22
+ def alive?: () -> bool
23
+ def wait_result: (?timeout: Numeric?) -> A
24
+ def on_complete: () { (A?, Exception?) -> void } -> self
25
+ def map: [B] () { (A) -> B } -> TaskResult[B]
26
+ def flat_map: [B] () { (A) -> TaskResult[B] } -> TaskResult[B]
27
+ end
28
+
29
+ end
@@ -20,27 +20,6 @@ module Phronomy
20
20
  end
21
21
  end
22
22
 
23
- module VectorStore
24
- class Base
25
- def add: (id: String, embedding: Array[Float], ?metadata: Hash[untyped, untyped], ?cancellation_token: Concurrency::CancellationToken?) -> untyped
26
- def search: (query_embedding: Array[Float], ?k: Integer, ?cancellation_token: Concurrency::CancellationToken?) -> Array[Hash[Symbol, untyped]]
27
- def remove: (id: String) -> untyped
28
- def clear: () -> untyped
29
- def size: () -> Integer
30
-
31
- def add_async: (id: String, embedding: Array[Float], ?metadata: Hash[untyped, untyped], ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> TaskResult[untyped]
32
- def search_async: (query_embedding: Array[Float], ?k: Integer, ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> TaskResult[Array[Hash[Symbol, untyped]]]
33
- def remove_async: (id: String, ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> TaskResult[untyped]
34
- def clear_async: (?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> TaskResult[untyped]
35
- end
36
-
37
- module Embeddings
38
- class Base
39
- def embed: (String text, ?Concurrency::CancellationToken? cancellation_token) -> Array[Float]
40
- def embed_async: (String text, ?Concurrency::CancellationToken? cancellation_token, ?timeout: Numeric?) -> TaskResult[Array[Float]]
41
- end
42
- end
43
- end
44
23
  module Testing
45
24
  module PersistenceContract
46
25
  SHARED_EXAMPLES: Array[String]
@@ -1,5 +1,5 @@
1
1
  module Phronomy
2
- module Agent
2
+ module MultiAgent
3
3
  class Handoff
4
4
  attr_reader source_agent: ::Phronomy::Agent::Base
5
5
  attr_reader target_agent: ::Phronomy::Agent::Base
@@ -10,6 +10,12 @@ module Phronomy
10
10
  end
11
11
 
12
12
  class HandoffPolicy
13
+ class Rule < Data
14
+ attr_reader category: Symbol
15
+ attr_reader mode: Symbol
16
+ attr_reader default: Symbol?
17
+ end
18
+
13
19
  CATEGORIES: Array[Symbol]
14
20
  MODES: Array[Symbol]
15
21
  DEFAULTS: Array[Symbol]
@@ -17,7 +23,7 @@ module Phronomy
17
23
  def self.define: () { () -> void } -> HandoffPolicy
18
24
  def self.default: () -> HandoffPolicy
19
25
 
20
- def rule: (Symbol | String) -> untyped
26
+ def rule: (Symbol | String) -> Rule
21
27
  def required?: (Symbol | String) -> bool
22
28
  def forbidden?: (Symbol | String) -> bool
23
29
  def selectable?: (Symbol | String) -> bool
@@ -25,14 +31,16 @@ module Phronomy
25
31
  def selectable_categories: () -> Array[Symbol]
26
32
  def to_h: () -> Hash[String, Hash[String, String]]
27
33
  end
34
+ end
28
35
 
36
+ module MultiAgent
29
37
  class HandoffRunner
30
38
  MAX_HANDOFFS: Integer
31
39
 
32
40
  attr_reader main_agent: ::Phronomy::Agent::Base
33
- attr_reader handoffs: Array[Handoff]
41
+ attr_reader handoffs: Array[::Phronomy::MultiAgent::Handoff]
34
42
 
35
- def initialize: (main_agent: ::Phronomy::Agent::Base, ?handoffs: Array[Handoff]) -> void
43
+ def initialize: (main_agent: ::Phronomy::Agent::Base, ?handoffs: Array[::Phronomy::MultiAgent::Handoff], persistence: Store) -> void
36
44
  def invoke: (untyped input, ?config: Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
37
45
  def result: (String execution_id) -> Hash[Symbol, untyped]
38
46
  def cancel: (String execution_id) -> Hash[Symbol, untyped]
@@ -0,0 +1,6 @@
1
+ module Phronomy
2
+ module LLMAdapter
3
+ class RubyLLM < Base
4
+ end
5
+ end
6
+ end
@@ -0,0 +1,14 @@
1
+ module Phronomy
2
+ module LLMAdapter
3
+ class Base
4
+ def identity: () -> Hash[String, String?]
5
+ def input_budget: (Hash[String, untyped] model_config) -> LlmContextWindow::TokenBudget?
6
+ def complete: (Request request, ?cancellation_token: _CancellationSignal?) -> Response
7
+ def stream: (Request request, ?cancellation_token: _CancellationSignal?) { (StreamChunk chunk) -> void } -> Response
8
+ # Protected extension SPI at runtime; RBS has no protected visibility.
9
+ private
10
+ def perform_complete: (Request request, cancellation_token: _CancellationSignal?) -> Response
11
+ def perform_stream: (Request request, cancellation_token: _CancellationSignal?) { (StreamChunk chunk) -> void } -> Response
12
+ end
13
+ end
14
+ end
@@ -0,0 +1,14 @@
1
+ module Phronomy
2
+ module LLMAdapter
3
+ class TokenUsage
4
+ attr_reader input: Integer?
5
+ attr_reader output: Integer?
6
+ attr_reader cached: Integer?
7
+ attr_reader cache_creation: Integer?
8
+ def initialize: (?input: Integer?, ?output: Integer?, ?cached: Integer?, ?cache_creation: Integer?) -> void
9
+ def self.zero: () -> TokenUsage
10
+ def +: (TokenUsage? other) -> TokenUsage
11
+ def to_h: () -> Hash[Symbol, Integer?]
12
+ end
13
+ end
14
+ end
@@ -0,0 +1,43 @@
1
+ module Phronomy
2
+ module LLMAdapter
3
+ class Request
4
+ attr_reader model_config: Hash[String, untyped]
5
+ attr_reader system: String?
6
+ attr_reader messages: Array[Message]
7
+ attr_reader tools: Array[Hash[String, untyped]]
8
+ attr_reader message: String?
9
+ def initialize: (?model_config: Hash[String | Symbol, untyped], ?system: String?, ?messages: Array[Message], ?tools: Array[Hash[String, untyped]], ?message: String?) -> void
10
+ end
11
+ class Message
12
+ attr_reader role: Symbol
13
+ attr_reader content: json_value
14
+ attr_reader tool_calls: Array[Tool::CallRequest]
15
+ attr_reader tool_call_id: String?
16
+ attr_reader metadata: Hash[String, json_value]
17
+ def initialize: (role: String | Symbol, ?content: json_value, ?tool_calls: Array[Tool::CallRequest], ?tool_call_id: String?, ?metadata: Hash[String, json_value]) -> void
18
+ def tool_call?: () -> bool
19
+ def content_present?: () -> bool
20
+ def to_h: () -> Hash[String, untyped]
21
+ end
22
+ class Response < Message
23
+ attr_reader usage: TokenUsage
24
+ def initialize: (?content: json_value, ?tool_calls: Array[Tool::CallRequest], ?usage: TokenUsage, ?metadata: Hash[String, json_value], ?role: String | Symbol) -> void
25
+ def self.from_h: (Hash[String | Symbol, untyped] value) -> Response
26
+ def to_h: () -> Hash[String, untyped]
27
+ end
28
+ class StreamChunk
29
+ attr_reader content: String?
30
+ def initialize: (content: String?) -> void
31
+ end
32
+ class InvalidResultError < Error
33
+ end
34
+ class TransportError < Error
35
+ end
36
+ class RateLimitError < TransportError
37
+ end
38
+ class AuthenticationError < TransportError
39
+ end
40
+ class ContextLengthError < Error
41
+ end
42
+ end
43
+ end
@@ -0,0 +1,10 @@
1
+ module Phronomy
2
+ module LlmContextWindow
3
+ class TokenBudget
4
+ attr_reader max_input_tokens: Integer
5
+ def initialize: (max_input_tokens: Integer) -> void
6
+ def effective_input_limit: () -> Integer
7
+ def available: (?used: Integer) -> Integer
8
+ end
9
+ end
10
+ end
@@ -0,0 +1,8 @@
1
+ module Phronomy
2
+ module MultiAgent
3
+ class ReservedChildAdmission
4
+ def initialize: (persistence: (Store | Agent::Store), owner: Hash[String, untyped]) -> void
5
+ def admit: (::Phronomy::Agent::Admission admission) -> nil
6
+ end
7
+ end
8
+ end
@@ -0,0 +1,54 @@
1
+ module Phronomy
2
+ interface _HandoffStateRepository
3
+ def load: (String main_agent_id) -> untyped
4
+ def load_locked: (String main_agent_id) -> untyped
5
+ def save: (String main_agent_id, expected_revision: Integer?, state: untyped) -> untyped
6
+ def delete: (String main_agent_id, expected_revision: Integer) -> untyped
7
+ end
8
+
9
+ interface _TeamRepository
10
+ def create: (untyped root) -> untyped
11
+ def load: (String team_id) -> untyped
12
+ def save: (String team_id, expected_revision: Integer, root: untyped) -> untyped
13
+ def delete: (String team_id) -> untyped
14
+ end
15
+
16
+ interface _TeamExecutionRepository
17
+ def create_active: (untyped execution) -> untyped
18
+ def load: (String team_execution_id) -> untyped
19
+ def save: (String team_execution_id, expected_revision: Integer, execution: untyped) -> untyped
20
+ def list_active: (String team_id) -> Array[untyped]
21
+ def list: (String team_id, ?after: String?, ?limit: Integer) -> Array[untyped]
22
+ def delete: (String team_execution_id) -> untyped
23
+ def delete_for_team: (String team_id) -> untyped
24
+ def assert_idle!: (String team_id) -> untyped
25
+ end
26
+
27
+ module MultiAgent
28
+ interface _Records
29
+ def contents: () -> _ContentRepository
30
+ def handoff_states: () -> _HandoffStateRepository
31
+ def teams: () -> _TeamRepository
32
+ def team_executions: () -> _TeamExecutionRepository
33
+ def guard_team!: (String team_id) -> untyped
34
+ end
35
+
36
+ class Store
37
+ attr_reader coordinator: ::Phronomy::Persistence
38
+ attr_reader contents: _ContentRepository
39
+ attr_reader handoff_states: _HandoffStateRepository
40
+ attr_reader teams: _TeamRepository
41
+ attr_reader team_executions: _TeamExecutionRepository
42
+ attr_reader agent_store: Agent::Store
43
+ def initialize: (coordinator: ::Phronomy::Persistence, records: ::Phronomy::Persistence::_Participant[_Records], agent_store: Agent::Store) -> void
44
+ def transaction: [R] () { (_Records, ::Phronomy::Persistence::Transaction) -> R } -> R
45
+ def participate: [R] (::Phronomy::Persistence::Transaction scope) { (_Records) -> R } -> R
46
+ def handoff_leaf: (String execution_id, main_agent_id: String, ?scope: ::Phronomy::Persistence::Transaction?) -> Agent::ExecutionObservation
47
+ def handoff_result: (String execution_id, main_agent_id: String) -> Agent::execution_result
48
+ def forget_handoff: (String main_agent_id) -> bool
49
+ def forget_subagents: (agent_id: String, execution_id: String) -> bool
50
+ def result: (String execution_id) -> Hash[Symbol, untyped]
51
+ def runs: (String owner_id, ?after: String?, ?limit: Integer) -> Array[untyped]
52
+ end
53
+ end
54
+ end
@@ -1,6 +1,27 @@
1
1
  module Phronomy
2
2
  module MultiAgent
3
+ class SharedState
4
+ class KnowledgeStore
5
+ def self.new: () -> instance
6
+ def read_all: () -> Array[Hash[Symbol, untyped]]
7
+ def write: (agent: untyped, content: untyped, cycle: untyped) -> nil
8
+ def size: () -> Integer
9
+ end
10
+
11
+ def self.new: () -> instance
12
+ def self.member: (singleton(::Phronomy::Agent::Base) klass, ?instruction: untyped) -> Array[Hash[Symbol, untyped]]
13
+ def self.coordination: (?untyped text) -> untyped
14
+ def self.max_cycles: (?untyped value) -> Integer?
15
+ def self.timeout: (?untyped value) -> Float?
16
+ def self.terminate_when: () ?{ (KnowledgeStore) -> untyped } -> untyped
17
+ def self.aggregate: () ?{ (KnowledgeStore) -> untyped } -> untyped
18
+ def invoke: (untyped input, ?config: Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
19
+ end
20
+
3
21
  class Orchestrator < ::Phronomy::Agent::Base
22
+ attr_reader coordination_store: Store?
23
+ def self.create: (?coordination_store: Store?, **Object options) ?{ (Object) -> void } -> instance
24
+ def self.load: (String agent_id, persistence: Agent::Store, coordination_store: Store, **Object options) ?{ (Object) -> void } -> instance
4
25
  def self.subagent: (Symbol | String name, singleton(::Phronomy::Agent::Base) agent_class, ?on_error: Symbol, ?inherit_knowledge: bool) -> untyped
5
26
  def self.registered_subagents: () -> Hash[Symbol | String, untyped]
6
27
  def resume: (String execution_id, ?config: Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
@@ -10,7 +31,7 @@ module Phronomy
10
31
 
11
32
  class TeamCoordinator
12
33
  attr_reader team_id: String
13
- attr_reader persistence: ::Phronomy::Persistence
34
+ attr_reader persistence: Store
14
35
  def self.team_definition: (?id: String?, ?version: Integer?) -> Hash[Symbol, String | Integer]
15
36
  def self.coordinator_model: (?String? value) -> String?
16
37
  def self.coordinator_instructions: (?String? value) -> String?
@@ -18,9 +39,9 @@ module Phronomy
18
39
  def self.pool: (size: Integer, agent: singleton(::Phronomy::Agent::Base), ?on_error: Symbol) -> untyped
19
40
  def self.schedule: () { (Array[untyped]) -> untyped } -> untyped
20
41
  def self.aggregate: () { (Array[Hash[Symbol, untyped]]) -> untyped } -> untyped
21
- def self.new: (?team_id: String, ?persistence: ::Phronomy::Persistence?, ?metadata: Hash[String, untyped], ?on_event: ^(untyped) -> untyped) -> instance
42
+ def self.new: (?team_id: String, ?persistence: Store?, ?metadata: Hash[String, untyped], ?on_event: ^(untyped) -> untyped) -> instance
22
43
  def self.create: (**untyped options) -> instance
23
- def self.load: (String team_id, persistence: ::Phronomy::Persistence, ?on_event: ^(untyped) -> untyped) -> instance
44
+ def self.load: (String team_id, persistence: Store, ?on_event: ^(untyped) -> untyped) -> instance
24
45
  def self.get: (String team_id) -> instance?
25
46
  def invoke: (untyped input, ?config: Hash[Symbol, untyped]) -> untyped
26
47
  def stream: (untyped input, ?config: Hash[Symbol, untyped]) ?{ (Hash[Symbol, untyped]) -> untyped } -> untyped
@@ -0,0 +1,18 @@
1
+ module Phronomy
2
+ class Persistence
3
+ class TransactionError < Error
4
+ end
5
+ class Error < Phronomy::Error
6
+ end
7
+ class ConflictError < Error
8
+ end
9
+ class StateConflictError < ConflictError
10
+ end
11
+ class NotFoundError < Error
12
+ end
13
+ class SerializationError < Error
14
+ end
15
+ class UnsupportedBackendError < Error
16
+ end
17
+ end
18
+ end
@@ -0,0 +1,13 @@
1
+ module Phronomy
2
+ class Persistence
3
+ module Migration
4
+ module InitialFormatMigration
5
+ def self.agent_root: (Hash[untyped, untyped] hash) -> Storage::DurableRecord
6
+ def self.agent_execution: (Hash[untyped, untyped] hash) -> Storage::DurableRecord
7
+ def self.journal_record: (Hash[untyped, untyped] hash) -> Storage::DurableRecord
8
+ def self.workflow_state: (workflow_instance_id: String, revision: Integer, snapshot: Hash[untyped, untyped]) -> Storage::DurableRecord
9
+ def self.llm_input_manifest: (Hash[untyped, untyped] hash) -> Hash[String, untyped]
10
+ end
11
+ end
12
+ end
13
+ end
@@ -0,0 +1,19 @@
1
+ module Phronomy
2
+ class Persistence
3
+ interface _Participant[T]
4
+ def new: (Storage::View view) -> T
5
+ end
6
+
7
+ class Transaction
8
+ def initialize: (Persistence persistence, Storage::View view, ?parent: Transaction?) -> void
9
+ def participate: [T, R] (persistence: Persistence, adapter: _Participant[T]) { (T) -> R } -> R
10
+ def outermost?: () -> bool
11
+ def committed?: () -> bool
12
+ def validate!: () -> bool
13
+ def close!: () -> bool
14
+ def confirm!: () -> bool
15
+ end
16
+
17
+ def atomic: [R] () { (Transaction) -> R } -> R
18
+ end
19
+ end