pikuri-core 0.0.7 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b034cfd9a32f43694e474444155ea4e18c0c728449f50f33755a789b4879ab6
-  data.tar.gz: 0fdff7d50e07f52f9063b240db87e67d8bb93ac85a09cbb56b3caace3232478c
+  metadata.gz: f2703004f3ce0c935f4ee932493db6231109f4ecde7bcfe0ec1481dfecc21001
+  data.tar.gz: adf19fd1af6df3aad4ef58d10d5845ce38932566ba5c9d33a7f45791c34287a3
 SHA512:
-  metadata.gz: 25ac79d6951ce4574d6400742bec3603306c72ca334786a13c34c3a3a5ab48de2735be5b5f51b1b6a25aa647c8f3d36da2f53d3bc97072ea276528464d6d4e16
-  data.tar.gz: 60100a4ab334e08066b29057d0eea4003a6c0db67947cf17a81484308dcd305ef08869b740965d6e81be246fd3ca964ad5afb2ca668bc101eaa867ed63c1bc02
+  metadata.gz: e7475e59d9dc941226a77c875a7236c6649f678e933938bc7d9bbe18a76cbb1b8b492c3d471d94db1e68dc242f2030e25a48c236b3690cb8191a77d403467bae
+  data.tar.gz: 28345b25378c2ae0dabe37d58b8cc592d2f45c4a634d57f134ecd0c15bad7b157c912aa09f9f93dab46a8e78e035400faf69f0e6a2e4222874ffe88e1c73503f

data/README.md

@@ -70,7 +70,7 @@ handling, and cancellation.
 
 ## Further reading
 
-- **Narrative walkthrough:** [chapter 1 of the pikuri guide](../docs/guide/01-chat.md)
+- **Narrative walkthrough:** [the first-conversation chapter of the pikuri guide](../book/chat.md)
   — install llama.cpp, start the server, run `pikuri-chat`, the
   agentic loop, the four bundled tools, and search-provider
   privacy postures.

data/lib/pikuri/agent/chat_transport.rb

@@ -2,106 +2,86 @@
 
 module Pikuri
   class Agent
-    # Everything that has to travel together for a chat to resolve to
-    # the same model *on the same server* on every construction: the
-    # model id, the provider hint, the registry-bypass flag, and — when
-    # the model lives on a server other than the process-global
-    # +RubyLLM.config+ default — that server's base URL and API key.
-    #
-    # Bundling them is structural protection against a recurring bug
-    # class — every forwarding site (the synthesizer rescue in
-    # {Agent#run_loop}, the +agent+ tool from +pikuri-subagents+
-    # spawning a sub-agent, a mid-conversation model switch) used to
-    # pass the resolution fields individually, and dropping one routed
-    # the chat to a different server or raised
-    # +RubyLLM::ModelNotFoundError+ on the unknown model id. With a
-    # single value object the call site can't silently miss a field.
+    # Everything that must travel together for a chat to resolve to the same
+    # model *on the same server* on every construction: model id, provider
+    # hint, registry-bypass flag, and — when the model lives off the
+    # process-global +RubyLLM.config+ default — that server's base URL and API
+    # key. One value object so a forwarding site (the synthesizer, a sub-agent
+    # spawn, a mid-conversation switch) can't silently drop a field and route
+    # the chat to the wrong server or raise +RubyLLM::ModelNotFoundError+.
     #
     # == Why +api_base+ / +api_key+ live here
     #
-    # +RubyLLM::Chat#with_model+ swaps only the model/provider against
-    # the chat's *existing* connection config, so switching to a model
-    # on a different server (a small local llama.cpp vs a big cloud
-    # model) needs the connection to travel with the model — otherwise
-    # the new model id is sent to the old server's URL with the old
-    # key. {Agent} maps these two generic fields onto the provider's
-    # ruby_llm config slots (+#{provider}_api_base+ /
-    # +#{provider}_api_key+) via a per-chat +RubyLLM::Context+; both are
-    # +nil+ for a transport that rides the process-global config.
+    # +RubyLLM::Chat#with_model+ swaps only model/provider against the chat's
+    # *existing* connection, so switching to a model on a different server
+    # needs the connection to travel with the model — else the new id is sent
+    # to the old server's URL with the old key. {Agent} maps these two generic
+    # fields onto the provider's config slots (+#{provider}_api_base+ /
+    # +#{provider}_api_key+) via a per-chat +RubyLLM::Context+; both +nil+ for a
+    # transport riding the global config.
     #
