phronomy 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0ea2e317999f3202e06d5afac0b46509fa22a813531919447040d1e048a087f
-  data.tar.gz: ae5740df9899b7463b35b54b885948ca1e0e42e01b8b85b1a93fd6437022c90b
+  metadata.gz: 633f62428045fed9447fd95414687cf8f2d0df11163afd767a73cc1c9b0ea97e
+  data.tar.gz: 68d352c78047e7b87dade2f8659cf44d4ecd16acf506090329d3e276f8a35f0c
 SHA512:
-  metadata.gz: 123b0998a7a299f97ce981a3561c68990c41e05decb534b4c4664e441abd6cf368e04ecf6cea61df6a1ea2c4016850b093e0c208aa034fc02b1fa498e0078263
-  data.tar.gz: f1ba3ee6163b1a746bd99f00241daf286ac5eb3d8d1e30f7caa739de1de5dd900f3b19b90a063c4a9f19f494a1e9ac1dca59b4d32ade41deabe71f849803ac62
+  metadata.gz: 67cd757c8efacd34360a3b876bae0ebbac0e37080f77472a9b69eaf774f14b5f2c070288d4e5d66bbfcc31a6be60353ca043e4f95ee6b1a14da09e8fe5792b00
+  data.tar.gz: '0382e7bbf708605dea900725e7ab4c093baf653ef0e88c11ba79c6ab227b1584624aa73b9b16cacd8644d4d1aafe0ffade1b6b1d6361a1f33d7395e730b4e1df'

data/CHANGELOG.md

@@ -9,8 +9,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+---
+
+## [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
@@ -30,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.
@@ -69,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

data/README.md

@@ -27,9 +27,9 @@ It provides composable building blocks — Workflows, Agents, Tools, Filters, an
 | Feature | Stability |
 |---|---|
 | **Workflow** — Stateful, branching workflows with wait_state/send_event | Stable |
-| **Agent** — ReAct-style tool-calling agents with guardrails and conversation history | Stable |
-| **Before-Completion Hook** — Three-tier LLM parameter injection | Stable |
-| **Context Management** — Token budget calculation, estimation, and pruning; `Agent::Base` protected hooks: `build_context` (overridable), `trim_messages`, `trim_to_budget`, `compact_messages`, `budget_exceeded?`, `drop_messages_over` | Stable |
+| **Agent** — Stateful ReAct-style tool-calling agents with stable `agent_id`, persistence-backed execution state, canonical execution history, guardrails, and conversation context | Stable |
+| **Before-LLM-Input Hook** — Three-tier per-call LLM input customization via `before_llm_input` and `LLMInputPatch` | Stable |
+| **Context Management** — Canonical Journal + per-LLM-call Manifest architecture with token-budget-aware selection and protocol-safe Tool Call / Tool message dependencies. Context selection never deletes canonical execution history | Stable |
 | **Filters** — Input/output transformation and blocking via `Filter::Base`; call `block!(reason)` to reject and raise `FilterBlockError` | Beta |
 | **`PromptInjectionFilter`** — Built-in `Filter::Base` subclass that detects prompt-injection patterns; usable standalone or as part of a filter chain | Beta |
 | **`Agent::Context::Capability::Base.redact_params` / `.max_result_size`** — Class-level DSL: `redact_params` masks parameter values in log/trace output; `max_result_size` truncates oversized tool results before they reach the LLM | Beta |
@@ -56,7 +56,7 @@ It provides composable building blocks — Workflows, Agents, Tools, Filters, an
 | **`stream` / `stream_async`** — callbacks execute on the EventLoop thread and must return quickly; the block form remains a compatibility alias for `on_event:` | Beta |
 | **`stream_callback_error_policy`** — Backward-compatible setting shared by `invoke_async` and `stream_async` terminal `on_event:` callbacks: `:report` (default) preserves the Agent result, while `:fail_task` fails the returned Task with `Phronomy::StreamCallbackError`; Agent execution errors are never replaced by callback errors | Beta |
 | **`invoke_async` / `call_async`** — `Agent::Base#invoke_async` and `Workflow#invoke_async` return a `Task`; `Agent::Context::Capability::Base#call_async` similarly; compatible with EventLoop and standalone contexts | Stable |
