pikuri-core 0.0.7 → 0.1.0

data/lib/pikuri/agent/event.rb

@@ -2,231 +2,166 @@
 
 module Pikuri
   class Agent
-    # Sealed value-object hierarchy describing a single event in the
-    # +Agent+'s normalized stream. Every listener consumes these through
-    # one {Listener::Base#on_event} entry point and pattern-matches on
-    # the variant.
+    # Sealed value-object hierarchy for the +Agent+'s normalized event
+    # stream. Listeners consume every variant through one
+    # {Listener::Base#on_event} and +case+-match on it.
     #
-    # Each variant is a +Data.define+ with the minimal fields it needs;
-    # value equality and pattern-matching support come for free.
-    #
-    # == One stream, no side channels
-    #
-    # Provider-reported token usage rides as {Tokens}; the detected
-    # context-window cap rides as a one-shot {ContextCap} emitted by
-    # {Agent#initialize}; everything else maps to a turn-or-tool-call
-    # variant. Listeners override a single +on_event+ method and
-    # +case+-match on the variant they care about. The per-variant
-    # docs below name the emission site for each (which {Agent}
-    # callback wires it and what payload it carries).
-    #
-    # == Sealed for loop narration; gems add domain events
-    #
-    # "Sealed" applies to the *loop-narration* vocabulary: the
-    # variants below are the complete set, all emitted by {Agent},
-    # and new chat-loop observability belongs here, not in a gem.
-    # Gems may define their own *domain* events in their own
-    # namespace (e.g. +Pikuri::Tasks::ListChanged+) and emit them
-    # via {ExtensionContext#emit_event}; they ride the same stream.
-    # Listeners must no-op on variants they don't recognize —
-    # {Listener::Base#on_event}'s default plus +case+-fallthrough
-    # give that for free.
+    # "Sealed" scopes the *loop-narration* vocabulary: the variants below
+    # are the complete set, all emitted by {Agent}, and new chat-loop
+    # observability belongs here. Gems define their own *domain* events in
+    # their own namespace (e.g. +Pikuri::Tasks::ListChanged+) and emit
+    # them via {ExtensionContext#emit_event} onto the same stream;
+    # listeners must no-op on variants they don't recognize.
     module Event
-      # User's input for a turn (+mid_loop: false+, the default) or a
-      # host-supplied injection delivered while the loop is running
-      # (+mid_loop: true+, drained from {Control::Interloper}). The
-      # flag exists so listeners that treat the +UserTurn+ as a turn
-      # boundary can distinguish a fresh turn from an in-loop
-      # injection (additional context for the same turn, not a new
-      # one). Controls themselves no longer see this event — the
-      # +Agent+ pokes their +reset!+ / +tick!+ entry points directly
-      # at the right boundaries.
-      #
-      # Emitted in two places: by {Agent#run_loop} at the start of
-      # each turn (with +mid_loop: false+), and by {Agent}'s
-      # +after_tool_result+ wiring when a queued
-      # {Control::Interloper} item drains into the chat history
-      # (with +mid_loop: true+).
+      # User input for a turn (+mid_loop: false+, the default) or a host
+      # injection delivered mid-loop (+mid_loop: true+, drained from
+      # {Control::Interloper}). The flag lets a listener treating
+      # +UserTurn+ as a turn boundary tell a fresh turn from an in-loop
+      # injection. Emitted by {Agent#run_loop} at turn start, and when an
+      # interloper item drains in after a tool batch.
       UserTurn = Data.define(:content, :mid_loop) do
         # @param content [String] user-supplied text
-        # @param mid_loop [Boolean] +false+ for a turn-starting message
-        #   (the default); +true+ when drained from
-        #   {Control::Interloper}
+        # @param mid_loop [Boolean] +true+ when drained from
+        #   {Control::Interloper}; default +false+
         def initialize(content:, mid_loop: false)
           super
         end
       end
 
-      # A system-role block an {Extension#on_user_message} hook
-      # injected into the chat log — recalled reference (memory
-      # context, retrieved snippets) tagged +role: :system+ so the
-      # model reads it as background, not new user input. Carries
-      # the injected text verbatim.
+      # A reference block injected into the chat log — recalled memory, a
+      # host-loaded skill, a path-activation promotion, retrieved snippets.
+      # Carries the block *unwrapped*, without the +<system-reminder>+
+      # envelope {Agent#append_reference_block} sends it under, so a listener
+      # renders what the host wrote rather than pikuri's framing.
       #
