pikuri-core 0.0.3 → 0.0.5

data/lib/pikuri/agent.rb

@@ -48,8 +48,8 @@ module Pikuri
   # and gets a fresh +step_limit+ at +max: 1+ (defensive — the
   # synth has no tools and shouldn't trip it). The synth's
   # answer becomes the value reported by
-  # {#last_assistant_content}, so callers (notably
-  # {Tool::SubAgent}) still get a usable reply.
+  # {#last_assistant_content}, so callers (notably the +agent+ tool
+  # from +pikuri-subagents+) still get a usable reply.
   #
   # == Cancellation rescue
   #
@@ -94,8 +94,16 @@ module Pikuri
     #   queue is drained on every +after_tool_result+, each item
     #   appended as a +role: :user+ message and emitted as
     #   {Event::UserTurn} with +mid_loop: true+
+    # @param on_user_message [Proc, nil] when set, called with each
+    #   drained interloper +content+ String *after* it is appended
+    #   to the chat — the per-turn {Extension#on_user_message}
+    #   dispatch (prefetch + recording). Threaded through here rather
+    #   than fired inline so {Synthesizer.run}, which reuses this
+    #   wiring without an interloper or memory, simply passes +nil+.
+    #   Only consulted when +interloper+ is also set.
     # @return [void]
-    def self.wire_chat(chat, listeners:, step_limit: nil, cancellable: nil, interloper: nil)
+    def self.wire_chat(chat, listeners:, step_limit: nil, cancellable: nil, interloper: nil,
+                       on_user_message: nil)
       chat.after_message do |msg|
         emit_after_message(msg, listeners)
       end
@@ -106,7 +114,7 @@ module Pikuri
       end
       chat.after_tool_result do |result|
         listeners.emit(Event::ToolResult.new(content: result))
-        drain_interloper(interloper, chat, listeners) if interloper
+        drain_interloper(interloper, chat, listeners, on_user_message) if interloper
       end
     end
 
@@ -216,18 +224,29 @@ module Pikuri
 
     # Drain the interloper queue: for each pending item, append a
     # +role: :user+ message to the chat history so the next
-    # round-trip sees it, then emit an {Event::UserTurn} with
-    # +mid_loop: true+ to the listener stream so renderers see
-    # the injection.
+    # round-trip sees it, emit an {Event::UserTurn} with
+    # +mid_loop: true+ to the listener stream so renderers see the
+    # injection, then run the per-turn {Extension#on_user_message}
+    # dispatch (so mid-loop injections are prefetched + recorded
+    # exactly like initial turns).
+    #
+    # The dispatch runs *after* the +:user+ append so any
+    # +<memory-context>+ it injects lands as a +:system+ message
+    # right behind the user turn it annotates — the same
+    # append-at-the-tail ordering {#run_loop} produces for initial
+    # turns.
     #
     # @param interloper [Control::Interloper]
     # @param chat [RubyLLM::Chat]
     # @param listeners [ListenerList]
+    # @param on_user_message [Proc, nil] per-content dispatch; +nil+
+    #   skips it (e.g. an interloper with no memory extension wired)
     # @return [void]
-    def self.drain_interloper(interloper, chat, listeners)
+    def self.drain_interloper(interloper, chat, listeners, on_user_message = nil)
       interloper.drain!.each do |content|
         chat.add_message(role: :user, content: content)
         listeners.emit(Event::UserTurn.new(content: content, mid_loop: true))
+        on_user_message&.call(content)
       end
     end
     private_class_method :drain_interloper
@@ -332,14 +351,16 @@ module Pikuri
     #   set. Typically derived by +bin/pikuri-chat+ from its
     #   configured +openai_api_base+; leave +nil+ when the
     #   configured server is anything other than llama.cpp.
