phronomy 0.16.0 → 0.17.0

data/benchmark/baseline.json

@@ -4,6 +4,5 @@
   "tool_params_schema_definition": 19534379.159046534,
   "dispatch_parallel_10": 886.0,
   "cancellation_token_cancelled": 4335060.97443425,
-  "cancellation_token_raise_if_cancelled_noop": 3566903.189098373,
-  "trim_messages_2000": 2896552.0
-}
+  "cancellation_token_raise_if_cancelled_noop": 3566903.189098373
+}

data/benchmark/bench_agent_invoke.rb

@@ -3,11 +3,11 @@
 # bench_agent_invoke.rb — Agent#invoke framework overhead benchmark.
 #
 # Measures the per-invoke cost of the Phronomy::Agent::Base framework path
-# (context assembly, guardrail checks, before_completion hooks, response
-# handling) with a fully stubbed LLM.  No network calls are made.
+# (context assembly, filter checks, before_llm_input hooks, response handling)
+# with a fully stubbed LLM. No network calls are made.
 #
 # Scenarios:
-#   1. Minimal agent (no tools, no knowledge) — baseline framework overhead.
+#   1. Minimal agent (no tools, no persistent Knowledge) — baseline framework overhead.
 #   2. Tool-aware agent with a registered stub Tool.
 #   3. Agent#stream setup latency (first-chunk time with stubbed stream).
 
@@ -81,7 +81,7 @@ end
 bench_tool_class = Class.new(Phronomy::Agent::Base) do
   agent_definition id: "bench-tool", version: 1
   model "stub-model"
-  tools BenchNullTool
+  tools(BenchNullTool => nil)
 
   define_method(:build_chat) { |*| BenchStubChat.new(BENCH_RESP) }
 end

data/benchmark/bench_context_assembler.rb

@@ -1,54 +1,154 @@
 # frozen_string_literal: true
 
-# Benchmark: Context::Assembler#build
+# Benchmark: Manifest-first Context assembly and Default Context Policy.
 #
-# Tests context assembly performance for varying numbers of messages and
-# knowledge chunks. This path is exercised on every agent turn.
+# Usage:
+#   ruby benchmark/bench_context_assembler.rb
+#
+# Measures:
+#   1. ContextPolicies::Default selection cost for growing canonical candidate sets.
+#   2. ContextAssembler#build_initial end-to-end Manifest construction.
+#
+# No provider call is performed.
 
 require "benchmark"
 require_relative "../lib/phronomy"
 
-BenchAsmMessage = Struct.new(:content)
+module BenchContextAssembler
+  module_function
 
-def make_assembler(n_messages:, n_chunks:, with_budget: false)
-  budget = if with_budget
-    Phronomy::LlmContextWindow::TokenBudget.new(context_window: 4096, max_output_tokens: 512)
-  end
-  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)
+  def candidate(index)
+    category, role = if (index % 10).zero?
+      [:knowledge, :user]
+    elsif index.even?
+      [:assistant_message, :assistant]
+    else
+      [:external_message, :user]
+    end
+
+    Phronomy::Agent::ContextCandidate.new(
+      candidate_id: "candidate-#{index}",
+      source_kind: :journal,
+      category: category,
+      role: role,
+      content_ref: "content-#{index}",
+      record_id: "record-#{index}",
+      agent_id: "bench-agent",
+      execution_id: "execution-#{index / 4}",
+      llm_call_id: nil,
+      tool_call_id: nil,
+      sequence: index,
+      requirement: :optional,
+      priority: 0,
+      metadata: {
+        "estimated_tokens" => 8,
+        "source_sequence" => index
+      }
+    )
   end
-  msgs = Array.new(n_messages) { BenchAsmMessage.new("This is a conversation message.") }
-  asm.add_messages(msgs)
-  asm
-end
 