-      # Emitted by {Agent#dispatch_ext_on_user_message}, once per
-      # extension that returns a non-empty block, at the same site
-      # that grows the chat log — so the event stream stays a
-      # faithful mirror of what the model actually sees. Without it
-      # an injection is invisible: it never surfaces in the stream,
-      # only as a secondary echo in the assistant's later reasoning.
-      # {Listener::Terminal} renders it dim grey with a +⊕+ marker.
+      # Named for the *role it plays* (background reference, not new user
+      # input), not the wire role it lands under — which is +:user+, because a
+      # mid-conversation +:system+ message is unportable.
       SystemInjected = Data.define(:content)
 
-      # Assistant reasoning ("thinking") block, extracted from the
-      # +thinking.text+ field on a +RubyLLM::Message+ with role
-      # +:assistant+. Emitted by {Agent}'s +after_message+ wiring;
-      # empty +thinking.text+ is filtered at the dispatch site so
-      # listeners never see vacuous events.
+      # Assistant reasoning ("thinking") block, from +thinking.text+ on a
+      # +RubyLLM::Message+. Emitted by +after_message+; empty text is
+      # filtered at the dispatch site.
       Thinking = Data.define(:content)
 
-      # Assistant Markdown content, extracted from a +RubyLLM::Message+
-      # with role +:assistant+. Emitted by {Agent}'s +after_message+
-      # wiring; empty +content+ is filtered at the dispatch site
-      # (pure tool-call turns surface {Tokens} only, no +Assistant+).
+      # Assistant Markdown content, from a +RubyLLM::Message+. Emitted by
+      # +after_message+; empty content is filtered (pure tool-call turns
+      # surface {Tokens} only).
       Assistant = Data.define(:content)
 
-      # Streaming fragment of an assistant reasoning block, pulled
-      # off a +RubyLLM::Chunk+ during a streaming completion.
-      # Emitted by the per-chunk streaming block {Agent#run_loop}
-      # passes to +Chat#complete+ when the agent's +streaming:+
-      # flag is on; empty fragments are filtered at the dispatch
-      # site.
+      # Streaming fragment of a reasoning block, off a +RubyLLM::Chunk+
+      # when +streaming:+ is on. Emitted per-chunk by {Agent#run_loop};
+      # empty fragments filtered.
       #
-      # Preview-only, not authoritative: the {Thinking} event
-      # emitted from +after_message+ at the end of the round-trip
-      # is the final reasoning text. Providers may normalize
-      # whitespace, and Anthropic thinking blocks include a
-      # signature that never appears in deltas, so
-      # +concat(deltas) == final.content+ is not guaranteed.
-      #
-      # == Ordering
-      #
-      # Per round-trip: all {ThinkingDelta}s (and {AssistantDelta}s)
-      # for a round arrive before that round's {Thinking} /
-      # {Assistant} / {Tokens} bookend, because the streaming block
-      # fires synchronously inside +Chat#ask+'s SSE read and
-      # +after_message+ fires once the message is complete. Within
-      # the delta stream itself, ordering between {ThinkingDelta}
-      # and {AssistantDelta} is provider-dependent (in practice
-      # non-interleaved on Anthropic and OpenAI reasoning models,
-      # but pikuri does not enforce it).
+      # Preview-only: the {Thinking} from +after_message+ is
+      # authoritative. +concat(deltas) == final+ is not guaranteed
+      # (whitespace normalization, Anthropic signature blocks). All of a
+      # round's deltas arrive before that round's
+      # {Thinking}/{Assistant}/{Tokens} bookend; {ThinkingDelta} vs
+      # {AssistantDelta} interleave order is provider-dependent.
       ThinkingDelta = Data.define(:content)
 
-      # Streaming fragment of an assistant Markdown content block,
-      # pulled off a +RubyLLM::Chunk+ during a streaming
-      # completion. Emitted by the per-chunk streaming block
-      # {Agent#run_loop} passes to +Chat#complete+ when the
-      # agent's +streaming:+ flag is on; empty fragments are
-      # filtered at the dispatch site.
-      #
-      # Preview-only, same semantics as {ThinkingDelta}: the
-      # {Assistant} event emitted from +after_message+ at the end
-      # of the round-trip is the authoritative final text;
-      # listeners that need an exact concat of fragments should
-      # consume {Assistant} instead. Per-round-trip ordering is
-      # guaranteed; per-modality ordering within the delta stream
-      # is best-effort.
+      # Streaming fragment of assistant Markdown, off a +RubyLLM::Chunk+
+      # when +streaming:+ is on. Same preview-only semantics as
+      # {ThinkingDelta}; consume {Assistant} for the authoritative text.
       AssistantDelta = Data.define(:content)
 