-| **`Task#map`** — transforms a Task's completed value and propagates failure/cancellation; Workflow entry and transition actions do not await mapped Tasks | Stable |
+| **`Task#map`** — transforms a Task's completed value and propagates failure/cancellation. `Task#map` remains available for application-level Task composition, but Workflow entry and transition actions must not return a Task | Stable |
 | **CancellationToken** — Cooperative cancellation via `cancel!`/`cancelled?`/`raise_if_cancelled!`; `timeout_after(seconds)` for monotonic-clock deadlines; optional `deadline:` (wall-clock) for backward compatibility; passed as `config: { cancellation_token: token }` to agents and `dispatch_parallel`; injected into `tool.execute` when the method declares a `cancellation_token:` keyword; bridged to `MCP::Cancellation` in `Phronomy::Tools::Mcp#execute` | Experimental |
 | **`dispatch_parallel` / `fan_out` `force_kill:` option** — `force_kill: false` (default) leaves timed-out workers running and raises `TimeoutError` immediately; `force_kill: true` restores the old `Thread#kill` behaviour with a `logger.warn` | Beta |
 | **`execution_mode` DSL on `Agent::Context::Capability::Base`** — Declares how a tool's `execute` should be dispatched: `:cooperative` (same scheduler thread), `:blocking_io` (default; offloaded to `BlockingAdapterPool`), `:cpu_bound`, `:external_process`; Tool-specific timeout/retry belongs to the Tool implementation or its client | Experimental |
@@ -78,7 +78,7 @@ It provides composable building blocks — Workflows, Agents, Tools, Filters, an
 | **`Phronomy::MultiAgent::Orchestrator`** — Parallel subagent dispatch, fan-out, and `subagent` DSL | Beta |
 | **`Phronomy::MultiAgent::TeamCoordinator`** — Agent teams pattern: LLM coordinator + stateful workers with sequential task assignment (worker-local message history persisted across tasks) | Beta |
 | **Agent::SharedState** — Shared state pattern: peer agents collaborate via a shared KnowledgeStore; `member` DSL with per-agent instructions and `coordination` team protocol | Experimental |
-| **Human-in-the-loop approval** — `Agent::Base#invoke` returns `{ suspended: true, agent_invocation_id: String, approval_request: Phronomy::Agent::ToolApprovalRequest }` when a tool requiring approval is encountered; `Agent::Base#approve(id, approval_request_id:, approved:)` (synchronous) or `Agent::Base#approve_async(id, approval_request_id:, approved:)` (returns `Task`) resumes execution; approval state is in-process only — not persisted across process restarts or shared across pods | Beta |
+| **Human-in-the-loop approval** — `Agent::Base#invoke` returns `{ suspended: true, execution_id: String, approval_request: Phronomy::Agent::ToolApprovalRequest }` when approval is required. `#approve` / `#approve_async` resume that execution. Suspended execution state is stored in Persistence, but durable activation rehydration after a process restart is not yet supported | Beta |
 | **`tool_approval_policy`** — Instance-level callable that maps each `ToolApprovalRequest` to `:allow`, `:require_approval`, or `:reject`; set on the agent instance before invoking | Beta |
 | **`Filter::Base` — unified value filter interface** — `Phronomy::Filter::Base` with a single abstract method `call(value, **context)`; apply to user input (`add_input_filter` / `input_filter` DSL), final LLM output (`add_output_filter` / `output_filter` DSL), or individual tool return values (`add_tool_result_filter(tool_class?, filter)` / `tool_result_filter` DSL); filters transform values and return the result, or raise `Phronomy::FilterBlockError` to reject; filter chains are composable; the same filter instance can be reused across all three sites | Beta |
 
@@ -176,6 +176,7 @@ class WebSearch < Phronomy::Agent::Context::Capability::Base
 end
 
 class ResearchAgent < Phronomy::Agent::Base
+  agent_definition id: "research-agent", version: 1
   model "gpt-4o"
   instructions "You are a research assistant. Use tools to answer questions."
   tools WebSearch
