phronomy 0.15.1 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98b90b892fcd752aa84d1a00d033bb627df70d143145502f044e5288c7b124a4
-  data.tar.gz: c1e37fa68d782d5f506a83e019594e2f77efeb7d37e8f46c8b57286d8b8c9eaa
+  metadata.gz: d3af942022237dc3396d6a658f4f1b9be12f03eb0f718ebea81525822f756308
+  data.tar.gz: c046a9670fb3e1e55640f5072ac6c04399edbdfdfc4b2238caefde135fc1a2e5
 SHA512:
-  metadata.gz: e8a62f9eb2d0971a0faa91d822a9ecff39b495242514dd5144f442c8bcfba85edd84a3e22738df17447604f8c6201169df1f0b308035ad8a5e50603ad379da5b
-  data.tar.gz: bcb09d22cf850b447e49e13d022cf760c6b4628fe3df6ea744f91738e1085fea6218bee4ce96c4caf0b6f8a8c07f2900bc7f243ed374cc71c940869f64856ea1
+  metadata.gz: f52c37ff47e703de492742a2753870c4e3b4ee63ef58ab0e875afcef1488bef95f6c2f0b96e19181d1fe0f7ec28b15a9f4581f18ce0685eff28ca773eabc3aa1
+  data.tar.gz: 9cdd430036ff931dedc3548005d448f1173bfe135d7eaed8b737f01bf44e23d3467c9ef96a6a0d64d8c6005d1f48b3d57f71e39bb5c9df109fd6230ae784c64a

data/.mutant.yml

@@ -1,22 +1,21 @@
 ---
-# Mutant configuration for Phronomy (opensource project)
-# See: https://github.com/mbj/mutant
-
 usage: opensource
-
 integration: rspec
-
 includes:
   - lib
-
 requires:
   - phronomy
-
 matcher:
   subjects:
     - Phronomy::WorkflowContext
     - Phronomy::WorkflowRunner
     - Phronomy::Tool::Base
-    - Phronomy::Context::TokenBudget
-    - Phronomy::Context::TokenEstimator
+    - Phronomy::LlmContextWindow::TokenBudget
+    - Phronomy::Agent::ContextAssembler
+    - Phronomy::Agent::ContextPolicies::Default
+    - Phronomy::Agent::ContextParts::UnitBuilders::DependencyAwareUnitBuilder
+    - Phronomy::Agent::ContextParts::Requirements::RequiredContextResolver
+    - Phronomy::Agent::ContextParts::Selectors::RecentFirstSelector
+    - Phronomy::Agent::ContextParts::Budget::TokenBudgetPacker
+    - Phronomy::Agent::ContextPlanValidator
     - Phronomy::VectorStore::InMemory

data/CHANGELOG.md

@@ -9,20 +9,100 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-### Changed
+### Agent Context / Knowledge cleanup
+
+#### Added
+
+- Journal-backed persistent Agent Knowledge via creation-time `knowledge:` and
+  post-creation `Agent#add_knowledge`.
+- `Agent#clear_knowledge!` for logical Knowledge invalidation without deleting
+  append-only Journal history.
+- ADR-013, defining persistent Knowledge as optional Context candidates selected
+  through the Manifest-first Context Policy pipeline.
+
+#### Changed
+
+- Persistent Knowledge and `before_llm_input` segment candidates now participate
+  in Context Policy and token-budget selection instead of being injected as
+  mandatory system context.
+- `clear_transcript!`, `clear_knowledge!`, and `reset_context!` now have distinct
+  transcript/Knowledge lifecycle semantics.
+- Active Context tests, integration fixtures, benchmarks, mutation subjects,
+  design documents, and API snapshots now describe the canonical
+  Journal -> ContextCandidate -> Context Policy -> Manifest architecture.
+
+#### Removed
+
+- `Phronomy::KnowledgeSource`, `Knowledge::Base`, `StaticKnowledge`, and
+  `EntityKnowledge`.
+- `static_knowledge*`, `add_knowledge_source`, `instance_knowledge_chunks`,
+  `Knowledge#static?`, `StaticKnowledge#source`, and the class-level static
+  Knowledge cache/fetch abstraction.
+- `Agent#clear_memory!` and `AgentRoot#memory_generation`.
+- Remaining no-op ContextVersionCache tests, fake legacy-import Context tests,
+  obsolete Memory/context integration helpers, legacy `:llm_message` benchmark
+  categories, and stale Agent `messages:` test-double signatures.
+
+### Phase 3 cleanup
+
+#### Changed
+
+- Active documentation, compatibility snapshots, benchmarks, integration fixtures,
+  and mutation targets now describe the Manifest-first Context architecture.
+- The Context benchmark now measures `Agent::ContextAssembler` and
+  `ContextPolicies::Default` instead of the removed legacy Assembler.
+- ADR-011 is marked Superseded by ADR-012; its historical analysis is retained.
+
+#### Removed
+
+- Remaining active compatibility references to `context_overhead`,
+  `LlmContextWindow::Assembler`, `ContextVersionCache`, Tool
+  `on_error :return_empty`, `force_kill:`, `runtime_backend :cooperative`,
+  the `Runtime.instance=` setter, tools-splat registration, and wall-clock
+  `CancellationToken.new(deadline:)`.
+- Obsolete legacy Assembler / ContextVersionCache executable specs.
 