-      # A tool invocation the LLM has requested but not yet observed.
-      # Arguments are the raw hash ruby_llm parsed from the model's
-      # +tool_calls+ JSON — no validation has run yet. Emitted by
-      # {Agent}'s +before_tool_call+ wiring.
+      # A tool the LLM requested but hasn't observed yet. +arguments+ is
+      # the raw hash ruby_llm parsed from the model's +tool_calls+ JSON —
+      # unvalidated. Emitted by +before_tool_call+.
       ToolCall = Data.define(:name, :arguments)
 
-      # The observation a tool produced, as returned by {Tool#run}.
-      # Recoverable failures arrive here as +"Error: ..."+ strings
-      # (per the pikuri error convention), not as exceptions.
-      # Emitted by {Agent}'s +after_tool_result+ wiring.
+      # The observation a tool produced ({Tool#run}'s return). Recoverable
+      # failures arrive as +"Error: ..."+ strings, not exceptions. Emitted
+      # by +after_tool_result+.
       ToolResult = Data.define(:content)
 
-      # Provider-reported token usage for a single assistant turn,
-      # copied off a +RubyLLM::Message+'s +tokens+ block. Emitted by
-      # {Agent}'s +after_message+ wiring on every assistant turn,
-      # including pure tool-call turns where {Assistant} would have
-      # been filtered for empty content (those are exactly the turns
-      # where context-window growth matters most).
-      #
-      # All counts are +Integer, nil+. +nil+ means the provider did not
-      # report that field — common with local llama.cpp / Ollama
-      # servers that leave parts of the OpenAI +usage+ block empty.
-      # Listeners treat +nil+ as zero.
+      # Provider-reported token usage for one assistant turn, off a
+      # +RubyLLM::Message+'s +tokens+ block. Emitted by +after_message+ on
+      # every assistant turn (including pure tool-call turns, where
+      # context growth matters most).
       #
-      # The fields +input+, +cached+, and +cache_creation+ are
-      # **exclusive portions of this turn's full prompt** under the
-      # shape ruby_llm exposes for llama.cpp and Anthropic: they sum
-      # to the total prompt size processed on this request. OpenAI
-      # proper nests +cached_tokens+ inside its +prompt_tokens+
-      # instead — if pikuri ever talks there directly, the sum formula
-      # needs revisiting.
+      # Every count is +Integer, nil+; +nil+ means the provider omitted
+      # the field (common on local llama.cpp/Ollama) and is treated as
+      # zero. +input+/+cached+/+cache_creation+ are *exclusive* slices of
+      # this turn's prompt and sum to its total size (llama.cpp +
+      # Anthropic shape; OpenAI nests +cached+ inside +input+, so revisit
+      # the sum if pikuri ever targets it directly). +cached+ still counts
+      # against the context window.
       #
       # - +input+ — newly-processed (uncached) prompt tokens this turn.
-      # - +output+ — tokens in this single assistant reply.
-      # - +cached+ — portion of this turn's prompt served from the
-      #   provider's prompt cache. Still counts against the context
-      #   window (caching is a speed/cost optimization, not a context-
-      #   savings mechanism).
-      # - +cache_creation+ — portion of this turn's prompt written
-      #   into the prompt cache. Anthropic-specific; usually +nil+ on
-      #   OpenAI-compatible local servers.
-      # - +thinking+ — extended-thinking (Anthropic) or reasoning
-      #   (OpenAI o-series) tokens produced on this turn. +nil+ on
-      #   providers without a reasoning channel.
-      # - +model_id+ — provider-side model name as reported on the
-      #   response; useful when a process targets multiple models.
-      #
-      # == Computing "current context window size"
-      #
-      # +input + cached + cache_creation+ is the size of the prompt
-      # processed on this turn. Add +output+ to get tokens consumed by
-      # the conversation *through* this turn — this turn's prompt plus
-      # its reply, both of which the model will re-process on the next
-      # turn. That's what climbs toward
-      # +RubyLLM::ContextLengthExceededError+ and is the snapshot
-      # {Listener::TokenLog#context_window_size} tracks.
+      # - +output+ — tokens in this reply.
+      # - +cached+ — prompt tokens served from the provider's cache.
+      # - +cache_creation+ — prompt tokens written to the cache (Anthropic).
+      # - +thinking+ — reasoning tokens (Anthropic thinking / OpenAI
+      #   o-series); +nil+ without a reasoning channel.
+      # - +model_id+ — provider-side model name on the response.
       Tokens = Data.define(:input, :output, :cached, :cache_creation, :thinking, :model_id)
 