-    # @param name [String] identifier for this agent. Empty for
-    #   the main agent; sub-agents get monotonic hierarchical
-    #   names like +"sub_agent 0"+, +"sub_agent 1"+,
-    #   +"sub_agent 0_0"+, ... generated by {Tool::SubAgent} from
-    #   the parent's name + a per-parent counter. Forwarded to
-    #   listeners through {ListenerList#for_sub_agent} so name-
-    #   aware ones (notably {Listener::TokenLog}) can tag their
-    #   output.
+    # @param id [String] unique identifier for this agent. Empty
+    #   for the main agent; sub-agents get persona-rooted ids
+    #   like +"researcher 0"+, +"researcher 1"+, +"file_miner 0"+, ...
+    #   generated by the +agent+ tool from +pikuri-subagents+ from
+    #   the persona name + a per-persona counter. Forwarded to
+    #   listeners through {ListenerList#for_sub_agent} so id-aware
+    #   ones (notably {Listener::TokenLog}) can tag their output.
+    #   The word "id" is deliberate — "name" is reserved throughout
+    #   the codebase for the persona-name load (the value the LLM
+    #   picks in the +agent+ tool's +name:+ argument).
     # @param streaming [Boolean] opt into chunk-level streaming.
     #   When +true+, {#run_loop} passes the block returned by
     #   {.streaming_block} to +Chat#ask+, and ruby_llm requests
@@ -348,25 +369,24 @@ module Pikuri
     #   the listener stream as they arrive. When +false+ (the
     #   default), +Chat#ask+ runs in single-shot mode and only
     #   the message-level {Event::Thinking} / {Event::Assistant}
-    #   bookends fire from +after_message+. Read by
-    #   {Tool::SubAgent} so spawned sub-agents inherit the same
-    #   mode without an extra kwarg.
+    #   bookends fire from +after_message+. Read by the +agent+
+    #   tool from +pikuri-subagents+ so spawned sub-agents inherit
+    #   the same mode without an extra kwarg.
     # @yield [Configurator] yields a {Configurator} that collects
     #   tools (via {Configurator#add_tool} / {Configurator#add_tools}),
     #   listeners (via {Configurator#add_listener} /
     #   {Configurator#add_listeners}), system-prompt snippets (via
     #   {Configurator#append_system_prompt}), extension instances
     #   (via {Configurator#add_extension} — which fires +configure+
-    #   immediately), close handlers (via {Configurator#on_close}),
-    #   and an optional +sub_agent+ tool (via
-    #   {Configurator#allow_sub_agent}). The Configurator is the
-    #   *only* path for adding any of these — there are no parallel
-    #   ctor kwargs. The block is optional; an agent constructed
-    #   without one has no tools, no listeners, no extensions.
+    #   immediately), and close handlers (via
+    #   {Configurator#on_close}). The Configurator is the *only*
+    #   path for adding any of these — there are no parallel ctor
+    #   kwargs. The block is optional; an agent constructed without
+    #   one has no tools, no listeners, no extensions.
     # @return [Agent]
     def initialize(transport:, system_prompt:,
                    step_limit: nil, cancellable: nil, interloper: nil,
-                   context_window: nil, llama_probe_url: nil, name: '',
+                   context_window: nil, llama_probe_url: nil, id: '',
                    streaming: false,
                    &block)
       @transport = transport.model ? transport : transport.with(model: RubyLLM.config.default_model)
@@ -376,95 +396,35 @@ module Pikuri
       @system_prompt = system_prompt
       @step_limit = step_limit
       @interloper = interloper
-      @name = name
+      @id = id
       @streaming = streaming
       @synth_answer = nil
       @on_close_handlers = []
