phronomy 0.15.1 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98b90b892fcd752aa84d1a00d033bb627df70d143145502f044e5288c7b124a4
-  data.tar.gz: c1e37fa68d782d5f506a83e019594e2f77efeb7d37e8f46c8b57286d8b8c9eaa
+  metadata.gz: 633f62428045fed9447fd95414687cf8f2d0df11163afd767a73cc1c9b0ea97e
+  data.tar.gz: 68d352c78047e7b87dade2f8659cf44d4ecd16acf506090329d3e276f8a35f0c
 SHA512:
-  metadata.gz: e8a62f9eb2d0971a0faa91d822a9ecff39b495242514dd5144f442c8bcfba85edd84a3e22738df17447604f8c6201169df1f0b308035ad8a5e50603ad379da5b
-  data.tar.gz: bcb09d22cf850b447e49e13d022cf760c6b4628fe3df6ea744f91738e1085fea6218bee4ce96c4caf0b6f8a8c07f2900bc7f243ed374cc71c940869f64856ea1
+  metadata.gz: 67cd757c8efacd34360a3b876bae0ebbac0e37080f77472a9b69eaf774f14b5f2c070288d4e5d66bbfcc31a6be60353ca043e4f95ee6b1a14da09e8fe5792b00
+  data.tar.gz: '0382e7bbf708605dea900725e7ab4c093baf653ef0e88c11ba79c6ab227b1584624aa73b9b16cacd8644d4d1aafe0ffade1b6b1d6361a1f33d7395e730b4e1df'

data/CHANGELOG.md

@@ -9,20 +9,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Changed
+---
 
-- Refactor: `Agent::AsyncEventApi` is now the single implementation of
-  `invoke`, `invoke_async`, `stream`, `stream_async`, and their session
-  lifecycle helpers (`_start_invocation`, `_handle_agent_completion`,
-  `_register_tool_invocation_session`, `_start_approval_resume`). The
-  duplicate definitions in `Agent::Base` have been removed. No public
-  behavior change is intended.
-- Remove `faraday` and `event_stream_parser` from gemspec declared
-  dependencies; both are transitive dependencies of `ruby_llm` and are
-  not used directly by phronomy.
+## [0.16.0] - 2026-08-08
 
 ### Added
 
+- Stateful Agent identity and persistence:
+  - Every concrete Agent definition declares a stable `agent_definition id:, version:`.
+  - Every Agent instance has a stable `agent_id`.
+  - `Agent::Base.create` creates a persistent Agent instance.
+  - `Agent::Base.load` restores an Agent from a shared Persistence backend.
+  - `Agent#agent_root`, `#transcript`, `#clear_transcript!`, `#clear_memory!`,
+    `#reset_context!`, `#close!`, and `#purge!` provide explicit state lifecycle operations.
+
+- Persistence-backed Agent execution state:
+  - Agent executions have stable `execution_id` values and are persisted separately from the owning Agent.
+  - Suspended approval executions remain represented in Persistence.
+  - Resuming after process loss still requires future durable activation rehydration support.
+
+- Canonical Complete Execution Log:
+  - Phronomy records observed logical execution facts in an append-only Agent Journal.
+  - Provider assistant responses preserve assistant content and all Tool Calls as one logical assistant message.
+  - Raw Tool return values and the Tool-role messages sent back to the LLM are represented as separate execution facts.
+
+- Per-LLM-call canonical Manifests:
+  - Each LLM Call is assembled from a canonical Manifest.
+  - The Manifest records the logical input selected for that specific LLM Call.
+  - Runtime RubyLLM messages are materialized from the Manifest rather than treated as the source of truth.
+
+- Context Policy domain:
+  - Context candidates are selected from canonical history without deleting the underlying Journal.
+  - Tool Call / Tool message protocol dependencies are selected atomically.
+  - Required context is validated independently from optional historical context.
+  - `ContextBudgetExceededError` is raised when required context cannot fit in the available model budget.
+
+- Context import for stateful Agents:
+  - Existing user / assistant / Tool history can be supplied through Agent creation context.
+  - Imported assistant messages retain their original logical message boundary and Tool Calls.
+  - Invalid Tool protocol histories are rejected instead of being guessed or repaired.
+
 - `Workflow#signal(thread_id:, event:, payload:)` for FIFO delivery to a live
   Workflow FSMSession.
 - Workflow transition `action:` callbacks, executed after source exit callbacks
@@ -42,27 +68,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - EventLoop emits a rate-limited warning when its shared event queue reaches
   1,000 pending entries. Events are observed only; they are not dropped.
 
-### Removed
+### Changed
 