-      # Model's resolved context-window cap. Emitted at construction
-      # by {Agent#initialize}, and again after every model switch
-      # (see {Agent#run_loop}'s +transport:+) since the cap is a
-      # property of the model. Carries +nil+ when no source produced
-      # a value (a non-llama server with no explicit cap). Listeners
-      # that care — {Listener::TokenLog} renders +ctx=<used>/<cap>+
-      # when set, +ctx=<used>+ when +nil+ — pick the value off this
-      # event and cache it; non-caring listeners ignore. A second
-      # ContextCap simply overwrites the first; the conversation is
-      # not re-baselined (a switch keeps the running context size).
+      # Model's resolved context-window cap (+nil+ if unknown). Emitted at
+      # construction and after each model switch. A later ContextCap
+      # overwrites the prior; the running context size is not re-baselined.
       ContextCap = Data.define(:cap)
 
-      # The agent switched to a different model mid-conversation,
-      # emitted by {Agent#run_loop} (via +apply_transport!+) just
-      # before the matching {ContextCap} for the new model. Carries
-      # the old and new {Agent::ChatTransport}s verbatim — unformatted
-      # by design, so each chrome presents them its own way (a TUI
-      # adds ANSI off +.model+, a web client adds CSS). The cap rides
-      # on the paired {ContextCap}, not here, so {Listener::TokenLog}
-      # needs no awareness of this event (its existing {ContextCap}
-      # arm picks up the new cap); a renderer wanting "switched to X
-      # (128k)" on one line correlates the two.
+      # Agent switched model mid-conversation. Emitted by {Agent#run_loop}
+      # just before the new model's {ContextCap}. Carries both
+      # {Agent::ChatTransport}s verbatim and unformatted — each chrome
+      # presents them its own way. The new cap rides on the paired
+      # {ContextCap}, not here.
       ModelSwitched = Data.define(:from, :to)
 
-      # Out-of-band notice that the agent had to take a rescue path.
-      # Emitted by {Agent#run_loop} when {Control::StepLimit} trips
-      # and the synthesizer fallback runs; carries the reason string
-      # the listener should surface. Lets listeners (Terminal, future
-      # web UI) surface the divergence to the user before the
-      # synthesizer's own assistant output flows through.
+      # Out-of-band notice that a rescue path was taken: emitted by
+      # {Agent#run_loop} when {Control::StepLimit} trips and the
+      # {Synthesizer} fallback runs. Carries the reason to surface before
+      # the synthesizer's own output flows through.
       FallbackNotice = Data.define(:reason)
 
-      # Out-of-band notice that the user cancelled the in-flight turn
-      # via {Control::Cancellable}. Emitted by {Agent#run_loop} just
-      # before the +Cancellable::Cancelled+ exception re-raises out of
-      # the loop, so listeners (Terminal renderer, structured
-      # recorders) can mark the turn as user-aborted. Unlike
-      # {FallbackNotice}, no recovery follows — the exception is
-      # re-raised and the caller is expected to return control to the
-      # user (typically the REPL prompt).
+      # Out-of-band notice that the user cancelled the in-flight turn via
+      # {Control::Cancellable}. Emitted by {Agent#run_loop} just before the
+      # +Cancelled+ exception re-raises — unlike {FallbackNotice}, no
+      # recovery follows; the caller returns control to the user.
       Cancelled = Data.define