-
-      # Single Configurator funnel for everything the block adds —
-      # tools, listeners, system-prompt snippets, extensions
-      # (both newly-configured via #add_extension and inherited
-      # via #inherit_extensions for sub-agents), on_close handlers,
-      # and the sub-agent request. See IDEAS.md §"Extension protocol
-      # design".
-      configurator = Configurator.new(
-        transport: @transport,
-        system_prompt_base: system_prompt,
-        name: @name,
-        streaming: @streaming,
-        step_limit: @step_limit,
-        cancellable: @cancellable,
-        interloper: @interloper
-      )
-
-      block&.call(configurator)
-
-      @tools = configurator.tools.dup
-      @listeners = ListenerList.new(configurator.listeners)
-      configurator.system_prompt_additions.each do |snippet|
-        @system_prompt = "#{@system_prompt}\n\n#{snippet}"
+      # Stashed for {#run_configure}, which runs the failure-prone
+      # build phase below out of a separate method.
+      @block = block
+      @context_window = context_window
+      @llama_probe_url = llama_probe_url
+
+      # Register *before* the build phase so a mid-construction raise
+      # is still recoverable: extensions arm their cleanup via
+      # +c.on_close+ (which writes straight to +@on_close_handlers+,
+      # see {Configurator}), and the rescue below fires whatever was
+      # armed before the failure. On the happy path this registration
+      # is the at-exit backstop if the host forgets {#close}; an
+      # explicit {#close} unregisters, so the agent isn't pinned alive
+      # until process exit.
+      Pikuri::Finalizers.register(self)
+
+      begin
+        run_configure
+      rescue StandardError
+        # Half-built agent (e.g. an extension's +configure+ raised
+        # Cancelled mid-spawn). Fire the handlers armed so far, drop
+        # out of the registry, and re-raise — no partial state leaks.
+        close
+        raise
       end
-      @on_close_handlers.concat(configurator.on_close_handlers)
-      @extensions = configurator.extensions.dup
-
-      @chat = RubyLLM.chat(**@transport.to_h)
-      @chat.with_instructions(@system_prompt)
-      @tools.each { |t| @chat.with_tool(t.to_ruby_llm_tool) }
-
-      @context_window_cap = ContextWindowDetector.new(
-        override: context_window,
-        ruby_llm_reported: @chat.model.context_window,
-        llama_probe_url: llama_probe_url
-      ).detect
-
-      self.class.wire_chat(
-        @chat,
-        listeners: @listeners,
-        step_limit: @step_limit,
-        cancellable: @cancellable,
-        interloper: @interloper
-      )
-
-      # One-shot context-window cap: lets every listener that
-      # cares (notably TokenLog) pick the value off the stream
-      # before any Tokens event arrives.
-      @listeners.emit(Event::ContextCap.new(cap: @context_window_cap))
-
-      # Sub-agent tool: constructed *after* @tools is final and
-      # @context_window_cap is set, so its snapshot of the parent's
-      # tool list doesn't include itself (recursion guard) and the
-      # cap can be threaded through to spawned sub-agents. The new
-      # +Tool::SubAgent+ instance is appended to both +@tools+ and
-      # +@chat+, so sub-agents inheriting via the snapshot still
-      # get the surrounding tool set but never the +sub_agent+ tool
-      # itself. See {Configurator#allow_sub_agent}.
-      if configurator.sub_agent_request
-        if @tools.any?(Tool::SubAgent)
-          raise 'Tool::SubAgent must not be added via c.add_tool when c.allow_sub_agent ' \
-                'is used; Agent auto-registers it from the Configurator request.'
-        end
-
-        sub_tool = Tool::SubAgent.new(self, max_steps: configurator.sub_agent_request.max_steps)
-        @tools << sub_tool
-        @chat.with_tool(sub_tool.to_ruby_llm_tool)
-      end
-
-      # Bind sweep — each extension gets its chance to install
-      # per-agent state (dynamic tools via #internal_add_tool,
-      # per-agent close hooks via #on_close, etc.) now that the
-      # chat is fully wired. See IDEAS.md §"Extension protocol
-      # design" for what #configure vs #bind are each for.
-      @extensions.each { |ext| ext.bind(self) }
-
-      # Fallback cleanup: if the host forgets to call #close, the
-      # at_exit hook fires it on process exit. Idempotent, so an
-      # explicit close earlier makes this a no-op. The closure
-      # captures self, which keeps the agent reachable until
-      # process exit — fine for the handful of agents a typical
-      # host creates; if pikuri grows a long-running host that
-      # constructs many short-lived agents, switch to a single
-      # process-global registry that close-then-removes.
-      at_exit { close }
     end
 
     # @return [RubyLLM::Chat] underlying chat; the extension seam