-BENCH_ASM_ITERATIONS = 1_000
+  def parts
+    {
+      unit_builder:
+        Phronomy::Agent::ContextParts::UnitBuilders::DependencyAwareUnitBuilder.new,
+      required_context_resolver:
+        Phronomy::Agent::ContextParts::Requirements::RequiredContextResolver.new,
+      recent_first_selector:
+        Phronomy::Agent::ContextParts::Selectors::RecentFirstSelector.new,
+      token_budget_packer:
+        Phronomy::Agent::ContextParts::Budget::TokenBudgetPacker.new
+    }.freeze
+  end
 
-puts "=== bench_context_assembler ==="
-Benchmark.bm(40) do |x|
-  x.report("build(10 msgs, 0 chunks)") do
-    BENCH_ASM_ITERATIONS.times { make_assembler(n_messages: 10, n_chunks: 0).build }
+  def request(candidate_count)
+    candidates = Array.new(candidate_count) { |i| candidate(i) }
+    Phronomy::Agent::ContextRequest.new(
+      agent_id: "bench-agent",
+      execution_id: "bench-execution",
+      call_sequence: 2,
+      call_mode: :complete,
+      candidates: candidates,
+      token_budget: Phronomy::LlmContextWindow::TokenBudget.new(
+        context_window: [candidate_count * 16, 4_096].max,
+        max_output_tokens: 512
+      ),
+      model_config: {},
+      previous_manifest: nil,
+      required_coverage: [],
+      parts: parts,
+      metadata: {"mandatory_token_estimate" => 32}
+    )
   end
 
-  x.report("build(100 msgs, 5 chunks)") do
-    BENCH_ASM_ITERATIONS.times { make_assembler(n_messages: 100, n_chunks: 5).build }
+  def assembler_fixture
+    persistence = Phronomy::Persistence::InMemory.new
+    agent_class = Class.new(Phronomy::Agent::Base) do
+      agent_definition id: "bench-manifest-context-assembler", version: 1
+      model "local-model"
+      context_window 16_384
+      max_output_tokens 1_024
+      instructions "Benchmark instruction"
+    end
+    agent = agent_class.new(
+      persistence: persistence,
+      knowledge: ["Persistent benchmark knowledge"]
+    )
+    root = agent.agent_root
+    input_ref = persistence.contents.put_text("benchmark input")
+    input_record = Phronomy::Agent::JournalRecord.new(
+      agent_id: agent.agent_id,
+      kind: :external_message,
+      channel: :external,
+      role: :user,
+      content_ref: input_ref,
+      context_generation: root.transcript_generation,
+      context_candidate: true
+    )
+    execution = Phronomy::Agent::AgentExecution.start(
+      agent_root: root,
+      input_record: input_record,
+      metadata: {
+        "current_input_ref" => input_ref,
+        "current_input_record_id" => input_record.record_id
+      }
+    ).with(
+      execution_revision: 0,
+      working_records: [input_record]
+    )
+
+    [
+      Phronomy::Agent::ContextAssembler.new(agent: agent, persistence: persistence),
+      root,
+      execution
+    ]
   end
+end
+
+puts "Manifest-first Context benchmark"
+puts "Ruby #{RUBY_VERSION} on #{RUBY_PLATFORM}"
+puts "=" * 72
 
-  x.report("build(1000 msgs, 10 chunks, no budget)") do
-    (BENCH_ASM_ITERATIONS / 10).times { make_assembler(n_messages: 1000, n_chunks: 10).build }
+policy = Phronomy::Agent::ContextPolicies::Default.new
+policy_requests = [10, 100, 1_000].to_h do |count|
+  [count, BenchContextAssembler.request(count)]
+end
+
+Benchmark.bm(46) do |x|
+  policy_requests.each do |count, request|
+    iterations = (count >= 1_000) ? 200 : 1_000
+    x.report("DefaultContextPolicy #{count} candidates x#{iterations}") do
+      iterations.times { policy.call(request) }
+    end
   end
 