+
+      # Marks a *domain* event whose successor **replaces** it rather than adding
+      # to a log: an indexing bar, a download percentage. A chrome that can
+      # rewrite a line does; one that cannot shows only the final state.
+      #
+      #   Progress = Data.define(:title, :done) do
+      #     include Pikuri::Agent::Event::Transient
+      #     def to_s = done ? "#{title} — done" : title
+      #   end
+      #
+      # The contract is two methods, both of which a +Data.define+ already
+      # answers: +#to_s+ is the whole rendering — a listener never inspects the
+      # fields, which is what keeps core ignorant of a gem's payload — and
+      # +#done+ says the sequence is over and its line may go away.
+      module Transient
+      end
+
+      # The conversation was cleared by {Agent#clear_conversation}: history
+      # is back to the system prompt, controls are reset, and each
+      # extension's {Extension#on_conversation_reset} has run. Emitted
+      # once, *before* the extension sweep, so pure-consumer listeners can
+      # reset display state; extension-owned state is signalled by the
+      # extensions' own domain events, not here. No payload.
+      Reset = Data.define
+
+      # A saved conversation was restored by {Agent#load_history!}. Always
+      # follows a {Reset}, which is the part that clears display state — this
+      # one says the conversation is *not* empty after all, and carries what a
+      # listener needs to stop lying about it.
+      #
+      # +tokens+ is the last assistant message's usage as recorded when the
+      # conversation was exported, so a running context readout can pick up
+      # where it left off instead of showing +0+ against 40k of restored
+      # history. +nil+ when the history holds no assistant turn, or was
+      # exported without usage.
+      #
+      # @!attribute [r] messages
+      #   @return [Integer] how many messages were restored
+      # @!attribute [r] tokens
+      #   @return [Tokens, nil] usage of the last restored assistant message
+      HistoryLoaded = Data.define(:messages, :tokens)
     end
   end
 end

data/lib/pikuri/agent/extension.rb

@@ -3,120 +3,144 @@
 module Pikuri
   class Agent
     # The Extension protocol — how hosts bolt extra capabilities
-    # (system-prompt snippets, tools, lifecycle hooks) onto an
-    # {Agent}. Extensions are added via {Configurator#add_extension}
-    # inside the +Agent.new+ block; the Agent then drives three hooks
-    # on each — {#configure} during the block, {#bind} once the agent
-    # is fully constructed, and {#on_user_message} on every user turn
-    # thereafter.
+    # (system-prompt sections, tools, lifecycle hooks) onto an {Agent}.
+    # Added via {Configurator#add_extension} inside the +Agent.new+ block;
+    # the Agent then drives a fixed hook set: {#configure} during the block
+    # (gets the {Configurator}), {#bind} once fully constructed,
+    # {#on_user_message} per user turn, {#on_conversation_reset} per
+    # {Agent#clear_conversation} (these three get the runtime
+    # {ExtensionContext}), and {#system_prompt_snippets} whenever the prompt
+    # is (re)assembled (no argument — reads state set in +configure+).
     #
-    # Each phase receives that phase's context object: +configure+
-    # gets the build-time {Configurator}; +bind+ and
-    # +on_user_message+ get the runtime {ExtensionContext} — the
-    # capability facade for everything that acts on the live agent
-    # (domain-event emission, raw tool registration, sub-agent
-    # listener derivation), with the agent itself readable via
-    # {ExtensionContext#agent}.
+    # Mix this module in to inherit no-op defaults for every hook, and
+    # override what you need. Not including it also works *if the class
+    # defines every hook* — the Agent calls them by name with no
+    # +respond_to?+ guard, so a missing one raises.
     #
-    # Mix this module into an extension class to inherit empty
-    # default implementations of all three hooks; override the ones
-    # you need. Extensions that don't +include+ this module still
-    # work *if they define all three methods themselves* — the Agent
-    # and Configurator call them by name with no +respond_to?+ guard,
-    # so a missing one raises. The module exists to make the protocol
-    # *explicit* and to give "I want to implement just +configure+"
-    # extensions free no-op +bind+ / +on_user_message+ defaults (and
-    # any other combination).
+    # The whole surface fires on the *parent agent only* — sub-agents do not
+    # inherit extensions (each persona owns its toolset and prompt verbatim).
     #
     # == Example
     #
     #   class MyExtension
     #     include Pikuri::Agent::Extension
-    #
-    #     def configure(c)
-    #       c.append_system_prompt("Always be polite.")
-    #     end
-    #
-    #     # bind not overridden — inherits the empty default
+    #     def system_prompt_snippets = ["Always be polite."]
+    #     # configure / bind not overridden — inherit the empty defaults
     #   end
     #
