phronomy 0.7.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9ae370d656048e38f700b6bced931fe249f731cea819ab94691eb4bcf6ef43c
-  data.tar.gz: 97d01ca3475f547a41397d1dad2ddb8ccaa10f6466d5a75c3f79e6875a7af0c6
+  metadata.gz: d91e0fb85732153a69d268b41bdfe865791dd8f007e8bed983269284478af002
+  data.tar.gz: c334678280139ac7934b6804b06e282051218472985c022823d26913a3f64905
 SHA512:
-  metadata.gz: d3ab9ebd145e1ed706ad1741a2e3184c412aa8fd0eac32c95eb0b4a1ef87af38ae73eb5b4205b7f2894dd228929130c9a7569d24a1d7a571a5aa3ec5a68a4172
-  data.tar.gz: efa88afdbaa2f3d8fc38ee7cbc7044711479490546a888d44540f3b6bae6da60a3a3e64cfbbef455d65f78bab64dd9a68056e4c9f7ac7a360d512179364c8b23
+  metadata.gz: 393567f7c01633ea20160101705b0fde21ddd009a4950f1cb44a106285500b90a3bec88d4c9681cebb7656d0529c09c9e7c52da42e3e12f103231423921b43aa
+  data.tar.gz: 03f5d2e764df9d3becb782ecdec0bf42f03b0f3fc7414efaad2334fe1d047443ef3180e1993244cad92c305607113d0afe2915caa6ff53d14c05c779a61f6b4b

data/README.md

@@ -7,7 +7,7 @@
 > We apologise for the instability this may cause.
 
 **Phronomy** is a Ruby AI agent framework inspired by open-source AI agent frameworks.  