@@ -474,19 +434,30 @@ module Pikuri
     #   agent was constructed with — same model id / provider /
     #   assume-model-exists flag passed to every +RubyLLM.chat+
     #   call originating from this agent (the main chat, the
-    #   synthesizer rescue, the sub-agent tool). Read by
-    #   {Tool::SubAgent} so spawned sub-agents reuse the same
-    #   transport.
+    #   synthesizer rescue, the +agent+ tool from
+    #   +pikuri-subagents+). Read by extensions that need to spawn
+    #   their own ruby_llm calls (e.g. MCP description synthesis,
+    #   sub-agent delegation).
     attr_reader :transport
 
     # @return [Array<Tool>] this agent's tool list in declaration
-    #   order. Snapshotted by {Tool::SubAgent} so spawned
-    #   sub-agents inherit the parent's tools (minus the
-    #   sub-agent tool itself, which {#allow_sub_agent} appends
-    #   to +@tools+ only after the snapshot has been taken —
-    #   recursion guard).
+    #   order. Read by extensions that filter against it (notably
+    #   the +agent+ tool from +pikuri-subagents+, which picks the
+    #   sub-agent's toolset from the parent's instances so any
+    #   already-bound workspace/confirmer wiring travels along).
+    #   Tools listed here are also the ones registered with
+    #   ruby_llm — the parent LLM can call any of them. Compare
+    #   with {#sub_agent_tools}.
     attr_reader :tools
 
+    # @return [Array<Tool>] tools registered via
+    #   {Configurator#add_sub_agent_tool}, in declaration order.
+    #   Invisible to the parent LLM (never sent to ruby_llm);
+    #   available only to sub-agents whose persona +tool_names+
+    #   match. See {Configurator}'s "Two tool pools" header for
+    #   the trifecta-defense rationale.
+    attr_reader :sub_agent_tools
+
     # @return [String] resolved model id from {#transport}.
     #   Convenience delegator for callers that don't need the
     #   full transport bundle.
@@ -496,12 +467,10 @@ module Pikuri
 
     # @return [String] system prompt actually sent to the chat —
     #   equal to the constructor's +system_prompt:+ argument plus
-    #   any snippets appended by extensions during
-    #   {Configurator#append_system_prompt} (Skills'
-    #   +<available_skills>+, MCP's +<available_mcps>+, ...).
-    #   {Tool::SubAgent} forwards this already-augmented value to
-    #   spawned sub-agents so they see the same advertisements
-    #   without re-running extension configure.
+    #   any snippets appended via {Configurator#append_system_prompt}
+    #   (extensions' +<available_skills>+ / +<available_mcps>+ /
+    #   +<available_agents>+, ...). Not inherited by sub-agents —
+    #   each persona owns its own system prompt verbatim.
     attr_reader :system_prompt
 
     # @return [ListenerList] the listener list attached to this
@@ -510,54 +479,55 @@ module Pikuri
 
     # @return [Control::StepLimit, nil] the step-budget control
     #   this agent was constructed with, or +nil+ when none.
-    #   Read by {Tool::SubAgent} so spawned sub-agents derive
-    #   their own.
     attr_reader :step_limit
 
     # @return [Control::Cancellable, nil] the cancellation
     #   control this agent was constructed with, or +nil+ when
-    #   none. Read by {Tool::SubAgent} so spawned sub-agents
-    #   share the same instance.
+    #   none. Read by extensions that propagate cancellation to
+    #   their own LLM calls (e.g. the +agent+ tool from
+    #   +pikuri-subagents+ shares it with spawned sub-agents so
+    #   one Ctrl+C stops the tree).
     attr_reader :cancellable
 
     # @return [Control::Interloper, nil] the mid-loop user-input
     #   control this agent was constructed with, or +nil+ when
-    #   none. Not propagated to sub-agents — see
-    #   {Control::Interloper#for_sub_agent}.
+    #   none.
     attr_reader :interloper
 