-- 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 +122,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 +183,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

data/CONTRIBUTING.md

@@ -58,15 +58,20 @@ When adding, removing, or renaming a public method or class:
 
 Key design decisions are documented as ADRs in
 [docs/decisions/](docs/decisions/). Read these before making significant changes
-to the threading model, caching strategy, or public API shape.
+to the threading model, persistence/context authority, or public API shape.
+
+For Agent Context work, ADR-012 and ADR-013 define the current Journal,
+Manifest, Context Policy and persistent Knowledge model.
 
 ---
 
 ## Mutation Testing
 
-Phronomy uses [mutant](https://github.com/mbj/mutant) to verify that each test
-actually detects real code changes. Mutation tests are **not** part of the
-required CI gate (they are slow), but run nightly via `.github/workflows/nightly-mutation.yml`.
+Phronomy uses [mutant](https://github.com/mbj/mutant) to verify that tests detect
+real code changes. Mutation tests are not part of the required CI gate. The
+repository contains `.github/workflows/nightly-mutation.yml` for mutation-run
+automation; whether that workflow is enabled is an operational choice and is
+not a normal pull-request requirement.
 
 ### Run mutation tests locally
 
@@ -78,18 +83,25 @@ bash scripts/run_mutation.sh
 bash scripts/run_mutation.sh "Phronomy::WorkflowContext"
 ```
 
-### Coverage targets
-
-| Subject | Baseline | Target |
-|---|---|---|
-| `Phronomy::WorkflowContext` | 84.85% | ≥ 80% |
-| `Phronomy::WorkflowRunner` | — | ≥ 80% |
-| `Phronomy::Tool::Base` | 55.74% | ≥ 80% |
-| `Phronomy::Context::TokenBudget` | — | ≥ 80% |
-| `Phronomy::VectorStore::InMemory` | — | ≥ 80% |
-
-When you add or modify tests for a covered subject, run mutation tests to confirm
-the score does not regress.
+### Covered subjects
+
+The authoritative subject list is `.mutant.yml`. It currently includes:
+
+- `Phronomy::WorkflowContext`
+- `Phronomy::WorkflowRunner`
+- `Phronomy::Tool::Base`
+- `Phronomy::LlmContextWindow::TokenBudget`
+- `Phronomy::Agent::ContextAssembler`
+- `Phronomy::Agent::ContextPolicies::Default`
+- `Phronomy::Agent::ContextParts::UnitBuilders::DependencyAwareUnitBuilder`
+- `Phronomy::Agent::ContextParts::Requirements::RequiredContextResolver`
+- `Phronomy::Agent::ContextParts::Selectors::RecentFirstSelector`
+- `Phronomy::Agent::ContextParts::Budget::TokenBudgetPacker`
+- `Phronomy::Agent::ContextPlanValidator`
+- `Phronomy::VectorStore::InMemory`
+
+When you add or modify tests for a covered subject, run mutation tests locally
+when practical and investigate meaningful score regressions.
 
 ---