-    # Pure data carrier: no +RubyLLM+ references here, so the seam stays
-    # in {Agent}, +bin/pikuri-chat+, and {Tool}.
+    # Pure data carrier — no +RubyLLM+ references here, so the seam stays in
+    # {Agent}, +bin/pikuri-chat+, and {Tool}.
     #
     # @!attribute [r] model
-    #   @return [String, nil] LLM identifier; +nil+ defers to
-    #     +RubyLLM.config.default_model+ at {Agent} construction time
+    #   @return [String, nil] LLM id; +nil+ defers to
+    #     +RubyLLM.config.default_model+ at {Agent} construction.
     # @!attribute [r] provider
-    #   @return [Symbol, nil] forwarded to +RubyLLM.chat+. Required
-    #     together with +assume_model_exists+ when pointing at a local
-    #     OpenAI-compatible server (llama.cpp, gpustack, ...) whose model
-    #     ids are not in ruby_llm's bundled registry; required whenever
-    #     +api_base+ / +api_key+ is set (it names the config slots).
+    #   @return [Symbol, nil] forwarded to +RubyLLM.chat+. Required with
+    #     +assume_model_exists+ for a local OpenAI-compatible server whose ids
+    #     aren't in ruby_llm's registry, and whenever +api_base+/+api_key+ is
+    #     set (it names the config slots).
     # @!attribute [r] assume_model_exists
-    #   @return [Boolean] forwarded to +RubyLLM.chat+; +true+ skips
-    #     ruby_llm's registry lookup and trusts the supplied model id.
-    #     Requires +provider+.
+    #   @return [Boolean] forwarded to +RubyLLM.chat+; +true+ skips the registry
+    #     lookup and trusts the model id. Requires +provider+.
     # @!attribute [r] api_base
-    #   @return [String, nil] connection base URL for this model's
-    #     server (e.g. +http://localhost:8080/v1+). +nil+ rides the
-    #     process-global +RubyLLM.config+ base. Mapped to the provider's
-    #     +#{provider}_api_base+ slot by {Agent}.
+    #   @return [String, nil] this server's base URL (e.g.
+    #     +http://localhost:8080/v1+); +nil+ rides the global config. Mapped to
+    #     +#{provider}_api_base+ by {Agent}.
     # @!attribute [r] api_key
-    #   @return [String, nil] API key for this model's server. +nil+
-    #     rides the process-global config key. Mapped to the provider's
-    #     +#{provider}_api_key+ slot by {Agent}. Redacted in {#inspect}
-    #     so it never leaks into a log line or backtrace.
+    #   @return [String, nil] API key for this server; +nil+ rides the global
+    #     config. Mapped to +#{provider}_api_key+ by {Agent}. Redacted in
+    #     {#inspect}.
     # @!attribute [r] context_window
     #   @return [Integer, nil] explicit context-window cap for this
-    #     model on this server, or +nil+ to defer to
-    #     {ContextWindowDetector}'s probe. Travels with the model
-    #     because the cap *is* a per-model-per-server property: a
-    #     {Ctrl+P}-style switch to a different transport must carry its
-    #     own cap, not inherit the previous model's. Never sent to
-    #     ruby_llm (it is neither a {#chat_kwargs} entry nor a
-    #     connection slot) — pure pikuri metadata read by
-    #     {Agent#detect_and_emit_context_cap!}. The cap-inheritance
-    #     channel too: the +agent+ tool from +pikuri-subagents+ and the
-    #     synthesizer hand a spawned agent +parent.transport.with(
-    #     context_window: parent.context_window_cap)+ so the parent's
-    #     *resolved* cap (explicit or probed) rides along without a
+    #     model-on-server, or +nil+ to defer to {ContextWindowDetector}. Travels
+    #     with the model because the cap *is* per-model-per-server. Never sent to
+    #     ruby_llm — pure pikuri metadata read by
+    #     {Agent#detect_and_emit_context_cap!}, and the cap-inheritance channel:
+    #     a spawned agent gets +parent.transport.with(context_window:
+    #     parent.context_window_cap)+ so the resolved cap rides along without a
     #     re-probe.