-    # @return [String] this agent's identifier — empty for the
-    #   main agent; for sub-agents, the hierarchical id assigned
-    #   by {Tool::SubAgent} (e.g. +"sub_agent 0"+,
-    #   +"sub_agent 1"+, +"sub_agent 0_0"+). Read by the
-    #   sub-agent tool so spawned sub-agents prefix their own
-    #   names with this one, and propagated to listeners via
-    #   {ListenerList#for_sub_agent} so name-aware ones can tag
-    #   output.
-    attr_reader :name
+    # @return [String] this agent's unique identifier — empty for
+    #   the main agent; for sub-agents, the persona-rooted id
+    #   assigned by the +agent+ tool from +pikuri-subagents+ (e.g.
+    #   +"researcher 0"+, +"researcher 1"+, +"file_miner 0"+).
+    #   Propagated to listeners via {ListenerList#for_sub_agent(id:)}
+    #   so id-aware ones can tag output. Distinct from the persona's
+    #   +name+ (the value the LLM picks in the +agent+ tool's
+    #   +name:+ argument).
+    attr_reader :id
 
     # @return [Boolean] +true+ when this agent opted into
     #   chunk-level streaming (see the +streaming:+ kwarg on
-    #   {#initialize}); +false+ otherwise. Read by
-    #   {Tool::SubAgent} so spawned sub-agents inherit the same
-    #   mode.
+    #   {#initialize}); +false+ otherwise. Read by extensions that
+    #   spawn their own ruby_llm calls (notably the +agent+ tool
+    #   from +pikuri-subagents+, so spawned sub-agents inherit the
+    #   same mode).
     attr_reader :streaming
 
     # @return [Array<Extension>] extension instances bound to this
-    #   agent — added via {Configurator#add_extension} (new — runs
-    #   +configure+ now and binds later) or {Configurator#inherit_extensions}
-    #   (sub-agent inheritance — skips +configure+, just binds), both
-    #   inside the +Agent.new+ block. Read by {Tool::SubAgent} so
-    #   spawned sub-agents inherit the parent's extension list and
-    #   re-bind them via the bind sweep.
+    #   agent — added via {Configurator#add_extension} inside the
+    #   +Agent.new+ block. Each instance's +configure+ runs during
+    #   the block and its +bind+ runs at the end of
+    #   {#initialize}, once per registration (so once per parent
+    #   agent in the typical setup; sub-agents do not inherit
+    #   extensions).
     attr_reader :extensions
 
     # @return [Integer, nil] context-window cap resolved by
     #   {ContextWindowDetector} at construction time. +nil+ when
     #   no source produced a value (custom local model with no
     #   override and no reachable llama.cpp +/props+). Read by
-    #   {Tool::SubAgent} so spawned sub-agents inherit the same
-    #   cap without re-probing.
+    #   extensions that spawn their own ruby_llm calls (notably
+    #   the +agent+ tool from +pikuri-subagents+, so spawned
+    #   sub-agents inherit the same cap without re-probing).
     attr_reader :context_window_cap
 
     # Final assistant message content for the most recent
@@ -610,13 +580,23 @@ module Pikuri
         if user_message.nil? || user_message.to_s.strip.empty?
 
       @synth_answer = nil
-      @listeners.emit(Event::UserTurn.new(content: user_message, mid_loop: false))
       @step_limit&.reset!
       @cancellable&.reset!
+      # Append the user turn, emit it, then run the memory dispatch — so
+      # any <memory-context> the dispatch injects lands as a :system
+      # message *after* the user turn it annotates (append-only at the
+      # tail; see {#dispatch_ext_on_user_message}). `ask` would bundle the
+      # user-message append with completion atomically, leaving no seam to
+      # inject between them, so the two halves run explicitly here:
+      # add_message + complete (the exact pair `ask` is sugar for). A raw
+      # String content matches the interloper drain path.
+      @chat.add_message(role: :user, content: user_message)
+      @listeners.emit(Event::UserTurn.new(content: user_message, mid_loop: false))
+      dispatch_ext_on_user_message(user_message)
       if @streaming