@@ -519,26 +520,106 @@ puts result[:output]           # final answer
 puts result[:agent].class      # => BillingAgent
 ```
 
-### Before-Completion Hook — Dynamic LLM parameter injection
+### Before-LLM-Input Hook — Per-call LLM input customization
+
+`before_llm_input` runs before every LLM call and allows an application to
+customize that call without mutating the Agent, RubyLLM chat, or canonical
+Journal state directly.
+
+Hooks can be configured at three levels:
+
+1. global — applies to every Agent
+2. class — applies to every instance of one Agent definition
+3. instance — applies only to one Agent instance
+
+They run in that order: global → class → instance.
+
+A hook receives an immutable `Phronomy::Agent::LLMInputBuildContext` containing
+metadata about the LLM call:
+
+- `agent_id`
+- `agent_definition_id`
+- `definition_version`
+- `config`
+- `call_sequence`
+
+The hook does not receive the mutable Agent instance, RubyLLM messages, or
+`RubyLLM::Chat`.
+
+Return either:
+
+- `nil` to leave the call unchanged, or
+- a `Phronomy::Agent::LLMInputPatch`
+
+### Class-level hook
 
 ```ruby
-# Class-level: applies to all instances
 class MyAgent < Phronomy::Agent::Base
+  agent_definition id: "my-agent", version: 1
+
   model "gpt-4o"
-  before_completion ->(ctx) { { temperature: ctx.config[:precise] ? 0.0 : 0.7 } }
+
+  before_llm_input ->(ctx) {
+    Phronomy::Agent::LLMInputPatch.new(
+      model_config_patch: {
+        temperature: ctx.config[:precise] ? 0.0 : 0.7
+      }
+    )
+  }
 end
+```
 
-# Instance-level: overrides class hook for this agent only
+### Instance-level hook
+
+```ruby
 agent = MyAgent.new
-agent.before_completion = ->(ctx) { { max_tokens: 512 } }
 
-# Global: applies to every agent across the app
-Phronomy.configure do |c|
-  c.before_completion = ->(ctx) { { temperature: 0.3 } }
+agent.before_llm_input = ->(_ctx) {
+  Phronomy::Agent::LLMInputPatch.new(
+    model_config_patch: {
+      max_output_tokens: 512
+    }
+  )
+}
+```
+
+### Global hook
+
+```ruby
+Phronomy.configure do |config|
+  config.before_llm_input = ->(_ctx) {
+    Phronomy::Agent::LLMInputPatch.new(
+      model_config_patch: {
+        temperature: 0.3
+      }
+    )
+  }
 end
 ```
 
-Hooks are called in order — global → class → instance — and shallow-merged (`Hash#merge`; last hook wins on key conflicts).
+When multiple hooks provide `model_config_patch`, patches are merged in hook
+order and later values win on key conflicts.
+
+`LLMInputPatch` can also supply `segment_candidates` for additional per-call
+context. Those segments participate in Manifest-first input assembly. This is
+intended for logical context supplied by the application; applications should
+not mutate RubyLLM message history directly.
+
+```ruby
+Phronomy::Agent::LLMInputPatch.new(
+  segment_candidates: [
+    {
+      content: "The customer is on the enterprise plan.",
+      category: :knowledge,
+      role: :user
+    }
+  ]
+)
+```
+
+The Journal remains the canonical record of observed execution history.
+`before_llm_input` customizes the logical input assembled for a particular LLM
+call; it does not rewrite previously recorded Journal history.
 
 ### GeneratorVerifier — Generator-Verifier loop with custom prompt builders
 
@@ -735,32 +816,78 @@ child process (stdio transport) or release the HTTP connection:
 search_tool.close
 ```
 
-### Conversation History — passing prior messages
+### Agent State and Conversation History
+
+Phronomy Agents are stateful objects. Each Agent has a stable `agent_id`, a persistent Agent root, an append-only execution Journal, and zero or more Agent executions.
+
+Every concrete Agent definition must declare a stable definition identity:
+
+```ruby
+class ResearchAgent < Phronomy::Agent::Base
+  agent_definition id: "research-agent", version: 1
+
+  model "gpt-4o"
+  instructions "You are a research assistant."
+end
+```
+
+The definition ID identifies the application-level Agent definition. The version is checked when a previously persisted Agent is loaded so that persisted state is not silently interpreted by an incompatible Agent definition.
 
-Phronomy does not manage conversation history internally. The application owns the
-message array and passes it in via the `messages:` keyword argument:
+Create and continue using the same Agent instance normally:
 
 ```ruby