-    class ChatTransport < Data.define(:model, :provider, :assume_model_exists, :api_base, :api_key, :context_window)
-      # Build an +:openai+-provider transport for an OpenAI-compatible
-      # server (a local llama.cpp, a cloud endpoint, ...), carrying that
-      # server's connection so the agent rides a per-chat
-      # +RubyLLM::Context+ instead of the process-global +RubyLLM.config+.
-      # This is the host-boot factory the +bin/pikuri-*+ demos use in
-      # place of +RubyLLM.configure+ — one isolated connection per agent,
-      # so several agents pointed at different servers (and different
-      # keys) don't stomp a shared global.
+    # @!attribute [r] faraday_adapter
+    #   @return [Class, Symbol, nil] a custom Faraday adapter to install on this
+    #     agent's per-chat +RubyLLM::Context+ (via +config.faraday_adapter=+),
+    #     or +nil+ for ruby_llm's default (+:net_http+). A generic HTTP seam —
+    #     inject a VCR / logging / *scripted-fake* adapter without touching the
+    #     global +RubyLLM.config+. Its worked use is
+    #     {Pikuri::Testing.fake_transport}, which bakes an anonymous scripted
+    #     adapter here so the real ruby_llm loop runs against canned HTTP. Only
+    #     honoured on the connection-override path ({#connection_overrides?}),
+    #     which any adapter-carrying transport is on (it also sets +api_base+).
+    class ChatTransport < Data.define(:model, :provider, :assume_model_exists, :api_base, :api_key,
+                                      :context_window, :faraday_adapter)
+      # Build an +:openai+-provider transport for an OpenAI-compatible server
+      # (local llama.cpp, cloud endpoint, ...), carrying its connection so the
+      # agent rides a per-chat +RubyLLM::Context+ instead of the global config.
+      # The +bin/pikuri-*+ host-boot factory in place of +RubyLLM.configure+ —
+      # one isolated connection per agent.
       #
-      # +server+ is the bare server origin; a trailing +/v1+ (the
-      # OpenAI-compatible suffix ruby_llm appends to reach
-      # +/v1/chat/completions+) is stripped and re-appended exactly once,
-      # so +https://api.x.ai+, +https://api.x.ai/v1+, and
-      # +https://api.x.ai/v1/+ all normalize to the same +.../v1+ base.
-      # Without this, a +server+ value that already ended in +/v1+ would
-      # double to +/v1/v1+ and every request would 404.
+      # A trailing +/v1+ on +server+ is stripped and re-appended exactly once,
+      # so +https://api.x.ai+, +.../v1+, and +.../v1/+ all normalize to the same
+      # +.../v1+ base — without which a +/v1+-terminated value would double to
+      # +/v1/v1+ and 404.
       #
-      # @param server [String] server origin, with or without a trailing
-      #   +/v1+, e.g. +"http://localhost:8080"+ or +"https://api.x.ai/v1"+
+      # @param server [String] server origin, with or without a trailing +/v1+
       # @param model [String] model id served there, trusted verbatim
-      #   (+assume_model_exists+ is +true+, so it need not appear in
-      #   ruby_llm's bundled registry)
-      # @param api_key [String] API key for the server; the conventional
-      #   +"not-needed"+ placeholder for a keyless local server
-      # @param context_window [Integer, nil] explicit context-window cap
-      #   for this model, or +nil+ to defer to {ContextWindowDetector}'s
-      #   +/props+ probe (the right default for a local llama.cpp, which
-      #   reports its launched +n_ctx+; the right *override* for a cloud
-      #   server the probe can't reach, e.g. a 2M-window model on x.ai)
-      # @return [ChatTransport] a transport whose +api_base+ is the
-      #   normalized +.../v1+ URL and whose +api_key+ is +api_key+
+      # @param api_key [String] API key; the +"not-needed"+ placeholder for a
+      #   keyless local server
+      # @param context_window [Integer, nil] explicit cap, or +nil+ to defer to
+      #   {ContextWindowDetector}'s +/props+ probe (right for local llama.cpp;
+      #   an override for a cloud server the probe can't reach)
+      # @return [ChatTransport]
       def self.from_openai_server(server:, model:, api_key: 'not-needed', context_window: nil)
         base = server.to_s.strip.chomp('/').delete_suffix('/v1')
         new(
@@ -120,11 +100,12 @@ module Pikuri
       # @param api_base [String, nil]
       # @param api_key [String, nil]
       # @param context_window [Integer, nil]
+      # @param faraday_adapter [Class, Symbol, nil]
       # @raise [ArgumentError] if +api_base+ or +api_key+ is set without
       #   a +provider+ (the provider names the config slots the
       #   connection overrides map onto)
       def initialize(model:, provider: nil, assume_model_exists: false,
-                     api_base: nil, api_key: nil, context_window: nil)
+                     api_base: nil, api_key: nil, context_window: nil, faraday_adapter: nil)
         if (api_base || api_key) && provider.nil?
           raise ArgumentError, "api_base/api_key require a provider, got #{provider.inspect}"
         end