-        @chat.ask(user_message, &self.class.streaming_block(listeners: @listeners, cancellable: @cancellable))
+        @chat.complete(&self.class.streaming_block(listeners: @listeners, cancellable: @cancellable))
       else
-        @chat.ask(user_message)
+        @chat.complete
       end
       nil
     rescue Control::Cancellable::Cancelled
@@ -629,14 +609,14 @@ module Pikuri
 
       # Synth runs under this agent's identity but on a fresh
       # chat with a different system prompt, so it gets a
-      # distinct +_synthesizer+ suffix on the name — same +_+
+      # distinct +_synthesizer+ suffix on the id — same +_+
       # separator the sub-agent generator uses, so main becomes
-      # +"synthesizer"+ and a sub-agent +"sub_agent 0"+ becomes
-      # +"sub_agent 0_synthesizer"+. Any +TokenLog+ in the list
+      # +"synthesizer"+ and a sub-agent +"researcher 0"+ becomes
+      # +"researcher 0_synthesizer"+. Any +TokenLog+ in the list
       # tags the synth's prompt under that bracket so it's
       # obvious from the log which turns were the rescue rather
       # than the original loop.
-      synth_name = @name.empty? ? 'synthesizer' : "#{@name}_synthesizer"
+      synth_id = @id.empty? ? 'synthesizer' : "#{@id}_synthesizer"
       synth_chat = RubyLLM.chat(**@transport.to_h)
       # Defensive step limit on the synth: the synth has no
       # tools so it should never trip +before_tool_call+, but
@@ -647,7 +627,7 @@ module Pikuri
         chat: synth_chat,
         parent_messages: @chat.messages,
         user_message: user_message,
-        listeners: @listeners.for_sub_agent(name: synth_name),
+        listeners: @listeners.for_sub_agent(id: synth_id),
         step_limit: synth_step_limit,
         cancellable: @cancellable,
         streaming: @streaming
@@ -670,6 +650,10 @@ module Pikuri
       return if @closed
 
       @closed = true
+      # Drop out of the process-global registry first: a deliberate
+      # close means this agent no longer needs the at-exit fallback,
+      # and removing the reference lets it be garbage-collected.
+      Pikuri::Finalizers.unregister(self)
       @on_close_handlers.reverse_each do |handler|
         handler.call
       rescue StandardError => e
@@ -706,9 +690,10 @@ module Pikuri
     # +Pikuri::Tool+ entirely."
     #
     # The added tool does NOT enter +@tools+, only +@chat+'s tool
-    # list. {Tool::SubAgent} therefore cannot snapshot it (which is
-    # the whole point — activation is strictly per-agent, see
-    # IDEAS.md §"Per-agent activation, no propagation").
+    # list. Sub-agents (the +agent+ tool from +pikuri-subagents+)
+    # therefore cannot snapshot it — which is the whole point:
+    # activation is strictly per-agent, see IDEAS.md §"Per-agent
+    # activation, no propagation".
     #
     # @param ruby_llm_tool [Class] subclass of +RubyLLM::Tool+
     # @return [void]
@@ -721,11 +706,119 @@ module Pikuri
     #
     # @example
     #   agent.to_s
-    #   # => "Agent(model=qwen3-35b, tools=4, listeners=[Terminal])"
+    #   # => "Agent(id=, model=qwen3-35b, tools=4, listeners=[Terminal])"
     #
     # @return [String]
     def to_s