-It provides composable building blocks — Workflows, Agents, Tools, Guardrails, RAG, and Tracing — all powered by [RubyLLM](https://github.com/crmne/ruby_llm) for LLM abstraction.
+It provides composable building blocks — Workflows, Agents, Tools, Guardrails, and Tracing — all powered by [RubyLLM](https://github.com/crmne/ruby_llm) for LLM abstraction.
 
 ## Features
 
@@ -30,10 +30,10 @@ It provides composable building blocks — Workflows, Agents, Tools, Guardrails,
 | **Workflow action_timeout** — Per-state `action_timeout:` keyword on `state` DSL; cancels Task-returning entry actions that exceed the limit and raises `Phronomy::ActionTimeoutError` | Beta |
 | **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 | 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 |
 | **Guardrails** — Input/output validation with custom `InputGuardrail`/`OutputGuardrail` | Beta |
 | **`PromptInjectionGuardrail`** — Built-in `InputGuardrail` subclass that detects prompt-injection patterns; usable standalone or as part of a guardrail chain | Beta |
-| **`Tool::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 |
+| **`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 |
 | **Output Parser** — JSON and Struct-mapped parsers for structured LLM responses | Stable |
 | **Eval Framework** — Dataset-driven evaluation with multiple scorer types | Beta |
 | **Tracing** — Pluggable span-based observability | Stable |
@@ -43,11 +43,11 @@ It provides composable building blocks — Workflows, Agents, Tools, Guardrails,
 
 | Feature | Stability |
 |---|---|
-| **Knowledge/RAG** — Retrieval sources with pluggable loaders, splitters, and vector stores; `static_knowledge_refresh!` for runtime cache invalidation | Beta |
+| **Knowledge** — Static context injection with pluggable loaders, splitters, and vector stores; `static_knowledge_refresh!` for runtime cache invalidation | Beta |
 | **`VectorStore#size`** — Returns document count for all three backends (InMemory, RedisSearch, Pgvector) | Beta |
 | **`VectorStore::AsyncBackend` mixin** — Pluggable async interface for `VectorStore`; default pool-backed implementations for `search_async`, `add_async`, `remove_async`, `clear_async`; backends with native async drivers override individual methods to bypass `BlockingAdapterPool` entirely; all existing backends remain unchanged | Beta |
-| **Parallel RAG multi-source fetch** — `Agent#build_context` fetches all `knowledge_sources` concurrently via `TaskGroup`; `config[:rag_failure_policy]` `:skip` (default) silently ignores failed sources so the agent answers with partial context, `:fail` surfaces the first error; per-source latency is emitted to `Phronomy.configuration.logger` at debug level | Beta |
-| **MCP Tool** — Model Context Protocol server integration | Beta |
+| **MCP Tool** — `Phronomy::Tools::Mcp`: Model Context Protocol server integration; `Phronomy::Tools::Agent`: wraps an agent class as a callable tool via `from_agent` | Beta |
+| **Vector Search Tool** — `Phronomy::Tools::VectorSearch`: wraps a `VectorStore` and `Embeddings` adapter as a callable agent tool via `from_store` | Beta |
 
 **Execution and reliability**
 
@@ -55,14 +55,14 @@ It provides composable building blocks — Workflows, Agents, Tools, Guardrails,
 |---|---|
 | **Workflow EventLoop Mode** — Opt-in event-driven execution: `Phronomy.configure { \|c\| c.event_loop = true }` | Experimental |
 | **Agent EventLoop Mode** — `Agent#invoke` (non-blocking via EventLoop), `Agent#run_as_child` (child-FSM pattern for Workflow integration), parallel tool dispatch via `ParallelToolChat` | Experimental |
-| **`invoke_async` / `call_async`** — `Agent::Base#invoke_async` and `Workflow#invoke_async` return a `Task`; `Tool::Base#call_async` similarly; compatible with EventLoop and standalone contexts | Experimental |
+| **`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 | Experimental |
 | **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 | 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 `Tool::Base`** — Declares how a tool's `execute` should be dispatched: `:cooperative` (same scheduler thread), `:blocking_io` (default; offloaded to `BlockingAdapterPool`), `:cpu_bound`, `:external_process` | Experimental |
+| **`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` | Experimental |
 | **`invocation_context:` keyword on `Agent#invoke` / `Workflow#invoke`** — Pass a `Phronomy::InvocationContext` directly; `thread_id`, `cancellation_token`, and `deadline`-based timeout are derived from it; `task_id` / `parent_task_id` appear in trace spans automatically; `config:` keys remain supported as backward-compat aliases | Beta |
-| **`ConcurrencyGate` — unified backpressure** — Counting semaphore that enforces per-resource concurrency caps (`max_concurrent_agent_tasks`, `max_concurrent_tool_tasks`, `max_concurrent_workflow_tasks`, `max_concurrent_llm_calls`, `max_concurrent_rag_fetches`, `max_concurrent_vector_searches`); configured via `Phronomy.configure`; backpressure behaviour follows the global `backpressure` setting (`:wait`, `:raise`/`:reject`, `:timeout`); `nil` cap = unlimited (default) | Beta |
+| **`ConcurrencyGate` — unified backpressure** — Counting semaphore that enforces per-resource concurrency caps (`max_concurrent_agent_tasks`, `max_concurrent_tool_tasks`, `max_concurrent_workflow_tasks`, `max_concurrent_llm_calls`, `max_concurrent_vector_searches`); configured via `Phronomy.configure`; backpressure behaviour follows the global `backpressure` setting (`:wait`, `:raise`/`:reject`, `:timeout`); `nil` cap = unlimited (default) | Beta |
 | **Cooperative scheduler yield points** — `Runtime#yield` (cooperative yield; yields the current task's time slice); `Runtime#yield_if_needed(every: N)` (thread-local counter, yields every N calls); CPU-bound detection when `blocking_detect_threshold_ms` is set (warns and increments `non_yield_threshold_violation_count` when a task runs longer than the threshold without yielding); `starvation_threshold_ms` configuration field (default: 50ms) | Beta |
-| **`Phronomy::Metrics`** — `Phronomy::Metrics.snapshot` returns task-tree and pool counters; task-centric keys: `active_agent_tasks`, `active_tool_tasks`, `active_workflow_tasks`, `active_rag_tasks`, `active_llm_tasks`, `task_wait_time_p50_ms`, `task_wait_time_p95_ms`, `task_run_time_p50_ms`, `task_run_time_p95_ms`, `cancelled_tasks`, `failed_tasks`, `non_yield_threshold_violation_count`; pool/event-loop keys remain for backward compatibility; `Runtime#task_snapshot` exposes task-centric metrics directly | Beta |
+| **`Phronomy::Metrics`** — `Phronomy::Metrics.snapshot` returns task-tree and pool counters; task-centric keys: `active_agent_tasks`, `active_tool_tasks`, `active_workflow_tasks`, `active_llm_tasks`, `task_wait_time_p50_ms`, `task_wait_time_p95_ms`, `task_run_time_p50_ms`, `task_run_time_p95_ms`, `cancelled_tasks`, `failed_tasks`, `non_yield_threshold_violation_count`; pool/event-loop keys remain for backward compatibility; `Runtime#task_snapshot` exposes task-centric metrics directly | Beta |
 | **`Phronomy.with_configuration` / `Phronomy.reset_runtime!`** — Scoped configuration override and full runtime reset for test isolation | Beta |
 
 **Agent patterns**
@@ -140,7 +140,7 @@ Install additional gems only for the features you use:
 ### Agent — ReAct tool-calling agent
 
 ```ruby runnable
-class WebSearch < Phronomy::Tool::Base
+class WebSearch < Phronomy::Agent::Context::Capability::Base
   description "Search the web"
   param :query, type: :string, desc: "Search query"
 
@@ -216,10 +216,10 @@ transition from: :run_agent, on: :child_failed,    to: :handle_error
 
 ### Multi-Agent — Agent-as-Tool pattern
 
-Wrap sub-agents as `Tool::Base` subclasses so the orchestrator LLM can call them on demand.
+Wrap sub-agents as `Agent::Context::Capability::Base` subclasses so the orchestrator LLM can call them on demand.
 
 ```ruby
-class ResearchTool < Phronomy::Tool::Base
+class ResearchTool < Phronomy::Agent::Context::Capability::Base
   description "Research a topic and return key findings as bullet points."
   param :topic, type: :string, desc: "The topic to research"
 
@@ -233,7 +233,7 @@ class WriterAgent < Phronomy::Agent::Base
   instructions "You are a professional technical writer."
 end
 
-class WriteTool < Phronomy::Tool::Base
+class WriteTool < Phronomy::Agent::Context::Capability::Base
   description "Write a technical blog post given research notes and a writing brief."
   param :instructions, type: :string, desc: "Writing brief including research notes"
 
@@ -280,35 +280,25 @@ end
 > that logic must be implemented by the application. Reference implementations for
 > common patterns are available in `phronomy-examples` (example 06).
 
-### Knowledge/RAG — Context injection and vector retrieval
+### Knowledge — Static context injection
 
 ```ruby
 # Static knowledge (policy files, reference docs)
-policy = Phronomy::KnowledgeSource::StaticKnowledge.new(
+policy = Phronomy::Agent::Context::Knowledge::StaticKnowledge.new(
   File.read("policy.md"),
   type:   :policy,
   source: "policy.md"   # exposed to LLM for citation
 )
 
-# RAG retrieval from a vector store
-store      = Phronomy::VectorStore::InMemory.new
-embeddings = Phronomy::Embeddings::RubyLLMEmbeddings.new(model: "text-embedding-3-small")
-
-# Add documents before querying
-text1 = "Refunds are processed within 5 business days."
-text2 = "Contact support@example.com for refund requests."
-store.add(id: "doc-1", embedding: embeddings.embed(text1), metadata: { content: text1, source: "policy.md" })
-store.add(id: "doc-2", embedding: embeddings.embed(text2), metadata: { content: text2, source: "policy.md" })
-
-rag = Phronomy::KnowledgeSource::RAGKnowledge.new(store: store, embeddings: embeddings, k: 5)
-
-# Inject at invocation time
-result = MyAgent.new.invoke("What is the refund policy?",
-  config: { knowledge_sources: [policy, rag] })
+# Inject at invocation time via the agent DSL
+class MyAgent < Phronomy::Agent::Base
+  model "gpt-4o-mini"
+  knowledge policy
+end
 ```
 
-`static_knowledge_refresh!` invalidates the class-level cache of *static* knowledge sources
-(not RAG stores). Call it when the underlying file or content has changed:
+`static_knowledge_refresh!` invalidates the class-level cache of static knowledge sources.
+Call it when the underlying file or content has changed:
 
 ```ruby
 # Static knowledge sources are cached at the class level after the first fetch.
@@ -319,8 +309,8 @@ MyAgent.static_knowledge_refresh!
 Load and split documents with built-in loaders:
 
 ```ruby
-chunks = Phronomy::Loader::MarkdownLoader.new.load("docs/guide.md")
-         .then { |docs| Phronomy::Splitter::RecursiveSplitter.new(chunk_size: 512).split(docs) }
+chunks = Phronomy::VectorStore::Loader::MarkdownLoader.new.load("docs/guide.md")
+         .then { |docs| Phronomy::VectorStore::Splitter::RecursiveSplitter.new(chunk_size: 512).split(docs) }
 ```
 
 ### Multi-Agent Handoff — Hub-and-spoke routing
@@ -539,7 +529,7 @@ end
 ### MCP Tool — External tool servers
 
 ```ruby
-search_tool = Phronomy::Tool::McpTool.from_server(
+search_tool = Phronomy::Tools::Mcp.from_server(
   "stdio://./mcp-server",
   tool_name: "web_search"
 )
@@ -674,7 +664,7 @@ agents automatically stay within the configured token limit.
 Derives the effective token budget from RubyLLM's model registry:
 
 ```ruby
-budget = Phronomy::Context::TokenBudget.new(
+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
 )
@@ -686,7 +676,7 @@ budget.effective_input_limit # => 191_308
 Or supply explicit values (useful for local / unregistered models):
 
 ```ruby
-budget = Phronomy::Context::TokenBudget.new(
+budget = Phronomy::LlmContextWindow::TokenBudget.new(
   context_window:    32_768,
   max_output_tokens: 4_096
 )
@@ -716,15 +706,15 @@ registry the budget is silently skipped.
 > ```ruby
 > require "tiktoken_ruby"
 > enc = Tiktoken.encoding_for_model("gpt-4o")
-> Phronomy::Context::TokenEstimator.tokenizer = ->(text) { enc.encode(text).length }
+> Phronomy::LlmContextWindow::TokenEstimator.tokenizer = ->(text) { enc.encode(text).length }
 > ```
 
 
 ### CancellationToken — Cooperative cancellation
 
 Pass a `CancellationToken` to any agent via `config: { cancellation_token: token }`.
-Cancellation is checked at multiple granular checkpoints: before the LLM call, before
-each RAG knowledge-source fetch, after each streaming chunk, before each parallel
+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
 raised immediately and is never retried. No threads are force-killed — `ensure`
 blocks always execute.
@@ -750,7 +740,7 @@ blocks always execute.
 > risky interruption.
 
 ```ruby
-token = Phronomy::CancellationToken.new
+token = Phronomy::Concurrency::CancellationToken.new
 
 # Cancel from another thread after 5 s
 Thread.new { sleep 5; token.cancel! }
@@ -762,15 +752,15 @@ rescue Phronomy::CancellationError
 end
 
 # Hard deadline via monotonic clock (recommended — immune to NTP/DST changes)
-token = Phronomy::CancellationToken.timeout_after(30)
+token = Phronomy::Concurrency::CancellationToken.timeout_after(30)
 result = MyAgent.new.invoke("...", config: { cancellation_token: token })
 
 # Hard deadline via wall-clock (legacy — still supported)
-token = Phronomy::CancellationToken.new(deadline: Time.now + 30)
+token = Phronomy::Concurrency::CancellationToken.new(deadline: Time.now + 30)
 result = MyAgent.new.invoke("...", config: { cancellation_token: token })
 
 # Propagate to all parallel workers via dispatch_parallel / fan_out
-token = Phronomy::CancellationToken.new
+token = Phronomy::Concurrency::CancellationToken.new
 Thread.new { sleep 10; token.cancel! }
 
 orchestrator.dispatch_parallel(

data/benchmark/baseline.json

@@ -5,5 +5,5 @@
   "dispatch_parallel_10": 886.0,
   "cancellation_token_cancelled": 4335060.97443425,
   "cancellation_token_raise_if_cancelled_noop": 3566903.189098373,
-  "trim_context_remove_2000": 1761.5700678986254
+  "trim_messages_2000": 2896552.0
 }

data/benchmark/bench_agent_invoke.rb

@@ -53,7 +53,7 @@ class BenchStubChat
 end
 
 # A stub tool that does nothing but conforms to the Tool::Base interface.
-class BenchNullTool < Phronomy::Tool::Base
+class BenchNullTool < Phronomy::Agent::Context::Capability::Base
   description "No-op benchmark tool"
   param :x, type: :string, desc: "input"
 

data/benchmark/bench_context_assembler.rb

@@ -12,9 +12,9 @@ BenchAsmMessage = Struct.new(:content)
 
 def make_assembler(n_messages:, n_chunks:, with_budget: false)
   budget = if with_budget
-    Phronomy::Context::TokenBudget.new(context_window: 4096, max_output_tokens: 512)
+    Phronomy::LlmContextWindow::TokenBudget.new(context_window: 4096, max_output_tokens: 512)
   end
-  asm = Phronomy::Context::Assembler.new(budget: budget)
+  asm = Phronomy::LlmContextWindow::Assembler.new(budget: budget)
   asm.add_instruction("You are a helpful assistant. Answer the user's question.")
   n_chunks.times do |i|
     asm.add_knowledge("Fact #{i}: The capital of country #{i} is City #{i}.", type: :entity, trusted: true)
@@ -41,6 +41,14 @@ Benchmark.bm(40) do |x|
   end
 
   x.report("build(1000 msgs, 10 chunks, budgeted)") do
-    (BENCH_ASM_ITERATIONS / 10).times { make_assembler(n_messages: 1000, n_chunks: 10, with_budget: true).build }
+    (BENCH_ASM_ITERATIONS / 10).times do
+      # Assembler raises ContextLengthError when messages exceed the budget;
+      # callers (e.g. Agent::Base#build_context) are expected to pre-trim via
+      # trim_to_budget before calling build. The rescue here keeps the benchmark
+      # measuring build's fast path without triggering the error path.
+      make_assembler(n_messages: 1000, n_chunks: 10, with_budget: true).build
+    rescue Phronomy::ContextLengthError
+      # expected — budget exceeded
+    end
   end
 end

data/benchmark/bench_regression.rb

@@ -62,7 +62,7 @@ end
 # ---------------------------------------------------------------------------
 # Target 3: Tool::Base#params_schema generation (10 params)
 # ---------------------------------------------------------------------------
-tool_class = Class.new(Phronomy::Tool::Base) do
+tool_class = Class.new(Phronomy::Agent::Context::Capability::Base) do
   description "Test tool with 10 params"
   param :p1, type: :string, desc: "param 1"
   param :p2, type: :string, desc: "param 2"
@@ -94,7 +94,7 @@ stub_agent_class = Class.new(Phronomy::Agent::Base) do
   define_method(:invoke_async) { |input, **_kw| Phronomy::Runtime.instance.spawn(name: "bench-stub") { invoke(input) } }
 end
 
-orchestrator_class = Class.new(Phronomy::Agent::Orchestrator)
+orchestrator_class = Class.new(Phronomy::MultiAgent::Orchestrator)
 orchestrator = orchestrator_class.new
 
 PARALLEL_ITERATIONS = 200
@@ -109,7 +109,7 @@ end
 # ---------------------------------------------------------------------------
 # Target 5: CancellationToken#cancelled? throughput (8 threads)
 # ---------------------------------------------------------------------------
-CANCEL_TOKEN = Phronomy::CancellationToken.new
+CANCEL_TOKEN = Phronomy::Concurrency::CancellationToken.new
 CANCEL_ITERATIONS = 10_000
 
 t5 = Benchmark.measure("CancellationToken#cancelled? (8 threads)") do
@@ -122,7 +122,7 @@ end
 # ---------------------------------------------------------------------------
 # Target 6: CancellationToken#raise_if_cancelled! hot path (no-op, single thread)
 # ---------------------------------------------------------------------------
-RAISE_TOKEN = Phronomy::CancellationToken.new  # not cancelled — no-op path
+RAISE_TOKEN = Phronomy::Concurrency::CancellationToken.new  # not cancelled — no-op path
 RAISE_ITERATIONS = 200_000
 
 t6 = Benchmark.measure("CancellationToken#raise_if_cancelled! (no-op)") do
@@ -130,18 +130,18 @@ t6 = Benchmark.measure("CancellationToken#raise_if_cancelled! (no-op)") do
 end
 
 # ---------------------------------------------------------------------------
-# Target 7: Context::TrimContext#remove on a 2000-element history
+# Target 7: Agent::Base#trim_messages on a 2000-message history
 # ---------------------------------------------------------------------------
 BenchMsg = Struct.new(:content) unless defined?(BenchMsg)
 
-TRIM_ELEMENTS = Array.new(2_000) { |i| {seq: i, message: BenchMsg.new("msg #{i}"), tokens: 10, role: :user} }
-TRIM_BUDGET = Phronomy::Context::TokenBudget.new(context_window: 4096, max_output_tokens: 512)
+TRIM_MESSAGES = Array.new(2_000) { |i| BenchMsg.new("msg #{i}") }
 TRIM_ITERATIONS = 500
 
-t7 = Benchmark.measure("TrimContext#remove (2000-element history)") do
+bench_trim_agent = Class.new(Phronomy::Agent::Base).new
+
+t7 = Benchmark.measure("Agent::Base#trim_messages (2000-msg history)") do
   TRIM_ITERATIONS.times do
-    tc = Phronomy::Context::TrimContext.new(message_elements: TRIM_ELEMENTS, budget: TRIM_BUDGET)
-    tc.remove((0...200).to_a)  # remove 200 oldest messages
+    bench_trim_agent.send(:trim_messages, TRIM_MESSAGES, keep: 1_800)
   end
 end
 
@@ -159,7 +159,7 @@ metrics = {
   "dispatch_parallel_10" => [t4, PARALLEL_ITERATIONS],
   "cancellation_token_cancelled" => [t5, 8 * CANCEL_ITERATIONS],
   "cancellation_token_raise_if_cancelled_noop" => [t6, RAISE_ITERATIONS],
-  "trim_context_remove_2000" => [t7, TRIM_ITERATIONS]
+  "trim_messages_2000" => [t7, TRIM_ITERATIONS]
 }
 
 REGRESSION_RESULTS = {} # rubocop:disable Style/MutableConstant

data/benchmark/bench_token_estimator.rb

@@ -23,22 +23,22 @@ BENCH_TOKEN_ITERATIONS = 10_000
 puts "=== bench_token_estimator ==="
 Benchmark.bm(30) do |x|
   x.report("estimate(short text)") do
-    BENCH_TOKEN_ITERATIONS.times { Phronomy::Context::TokenEstimator.estimate(SHORT_TEXT) }
+    BENCH_TOKEN_ITERATIONS.times { Phronomy::LlmContextWindow::TokenEstimator.estimate(SHORT_TEXT) }
   end
 
   x.report("estimate(medium text 500c)") do
-    BENCH_TOKEN_ITERATIONS.times { Phronomy::Context::TokenEstimator.estimate(MEDIUM_TEXT) }
+    BENCH_TOKEN_ITERATIONS.times { Phronomy::LlmContextWindow::TokenEstimator.estimate(MEDIUM_TEXT) }
   end
 
   x.report("estimate(long text 10k c)") do
-    BENCH_TOKEN_ITERATIONS.times { Phronomy::Context::TokenEstimator.estimate(LONG_TEXT) }
+    BENCH_TOKEN_ITERATIONS.times { Phronomy::LlmContextWindow::TokenEstimator.estimate(LONG_TEXT) }
   end
 
   x.report("estimate(100 messages)") do
-    BENCH_TOKEN_ITERATIONS.times { Phronomy::Context::TokenEstimator.estimate(MESSAGES_100) }
+    BENCH_TOKEN_ITERATIONS.times { Phronomy::LlmContextWindow::TokenEstimator.estimate(MESSAGES_100) }
   end
 
   x.report("estimate(1000 messages)") do
-    (BENCH_TOKEN_ITERATIONS / 10).times { Phronomy::Context::TokenEstimator.estimate(MESSAGES_1000) }
+    (BENCH_TOKEN_ITERATIONS / 10).times { Phronomy::LlmContextWindow::TokenEstimator.estimate(MESSAGES_1000) }
   end
 end

data/benchmark/bench_tool_schema.rb

@@ -11,7 +11,7 @@ require_relative "../lib/phronomy"
 
 # --- Tool schema ---
 
-class BenchTool10Params < Phronomy::Tool::Base
+class BenchTool10Params < Phronomy::Agent::Context::Capability::Base
   description "A tool with 10 parameters for benchmarking purposes"
   param :param1, type: :string, desc: "First parameter"
   param :param2, type: :integer, desc: "Second parameter"
@@ -43,7 +43,7 @@ end
 
 # --- static_knowledge_chunks cache ---
 
-class BenchKnowledgeSource < Phronomy::KnowledgeSource::Base
+class BenchKnowledgeSource < Phronomy::Agent::Context::Knowledge::Base
   def fetch(query: nil)
     [{content: "Cached knowledge fact.", type: :static}]
   end

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

@@ -0,0 +1,224 @@
+# ADR-011: build_context as the Single Authority for LLM Input
+
+## Status
+
+Proposed — 2026-05-31
+
+## Context
+
+### Background
+
+`Agent::Base#build_context` was introduced as a hook for subclasses to customise
+the system prompt and conversation history passed to the LLM.  Its original return
+value was `{ system: String|nil, messages: Array }`, covering only two of the four
+conceptual regions of an LLM context window.
+
+`LlmContextWindow::Assembler` documents the four regions explicitly:
+
+```
+1. Instruction  — system prompt text
+2. Capability   — tool definitions
+3. Knowledge    — external facts (XML context tags)
+4. Conversation — conversation messages
+```
+
+However, the Assembler itself states Region 2 is "handled by RubyLLM, not here",
+leaving tool registration entirely outside the `build_context` path.
+
+### Problems identified
+
+**P1 — Tool definitions are not part of `build_context` output**
+
+Tools were registered with `chat.with_tool(tc)` *after* `build_context` returned,
+directly in `InvocationPipeline`, `_stream_impl`, and `ReactAgent#step`.
+This means a subclass that overrides `build_context` cannot control which tools
+are actually sent to the LLM; tools are always added behind its back.
+
+**P2 — `_handoff_tools` bypass `build_context` entirely**
+
+`Runner` adds handoff tools via `_add_handoff_tool` onto the agent instance.
+These were registered with `chat.with_tool(tc)` at every call site, separately
+from `context[:tool_classes]`, without going through `build_context` at all.
+Even if a subclass override returned a modified tool list, handoff tools would
+still be added unconditionally.
+
+**P3 — Tool token cost excluded from budget calculation**
+
+LLM providers (OpenAI, Anthropic, Gemini) count tool schema tokens against the
+context window.  The `TokenBudget` / `Assembler` pipeline never subtracted tool
+tokens from the available budget before trimming conversation messages.  This
+caused the budget calculation to be consistently optimistic: the `effective_input_limit`
+was always larger than the tokens actually available for messages, risking context
+window overflow on long conversations with many or complex tools.
+
+The existing `context_overhead` DSL was a manual workaround:
+
+```ruby
+class MyAgent < Phronomy::Agent::Base
+  context_overhead 800  # developer guesses tool token cost
+end
+```
+
+This is inaccurate by design and should not be necessary.
+
+**P4 — RAG fetch called inside `build_context` on every invocation**
+
+`build_context` called `fetch_knowledge_chunks` dynamically.  In a ReAct loop
+with N iterations, RAG was fetched N times for the same query.  More importantly,
+dynamic per-call RAG fetch is architecturally misplaced:
+
+- Knowledge fetched by RAG and injected as Region 3 context belongs to the
+  *agent's knowledge*, not to the per-invocation message flow.
+- If the LLM needs to retrieve information dynamically, the correct mechanism is
+  **function calling**: the LLM calls a retrieval tool, and the result appears in
+  the conversation log as a tool result message (Region 4).
+- Static knowledge that the agent always needs should be registered once at
+  agent initialisation time, not re-fetched on every `build_context` call.
+
+**P5 — `build_capability_tool_classes` is redundant indirection**
+
+`build_capability_tool_classes` was introduced as a narrower override hook to
+avoid requiring subclasses to copy `build_context` just to change tool selection.
+However, it has no documentation, no usage examples, and provides no capability
+that overriding `build_context` itself does not already provide.  Its existence
+adds a public API surface and conceptual overhead without commensurate value.
+
+**P6 — No access to previous context**
+
+`build_context` builds from scratch every call with no knowledge of what was sent
+to the LLM in the previous call.  This prevents:
+- Token cache hit optimisations (OpenAI prompt caching, Anthropic `cache_control`)
+  which require a stable prompt prefix
+- Incremental context strategies that avoid recomputing unchanged regions
+
+## Decision
+
+### D1 — `build_context` is the single authority for all LLM input
+
+**Nothing may be added to or removed from the LLM request outside of
+`build_context`.**  Every call site (`InvocationPipeline`, `_stream_impl`,
+`ReactAgent#step`, `ReactAgent#stream_step`) must:
+
+1. Call `build_context` to obtain `{ system:, messages:, tool_classes: }`.
+2. Apply the result to `chat` — and *only* the result.
+3. Not register any additional tools, messages, or instructions independently.
+
+### D2 — Assembler handles all four regions including Capability
+
+`LlmContextWindow::Assembler` gains `add_capability(tool_classes)`:
+
+```ruby
+assembler.add_capability(tools)  # Region 2
+```
+
+Responsibilities of `add_capability`:
+
+1. Store `tool_classes` for pass-through in `build` return value.
+2. Serialise each tool's schema (via RubyLLM's provider-specific `tool_for` /
+   `function_declaration_for`) and estimate its token cost.
+3. Add that cost to the `used` token count before conversation message trimming.
+
+`build` return value expands to:
+
+```ruby
+{ system: String|nil, messages: Array, tool_classes: Array }
+```
+
+### D3 — `build_context` includes all tools (user tools + handoff tools)
+
+`build_context` passes `self.class.tools + _handoff_tools` to
+`assembler.add_capability`.  `_handoff_tools` are framework-managed routing tools;
+they are always included and are not subject to user-level filtering.
+
+Subclasses that need dynamic tool selection override `build_context` and call
+`assembler.add_capability` with their own selection logic.
+
+`build_capability_tool_classes` is **removed** (P5 resolution).
+
+### D4 — `fetch_knowledge_chunks` is removed from `build_context`
+
+Knowledge enters Region 3 through exactly two paths:
+
+**Path A — Agent initialisation (static knowledge)**
+
+```ruby
+class MyAgent < Phronomy::Agent::Base
+  knowledge "The capital of Japan is Tokyo.", type: :entity
+end
+```
+
+Registered once; the Assembler always includes it.
+
+**Path B — Per-invocation dynamic knowledge via `config[:knowledge_sources]`**
+
+The caller passes knowledge sources in the invocation config:
+
+```ruby
+agent.invoke(input, config: { knowledge_sources: [my_rag_source] })
+```
+
+`build_context` calls `fetch_knowledge_chunks` exactly **once per `invoke`**,
+not once per LLM call within a ReAct loop.  The result is cached on the agent
+instance for the duration of that invocation.
+
+This is a caller responsibility: if the caller needs fresh knowledge on every
+`invoke`, it passes new sources.  Within a single `invoke`, knowledge is stable.
+
+### D5 — Previous context stored as instance variable
+
+After each `build_context` call, the result is stored:
+
+```ruby
+@last_context = { system: ..., messages: ..., tool_classes: ... }
+```
+
+`build_context` may reference `@last_context` for optimisations such as:
+
+- Detecting that `system` and `tool_classes` are unchanged → skip regeneration
+  of the stable prefix to improve LLM provider token cache hit rate.
+- Skipping Assembler work when the context is provably identical to the last call.
+
+`@last_context` is **not** passed as a method parameter; it is read from the
+instance.  This avoids changing call-site signatures.
+
+Note: `Agent` instances are not thread-safe (already documented).  `@last_context`
+inherits this constraint — concurrent invocations on the same instance are not
+supported.
+
+## Consequences
+
+### Token budget accuracy
+
+With D2, `effective_input_limit` correctly reflects the tokens actually available
+for conversation messages after system prompt, tool schemas, and knowledge are
+accounted for.  `context_overhead` becomes unnecessary for tool costs; it may
+still be used as a manual reserve for provider-specific overhead not captured by
+schema serialisation.
+
+### `build_context` as the integration surface
+
+Subclasses override `build_context` for all customisation: tool selection,
+knowledge injection, system prompt variants, context compression strategies.
+There is one integration point, not several.
+
+### RAG fetch frequency
+
+`fetch_knowledge_chunks` runs at most once per `invoke` call (P4 resolution).
+In ReAct loops with N iterations, RAG is fetched once, not N times.
+
+### Removed API
+
+`build_capability_tool_classes` is removed.  It was never documented or used
+outside of internal framework code, so there is no public API break.
+
+## Migration notes
+
+- All call sites (`InvocationPipeline`, `_stream_impl`, `ReactAgent#step/stream_step`)
+  must be updated to remove the separate `_handoff_tools` registration lines and
+  rely solely on `context[:tool_classes]`.
+- `Assembler#add_capability` and the token estimation for tool schemas must be
+  implemented.
+- `build_context` must be updated to pass all tools to `assembler.add_capability`
+  and to cache `@last_context`.
+- `fetch_knowledge_chunks` must be lifted out of `build_context` into the
+  invocation-scoped cache described in D4.