-    # See +Pikuri::Mcp::Extension+ and +Pikuri::Skill::Extension+
-    # (once those land in Steps 2-3 of the gem-split refactor — see
-    # IDEAS.md §"Extension protocol design") for the canonical
-    # worked implementations.
+    # See +Pikuri::Mcp::Extension+ / +Pikuri::Skill::Extension+ for worked
+    # implementations.
     module Extension
       # Called immediately by {Configurator#add_extension} during the
-      # +Agent.new+ block, with the parent agent's {Configurator}.
-      # Runs exactly once per extension instance, on the parent agent
-      # only — sub-agents do not re-run +configure+. The default is a
-      # no-op; override when you need to install *agent-agnostic*
-      # state. Things you typically do here:
-      #
-      # * append snippets to the system prompt via
-      #   {Configurator#append_system_prompt}
-      # * register tools via {Configurator#add_tool}
-      # * register listeners via {Configurator#add_listener}
-      # * register parent-only +on_close+ handlers via
-      #   {Configurator#on_close} (for cleanup of resources the
-      #   extension created in +configure+)
-      # * read the agent's transport / cancellable / etc. via the
-      #   Configurator's +attr_reader+s
+      # +Agent.new+ block, once per instance, with the parent's
+      # {Configurator}. Default no-op; override to install *agent-agnostic*
+      # state — typically:
+      #
+      # * tools via {Configurator#add_tool}, listeners via
+      #   {Configurator#add_listener}
+      # * parent-only +on_close+ cleanup via {Configurator#on_close}
+      # * read transport / cancellable / etc. off the Configurator
       #
       # @param c [Configurator] the parent agent's Configurator
       # @return [void]
       def configure(c); end
 
-      # Called by {Agent#initialize} after the block returns and the
-      # chat is fully wired, with the agent's {ExtensionContext} as
-      # the argument. Fires once per agent the extension was
-      # registered to via {Configurator#add_extension} — in the
-      # typical setup that's the parent agent only, since sub-agents
-      # do not inherit extensions. The default is a no-op; override
-      # when you need to install state keyed to the live agent.
-      # Things you typically do here:
-      #
-      # * register dynamic tools via {ExtensionContext#add_raw_tool}
-      #   (used by {Pikuri::Mcp::Extension} for +mcp_connect+,
-      #   whose +execute+ closure needs the context so activations
-      #   register on the right chat)
-      # * wire domain-event emission via
-      #   {ExtensionContext#emit_event} (e.g. +Pikuri::Tasks::Extension+
-      #   arms its list's +on_change+ here)
-      # * register per-agent +on_close+ handlers via
-      #   {ExtensionContext#on_close}
-      # * stash the +ctx+ if the extension's tools need to act on
-      #   this specific agent later
-      #
-      # @param ctx [ExtensionContext] capability facade for the
-      #   live, fully wired agent
+      # Called by {Agent#initialize} after the block returns and the chat is
+      # fully wired, with the agent's {ExtensionContext}. Default no-op;
+      # override to install state keyed to the live agent — typically:
+      #
+      # * dynamic tools via {ExtensionContext#add_raw_tool}
+      # * domain-event wiring via {ExtensionContext#emit_event}
+      # * per-agent +on_close+ via {ExtensionContext#on_close}
+      # * stash +ctx+ if the extension's tools act on this agent later
+      #
+      # @param ctx [ExtensionContext] capability facade for the live agent
       # @return [void]
       def bind(ctx); end
 
-      # Optional per-turn hook fired by the {Agent} after a user-message
-      # is added to the chat. The
-      # default is a no-op returning +nil+; override and return {String}
-      # to emit a `:system` message with that text.
-      #
-      # == Append-only, never mutate
-      #
-      # The Agent only ever *appends* the returned block at the tail; it never
-      # rewrites or removes an earlier one. Mutating mid-log would bust the
-      # provider prefix cache for every message after the edit. Stale blocks
-      # ride the existing context-window machinery, not a per-turn rewrite.
-      #
-      # == Not inherited by sub-agents
-      #
-      # Like the rest of the extension surface, this fires on the parent agent
-      # only — sub-agents do not inherit extensions, so a persona's turns are
-      # never prefetched or recorded by the parent's memory.
-      #
-      # @param ctx [ExtensionContext] capability facade for the live
-      #   agent whose turn this is — same instance +bind+ received
-      # @param content [String] the user message (initial or interloper) about
-      #   to be sent to the model
-      # @return [String, nil] an optional block of text to be injected verbatim as
-      #   a system-role message (after the user message), or +nil+ to inject nothing
+      # Optional per-turn hook fired after a user message is added to the
+      # chat. Default no-op returning +nil+; override and return a {String} to
+      # have it appended after the user turn as a +<system-reminder>+ reference
+      # block (see {Agent#append_reference_block} for the envelope and why it
+      # is not a +:system+ message).
+      #
+      # The Agent only ever *appends* the returned block at the tail — never
+      # rewrites or removes an earlier one, which would bust the provider
+      # prefix cache for everything after the edit. Stale blocks ride the
+      # existing context-window machinery, not a per-turn rewrite.
+      #
+      # @param ctx [ExtensionContext] the live agent whose turn this is (same
+      #   instance +bind+ received)
+      # @param content [String] the user message (initial or interloper)
+      # @return [String, nil] text to inject verbatim as a system-role message
+      #   after the user message, or +nil+ to inject nothing
       def on_user_message(ctx, content); end