@@ -132,10 +113,9 @@ module Pikuri
         super
       end
 
-      # The model-resolution kwargs to spread into +RubyLLM.chat+ /
-      # +RubyLLM::Context#chat+. Excludes the connection fields — those
-      # configure the +Context+ the chat is built from, not the +chat+
-      # call itself.
+      # Model-resolution kwargs to spread into +RubyLLM.chat+ /
+      # +RubyLLM::Context#chat+. Excludes the connection fields (those configure
+      # the +Context+, not the +chat+ call).
       #
       # @return [Hash{Symbol => String, Symbol, Boolean, nil}]
       def chat_kwargs
@@ -150,15 +130,15 @@ module Pikuri
         !api_base.nil? || !api_key.nil?
       end
 
-      # Default +Data#inspect+ would print +api_key+ verbatim, leaking
-      # the secret into any log line, +to_s+ interpolation, or backtrace
-      # that touches the transport. Redact it.
+      # Default +Data#inspect+ would print +api_key+ verbatim into any log line
+      # or backtrace. Redact it.
       #
       # @return [String]
       def inspect
         "#<#{self.class} model=#{model.inspect} provider=#{provider.inspect} " \
           "assume_model_exists=#{assume_model_exists} api_base=#{api_base.inspect} " \
-          "api_key=#{api_key.nil? ? 'nil' : '[REDACTED]'} context_window=#{context_window.inspect}>"
+          "api_key=#{api_key.nil? ? 'nil' : '[REDACTED]'} context_window=#{context_window.inspect} " \
+          "faraday_adapter=#{faraday_adapter.inspect}>"
       end
       alias to_s inspect
     end

data/lib/pikuri/agent/configurator.rb

@@ -2,64 +2,40 @@
 
 module Pikuri
   class Agent
-    # Build-time collector yielded into the +Pikuri::Agent.new+ block.
-    # Hosts and {Extension} implementations call its methods to declare
-    # additional tools, listeners, system-prompt snippets, +on_close+
-    # handlers, extension instances, and persona-flavored sub-agents;
-    # {Agent#initialize} drains the collected state into the agent's
-    # final wiring before returning.
-    #
-    # == Why this exists
-    #
-    # Splits "configure the agent" from "the agent's runtime state".
-    # Hosts can write a block that reads cleanly:
+    # Build-time collector yielded into the +Pikuri::Agent.new+ block. Hosts
+    # and {Extension}s call its methods to declare tools, listeners,
+    # +on_close+ handlers, and extension instances; {Agent#initialize} drains
+    # the collected state into the agent's wiring before returning, then
+    # discards the Configurator (it carries no runtime state). System-prompt
+    # contributions are *not* collected here — the Agent pulls them from each
+    # extension's {Extension#system_prompt_snippets} at assembly time.
     #
     #   Pikuri::Agent.new(transport: ..., system_prompt: ...) do |c|
     #     c.add_listener Pikuri::Agent::Listener::Terminal.new
     #     c.add_tool     Pikuri::Tool::WebSearch.build
-    #     c.add_tool     Pikuri::Tool::WEB_SCRAPE
-    #     c.add_tool     Pikuri::Tool::FETCH
-    #     c.add_extension Pikuri::Skill::Extension.new(catalog: catalog)
+    #     c.add_extension Pikuri::Skill::Extension.new(catalog: catalog, root: project_root)
     #   end
     #
-    # == Two tool pools: regular vs. sub-agent-only
-    #
-    # {#add_tool} registers a tool the parent agent can call: it lands
-    # in {#tools} and gets handed to ruby_llm via +chat.with_tool+.
-    # {#add_sub_agent_tool} registers a tool the parent *cannot* call
-    # — it lands in {#sub_agent_tools} and is never sent to ruby_llm
-    # for the parent, but is visible to {Pikuri::SubAgent::Extension}'s
-    # persona-tool-name resolution. The use case is the lethal-trifecta
-    # defense in {Pikuri::Code::Bash::Sandbox} terms: keep network tools
-    # (+web_search+ / +web_scrape+ / +fetch+) off the parent so a prompt-
-    # injected file read cannot egress through the parent's own tools,
-    # while still letting the +researcher+ persona reach them via the
-    # +agent+ delegation tool. See SECURITY.md §"Defense: capability
-    # boundaries via sub-agents".
+    # Extensions implement +configure(c)+ against this same type, so
+    # block-users and extensions share one API.
     #