-      "Agent(model=#{model}, tools=#{@tools.size}, listeners=#{@listeners})"
+      "Agent(id=#{@id}, model=#{model}, tools=#{@tools.size}, listeners=#{@listeners})"
+    end
+
+    private
+
+    # The failure-prone build phase, split out of {#initialize} so the
+    # constructor can wrap it in a rescue and self-heal. Funnels the
+    # +Agent.new+ block through a single {Configurator} — tools,
+    # listeners, system-prompt snippets, extensions, and +on_close+
+    # handlers — then wires the chat and runs the extension +bind+
+    # sweep. The Configurator's +on_close_sink:+ is +@on_close_handlers+
+    # itself, so a handler an extension arms via +c.on_close+ is live on
+    # the agent the instant it's registered — that's what lets the
+    # constructor's rescue close a half-built agent.
+    #
+    # @return [void]
+    def run_configure
+      configurator = Configurator.new(
+        transport: @transport,
+        system_prompt_base: @system_prompt,
+        id: @id,
+        streaming: @streaming,
+        step_limit: @step_limit,
+        cancellable: @cancellable,
+        interloper: @interloper,
+        on_close_sink: @on_close_handlers
+      )
+
+      @block&.call(configurator)
+
+      @tools = configurator.tools.dup
+      @sub_agent_tools = configurator.sub_agent_tools.dup
+      @listeners = ListenerList.new(configurator.listeners)
+      configurator.system_prompt_additions.each do |snippet|
+        @system_prompt = "#{@system_prompt}\n\n#{snippet}"
+      end
+      @extensions = configurator.extensions.dup
+
+      @chat = RubyLLM.chat(**@transport.to_h)
+      @chat.with_instructions(@system_prompt)
+      @tools.each { |t| @chat.with_tool(t.to_ruby_llm_tool) }
+
+      @context_window_cap = ContextWindowDetector.new(
+        override: @context_window,
+        ruby_llm_reported: @chat.model.context_window,
+        llama_probe_url: @llama_probe_url,
+        model_id: @chat.model.id
+      ).detect
+
+      self.class.wire_chat(
+        @chat,
+        listeners: @listeners,
+        step_limit: @step_limit,
+        cancellable: @cancellable,
+        interloper: @interloper,
+        on_user_message: method(:dispatch_ext_on_user_message)
+      )
+
+      # One-shot context-window cap: lets every listener that
+      # cares (notably TokenLog) pick the value off the stream
+      # before any Tokens event arrives.
+      @listeners.emit(Event::ContextCap.new(cap: @context_window_cap))
+
+      # Bind sweep — each extension gets its chance to install
+      # per-agent state (dynamic tools via #internal_add_tool,
+      # per-agent close hooks via #on_close, etc.) now that the
+      # chat is fully wired. See IDEAS.md §"Extension protocol
+      # design" for what #configure vs #bind are each for.
+      @extensions.each { |ext| ext.bind(self) }
+    end
+
+    # Fire the per-turn {Extension#on_user_message} hook on every
+    # extension that defines it, appending any returned
+    # +<memory-context>+ block to the chat as a +role: :system+
+    # message right after the user turn it annotates (callers append
+    # the +:user+ message first; this runs last). The system role is
+    # load-bearing — it tags the block as recalled reference (not new
+    # input) and keeps it excludable from a later extraction pass.
+    # See {Extension#on_user_message}.
+    #
+    # Each injected block also emits an {Event::SystemInjected} at
+    # this site, so the listener stream mirrors the log growth (the
+    # Terminal renders it; otherwise an injection would be invisible
+    # except as a downstream echo in the assistant's reasoning).
+    #
+    # Private and the single place the chat log grows by a memory
+    # block — keeps "what mutates the log, when" one grep in this
+    # file. Fired from {#run_loop} (initial turn) and, via the
+    # +on_user_message:+ proc threaded into {.wire_chat}, from
+    # {.drain_interloper} (mid-loop interlopers). Called on every
+    # extension unconditionally — same as {Extension#configure} /
+    # {Extension#bind}: the hook is part of the protocol and the
+    # {Extension} module supplies a no-op default, so any extension
+    # that includes the module responds. An extension is "opted out"
+    # by leaving the default in place (it returns +nil+, injecting
+    # nothing), not by omitting the method.
+    #
+    # @param content [String] the incoming user message
+    # @return [void]
+    def dispatch_ext_on_user_message(content)
+      @extensions.each do |ext|
+        message = ext.on_user_message(self, content)
+        next unless message.is_a?(String) && !message.strip.empty?
+
+        block = message.strip
+        @chat.add_message(role: :system, content: block)
+        @listeners.emit(Event::SystemInjected.new(content: block))
+      end
+      nil
     end
   end
 end