-# First turn
-result1 = MyAgent.new.invoke("Hello! I'm Alice.", thread_id: "session-1")
-prior_messages = result1[:messages]   # Array<RubyLLM::Message>
-
-# Second turn — pass prior messages so the agent has context
-result2 = MyAgent.new.invoke(
-  "What is my name?",
-  messages: prior_messages,
-  thread_id: "session-1"
+persistence = Phronomy::Persistence::InMemory.new
+
+agent = ResearchAgent.create(
+  agent_id: "research-session-42",
+  persistence: persistence
 )
-puts result2[:output]   # => "Your name is Alice."
+
+agent.invoke("My name is Alice.")
+result = agent.invoke("What is my name?")
+
+puts result[:output]
 ```
 
-`result[:messages]` contains the complete message history after each invocation.
-Persist it however suits your application (in-memory hash, Redis, ActiveRecord, etc.).
+Conversation history does not need to be passed back through `messages:` on every invocation. The Agent's canonical history is retained in its Journal and selected automatically when later LLM Calls are assembled.
+
+A persisted Agent can be loaded again when the same Persistence backend is available:
+
+```ruby
+agent = ResearchAgent.load(
+  "research-session-42",
+  persistence: persistence
+)
+
+result = agent.invoke("Continue our previous discussion.")
+```
+
+`result[:messages]` remains available as a materialized transcript of the Agent's current conversation history. It is a projection of canonical Agent state, not the authoritative storage mechanism and does not need to be supplied to the next `invoke`.
+
+Existing external conversation history can be supplied when a new Agent is created:
+
+```ruby
+agent = ResearchAgent.create(
+  context: existing_messages,
+  persistence: persistence
+)
+```
 
-> **Note on `thread_id`**: `thread_id` is a correlation identifier used internally for
-> EventLoop session routing and compaction context. It does **not** automatically persist or
-> restore conversation history — you must pass `messages:` explicitly on each turn as shown above.
+Imported history must satisfy Phronomy's Import contract. User, assistant, and Tool messages are journaled without destroying their logical message boundaries. System instructions are Agent configuration and are not imported as ordinary conversation messages.
 
+`thread_id` is an execution correlation identifier. It does not identify the persistent Agent and is not a substitute for `agent_id`.
+
+The current conversation or memory view can be advanced without deleting the canonical Journal:
+
+```ruby
+agent.clear_transcript!
+agent.clear_memory!
+agent.reset_context!
+```
+
+These operations change which historical records belong to the active context generation. The underlying append-only Journal remains intact.
+
+`purge!` is different: it permanently removes the Agent and its persisted execution history from the configured Persistence backend.
 
 ## Configuration
 
@@ -769,7 +896,7 @@ Phronomy.configure do |c|
   c.default_model                   = "gpt-4o-mini"
   c.recursion_limit                 = 25
   c.tracer                          = Phronomy::Tracing::NullTracer.new
-  c.before_completion               = nil   # optional; global hook lambda
+  c.before_llm_input                 = nil   # optional global before_llm_input hook
   c.trace_pii                       = false # default; set to true only when trace data contains no PII
   c.logger                          = nil   # optional; any object responding to #warn (e.g. Rails.logger)
   c.event_loop_stop_grace_seconds   = 5     # seconds to wait for sessions to drain on shutdown
@@ -796,7 +923,7 @@ Understanding when to use each prevents scheduler stalls and hidden deadlocks.
 | Context | Recommended API |
 |---------|----------------|
 | Top-level application code, Rails controller, background job | `agent.invoke(input)` — blocks the calling thread until done |
-| Workflow action / EventLoop callback | `agent.invoke_async(input).map { |r| ctx.merge(output: r[:output]) }` — returns a Task and resumes by state transition |
+| Workflow action | Start `invoke_async` and use `Workflow#signal` in the `on_event:` callback to deliver the result as a later Workflow event |
 | Top-level code that wants explicit async | `agent.invoke_async(input).wait_result` — blocks the calling thread until the Task completes |
 | Streaming from top-level code | `agent.stream(input) { |event| ... }` — blocks until done; callbacks run on the EventLoop thread |
 | Streaming non-blocking | `task = agent.stream_async(input) { |event| ... }` — returns Task immediately; callbacks run on the EventLoop thread |
@@ -805,11 +932,21 @@ Understanding when to use each prevents scheduler stalls and hidden deadlocks.
 
 ### Why this matters
 
-`invoke` is a synchronous wrapper that calls `invoke_async` and then _blocks_ the calling
-thread until the task completes.  It is intended for top-level application threads such as
-Rails controller actions, CLI scripts, or background jobs.  Inside EventLoop-driven
-workflow actions, return a Task and let `Task#map` / `Task#on_complete` drive the next
-state transition instead of waiting inside the EventLoop thread.
+`invoke` is a synchronous wrapper around asynchronous Agent execution and blocks
+the calling thread until the Agent finishes. It is appropriate for top-level
+application code such as CLI commands, controller actions, or background jobs.
+
+Workflow entry and transition actions have a different contract: they are
+synchronous Run-to-Completion callbacks and must finish promptly.
+
+If a Workflow action needs an Agent or another asynchronous operation, start the
+operation asynchronously, register its completion listener, return the Workflow
+context, and use `Workflow#signal` to deliver completion as a later Workflow
+event.
+
+Do not call blocking `Agent#invoke` from an EventLoop callback, and do not return
+the `Task` from `Agent#invoke_async` as the result of a Workflow entry or
+transition action.
 
 ### Runtime guard
 
@@ -837,15 +974,93 @@ result = my_agent.invoke("Hello")
 
 # Explicit async from top-level code
 result = my_agent.invoke_async("Hello").wait_result
+```
+
+### Async work inside a Workflow
+
+Workflow entry and transition actions are synchronous Run-to-Completion
+callbacks.
 
-# Workflow action / EventLoop-safe use
-NODE = ->(ctx) {
-  my_agent.invoke_async("Hello").map { |result|
-    ctx.merge(answer: result[:output])
+They may start asynchronous work, but they must return the Workflow context (or
+`nil`). Returning a `Phronomy::Task` from an entry or transition action is an
+error.
+
+When an asynchronous Agent finishes, deliver its result back to the live
+Workflow as a later event with `Workflow#signal`.
+
+```ruby
+class AnswerContext
+  include Phronomy::WorkflowContext
+
+  field :question, type: :replace, default: ""
+  field :answer,   type: :replace, default: nil
+end
+
+workflow = nil
+
+workflow = Phronomy::Workflow.define(AnswerContext) do
+  initial :asking
+
+  state :asking
+  state :done
+
+  entry :asking, ->(ctx) {
+    thread_id = ctx.thread_id
+
+    my_agent.invoke_async(
+      ctx.question,
+      on_event: ->(event) {
+        next unless event.type == :done
+
+        workflow.signal(
+          thread_id: thread_id,
+          event: :answer_ready,
+          payload: { answer: event.payload[:output] }
+        )
+      }
+    )
+
+    ctx
   }
-}
+
+  transition(
+    from: :asking,
+    on: :answer_ready,
+    to: :done,
+    action: ->(ctx, event) {
+      ctx.merge(answer: event.payload[:answer])
+    }
+  )
+
+  transition from: :done, to: :__finish__
+end
 ```
 
+The important separation is:
+
+```text
+Workflow action
+    │
+    ├─ starts asynchronous work
+    │
+    └─ returns context immediately
+             │
+             ▼
+       asynchronous Agent
+             │
+             ▼
+      on_event / callback
+             │
+             ▼
+       Workflow#signal
+             │
+             ▼
+      later Workflow event
+```
+
+`Task#map` remains a valid Task API for transforming Task results, but a mapped
+Task must not be returned from a Workflow entry or transition action.
+
 ### :immediate backend (synchronous / test mode)
 
 The `:immediate` backend runs tasks synchronously using `FakeScheduler`
@@ -863,46 +1078,57 @@ end
 
 ## Context Management
 
-Phronomy includes a context window management layer. When model metadata is
-available (either from the built-in registry or via an explicit `context_window:` setting),
-agents automatically stay within the configured token limit.
-
-### TokenBudget
+Phronomy uses a Manifest-first context architecture for stateful Agents.
 
-Derives the effective token budget from RubyLLM's model registry:
+The main flow is:
 
-```ruby
-budget = Phronomy::LlmContextWindow::TokenBudget.new(
-  model:    "claude-3-5-sonnet-20241022",  # looks up context_window + max_output_tokens
-  overhead: 500                            # extra reservation for tool definitions
-)
-budget.context_window       # => 200_000
-budget.max_output_tokens    # => 8_192
-budget.effective_input_limit # => 191_308
+```text
+Canonical Journal
+      ↓
+Context Policy
+      ↓
+LLM Call Manifest
+      ↓
+Runtime Projection
+      ↓
+RubyLLM / Provider
 ```
 
-Or supply explicit values (useful for local / unregistered models):
+The **Journal** is the canonical append-only record of logical execution facts observed by Phronomy.
 
-```ruby
-budget = Phronomy::LlmContextWindow::TokenBudget.new(
-  context_window:    32_768,
-  max_output_tokens: 4_096
-)
-```
+The **Manifest** is the canonical logical input fixed for one particular LLM Call.
+
+Context-window management therefore does not trim or rewrite the Agent's canonical history. Instead, Phronomy selects the subset of available context needed for each LLM Call and records that selection in the Manifest.
+
+This distinction allows old history to remain available even when it does not fit in the current model's context window.
+
+Tool protocol dependencies are preserved during selection. For example, an assistant message containing Tool Calls and the corresponding Tool-role messages are selected as a protocol-safe unit rather than independently pruning messages in a way that would create an invalid LLM conversation.
+
+When the available budget is insufficient, optional historical context can be omitted from the current Manifest. Required context is never silently removed merely to satisfy the budget. If the required input cannot fit, Phronomy raises `ContextBudgetExceededError`.
+
+### Context-window configuration
 
-### Agent DSL extensions
+Phronomy derives the effective context budget from RubyLLM model metadata when available.
+
+For local or otherwise unregistered models, the context window can be declared explicitly:
 
 ```ruby
-class MyAgent < Phronomy::Agent::Base
-  model "gpt-4o"
-  max_output_tokens 4096   # override max_output_tokens from registry
-  context_overhead  600    # extra reservation for system prompt + tools
-  # LLM timeout/retry is configured on RubyLLM, not on the Agent class.
+class LocalAgent < Phronomy::Agent::Base
+  agent_definition id: "local-agent", version: 1
+
+  model "local-model"
+  context_window 32_768
+  max_output_tokens 4_096
 end
 ```
 
-`Agent::Base#invoke` builds a `TokenBudget` automatically. When the model is not in the
-registry the budget is silently skipped.
+`context_window` determines the model's total context capacity.
+
+`max_output_tokens` reserves capacity for the model's output.
+
+The legacy `context_overhead` setting remains for compatibility with the legacy `build_context` path, but it is not the mechanism used to reserve system-prompt or Tool-definition space in Manifest-first context assembly. New Agent implementations should not rely on `context_overhead` for that purpose.
+
+The current default Context Policy is framework-managed. Public custom Context Policy APIs, deterministic persistent compaction, and other advanced policy extension points are still evolving and should not yet be treated as stable application APIs.
 
 > **Note on CJK languages**: The default `TokenEstimator` uses a character-ratio heuristic
 > calibrated for ASCII/Latin text (4 chars/token). For Chinese, Japanese, and Korean text,
@@ -922,7 +1148,7 @@ registry the budget is silently skipped.
 Pass a `CancellationToken` to any agent via `config: { cancellation_token: token }`.
 Cancellation is checked at multiple granular checkpoints: before the LLM call,
 after each streaming chunk, before each parallel
-tool-call batch, and after each `before_completion` hook. `CancellationError` is
+tool-call batch, and after each `before_llm_input` hook. `CancellationError` is
 raised immediately. Phronomy does not replay the complete Agent invocation. No threads are force-killed — `ensure`
 blocks always execute.
 
@@ -1035,7 +1261,6 @@ bundle exec ruby NN_example_name/run.rb
 | 12 | `12_prompt_template/` | Advanced prompt templates |
 | 13 | `13_mcp_http_tool/` | HTTP-based MCP tool server |
 | 14 | `14_code_review/` | Automated code review agent |
-| 16 | `16_before_completion_hook/` | Global/class/instance before_completion hooks |
 | 17 | `17_multi_agent_handoff/` | Hub-and-spoke agent routing via Runner |
 
 The following examples are **app-level demos** (Rails apps or advanced pipelines)