+
+      # Optional hook fired by {Agent#clear_conversation} (a "/clear").
+      # Override to drop *conversation-scoped* state; default no-op, so an
+      # extension holding only process/infrastructure state opts out by not
+      # defining it.
+      #
+      # That distinction is the point: reset state that only makes sense
+      # within one conversation (+Pikuri::Tasks::Extension+ clears its list,
+      # the workspace clears its read-record); leave infrastructure alone
+      # (MCP subprocesses, a docker-backed server, the memory recorder's
+      # queue — a clear is not a quit).
+      #
+      # Do *not* touch the system prompt here — that refreshes automatically
+      # via {#system_prompt_snippets}, which the clear re-pulls. This hook is
+      # only for imperative state the prompt machinery can't express. An
+      # extension owning a domain event should emit it here so UI listeners
+      # see the reset (Tasks fires +Tasks::ListChanged+ with an empty list),
+      # synchronously after the Agent's {Event::Reset}.
+      #
+      # @param ctx [ExtensionContext] the live agent being cleared (same
+      #   instance +bind+ received)
+      # @return [void]
+      def on_conversation_reset(ctx); end
+
+      # This extension's system-prompt contributions, as text sections.
+      # Default none (+[]+); override to contribute one or more.
+      #
+      # Pull, not push: the {Agent} assembles its prompt by concatenating the
+      # base with what every extension returns here — at construction and
+      # again on every {Agent#clear_conversation}. So a section computed from
+      # live state (a resident memory persona, +MACHINE.md+ from disk) is
+      # *recomputed* on clear and stays current; a static section returns the
+      # same constant.
+      #
+      # No argument: read instance state populated in {#configure} (which runs
+      # first). Producing that state (starting servers, probing a model)
+      # belongs in +configure+; this only *reads* it, so it stays cheap enough
+      # for every clear (memoize an expensive one-shot at its source —
+      # +Pikuri::Os::SystemInfo#prompt_section+). Sections are joined by the
+      # Agent (blank/nil dropped), in registration order.
+      #
+      # @return [Array<String>] zero or more prompt sections; +[]+ for none
+      def system_prompt_snippets = []
+
+      # What this extension adds to the lethal-trifecta tree
+      # ({Pikuri::Trifecta}): legs the wired agent holds beyond its own tools,
+      # and child nodes for any sub-agents it introduces. Default none.
+      #
+      # Only two kinds of extension owe an answer, and both are things per-tool
+      # tagging structurally cannot see: one that introduces **sub-agents** (a
+      # whole node, plus the gate on the delegation edge) and one that mounts a
+      # **foreign tool surface** whose tools carry no legs of their own.
+      #
+      # +tools+ is the wired agent's tools plus its sub-agent tools, so an
+      # extension resolving a persona's +tool_names+ can select the same
+      # objects the sub-agent will actually receive — the resolution and the
+      # node it produces stay with whoever owns them.
+      #
+      # Unlike every other hook here, the Agent calls this **guarded by
+      # +respond_to?+**: this protocol permits a class that defines all hooks
+      # without including the module, and an unguarded new hook would break
+      # those. So a non-including extension may simply not have it.
+      #
+      # @param tools [Array<Pikuri::Tool>] the agent's tools + sub-agent tools
+      # @return [Pikuri::Trifecta::Contribution, nil] +nil+ for none
+      def trifecta_contribution(tools) = nil
     end
   end
 end