-    # Extensions implement their +configure(c)+ hook against the same
-    # type, so the call sites for "block users add stuff" and
-    # "extensions add stuff" share one API.
-    #
-    # == Lifecycle
+    # == Two tool pools: regular vs. sub-agent-only
     #
-    # One +Configurator+ per +Agent.new+ invocation. The Configurator
-    # is constructed inside {Agent#initialize}, yielded to the block
-    # (if any), then its collected state is drained by the Agent body.
-    # The Configurator instance is discarded once +Agent.new+ returns
-    # — it carries no runtime state.
+    # {#add_tool} registers a tool the parent agent can call (lands in {#tools},
+    # handed to ruby_llm). {#add_sub_agent_tool} registers one the parent
+    # *cannot* call (lands in {#sub_agent_tools}, never sent to ruby_llm for the
+    # parent) but which {Pikuri::SubAgent::Extension}'s persona-tool-name
+    # resolution can reach. The use case is the lethal-trifecta defense: keep
+    # network tools (+web_search+ / +web_scrape+ / +fetch+) off the parent so a
+    # prompt-injected file read can't egress through it, while the +researcher+
+    # persona still reaches them via the +agent+ tool. See SECURITY.md.
     class Configurator
-      # @return [Agent::ChatTransport] same transport the Agent will
-      #   use. Extensions read this to wire helpers consistently
-      #   (e.g. an MCP description-synthesizer that calls the same
-      #   model the agent itself uses).
+      # @return [Agent::ChatTransport] same transport the Agent will use, so an
+      #   extension can wire helpers against the same model.
       attr_reader :transport
 
-      # @return [String] the +system_prompt:+ kwarg passed to
-      #   {Agent#initialize}, untouched. Extensions append to the
-      #   prompt via {#append_system_prompt} rather than mutating
-      #   this; the attribute exists so a peek at the base is
-      #   available for diagnostics.
+      # @return [String] the +system_prompt:+ kwarg, untouched — the base the
+      #   Agent prepends to the pulled {Extension#system_prompt_snippets}.
       attr_reader :system_prompt_base
 
       # @return [String] this agent's unique identifier; empty for the
@@ -74,28 +50,22 @@ module Pikuri
       #   to the Agent ctor, or +nil+.
       attr_reader :step_limit
 
-      # @return [Control::Cancellable, nil] cancellation control
-      #   passed to the Agent ctor, or +nil+. Extensions that run
-      #   sub-LLM calls during +configure+ (e.g. an MCP description
-      #   synthesizer) share this so a user cancel during boot
-      #   propagates correctly.
+      # @return [Control::Cancellable, nil] cancellation control, or +nil+.
+      #   Extensions running sub-LLM calls in +configure+ share it so a user
+      #   cancel during boot propagates.
       attr_reader :cancellable
 
       # @return [Control::Interloper, nil] mid-loop user-input queue
       #   passed to the Agent ctor, or +nil+.
       attr_reader :interloper
 
-      # @return [Array<Tool>] tools added via {#add_tool}, in
-      #   declaration order. Drained by {Agent#initialize} and
-      #   registered with ruby_llm so the parent LLM can call them.
+      # @return [Array<Tool>] tools added via {#add_tool}, in declaration order;
+      #   drained by {Agent#initialize} and registered with ruby_llm.
       attr_reader :tools
 
-      # @return [Array<Tool>] tools added via {#add_sub_agent_tool},
-      #   in declaration order. Drained by {Agent#initialize} but
-      #   *not* registered with ruby_llm — invisible to the parent
-      #   LLM, available only to sub-agents through
-      #   {Pikuri::SubAgent::Extension}'s persona-tool-name
-      #   resolution. See the class header.
+      # @return [Array<Tool>] tools added via {#add_sub_agent_tool}, in
+      #   declaration order; drained but *not* registered with ruby_llm —
+      #   available only to sub-agents (see the class header).
       attr_reader :sub_agent_tools
 
       # @return [Array<Listener::Base>] listeners added via
