phronomy 0.15.1 → 0.16.0

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)

data/benchmark/bench_agent_invoke.rb

@@ -40,6 +40,7 @@ class BenchStubChat
   def with_cache_instructions(_) = self
   def with_output_schema(_) = self
   def on_tool_call(&) = self
+  def before_tool_call(&) = self
   def last_message = @response
 
   def ask(_)
@@ -71,12 +72,14 @@ BENCH_RESP = BenchAgentMessage.assistant("benchmark complete")
 BENCH_RESP_CHAT = BenchStubChat.new(BENCH_RESP)
 
 bench_minimal_class = Class.new(Phronomy::Agent::Base) do
+  agent_definition id: "bench-minimal", version: 1
   model "stub-model"
 
   define_method(:build_chat) { |*| BenchStubChat.new(BENCH_RESP) }
 end
 
 bench_tool_class = Class.new(Phronomy::Agent::Base) do
+  agent_definition id: "bench-tool", version: 1
   model "stub-model"
   tools BenchNullTool
 

data/benchmark/bench_regression.rb

@@ -88,6 +88,7 @@ end
 # Target 4: Orchestrator#dispatch_parallel overhead (10 stub agents, no LLM)
 # ---------------------------------------------------------------------------
 stub_agent_class = Class.new(Phronomy::Agent::Base) do
+  agent_definition id: "bench-stub", version: 1
   define_method(:invoke) do |_input, messages: [], thread_id: nil, config: {}|
     {output: "stub", messages: []}
   end
@@ -129,22 +130,6 @@ t6 = Benchmark.measure("CancellationToken#raise_if_cancelled! (no-op)") do
   RAISE_ITERATIONS.times { RAISE_TOKEN.raise_if_cancelled! }
 end
 
-# ---------------------------------------------------------------------------
-# Target 7: Agent::Base#trim_messages on a 2000-message history
-# ---------------------------------------------------------------------------
-BenchMsg = Struct.new(:content) unless defined?(BenchMsg)
-
-TRIM_MESSAGES = Array.new(2_000) { |i| BenchMsg.new("msg #{i}") }
-TRIM_ITERATIONS = 500
-
-bench_trim_agent = Class.new(Phronomy::Agent::Base).new
-
-t7 = Benchmark.measure("Agent::Base#trim_messages (2000-msg history)") do
-  TRIM_ITERATIONS.times do
-    bench_trim_agent.send(:trim_messages, TRIM_MESSAGES, keep: 1_800)
-  end
-end
-
 # ---------------------------------------------------------------------------
 # Print results and store in REGRESSION_RESULTS
 # ---------------------------------------------------------------------------
@@ -158,8 +143,7 @@ metrics = {
   "tool_params_schema_definition" => [t3, REGRESSION_ITERATIONS],
   "dispatch_parallel_10" => [t4, PARALLEL_ITERATIONS],
   "cancellation_token_cancelled" => [t5, 8 * CANCEL_ITERATIONS],
-  "cancellation_token_raise_if_cancelled_noop" => [t6, RAISE_ITERATIONS],
-  "trim_messages_2000" => [t7, TRIM_ITERATIONS]
+  "cancellation_token_raise_if_cancelled_noop" => [t6, RAISE_ITERATIONS]
 }
 
 REGRESSION_RESULTS = {} # rubocop:disable Style/MutableConstant

data/benchmark/bench_tool_schema.rb

@@ -54,6 +54,7 @@ class BenchKnowledgeSource < Phronomy::Agent::Context::Knowledge::Base
 end
 
 class BenchAgentWithKnowledge < Phronomy::Agent::Base
+  agent_definition id: "bench-knowledge", version: 1
   model "gpt-4o-mini"
   static_knowledge BenchKnowledgeSource.new
 end

data/docs/decisions/011-build-context-as-single-llm-input-authority.md

@@ -2,7 +2,46 @@
 
 ## Status
 
-Proposed — 2026-05-31
+Partially Superseded by ADR-012 — 2026-08-08
+
+Originally proposed — 2026-05-31.
+
+## Supersession Note
+
+ADR-012, **Canonical Complete Execution Log and Context Policy**, supersedes the architectural parts of this ADR that treat the legacy `build_context` / `LlmContextWindow::Assembler` path as the long-term single authority for LLM input.
+
+In particular, the following parts of this ADR are no longer normative for the stateful Agent architecture:
+
+* **D1 — `build_context` is the single authority for all LLM input**
+* **D2 — Assembler handles all four regions including Capability**
+* **D3 — `build_context` includes all tools**
+* **D5 — Previous context stored as an instance variable**
+
+The replacement authority model is:
+
+```text
+Canonical Journal
+      ↓
+Context Policy
+      ↓
+LLM Call Manifest
+      ↓
+Runtime Projection
+      ↓
+RubyLLM / Provider
+```
+
+Under ADR-012:
+
+* the **Journal** is authoritative for logical execution facts observed by Phronomy;
+* the **Manifest** is authoritative for the logical input fixed for one specific LLM Call;
+* Context Policy determines which canonical history is selected for that Manifest;
+* selection, pruning, and compaction do not delete or rewrite the canonical Journal;
+* Tool protocol dependencies are preserved independently from semantic Context-selection policy.
+
+The problem statements and historical analysis in this ADR remain useful as design history. Decisions or implementation notes that do not conflict with ADR-012 may still describe valid constraints, but ADR-012 is authoritative whenever the two documents differ.
+
+See: `012-canonical-execution-log-and-context-policy.md`
 
 ## Context