-- Implicit awaiting of Task-returning Workflow/Agent/Tool entry actions and the
-  Workflow `action_timeout:` DSL. Entry actions are synchronous RTC callbacks.
-- The duplicate caller-thread `WorkflowRunner#run_workflow` execution path.
-- Agent-wide automatic replay: `Agent::Base.retry_policy` and the `Retryable`
-  concern. A failed AgentInvocation is no longer started again by Phronomy.
-- Agent-class `invoke_timeout`. Callers that need a root deadline should pass an
-  `InvocationContext` with `deadline:` or `cancellation_token:`.
-- Phronomy LLM operation timeout `config[:llm_timeout]`; configure RubyLLM's
-  `request_timeout` instead.
-- Generic Tool retry DSL (`retry_on`, `retry_policies`) and
-  `config[:tool_timeout]`; Tool/client implementations own their transport policy.
-- `max_parallel_tools` from Agent, AgentInvocation, ParallelToolChat, and
-  InvocationContext.
-- Unused `InvocationContext#provider_limits`.
-- `Configuration#stream_queue_max_size`, which no longer affected the
-  Runtime-owned EventLoop streaming path.
+- Agent instances are now always stateful and Persistence-backed.
 
-### Changed
+- Conversation history ownership has moved from the caller to the Agent:
+  callers no longer need to pass the previous `messages` array back on every invocation.
+  Completed invocation results may still expose `result[:messages]` as a materialized
+  transcript projection.
+
+- `agent_definition id:, version:` is required for concrete Agent definitions.
+  Loading persisted Agent state validates the stored definition identity and version
+  against the runtime Agent class.
+
+- Context-window management is now Manifest-first:
+  canonical Agent history is retained in the Journal while each LLM Call receives
+  only the context selected for its Manifest.
+
+- Context pruning no longer means deleting or mutating historical Agent messages.
+  Context Policy omission affects only the current LLM Call input.
+
+- Tool execution results and Tool protocol messages are no longer treated as the
+  same value. The raw Tool return value is retained as an execution fact while the
+  exact Tool-role message remains independently available for LLM context assembly.
 
+- `thread_id` is an execution/correlation identifier rather than the owner of
+  conversation state. Persistent Agent identity is defined by `agent_id`.
+
+- `context_overhead` is retained only for the legacy `build_context` path.
+  Manifest-first context assembly accounts for actual mandatory context instead of
+  reserving this value as Tool/system-prompt overhead.
+
+- Phronomy now requires `ruby_llm >= 1.15, < 2` so Provider assistant messages can
+  be captured before Agent-owned Tool execution begins.
+
+- Refactor: `Agent::AsyncEventApi` is now the single implementation of
+  `invoke`, `invoke_async`, `stream`, `stream_async`, and their session
+  lifecycle helpers (`_start_invocation`, `_handle_agent_completion`,
+  `_register_tool_invocation_session`, `_start_approval_resume`). The
+  duplicate definitions in `Agent::Base` have been removed. No public
+  behavior change is intended.
+- Remove `faraday` and `event_stream_parser` from gemspec declared
+  dependencies; both are transitive dependencies of `ruby_llm` and are
+  not used directly by phronomy.
 - `Workflow#invoke`, `#invoke_async`, and `#stream` now share context
   preparation, StateStore load/save, EventLoop registration, and FSMSession
   execution.
@@ -81,6 +129,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   bounded workers and queues remain the coarse process-protection boundary.
 - Caller-provided deadline and cancellation-token propagation is unchanged.
 
+### Removed
+
+- Caller-managed `messages:` continuation from the Agent invocation API.
+  Stateful Agent history is now obtained from the Agent's persisted Journal.
+
+- `Agent::Base#trim_messages` and the legacy Agent-level message-trimming model.
+  Context selection is performed by the Context Policy / Manifest assembly path.
+
+- The assumption that `build_context` and the legacy `LlmContextWindow::Assembler`
+  are the long-term single authority for LLM input. ADR-012 defines the replacement
+  Journal / Context Policy / Manifest architecture.
+
+- Implicit awaiting of Task-returning Workflow/Agent/Tool entry actions and the
+  Workflow `action_timeout:` DSL. Entry actions are synchronous RTC callbacks.
+- The duplicate caller-thread `WorkflowRunner#run_workflow` execution path.
+- Agent-wide automatic replay: `Agent::Base.retry_policy` and the `Retryable`
+  concern. A failed AgentInvocation is no longer started again by Phronomy.
+- Agent-class `invoke_timeout`. Callers that need a root deadline should pass an
+  `InvocationContext` with `deadline:` or `cancellation_token:`.
+- Phronomy LLM operation timeout `config[:llm_timeout]`; configure RubyLLM's
+  `request_timeout` instead.
+- Generic Tool retry DSL (`retry_on`, `retry_policies`) and
+  `config[:tool_timeout]`; Tool/client implementations own their transport policy.
+- `max_parallel_tools` from Agent, AgentInvocation, ParallelToolChat, and
+  InvocationContext.
+- Unused `InvocationContext#provider_limits`.
+- `Configuration#stream_queue_max_size`, which no longer affected the
+  Runtime-owned EventLoop streaming path.
+
 ### Fixed
 
 - `Agent#approve` now rejects EventLoop re-entry instead of synchronously waiting