@@ -103,21 +73,14 @@ module Pikuri
       #   {Agent#initialize}.
       attr_reader :listeners
 
-      # @return [Array<String>] system-prompt snippets added via
-      #   {#append_system_prompt}, in declaration order. Joined with
-      #   double-newline separators between the base prompt and each
-      #   snippet by {Agent#initialize}.
-      attr_reader :system_prompt_additions
-
       # @return [Array<Proc>] +on_close+ handlers added via
       #   {#on_close}, in declaration order. Fired by {Agent#close}
       #   in LIFO order with per-handler rescue.
       attr_reader :on_close_handlers
 
       # @return [Array<#configure>] extension instances added via
-      #   {#add_extension}, in declaration order. The Agent ctor
-      #   walks this list after wiring is complete and calls +bind+
-      #   on each with the agent's {ExtensionContext}.
+      #   {#add_extension}, in declaration order. The Agent calls +bind+ on
+      #   each after wiring is complete.
       attr_reader :extensions
 
       # @param transport [Agent::ChatTransport]
@@ -127,15 +90,14 @@ module Pikuri
       # @param step_limit [Control::StepLimit, nil]
       # @param cancellable [Control::Cancellable, nil]
       # @param interloper [Control::Interloper, nil]
-      # @param on_close_sink [Array<Proc>, nil] array that {#on_close}
-      #   appends to. {Agent#initialize} passes its own live
-      #   +@on_close_handlers+ so a handler an extension arms via
-      #   +c.on_close+ is reachable the instant it's registered — which
-      #   is what lets the constructor close a half-built agent if a
-      #   later extension's +configure+ raises. Defaults to a fresh
-      #   array for standalone use (e.g. specs).
+      # @param on_close_sink [Array<Proc>, nil] array {#on_close} appends to.
+      #   {Agent#initialize} passes its live +@on_close_handlers+ so a handler
+      #   armed via +c.on_close+ is reachable instantly — what lets the
+      #   constructor close a half-built agent if a later +configure+ raises.
+      #   Defaults to a fresh array (standalone/spec use).
       def initialize(transport:, system_prompt_base:, id:, streaming:,
-                     step_limit:, cancellable:, interloper:, on_close_sink: nil)
+                     step_limit:, cancellable:, interloper:,
+                     on_close_sink: nil)
         @transport = transport
         @system_prompt_base = system_prompt_base
         @id = id
@@ -147,7 +109,6 @@ module Pikuri
         @tools = []
         @sub_agent_tools = []
         @listeners = []
-        @system_prompt_additions = []
         @on_close_handlers = on_close_sink || []
         @extensions = []
       end
@@ -202,30 +163,10 @@ module Pikuri
         nil
       end
 
-      # Append a snippet to the system prompt. Snippets are joined
-      # to the base prompt with double-newline separators.
-      #
-      # Used by extensions to register +<available_skills>+,
-      # +<available_mcps>+, and similar advertisement blocks. Block
-      # users typically pass the full system prompt via the ctor's
-      # +system_prompt:+ kwarg instead.
-      #
-      # @param snippet [String]
-      # @return [void]
-      def append_system_prompt(snippet)
-        @system_prompt_additions << snippet
-        nil
-      end
-
-      # Register an extension. The extension's +configure(self)+ is
-      # called immediately so source-order matches execution-order.
-      # The instance is also retained for the +bind(ctx)+ sweep
-      # that runs at the end of {Agent#initialize}.
-      #
-      # Extensions must implement both +configure+ and +bind+. The
-      # easy way is to +include Pikuri::Agent::Extension+ — that
-      # mixes in empty defaults for both, so an extension overrides
-      # only what it cares about and leaves the other as a no-op.
+      # Register an extension: its +configure(self)+ runs immediately (so
+      # source order matches execution order), and the instance is retained for
+      # the +bind(ctx)+ sweep at the end of {Agent#initialize}. Both hooks are
+      # required — +include Pikuri::Agent::Extension+ for no-op defaults.
       #
       # @param extension [Extension, #configure, #bind] extension instance
       # @return [void]
@@ -235,9 +176,8 @@ module Pikuri
         nil
       end
 
-      # Register a handler called by {Agent#close}. Handlers fire in
-      # LIFO order, each inside its own +rescue+ — same semantics as
-      # +ensure+-block cleanup discipline.
+      # Register a handler called by {Agent#close} (LIFO, each inside its own
+      # +rescue+).
       #
       # @yield called with no arguments at close time
       # @return [void]