-  x.report("build(1000 msgs, 10 chunks, budgeted)") do
-    (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
+  assembler, root, execution = BenchContextAssembler.assembler_fixture
+  x.report("ContextAssembler#build_initial x500") do
+    500.times do
+      assembler.build_initial(
+        input: "benchmark input",
+        agent_root: root,
+        execution: execution
+      )
     end
   end
 end

data/benchmark/bench_regression.rb

@@ -89,7 +89,7 @@ end
 # ---------------------------------------------------------------------------
 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: {}|
+  define_method(:invoke) do |_input, thread_id: nil, config: {}|
     {output: "stub", messages: []}
   end
   define_method(:invoke_async) { |input, **_kw| Phronomy::Runtime.instance.spawn(name: "bench-stub") { invoke(input) } }

data/benchmark/bench_tool_schema.rb

@@ -1,16 +1,12 @@
 # frozen_string_literal: true
 
-# Benchmark: Tool::Base params_schema generation and static_knowledge_chunks cache
+# Benchmark: Tool::Base params_schema generation.
 #
-# Tool schema generation happens once per tool class (lazily memoised).
-# static_knowledge_chunks is cached at the class level; cache-hit overhead
-# should be negligible compared to cache-miss (which calls the knowledge source).
+# Tool schema generation happens once per tool class and is lazily memoized.
 
 require "benchmark"
 require_relative "../lib/phronomy"
 
-# --- Tool schema ---
-
 class BenchTool10Params < Phronomy::Agent::Context::Capability::Base
   description "A tool with 10 parameters for benchmarking purposes"
   param :param1, type: :string, desc: "First parameter"
@@ -29,7 +25,6 @@ class BenchTool10Params < Phronomy::Agent::Context::Capability::Base
   end
 end
 
-# Warm up memoisation
 BenchTool10Params.params_schema_definition
 
 BENCH_TOOL_ITERATIONS = 50_000
@@ -40,31 +35,3 @@ Benchmark.bm(35) do |x|
     BENCH_TOOL_ITERATIONS.times { BenchTool10Params.params_schema_definition }
   end
 end
-
-# --- static_knowledge_chunks cache ---
-
-class BenchKnowledgeSource < Phronomy::Agent::Context::Knowledge::Base
-  def fetch(query: nil)
-    [{content: "Cached knowledge fact.", type: :static}]
-  end
-
-  def static?
-    true
-  end
-end
-
-class BenchAgentWithKnowledge < Phronomy::Agent::Base
-  agent_definition id: "bench-knowledge", version: 1
-  model "gpt-4o-mini"
-  static_knowledge BenchKnowledgeSource.new
-end
-
-# Warm up cache
-BenchAgentWithKnowledge.static_knowledge_chunks
-
-puts "\n=== bench_static_knowledge_cache ==="
-Benchmark.bm(35) do |x|
-  x.report("static_knowledge_chunks (hit)") do
-    BENCH_TOOL_ITERATIONS.times { BenchAgentWithKnowledge.static_knowledge_chunks }
-  end
-end

data/docs/decisions/005-static-knowledge-class-level-cache.md

@@ -2,7 +2,12 @@
 
 ## Status
 
-Accepted
+Superseded by ADR-013.
+
+This ADR records the historical decision for the former KnowledgeSource-based
+architecture. `static_knowledge`, `KnowledgeSource`, `StaticKnowledge`,
+`EntityKnowledge` and the class-level Knowledge cache are no longer part of the
+active design.
 
 ## Context
 
@@ -43,3 +48,9 @@ re-fetched on each invocation because their content depends on runtime state.
   non-static knowledge source.
 - In tests, the cache must be cleared between examples. `Phronomy.reset_runtime!`
   handles this.
+
+## Supersession
+
+ADR-013 replaces the source-object/cache model with Journal-backed persistent
+Knowledge selected through Context Policy. The historical rationale above is
+retained only to explain the superseded architecture.

data/docs/decisions/010-cooperative-first-concurrency.md

@@ -5,6 +5,13 @@
 Accepted — updated 2026-05-25 to document current scheduler landscape and
 production-cooperative roadmap (Issues #331, #332, #334).
 
+> **Historical implementation note (2026-08-09):** The implementation-detail
+> inventory below is intentionally preserved as decision history. Compatibility
+> APIs subsequently removed from the active contract — including the
+> `runtime_backend :cooperative` alias and direct Runtime singleton replacement —
+> must not be read as current API guidance. The cooperative-first layering
+> principle remains the decision; use README/current source for current symbols.
+
 ## Context
 
 Phronomy provides its own concurrency primitives:

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

@@ -2,13 +2,13 @@
 
 ## Status
 
-Partially Superseded by ADR-012 — 2026-08-08
+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.
+ADR-012, **Canonical Complete Execution Log and Context Policy**, supersedes this ADR as an active architecture contract. This document is retained as historical design analysis; references below to `build_context`, `context_overhead`, and `LlmContextWindow::Assembler` are non-normative.
 
 In particular, the following parts of this ADR are no longer normative for the stateful Agent architecture:
 

data/docs/decisions/013-journal-backed-knowledge-as-context-candidates.md

@@ -0,0 +1,122 @@
+# ADR-013: Journal-backed Knowledge as Context Candidates
+
+## Status
+
+Accepted.
+
+## Context
+
+The Manifest-first Agent refactor established the Journal as the canonical
+append-only record of Agent state and `LLMInputManifest` as the authority for
+one provider call. The older Knowledge design remained outside that model:
+`StaticKnowledge` and other `KnowledgeSource` objects were fetched separately,
+then concatenated into the mandatory system prompt. That created several
+problems:
+
+- static/entity/RAG distinctions described acquisition strategy rather than
+  Context semantics;
+- class-level and instance-level Knowledge followed different storage paths;
+- persistent Knowledge did not share Agent persistence/reload semantics;
+- Knowledge bypassed Context Policy and was always mandatory once configured;
+- `static?`, `source`, fetch/caching APIs and EntityKnowledge behavior existed
+  primarily to support the obsolete source abstraction.
+
+Applications still need two different lifetimes:
+
+1. information that becomes durable Agent Knowledge at creation time or later;
+2. request-scoped information used for only one LLM call.
+
+## Decision
+
+Phronomy has one Knowledge Context category.
+
+### Persistent Knowledge
+
+Persistent Knowledge is stored as ordinary append-only Journal records with
+`kind: :knowledge`, `channel: :context`, `role: :user` and
+`context_candidate: true`. Content lives in ContentStore and the Journal holds
+its content reference and application metadata.
+
+Agent instances accept Knowledge at creation and after creation:
+
+```ruby
+agent = MyAgent.new(knowledge: ["Policy: ..."])
+agent.add_knowledge("Customer locale: ja-JP")
+```
+
+`Agent.load` requires no separate Knowledge source reconstruction because the
+records are already persisted with the Agent.
+
+### Selection
+
+Knowledge is not part of the public conversation transcript.
+`JournalProjection` exposes active Knowledge together with active transcript
+records for Context selection. `ContextCandidateResolver` and Context Policy
+therefore handle persistent Knowledge through the same selection pipeline as
+other optional Context.
+
+Knowledge is optional by default. The fact that content is Knowledge does not
+make it mandatory.
+
+Selected Knowledge is materialized before ordinary conversation-history
+segments so that persistent background Context is not interleaved into the
+middle of dialogue chronology.
+
+### Reset semantics
+
+`clear_knowledge!` appends a `knowledge_cleared` marker. Earlier Knowledge
+records remain in the Journal but are excluded from later Context projections.
+No Knowledge-generation counter is required.
+
+`clear_transcript!` affects conversation history only. `reset_context!` resets
+both transcript eligibility and Knowledge eligibility while retaining raw
+Journal records.
+
+### Per-call Context
+
+`before_llm_input` continues to accept `LLMInputPatch#segment_candidates`.
+Those candidates are not persisted. They enter the same Context Policy request
+as Journal-backed candidates and may be omitted when optional and over budget.
+
+### Acquisition responsibility
+
+Phronomy core does not model `StaticKnowledge`, `EntityKnowledge`,
+`RAGKnowledge` or `KnowledgeSource` subclasses. File loading, retrieval, entity
+extraction and other acquisition strategies belong to applications or Tools.
+Once an application chooses to retain the resulting information, it registers
+plain logical Knowledge with the Agent.
+
+## Consequences
+
+### Positive
+
+- one persistent representation and one Context-selection path;
+- creation-time and post-creation Knowledge behave identically;
+- durable Knowledge naturally survives Agent reload;
+- token-budget selection can omit optional Knowledge without rewriting state;
+- RAG/entity extraction can evolve independently of Agent Context persistence;
+- no class-level static cache or `static?` distinction is needed.
+
+### Tradeoffs
+
+- applications that previously declared class-level static Knowledge must pass
+  common Knowledge when constructing each Agent instance;
+- source-specific refresh behavior is no longer a framework abstraction;
+- provenance that matters to an application must be stored explicitly in
+  metadata rather than through a dedicated `source:` API.
+
+## Removed contracts
+
+This decision removes the active contracts for:
+
+- `Phronomy::KnowledgeSource`;
+- `Agent::Context::Knowledge::Base`;
+- `StaticKnowledge`;
+- `EntityKnowledge`;
+- `static_knowledge`, `static_knowledge_sources`, `static_knowledge_chunks`,
+  `static_knowledge_refresh!`;
+- `add_knowledge_source`, `instance_knowledge_chunks`;
+- `clear_memory!` / `memory_generation` as obsolete Agent Context concepts.
+
+ADR-005 is superseded by this decision. ADR-012 remains the authority for the
+Journal/Manifest separation and Context Policy model.

data/lib/phronomy/agent/agent_invocation.rb

@@ -29,7 +29,6 @@ module Phronomy
       CALLBACK_FAILED_EVENTS = %i[application_callback_failed].freeze
 
       attr_accessor :input,
-        :messages,
         :chat,
         :output,
         :usage,
@@ -59,18 +58,15 @@ module Phronomy
       def initialize(
         agent:,
         input:,
-        messages:,
         config:,
         approval_policy: nil,
         approval_listener: nil,
         event_listener: nil,
-        stream_listener: nil,
         mode: nil,
         id: nil
       )
         @agent = agent
         @input = input
-        @messages = Array(messages)
         @config = config
         @thread_id = config[:thread_id]
         @id = (id || config[:agent_invocation_id] || SecureRandom.uuid).to_s
@@ -80,8 +76,8 @@ module Phronomy
         end
         @approval_policy = invocation_policy || approval_policy
         @approval_listener = approval_listener
-        @event_listener = event_listener || stream_listener
-        @mode = (mode || (stream_listener ? :stream : :invoke)).to_sym
+        @event_listener = event_listener
+        @mode = (mode || :invoke).to_sym
 
         @chat = nil
         @output = nil
@@ -104,14 +100,6 @@ module Phronomy
         @tool_batch_llm_call_id = nil
       end
 
-      def stream_listener
-        @event_listener
-      end
-
-      def stream_listener=(listener)
-        @event_listener = listener
-      end
-
       def streaming?
         @mode == :stream
       end
@@ -180,29 +168,9 @@ module Phronomy
         true
       end
 
-      def apply_fsm_action_result(result)
-        event_type =
-          if result.respond_to?(:error) &&
-              result.error &&
-              !result.error.is_a?(ToolCallIntercepted)
-            :llm_failed
-          else
-            :llm_completed
-          end
-        handle_fsm_event(
-          Phronomy::Event.new(
-            type: event_type,
-            target_id: @id,
-            payload: result
-          )
-        )
-        self
-      end
-
       def accept_tool_calls!(tool_calls, llm_call_id: nil)
         @user_message_sent = true
         @pending_tool_calls = Array(tool_calls)
-        @messages = @chat.messages
         @tool_batch_llm_call_id = (llm_call_id || @current_llm_call_id)&.to_s
         @current_llm_call_id = nil
         @pending_tool_calls.each do |tool_call|
@@ -227,7 +195,6 @@ module Phronomy
         @user_message_sent = true
         @output = response.content
         @usage = Phronomy::TokenUsage.from_tokens(response.tokens)
-        @messages = @chat.messages
         @pending_tool_calls = []
         @current_llm_call_id = nil
         self
@@ -298,7 +265,6 @@ module Phronomy
             )
           )
         end
-        @messages = @chat.messages
         clear_tool_batch!
         self
       end